**גרסאות API** · [V2 (Latest)](/integrations/v2/docs?lang=he) · **V1**

> **גרסה זו של ה־API מיושנת.** לחיבורים חדשים יש להשתמש בגרסה העדכנית ביותר. [לתיעוד העדכני](/integrations/v2/docs?lang=he)

# Annual Events

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "description": "API"
  }
]
```

Managed ordinary events: create from structured data or a poster, publish the public page, registration form and/or fundraiser, then prepare a campaign draft. Shabbat and prefab-holiday events are deliberately outside this API. Scopes: `events:read` / `events:write`.

## פעולות

## GET /annual-events

List managed annual events

`list_annual_events`

Required scope: `events:read`. Lists event projects created through the guided annual-event facade. Includes one-off and recurring ordinary events, and excludes all Shabbat / prefab-holiday flows by construction.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "events:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Number of results per page"
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Opaque cursor returned by the previous request"
}
```

```json
{
  "name": "year",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 2000,
    "maximum": 2200
  }
}
```

```json
{
  "name": "publicationStatus",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "CREATED",
      "PUBLISHED",
      "PUBLISHING",
      "PUBLISH_FAILED"
    ]
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AnnualEventProject"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "INSUFFICIENT_SCOPE"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "events:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /annual-events

Create and publish an ordinary event

`create_annual_event`

Required scope: `events:write`. Idempotently coordinates the page, group, sessions and requested form/fundraiser/campaign draft from one reviewed recipe. `idempotencyKey` is required in the JSON body for both REST and MCP; the optional `Idempotency-Key` header may override it for transport-level retries. A campaign is always left in draft and is never sent here.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "events:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "Idempotency-Key",
  "in": "header",
  "schema": {
    "type": "string",
    "maxLength": 200
  }
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AnnualEventCreateInput"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AnnualEventPublishResult"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "INVALID_INPUT"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "CONFLICT"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "VALIDATION_ERROR"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-scope": "events:write"
}
```

## GET /annual-events/groups

List compatible ordinary event groups

`list_annual_event_groups`

Required scope: `events:read`. Lists only ordinary single-session groups that can safely receive a new event. Shabbat, prefab-holiday and multi-session groups are excluded.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "events:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Number of results per page"
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Opaque cursor returned by the previous request"
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AnnualEventCompatibleGroup"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "INSUFFICIENT_SCOPE"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "events:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /annual-events/poster-analysis

Prepare an event draft from a poster

`analyze_annual_event_poster`

Required scope: `events:write`. Reads a real poster image and returns a comprehensive suggested recipe. This does not publish anything; the caller must show the result for review, complete uncertain fields, then call `create_annual_event`.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "events:write",
  "additional": []
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AnnualEventPosterAnalysisRequest"
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/AnnualEventPosterAnalysis"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "INVALID_POSTER"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "POSTER_NOT_FOUND"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "AI_UNAVAILABLE"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "events:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /annual-events/{id}

Get a managed annual event

`get_annual_event`

Required scope: `events:read`. Returns the canonical project, its reviewed recipe, revision, public URL and the ids of its sessions, forms, fundraisers and campaign drafts.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "events:read",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{3,128}$"
  },
  "description": "Annual-event project id."
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/AnnualEventProject"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "EVENT_NOT_FOUND"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "events:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /annual-events/{id}

Update and republish a managed annual event

`update_annual_event`

Required scope: `events:write`. Applies a partial patch to the stored recipe and republishes its managed resources. Send `expectedRevision` to reject a stale edit with 409. Arrays supplied in the patch replace their previous value. A campaign remains a draft and is never sent here.

### אימות

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### הרשאות נדרשות

```json
{
  "accepted": "events:write",
  "additional": []
}
```

### פרמטרים

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{3,128}$"
  },
  "description": "Annual-event project id."
}
```

### גוף הבקשה

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "expectedRevision": {
            "type": "integer",
            "minimum": 1
          },
          "patch": {
            "$ref": "#/components/schemas/AnnualEventPatch"
          },
          "idempotencyKey": {
            "type": "string",
            "maxLength": 200
          },
          "timeZone": {
            "type": "string"
          }
        },
        "required": [
          "expectedRevision",
          "patch"
        ]
      }
    }
  }
}
```

