# Eventry Platform API — Full Reference for AI Tools

> This file contains everything an AI tool needs to generate integrations against the Eventry Platform API.
> For the machine-readable OpenAPI spec, see [api/openapi.json](api/openapi.json).

---

## Platform Overview

Eventry is a multi-tenant event management platform (SaaS). Organizations sign up as tenants and can:
- Create and publish events with custom registration forms
- Accept registrations and payments (Stripe, Swish, invoicing)
- Manage participants and attendees
- Issue certificates of attendance
- Build public event collection portals
- Receive real-time webhook notifications
- Manage team members and API keys

## API Basics

| Property | Value |
|---|---|
| Base URL | `https://api.eventry.com/api/v1` |
| Auth URL | `https://auth.eventry.com/realms/eventry-platform` |
| Protocol | REST over HTTPS |
| Format | JSON (request and response) |
| Versioning | URL-based (`/api/v1/...`) |
| Errors | RFC 7807 Problem Details |
| IDs | UUID v4 |
| Timestamps | ISO 8601 UTC |
| Money | Minor units (öre/cents), e.g. `15000` = 150.00 SEK |
| Pagination | Cursor-based (`limit`, `cursor`, `has_more`, `next_cursor`) |
| Rate Limits | 5,000 req/hr (authenticated), 100 req/hr (unauthenticated) |

### Multi-Tenant Header

Tenant-scoped endpoints require:
```
X-Tenant-Id: {customer-uuid}
```

Public discovery endpoints and collection endpoints do not require this header.

---

## Authentication

### Method 1: API Key (Server-to-Server)

```http
Authorization: Bearer eventry_live_your_api_key_here
```

API keys are created via the portal or API (`POST /api/v1/Organizations/{id}/api-keys`).

### Method 2: OAuth2 via Keycloak

**Token endpoint:**
```
POST https://auth.eventry.com/realms/eventry-platform/protocol/openid-connect/token
```

**Password Grant (scripts/testing):**
```bash
curl -s -X POST \
  "https://auth.eventry.com/realms/eventry-platform/protocol/openid-connect/token" \
  -d "grant_type=password" \
  -d "client_id=eventry-portal" \
  -d "username=user@example.com" \
  -d "password=yourpassword" \
  | jq -r '.access_token'
```

**Authorization Code + PKCE (web apps):**
1. Redirect to: `https://auth.eventry.com/realms/eventry-platform/protocol/openid-connect/auth?client_id=...&response_type=code&redirect_uri=...&scope=openid&code_challenge=...&code_challenge_method=S256`
2. Exchange code for token at the token endpoint with `grant_type=authorization_code`

**Using the token:**
```http
Authorization: Bearer {access_token}
```

---

## Endpoint Reference

### Events

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/Events` | List events for current organization | Required |
| POST | `/Events` | Create a new event | Required |
| GET | `/Events/{id}` | Get event details | Required |
| PUT | `/Events/{id}` | Update an event | Required |
| DELETE | `/Events/{id}` | Delete an event | Required |
| GET | `/Events/{id}/attendees` | List attendees for an event | Required |
| POST | `/Events/{id}/calculate-price` | Calculate registration price | Required |

### Discover (Public)

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/Discover` | Public event discovery feed | None |
| GET | `/Discover/{id}` | Get public event details | None |
| GET | `/Discover/collections` | List public collections | None |
| GET | `/Discover/collections/{slug}` | Get public collection by slug | None |
| GET | `/Discover/companies/{companyKey}` | Events by company | None |
| GET | `/Discover/organisers` | List event organisers | None |
| GET | `/Discover/categories/popular` | Popular event categories | None |
| GET | `/Discover/resolve/{eventKey}` | Resolve event by key | None |
| GET | `/Discover/{id}/translated-content` | Translated event content | None |
| POST | `/Discover/translate-titles` | Batch translate event titles | None |

### Registrations

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/Registrations` | List registrations | Required |
| POST | `/Registrations` | Create a registration | Required |
| GET | `/Registrations/{id}` | Get registration details | Required |
| POST | `/Registrations/{id}/confirm` | Confirm a registration | Required |
| POST | `/Registrations/{id}/cancel` | Cancel a registration | Required |
| POST | `/Registrations/{id}/approve` | Approve a registration | Required |
| POST | `/Registrations/{id}/reject` | Reject a registration | Required |
| POST | `/Registrations/{id}/check-in` | Check in a registration | Required |
| DELETE | `/Registrations/{id}/check-in` | Undo check-in | Required |
| GET | `/Registrations/by-event/{eventId}` | Registrations for an event | Required |
| GET | `/Registrations/by-event/{eventId}/participants` | Participants for event | Required |
| GET | `/Registrations/by-participant/{participantId}` | Registrations by participant | Required |

### Participants

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/Participants` | List participants | Required |
| POST | `/Participants` | Create participant | Required |
| GET | `/Participants/{id}` | Get participant | Required |
| PUT | `/Participants/{id}` | Update participant | Required |
| DELETE | `/Participants/{id}` | Delete participant (GDPR) | Required |
| GET | `/Participants/{id}/export` | Export participant data | Required |
| GET | `/Participants/{id}/export/csv` | Export as CSV | Required |
| GET | `/Participants/{id}/export/json` | Export as JSON | Required |
| POST | `/Participants/request-deletion` | GDPR deletion request | Required |
| POST | `/Participants/cancel-deletion` | Cancel deletion request | Required |
| PATCH | `/participants/{participantId}/communication-preferences` | Update comm prefs | Required |

