> ## Documentation Index > Fetch the complete documentation index at: https://cactal.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Add a field to a collection > Adds a typed field at the end of the collection’s field order. `key` is lowercase snake_case (max 64 characters), must be unique in the collection, and cannot use the reserved metadata names `id`, `slug`, `publishedAt`, `publishAt`, `createdAt`, `updatedAt`, or `position`; `type` is immutable after creation. `reference` and `multi_reference` fields require a `targetCollectionId` in the same website, and `option` fields require `config.choices` (1–1,000 choices). A collection can hold at most 100 fields, and `required: true` is rejected while the collection has active items — add the field as optional, backfill every item, then mark it required. ## OpenAPI ````yaml /api-reference/openapi.json post /cms/collections/{collectionId}/fields openapi: 3.1.0 info: title: Cactal API version: 1.0.0 description: >- The Cactal public API. Create, edit, publish, and operate websites programmatically. Authenticate every request with an API key sent as `Authorization: Bearer `. servers: - url: https://api.cactal.ai/v1 security: - apiKey: [] tags: - name: Documentation description: >- Search and read the Cactal product documentation for concepts, guides, agent workflows, platform behavior, and API operations. - name: Feedback description: >- Submit free-form product feedback from users and agents to the Cactal feedback inbox. - name: Websites description: >- Create and manage websites — the top-level resource that owns source code, content, assets, domains, and analytics. - name: Website editors description: >- Grant, list, and revoke website-scoped editor access, and invite collaborators to a single website by email. - name: API keys description: >- Create, scope, rotate, and revoke the API keys that authenticate programmatic and agent access. - name: Source code description: >- Read and edit the framework source files of a website draft. Mutations require an edit lease. - name: Publishing description: Validate, build, publish, and roll back website versions. - name: CMS collections description: >- Define the content model: collections of structured content owned by a website. - name: CMS fields description: Manage the typed fields that make up a collection schema. - name: CMS items description: >- Create, query, publish, and organize the content entries inside a collection. - name: Domains description: >- Manage platform subdomains and custom domains, including DNS verification and the primary domain. - name: Assets description: Upload and manage website files and images served from the Cactal CDN. - name: Media generation description: >- Generate reference-guided website images that are stored as ordinary Cactal CDN assets. - name: Project Context description: >- Upload private durable reference material that the website agent can search, read, and inspect. - name: Analytics description: >- Read first-party traffic analytics for a website and export datasets as CSV. - name: Organizations description: Manage organizations, members, and organization-wide invitations. - name: Audit log description: >- Read the immutable record of actions performed in an organization by users and API keys. - name: Billing description: >- Read billing state and manage plans, site capacity, and prepaid usage balance. Every billing operation requires the organization owner role, which API keys cannot hold — today these operations are performed from the dashboard, return 403 for API-key callers, and are hidden from MCP tool lists. paths: /cms/collections/{collectionId}/fields: post: tags: - CMS fields summary: Add a field to a collection description: >- Adds a typed field at the end of the collection’s field order. `key` is lowercase snake_case (max 64 characters), must be unique in the collection, and cannot use the reserved metadata names `id`, `slug`, `publishedAt`, `publishAt`, `createdAt`, `updatedAt`, or `position`; `type` is immutable after creation. `reference` and `multi_reference` fields require a `targetCollectionId` in the same website, and `option` fields require `config.choices` (1–1,000 choices). A collection can hold at most 100 fields, and `required: true` is rejected while the collection has active items — add the field as optional, backfill every item, then mark it required. operationId: cms.fields.create parameters: - name: collectionId in: path required: true schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: type: object properties: key: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ displayName: type: string minLength: 1 maxLength: 200 description: anyOf: - type: string maxLength: 2000 - type: 'null' type: type: string enum: - plain_text - markdown - number - boolean - date - link - email - color - option - reference - multi_reference - image - gallery - file required: type: boolean isUnique: type: boolean example: {} targetCollectionId: type: string minLength: 1 config: type: object properties: choices: minItems: 1 maxItems: 1000 type: array items: type: object properties: id: type: string minLength: 1 maxLength: 100 label: type: string minLength: 1 maxLength: 200 required: - id - label multiple: type: boolean required: - choices required: - key - displayName - type responses: '200': description: The created field. content: application/json: schema: type: object properties: id: type: string description: Unique field id. collectionId: type: string description: Id of the owning collection. key: type: string description: >- JSON key under item `data`. Lowercase snake_case, max 64 characters, unique per collection. Changed only via `key` on the update-field endpoint, which migrates stored data. displayName: type: string description: Human-readable name, 1–200 characters. description: anyOf: - type: string - type: 'null' description: Optional description, up to 2,000 characters. type: type: string enum: - plain_text - markdown - number - boolean - date - link - email - color - option - reference - multi_reference - image - gallery - file description: Value type. Immutable after creation. required: type: boolean description: >- Whether every item must carry a non-null value for this field. Enforced on write. isUnique: type: boolean description: >- Whether values must be unique across the collection’s active items. Not supported for `plain_text`, `markdown`, `multi_reference`, `image`, `gallery`, or `file` fields. position: type: string description: >- Fractional ordering key; fields sort lexicographically by this value. example: description: >- Optional example value used as a design-phase placeholder. Any JSON value; `null` when unset. config: anyOf: - type: object properties: choices: type: array items: type: object properties: id: type: string description: Stable choice id stored as the field value. label: type: string description: Human-readable choice label. required: - id - label additionalProperties: false description: Selectable choices, 1–1,000. multiple: type: boolean description: Whether items may select multiple choices. required: - choices - multiple additionalProperties: false - type: 'null' description: >- Type-specific configuration. Present for `option` fields only; `null` for all other types. targetCollectionId: anyOf: - type: string - type: 'null' description: >- For `reference` and `multi_reference` fields, the id of the collection referenced items must belong to (same website). `null` otherwise. Immutable. required: - id - collectionId - key - displayName - description - type - required - isUnique - position - example - config - targetCollectionId additionalProperties: false '400': description: >- Validation failed. The response `message` names the first invalid field. content: application/json: schema: $ref: '#/components/schemas/ServiceError' '401': description: Missing, invalid, expired, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/ServiceError' '403': description: The authenticated principal lacks the required capability. content: application/json: schema: $ref: '#/components/schemas/ServiceError' '404': description: >- The resource does not exist or is outside the principal’s access scope. content: application/json: schema: $ref: '#/components/schemas/ServiceError' '409': description: The request conflicts with the current state of the resource. content: application/json: schema: $ref: '#/components/schemas/ServiceError' '429': description: >- Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/ServiceError' components: schemas: ServiceError: type: object required: - kind - message description: >- Canonical error body returned by every non-2xx response. Extra fields carry error-specific details. properties: kind: type: string enum: - validation - unauthorized - forbidden - not_found - conflict - rate_limited - internal description: Stable, machine-readable error category. message: type: string description: Human-readable explanation of the failure. suggestion: type: string description: >- What to do next when the failure has a known fix; may name the exact operation to call. validValues: type: array items: type: string description: The acceptable values for the failing field, when the set is closed. additionalProperties: true securitySchemes: apiKey: type: http scheme: bearer description: >- Cactal API key. Create one in the dashboard or via `POST /apiKeys`. The plaintext key is shown once at creation. ````