### תגובות

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AnnualEventPublishResult"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "EVENT_NOT_FOUND"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "REVISION_CONFLICT"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "description": "VALIDATION_ERROR"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "events:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## סכמות

```json
{
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "Number of results per page"
      },
      "CursorParam": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Opaque cursor returned by the previous request"
      }
    },
    "schemas": {
      "AnnualEventProject": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AnnualEventPublishResult"
          },
          {
            "type": "object",
            "properties": {
              "draft": {
                "$ref": "#/components/schemas/AnnualEventDraft"
              },
              "snapshotHash": {
                "type": "string"
              },
              "datetime": {
                "type": "string",
                "format": "date-time"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "AnnualEventPublishResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "eventId": {
            "type": "string"
          },
          "projectId": {
            "type": "string"
          },
          "revision": {
            "type": "integer"
          },
          "publicationStatus": {
            "type": "string",
            "enum": [
              "CREATED",
              "PUBLISHED",
              "PUBLISHING",
              "PUBLISH_FAILED"
            ]
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "publicUrl": {
            "type": "string",
            "nullable": true
          },
          "resources": {
            "$ref": "#/components/schemas/AnnualEventResources"
          },
          "operationalState": {
            "$ref": "#/components/schemas/AnnualEventOperationalState"
          }
        }
      },
      "AnnualEventResources": {
        "type": "object",
        "properties": {
          "groupId": {
            "type": "string",
            "nullable": true
          },
          "sessionIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "formIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "fundraiserIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "campaignIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "AnnualEventOperationalState": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "registration": {
            "$ref": "#/components/schemas/AnnualEventRegistrationState"
          }
        },
        "required": [
          "registration"
        ]
      },
      "AnnualEventRegistrationState": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "configured": {
            "type": "boolean",
            "description": "Whether at least one managed registration form exists."
          },
          "open": {
            "type": "boolean",
            "description": "Whether a managed form and one of its event sessions are currently active."
          },
          "submissionCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Received, non-archived registrations in SUBMIT or VALIDE state."
          }
        },
        "required": [
          "configured",
          "open",
          "submissionCount"
        ]
      },
      "AnnualEventDraft": {
        "type": "object",
        "additionalProperties": false,
        "description": "Complete event recipe. The server normalises this object and materialises all requested resources. Amounts are in major currency units. An `upload` poster is a real image; pass either a hosted filename from `/uploads/image` or an http(s) URL that the server can re-host.",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "description": "Optional project UUID. Omit on create; keep it for updates."
          },
          "version": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          "templateId": {
            "type": "string",
            "description": "Suggested format id, or `custom`."
          },
          "destination": {
            "$ref": "#/components/schemas/AnnualEventDestination"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "title": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500
          },
          "sourceLanguage": {
            "type": "string",
            "description": "Language of the supplied content; defaults to the organisation language. Multilingual organisations receive automatic content translations at creation."
          },
          "currency": {
            "type": "string",
            "readOnly": true,
            "description": "Primary currency resolved by the server from the organisation."
          },
          "tagline": {
            "type": "string",
            "maxLength": 2000
          },
          "description": {
            "type": "string",
            "maxLength": 20000
          },
          "mode": {
            "type": "string",
            "enum": [
              "registration",
              "fundraising",
              "both",
              "information"
            ]
          },
          "attendeeMode": {
            "type": "string",
            "enum": [
              "individual",
              "group",
              "family",
              "children"
            ]
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Required except for a date-optional standalone fundraiser."
          },
          "dateOptional": {
            "type": "boolean"
          },
          "startTime": {
            "type": "string",
            "pattern": "^[0-2][0-9]:[0-5][0-9]$"
          },
          "endTime": {
            "type": "string",
            "pattern": "^[0-2][0-9]:[0-5][0-9]$"
          },
          "locationMode": {
            "type": "string",
            "enum": [
              "onsite",
              "online"
            ]
          },
          "locationName": {
            "type": "string",
            "maxLength": 500
          },
          "address": {
            "type": "string",
            "maxLength": 1000
          },
          "onlineUrl": {
            "type": "string",
            "format": "uri"
          },
          "cadence": {
            "type": "string",
            "enum": [
              "once",
              "weekly",
              "monthly",
              "custom"
            ]
          },
          "recurrenceCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          },
          "customDates": {
            "type": "array",
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "date"
            },
            "description": "All session dates when cadence=custom. The first date and count are derived from this list."
          },
          "excludedDates": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "string",
              "format": "date"
            }
          },
          "slotDuration": {
            "type": "integer",
            "minimum": 0
          },
          "slotCapacity": {
            "type": "integer",
            "minimum": 0
          },
          "capacityEnabled": {
            "type": "boolean"
          },
          "capacity": {
            "type": "integer",
            "minimum": 0
          },
          "priceMode": {
            "type": "string",
            "enum": [
              "free",
              "fixed",
              "multiple",
              "freeAmount"
            ]
          },
          "price": {
            "type": "number",
            "minimum": 0
          },
          "prices": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "minimum": 0
            },
            "description": "Optional prices keyed by enabled secondary currency (lowercase ISO code). Missing values keep the primary numeric price without conversion."
          },
          "tariffs": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/AnnualEventTariff"
            }
          },
          "target": {
            "type": "number",
            "minimum": 0
          },
          "partialPayments": {
            "type": "boolean"
          },
          "depositAmount": {
            "type": "number",
            "minimum": 0
          },
          "contributionAmounts": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "number",
              "minimum": 0
            }
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "firstName",
                "lastName",
                "email",
                "phone",
                "address",
                "birthDate"
              ]
            }
          },
          "children": {
            "type": "boolean"
          },
          "questions": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/AnnualEventQuestion"
            }
          },
          "requirementsEnabled": {
            "type": "boolean"
          },
          "requirements": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/AnnualEventRequirement"
            }
          },
          "manualValidation": {
            "type": "boolean"
          },
          "confirmationText": {
            "type": "string",
            "maxLength": 5000
          },
          "reminders": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "confirmation": {
                "type": "boolean"
              },
              "weekBefore": {
                "type": "boolean"
              },
              "dayBefore": {
                "type": "boolean"
              }
            }
          },
          "page": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "layout": {
                "type": "string",
                "enum": [
                  "essential",
                  "story",
                  "campaign"
                ]
              },
              "ctaLabel": {
                "type": "string",
                "maxLength": 300
              },
              "showDescription": {
                "type": "boolean"
              },
              "showPracticalInfo": {
                "type": "boolean"
              },
              "showOrganizer": {
                "type": "boolean"
              },
              "showProgress": {
                "type": "boolean"
              },
              "customContent": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "faq",
                      "pricing",
                      "programme",
                      "speakers",
                      "free"
                    ]
                  },
                  "aiContentBlockId": {
                    "type": "string",
                    "nullable": true,
                    "description": "Existing AI content-block id. Manage its HTML through `/content-blocks`."
                  }
                }
              }
            }
          },
          "poster": {
            "type": "object",
            "additionalProperties": false,
            "description": "A poster exists only when `source=upload` and `image` references a real image.",
            "properties": {
              "source": {
                "type": "string",
                "enum": [
                  "none",
                  "upload"
                ]
              },
              "image": {
                "type": "string",
                "nullable": true,
                "description": "Hosted filename or http(s) image URL."
              },
              "tone": {
                "type": "string",
                "enum": [
                  "auto",
                  "blue",
                  "cyan",
                  "violet",
                  "green",
                  "amber",
                  "rose",
                  "red"
                ],
                "description": "auto follows the public site's theme; explicit colors stay fixed."
              },
              "badge": {
                "type": "string",
                "maxLength": 300
              }
            }
          },
          "campaignEnabled": {
            "type": "boolean",
            "description": "When true, create or update a campaign DRAFT; it is never sent automatically."
          },
          "campaign": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "channels": {
                "type": "array",
                "minItems": 1,
                "maxItems": 3,
                "items": {
                  "type": "string",
                  "enum": [
                    "email",
                    "whatsapp",
                    "sms"
                  ]
                }
              },
              "audience": {
                "type": "string",
                "enum": [
                  "all",
                  "families",
                  "participants",
                  "custom"
                ],
                "description": "`families`, `participants` and `custom` keep the draft without automatic targeting until the organiser chooses the exact audience."
              },
              "includePoster": {
                "type": "boolean",
                "description": "The image is attached only when a real uploaded poster exists."
              },
              "message": {
                "type": "string",
                "maxLength": 10000
              },
              "schedule": {
                "type": "string",
                "enum": [
                  "now",
                  "later"
                ]
              },
              "scheduledAt": {
                "type": "string",
                "nullable": true,
                "description": "ISO date-time used when the campaign is eventually sent."
              }
            }
          },
          "posterAnalysis": {
            "type": "object",
            "nullable": true,
            "additionalProperties": false,
            "description": "Audit metadata retained when the draft was prepared from a poster.",
            "properties": {
              "confidence": {
                "type": "string",
                "enum": [
                  "high",
                  "medium",
                  "low"
                ]
              },
              "detectedLanguage": {
                "type": "string"
              },
              "sourceSummary": {
                "type": "string"
              },
              "extractedText": {
                "type": "string"
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "analyzedAt": {
                "type": "string"
              }
            }
          },
          "draftStatus": {
            "type": "string",
            "enum": [
              "EDITING",
              "READY"
            ]
          },
          "validatedAt": {
            "type": "string",
            "nullable": true
          },
          "cursorStepId": {
            "type": "string"
          }
        },
        "required": [
          "title",
          "destination",
          "mode"
        ]
      },
      "AnnualEventDestination": {
        "type": "object",
        "additionalProperties": false,
        "description": "Where the event belongs. Use `existing` only after listing and explicitly selecting a compatible ordinary group; protected and multi-session groups are rejected.",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "new",
              "existing"
            ],
            "default": "new"
          },
          "groupId": {
            "type": "string",
            "nullable": true,
            "description": "Existing ordinary standalone group id."
          },
          "groupLabel": {
            "type": "string",
            "maxLength": 500
          },
          "confirmed": {
            "type": "boolean",
            "description": "Must be true: the caller confirms the destination decision."
          }
        },
        "required": [
          "kind",
          "confirmed"
        ]
      },
      "AnnualEventTariff": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 100
          },
          "label": {
            "type": "string",
            "maxLength": 300
          },
          "price": {
            "type": "number",
            "minimum": 0
          },
          "prices": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "minimum": 0
            },
            "description": "Optional prices keyed by enabled secondary currency (lowercase ISO code). Missing values keep the primary numeric price without conversion."
          },
          "stock": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          }
        },
        "required": [
          "label",
          "price"
        ]
      },
      "AnnualEventQuestion": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 100
          },
          "label": {
            "type": "string",
            "maxLength": 500
          },
          "type": {
            "type": "string",
            "enum": [
              "shortText",
              "longText",
              "yesNo",
              "choice",
              "document"
            ]
          },
          "required": {
            "type": "boolean"
          },
          "options": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "string",
              "maxLength": 300
            }
          },
          "condition": {
            "type": "object",
            "nullable": true,
            "additionalProperties": false,
            "properties": {
              "questionId": {
                "type": "string"
              },
              "value": {
                "type": "string"
              }
            },
            "required": [
              "questionId",
              "value"
            ]
          }
        },
        "required": [
          "label",
          "type"
        ]
      },
      "AnnualEventRequirement": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string",
            "maxLength": 500
          },
          "required": {
            "type": "boolean"
          }
        },
        "required": [
          "label"
        ]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "AnnualEventCreateInput": {
        "type": "object",
        "additionalProperties": false,
        "description": "Complete event recipe. The server normalises this object and materialises all requested resources. Amounts are in major currency units. An `upload` poster is a real image; pass either a hosted filename from `/uploads/image` or an http(s) URL that the server can re-host.",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "description": "Optional project UUID. Omit on create; keep it for updates."
          },
          "version": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          "templateId": {
            "type": "string",
            "description": "Suggested format id, or `custom`."
          },
          "destination": {
            "$ref": "#/components/schemas/AnnualEventDestination"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "title": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500
          },
          "sourceLanguage": {
            "type": "string",
            "description": "Language of the supplied content; defaults to the organisation language. Multilingual organisations receive automatic content translations at creation."
          },
          "currency": {
            "type": "string",
            "readOnly": true,
            "description": "Primary currency resolved by the server from the organisation."
          },
          "tagline": {
            "type": "string",
            "maxLength": 2000
          },
          "description": {
            "type": "string",
            "maxLength": 20000
          },
          "mode": {
            "type": "string",
            "enum": [
              "registration",
              "fundraising",
              "both",
              "information"
            ]
          },
          "attendeeMode": {
            "type": "string",
            "enum": [
              "individual",
              "group",
              "family",
              "children"
            ]
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Required except for a date-optional standalone fundraiser."
          },
          "dateOptional": {
            "type": "boolean"
          },
          "startTime": {
            "type": "string",
            "pattern": "^[0-2][0-9]:[0-5][0-9]$"
          },
          "endTime": {
            "type": "string",
            "pattern": "^[0-2][0-9]:[0-5][0-9]$"
          },
          "locationMode": {
            "type": "string",
            "enum": [
              "onsite",
              "online"
            ]
          },
          "locationName": {
            "type": "string",
            "maxLength": 500
          },
          "address": {
            "type": "string",
            "maxLength": 1000
          },
          "onlineUrl": {
            "type": "string",
            "format": "uri"
          },
          "cadence": {
            "type": "string",
            "enum": [
              "once",
              "weekly",
              "monthly",
              "custom"
            ]
          },
          "recurrenceCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          },
          "customDates": {
            "type": "array",
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "date"
            },
            "description": "All session dates when cadence=custom. The first date and count are derived from this list."
          },
          "excludedDates": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "string",
              "format": "date"
            }
          },
          "slotDuration": {
            "type": "integer",
            "minimum": 0
          },
          "slotCapacity": {
            "type": "integer",
            "minimum": 0
          },
          "capacityEnabled": {
            "type": "boolean"
          },
          "capacity": {
            "type": "integer",
            "minimum": 0
          },
          "priceMode": {
            "type": "string",
            "enum": [
              "free",
              "fixed",
              "multiple",
              "freeAmount"
            ]
          },
          "price": {
            "type": "number",
            "minimum": 0
          },
          "prices": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "minimum": 0
            },
            "description": "Optional prices keyed by enabled secondary currency (lowercase ISO code). Missing values keep the primary numeric price without conversion."
          },
          "tariffs": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/AnnualEventTariff"
            }
          },
          "target": {
            "type": "number",
            "minimum": 0
          },
          "partialPayments": {
            "type": "boolean"
          },
          "depositAmount": {
            "type": "number",
            "minimum": 0
          },
          "contributionAmounts": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "number",
              "minimum": 0
            }
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "firstName",
                "lastName",
                "email",
                "phone",
                "address",
                "birthDate"
              ]
            }
          },
          "children": {
            "type": "boolean"
          },
          "questions": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/AnnualEventQuestion"
            }
          },
          "requirementsEnabled": {
            "type": "boolean"
          },
          "requirements": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/AnnualEventRequirement"
            }
          },
          "manualValidation": {
            "type": "boolean"
          },
          "confirmationText": {
            "type": "string",
            "maxLength": 5000
          },
          "reminders": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "confirmation": {
                "type": "boolean"
              },
              "weekBefore": {
                "type": "boolean"
              },
              "dayBefore": {
                "type": "boolean"
              }
            }
          },
          "page": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "layout": {
                "type": "string",
                "enum": [
                  "essential",
                  "story",
                  "campaign"
                ]
              },
              "ctaLabel": {
                "type": "string",
                "maxLength": 300
              },
              "showDescription": {
                "type": "boolean"
              },
              "showPracticalInfo": {
                "type": "boolean"
              },
              "showOrganizer": {
                "type": "boolean"
              },
              "showProgress": {
                "type": "boolean"
              },
              "customContent": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "faq",
                      "pricing",
                      "programme",
                      "speakers",
                      "free"
                    ]
                  },
                  "aiContentBlockId": {
                    "type": "string",
                    "nullable": true,
                    "description": "Existing AI content-block id. Manage its HTML through `/content-blocks`."
                  }
                }
              }
            }
          },
          "poster": {
            "type": "object",
            "additionalProperties": false,
            "description": "A poster exists only when `source=upload` and `image` references a real image.",
            "properties": {
              "source": {
                "type": "string",
                "enum": [
                  "none",
                  "upload"
                ]
              },
              "image": {
                "type": "string",
                "nullable": true,
                "description": "Hosted filename or http(s) image URL."
              },
              "tone": {
                "type": "string",
                "enum": [
                  "auto",
                  "blue",
                  "cyan",
                  "violet",
                  "green",
                  "amber",
                  "rose",
                  "red"
                ],
                "description": "auto follows the public site's theme; explicit colors stay fixed."
              },
              "badge": {
                "type": "string",
                "maxLength": 300
              }
            }
          },
          "campaignEnabled": {
            "type": "boolean",
            "description": "When true, create or update a campaign DRAFT; it is never sent automatically."
          },
          "campaign": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "channels": {
                "type": "array",
                "minItems": 1,
                "maxItems": 3,
                "items": {
                  "type": "string",
                  "enum": [
                    "email",
                    "whatsapp",
                    "sms"
                  ]
                }
              },
              "audience": {
                "type": "string",
                "enum": [
                  "all",
                  "families",
                  "participants",
                  "custom"
                ],
                "description": "`families`, `participants` and `custom` keep the draft without automatic targeting until the organiser chooses the exact audience."
              },
              "includePoster": {
                "type": "boolean",
                "description": "The image is attached only when a real uploaded poster exists."
              },
              "message": {
                "type": "string",
                "maxLength": 10000
              },
              "schedule": {
                "type": "string",
                "enum": [
                  "now",
                  "later"
                ]
              },
              "scheduledAt": {
                "type": "string",
                "nullable": true,
                "description": "ISO date-time used when the campaign is eventually sent."
              }
            }
          },
          "posterAnalysis": {
            "type": "object",
            "nullable": true,
            "additionalProperties": false,
            "description": "Audit metadata retained when the draft was prepared from a poster.",
            "properties": {
              "confidence": {
                "type": "string",
                "enum": [
                  "high",
                  "medium",
                  "low"
                ]
              },
              "detectedLanguage": {
                "type": "string"
              },
              "sourceSummary": {
                "type": "string"
              },
              "extractedText": {
                "type": "string"
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "analyzedAt": {
                "type": "string"
              }
            }
          },
          "draftStatus": {
            "type": "string",
            "enum": [
              "EDITING",
              "READY"
            ]
          },
          "validatedAt": {
            "type": "string",
            "nullable": true
          },
          "cursorStepId": {
            "type": "string"
          },
          "idempotencyKey": {
            "type": "string",
            "maxLength": 200
          },
          "timeZone": {
            "type": "string"
          }
        },
        "required": [
          "title",
          "destination",
          "mode",
          "idempotencyKey"
        ]
      },
      "AnnualEventCompatibleGroup": {
        "type": "object",
        "additionalProperties": false,
        "description": "An ordinary, single-session group that may receive a newly created event.",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "image": {
            "type": "string",
            "nullable": true
          },
          "mode": {
            "type": "string",
            "enum": [
              "STANDALONE"
            ]
          }
        },
        "required": [
          "id",
          "label",
          "mode"
        ]
      },
      "AnnualEventPosterAnalysisRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "poster": {
            "type": "string",
            "description": "Hosted image filename from `/uploads/image`, or an http(s) URL to re-host first."
          }
        },
        "required": [
          "poster"
        ]
      },
      "AnnualEventPosterAnalysis": {
        "type": "object",
        "description": "A suggested event draft extracted from the poster. Every field remains reviewable before publishing.",
        "properties": {
          "analysis": {
            "type": "object",
            "properties": {
              "detectedLanguage": {
                "type": "string"
              },
              "confidence": {
                "type": "string",
                "enum": [
                  "high",
                  "medium",
                  "low"
                ]
              },
              "sourceSummary": {
                "type": "string"
              },
              "extractedText": {
                "type": "string"
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "event": {
            "type": "object",
            "description": "Raw evidence-based suggestion returned by the poster model. Prefer `draft`, which is already mapped to the canonical creation contract.",
            "additionalProperties": true
          },
          "poster": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string"
              },
              "image": {
                "type": "string"
              }
            }
          },
          "draft": {
            "$ref": "#/components/schemas/AnnualEventDraft"
          }
        }
      },
      "AnnualEventPatch": {
        "type": "object",
        "additionalProperties": false,
        "description": "Complete event recipe. The server normalises this object and materialises all requested resources. Amounts are in major currency units. An `upload` poster is a real image; pass either a hosted filename from `/uploads/image` or an http(s) URL that the server can re-host.",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "description": "Optional project UUID. Omit on create; keep it for updates."
          },
          "version": {
            "type": "integer",
            "minimum": 1,
            "default": 1
          },
          "templateId": {
            "type": "string",
            "description": "Suggested format id, or `custom`."
          },
          "destination": {
            "$ref": "#/components/schemas/AnnualEventDestination"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "title": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500
          },
          "sourceLanguage": {
            "type": "string",
            "description": "Language of the supplied content; defaults to the organisation language. Multilingual organisations receive automatic content translations at creation."
          },
          "currency": {
            "type": "string",
            "readOnly": true,
            "description": "Primary currency resolved by the server from the organisation."
          },
          "tagline": {
            "type": "string",
            "maxLength": 2000
          },
          "description": {
            "type": "string",
            "maxLength": 20000
          },
          "mode": {
            "type": "string",
            "enum": [
              "registration",
              "fundraising",
              "both",
              "information"
            ]
          },
          "attendeeMode": {
            "type": "string",
            "enum": [
              "individual",
              "group",
              "family",
              "children"
            ]
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Required except for a date-optional standalone fundraiser."
          },
          "dateOptional": {
            "type": "boolean"
          },
          "startTime": {
            "type": "string",
            "pattern": "^[0-2][0-9]:[0-5][0-9]$"
          },
          "endTime": {
            "type": "string",
            "pattern": "^[0-2][0-9]:[0-5][0-9]$"
          },
          "locationMode": {
            "type": "string",
            "enum": [
              "onsite",
              "online"
            ]
          },
          "locationName": {
            "type": "string",
            "maxLength": 500
          },
          "address": {
            "type": "string",
            "maxLength": 1000
          },
          "onlineUrl": {
            "type": "string",
            "format": "uri"
          },
          "cadence": {
            "type": "string",
            "enum": [
              "once",
              "weekly",
              "monthly",
              "custom"
            ]
          },
          "recurrenceCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          },
          "customDates": {
            "type": "array",
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "date"
            },
            "description": "All session dates when cadence=custom. The first date and count are derived from this list."
          },
          "excludedDates": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "string",
              "format": "date"
            }
          },
          "slotDuration": {
            "type": "integer",
            "minimum": 0
          },
          "slotCapacity": {
            "type": "integer",
            "minimum": 0
          },
          "capacityEnabled": {
            "type": "boolean"
          },
          "capacity": {
            "type": "integer",
            "minimum": 0
          },
          "priceMode": {
            "type": "string",
            "enum": [
              "free",
              "fixed",
              "multiple",
              "freeAmount"
            ]
          },
          "price": {
            "type": "number",
            "minimum": 0
          },
          "prices": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "minimum": 0
            },
            "description": "Optional prices keyed by enabled secondary currency (lowercase ISO code). Missing values keep the primary numeric price without conversion."
          },
          "tariffs": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/AnnualEventTariff"
            }
          },
          "target": {
            "type": "number",
            "minimum": 0
          },
          "partialPayments": {
            "type": "boolean"
          },
          "depositAmount": {
            "type": "number",
            "minimum": 0
          },
          "contributionAmounts": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "number",
              "minimum": 0
            }
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "firstName",
                "lastName",
                "email",
                "phone",
                "address",
                "birthDate"
              ]
            }
          },
          "children": {
            "type": "boolean"
          },
          "questions": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/AnnualEventQuestion"
            }
          },
          "requirementsEnabled": {
            "type": "boolean"
          },
          "requirements": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/AnnualEventRequirement"
            }
          },
          "manualValidation": {
            "type": "boolean"
          },
          "confirmationText": {
            "type": "string",
            "maxLength": 5000
          },
          "reminders": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "confirmation": {
                "type": "boolean"
              },
              "weekBefore": {
                "type": "boolean"
              },
              "dayBefore": {
                "type": "boolean"
              }
            }
          },
          "page": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "layout": {
                "type": "string",
                "enum": [
                  "essential",
                  "story",
                  "campaign"
                ]
              },
              "ctaLabel": {
                "type": "string",
                "maxLength": 300
              },
              "showDescription": {
                "type": "boolean"
              },
              "showPracticalInfo": {
                "type": "boolean"
              },
              "showOrganizer": {
                "type": "boolean"
              },
              "showProgress": {
                "type": "boolean"
              },
              "customContent": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": [
                      "faq",
                      "pricing",
                      "programme",
                      "speakers",
                      "free"
                    ]
                  },
                  "aiContentBlockId": {
                    "type": "string",
                    "nullable": true,
                    "description": "Existing AI content-block id. Manage its HTML through `/content-blocks`."
                  }
                }
              }
            }
          },
          "poster": {
            "type": "object",
            "additionalProperties": false,
            "description": "A poster exists only when `source=upload` and `image` references a real image.",
            "properties": {
              "source": {
                "type": "string",
                "enum": [
                  "none",
                  "upload"
                ]
              },
              "image": {
                "type": "string",
                "nullable": true,
                "description": "Hosted filename or http(s) image URL."
              },
              "tone": {
                "type": "string",
                "enum": [
                  "auto",
                  "blue",
                  "cyan",
                  "violet",
                  "green",
                  "amber",
                  "rose",
                  "red"
                ],
                "description": "auto follows the public site's theme; explicit colors stay fixed."
              },
              "badge": {
                "type": "string",
                "maxLength": 300
              }
            }
          },
          "campaignEnabled": {
            "type": "boolean",
            "description": "When true, create or update a campaign DRAFT; it is never sent automatically."
          },
          "campaign": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "channels": {
                "type": "array",
                "minItems": 1,
                "maxItems": 3,
                "items": {
                  "type": "string",
                  "enum": [
                    "email",
                    "whatsapp",
                    "sms"
                  ]
                }
              },
              "audience": {
                "type": "string",
                "enum": [
                  "all",
                  "families",
                  "participants",
                  "custom"
                ],
                "description": "`families`, `participants` and `custom` keep the draft without automatic targeting until the organiser chooses the exact audience."
              },
              "includePoster": {
                "type": "boolean",
                "description": "The image is attached only when a real uploaded poster exists."
              },
              "message": {
                "type": "string",
                "maxLength": 10000
              },
              "schedule": {
                "type": "string",
                "enum": [
                  "now",
                  "later"
                ]
              },
              "scheduledAt": {
                "type": "string",
                "nullable": true,
                "description": "ISO date-time used when the campaign is eventually sent."
              }
            }
          },
          "posterAnalysis": {
            "type": "object",
            "nullable": true,
            "additionalProperties": false,
            "description": "Audit metadata retained when the draft was prepared from a poster.",
            "properties": {
              "confidence": {
                "type": "string",
                "enum": [
                  "high",
                  "medium",
                  "low"
                ]
              },
              "detectedLanguage": {
                "type": "string"
              },
              "sourceSummary": {
                "type": "string"
              },
              "extractedText": {
                "type": "string"
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "analyzedAt": {
                "type": "string"
              }
            }
          },
          "draftStatus": {
            "type": "string",
            "enum": [
              "EDITING",
              "READY"
            ]
          },
          "validatedAt": {
            "type": "string",
            "nullable": true
          },
          "cursorStepId": {
            "type": "string"
          }
        },
        "required": []
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