### Payments

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| POST | `/payments/checkout-session` | Create Stripe checkout session | Required |
| POST | `/payments/event-checkout` | Event-specific checkout | Required |
| POST | `/payments/intent` | Create payment intent | Required |
| GET | `/payments/by-registration/{registrationId}` | Get payment for registration | Required |
| POST | `/payments/{paymentId}/refund` | Refund a payment | Required |
| POST | `/payments/refunds` | Process refund | Required |
| GET | `/payments/invoices` | List invoices | Required |
| GET | `/payments/config` | Payment configuration | Required |
| POST | `/payments/customer-portal` | Open Stripe customer portal | Required |
| GET | `/payments/stripe/connect/status` | Stripe Connect status | Required |
| POST | `/payments/stripe/onboarding` | Start Stripe onboarding | Required |

### Collections

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/Collections` | List my collections | Required |
| POST | `/Collections` | Create a collection | Required |
| GET | `/Collections/{slug}` | Get collection by slug | None |
| PUT | `/Collections/{id}` | Update collection | Required |
| DELETE | `/Collections/{id}` | Delete collection | Required |
| GET | `/Collections/available` | Available collections | Required |
| POST | `/Collections/{id}/events` | Add event to collection | Required |
| DELETE | `/Collections/{id}/events/{publicEventIndexId}` | Remove event | Required |
| GET | `/Collections/{id}/members` | List collection members | Required |
| POST | `/Collections/{id}/members` | Invite member | Required |
| DELETE | `/Collections/{id}/members/{memberId}` | Remove member | Required |
| POST | `/Collections/accept-invitation` | Accept collection invite | Required |
| GET | `/Collections/{id}/tags` | List collection tags | Required |
| POST | `/Collections/{id}/tags` | Create collection tag | Required |
| PUT | `/Collections/{id}/tags/{tagId}` | Update tag | Required |
| DELETE | `/Collections/{id}/tags/{tagId}` | Delete tag | Required |
| GET | `/Collections/{id}/custom-fields` | List custom fields | Required |
| POST | `/Collections/{id}/custom-fields` | Create custom field | Required |
| PUT | `/Collections/{id}/custom-fields/{fieldId}` | Update custom field | Required |
| DELETE | `/Collections/{id}/custom-fields/{fieldId}` | Delete custom field | Required |
| PUT | `/Collections/{id}/events/{publicEventIndexId}/tags` | Set event tags | Required |
| GET | `/Collections/{collectionId}/events/{itemId}/custom-field-values` | Get field values | Required |
| PUT | `/Collections/{collectionId}/events/{itemId}/custom-field-values` | Set field values | Required |

### Forms

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/form-templates` | List form templates | Required |
| POST | `/form-templates` | Create form template | Required |
| GET | `/form-templates/{id}` | Get form template | Required |
| PUT | `/form-templates/{id}` | Update form template | Required |
| DELETE | `/form-templates/{id}` | Delete form template | Required |
| POST | `/form-templates/{id}/publish` | Publish form | Required |
| POST | `/form-templates/copy-global/{globalFormTemplateId}` | Copy global template | Required |
| GET | `/global-form-templates` | List global templates | Required |
| GET | `/global-form-templates/{id}` | Get global template | Required |

### Certificates

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/Certificates` | List certificates | Required |
| POST | `/Certificates` | Create certificate | Required |
| POST | `/Certificates/generate` | Batch generate | Required |
| GET | `/Certificates/by-registration/{registrationId}` | Get by registration | Required |
| GET | `/Certificates/verify/{verificationCode}` | Verify certificate | None |
| GET | `/certificate-templates` | List templates | Required |
| POST | `/certificate-templates` | Create template | Required |
| GET | `/certificate-templates/{id}` | Get template | Required |
| PUT | `/certificate-templates/{id}` | Update template | Required |
| DELETE | `/certificate-templates/{id}` | Delete template | Required |

### Organizations

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| POST | `/Organizations/signup` | Register new organization | None |
| PUT | `/Organizations/{id}/profile` | Update org profile | Required |
| GET | `/Organizations/{id}/subscription` | Get subscription | Required |
| PUT | `/Organizations/{id}/subscription` | Update subscription | Required |
| GET | `/Organizations/{id}/members` | List team members | Required |
| POST | `/Organizations/{id}/members/invite` | Invite team member | Required |
| DELETE | `/Organizations/{id}/members/{memberId}` | Remove member | Required |
| GET | `/Organizations/{id}/api-keys` | List API keys | Required |
| POST | `/Organizations/{id}/api-keys` | Create API key | Required |
| DELETE | `/Organizations/{id}/api-keys/{keyId}` | Revoke API key | Required |
| GET | `/Organizations/{id}/email-provider` | Get email config | Required |
| PUT | `/Organizations/{id}/email-provider` | Set email config | Required |

### Webhooks

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/Webhooks` | List webhook subscriptions | Required |
| POST | `/Webhooks` | Create webhook subscription | Required |
| GET | `/Webhooks/{id}` | Get webhook | Required |
| PUT | `/Webhooks/{id}` | Update webhook | Required |
| DELETE | `/Webhooks/{id}` | Delete webhook | Required |
| GET | `/Webhooks/{id}/deliveries` | List webhook deliveries | Required |

### Consents (GDPR)

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/Consents` | List consents | Required |
| POST | `/Consents` | Record consent | Required |
| POST | `/Consents/{id}/revoke` | Revoke consent | Required |
| GET | `/Consents/types` | List consent types | Required |

### Tags

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/Tags` | List tags | Required |
| POST | `/Tags` | Create tag | Required |
| PUT | `/Tags/{id}` | Update tag | Required |
| DELETE | `/Tags/{id}` | Delete tag | Required |
| POST | `/Tags/suggest` | AI-suggest tags | Required |

### Translations

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| PUT | `/Translations` | Create/update translation | Required |
| GET | `/Translations/{entityType}/{entityId}` | Get translations | Required |
| DELETE | `/Translations/{entityType}/{entityId}` | Delete translations | Required |
| GET | `/Translations/{entityType}/{entityId}/status` | Translation status | Required |
| POST | `/Translations/{entityType}/{entityId}/mark-outdated` | Mark outdated | Required |
| POST | `/Translations/translate` | Auto-translate content | Required |

### Reports

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/reports/registrations` | Registration statistics | Required |
| GET | `/reports/revenue` | Revenue reports | Required |
| GET | `/reports/events/{eventId}/analytics` | Event analytics | Required |
| GET | `/reports/export` | Export report data | Required |

### Event Collaborators

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/events/{eventId}/collaborators` | List collaborators | Required |
| POST | `/events/{eventId}/collaborators` | Invite collaborator | Required |
| DELETE | `/events/{eventId}/collaborators/{collaboratorId}` | Remove collaborator | Required |

### Images

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| POST | `/images/upload` | Upload image | Required |
| GET | `/images/resize` | Resize/proxy image | None |

---

## Webhook Events

Register a webhook URL to receive these events:

**Events:** `event.created`, `event.updated`, `event.deleted`, `event.published`, `event.cancelled`
**Registrations:** `registration.created`, `registration.updated`, `registration.confirmed`, `registration.cancelled`, `registration.completed`
**Participants:** `participant.created`, `participant.updated`, `participant.deleted`
**Payments:** `payment.created`, `payment.processing`, `payment.succeeded`, `payment.failed`, `payment.refunded`, `payment.partially_refunded`
**Certificates:** `certificate.generated`, `certificate.downloaded`, `certificate.revoked`
**Communications:** `communication.sent`, `communication.delivered`, `communication.failed`, `communication.opened`, `communication.clicked`
**Consents:** `consent.granted`, `consent.revoked`, `consent.expired`

**Payload format:**
```json
{
  "id": "evt_webhook_...",
  "type": "registration.created",
  "created": 1705328400,
  "data": {
    "object": { /* full resource object */ }
  }
}
```

Webhooks include an HMAC signature in the `X-Webhook-Signature` header for verification.

---

## Common Patterns

### Create Event → Open Registration → Handle Payment

```bash
# 1. Create event
curl -X POST https://api.eventry.com/api/v1/Events \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Workshop", "startDate": "2026-06-01T09:00:00Z", "endDate": "2026-06-01T17:00:00Z", "maxAttendees": 50}'

# 2. Create registration
curl -X POST https://api.eventry.com/api/v1/Registrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"eventId": "EVENT_ID", "participantId": "PARTICIPANT_ID"}'

# 3. Create checkout session (if paid event)
curl -X POST https://api.eventry.com/api/v1/payments/checkout-session \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"registrationId": "REG_ID", "successUrl": "https://yoursite.com/success", "cancelUrl": "https://yoursite.com/cancel"}'
```

### Collection Community Portal

```bash
# 1. Create a collection
curl -X POST https://api.eventry.com/api/v1/Collections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Summer Events 2026", "isPublic": true}'

# 2. Add events to collection
curl -X POST https://api.eventry.com/api/v1/Collections/{id}/events \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"publicEventIndexId": "EVENT_INDEX_ID"}'

# 3. Invite collaborator
curl -X POST https://api.eventry.com/api/v1/Collections/{id}/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "partner@example.com", "role": "Contributor"}'

# 4. Public access (no auth needed)
curl https://api.eventry.com/api/v1/Collections/{slug}
```

### Webhook Integration

```bash
# Register webhook
curl -X POST https://api.eventry.com/api/v1/Webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yoursite.com/webhook", "events": ["registration.created", "payment.succeeded"]}'
```

---

## Error Response Format

```json
{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "errors": {
    "email": ["The Email field is required."]
  }
}
```

Common status codes: `200 OK`, `201 Created`, `204 No Content`, `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`, `409 Conflict`, `429 Too Many Requests`.