> ## 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 website editor by email

> Gives an email address `full` or `content` editor access to this single website. When the email already belongs to an account, the grant is created immediately (`granted`) — or nothing changes if that account already inherits access through its organization role (`already_inherited`). Otherwise a `pending` invitation is created and emailed; it expires after 48 hours unless you set `expiresAt`. Re-adding an email with a pending invitation refreshes that invitation instead of creating a duplicate. Change an existing editor’s role with `websites.editors.setRole`.



## OpenAPI

````yaml /api-reference/openapi.json post /websites/{websiteId}/editors
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 <key>`.
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:
  /websites/{websiteId}/editors:
    post:
      tags:
        - Website editors
      summary: Add a website editor by email
      description: >-
        Gives an email address `full` or `content` editor access to this single
        website. When the email already belongs to an account, the grant is
        created immediately (`granted`) — or nothing changes if that account
        already inherits access through its organization role
        (`already_inherited`). Otherwise a `pending` invitation is created and
        emailed; it expires after 48 hours unless you set `expiresAt`. Re-adding
        an email with a pending invitation refreshes that invitation instead of
        creating a duplicate. Change an existing editor’s role with
        `websites.editors.setRole`.
      operationId: websites.editors.add
      parameters:
        - name: websiteId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  pattern: >-
                    ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                role:
                  type: string
                  enum:
                    - full
                    - content
                expiresAt:
                  anyOf:
                    - {}
                    - type: string
                      format: date-time
                      pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                callbackUrl:
                  type: string
                  format: uri
              required:
                - email
                - role
      responses:
        '200':
          description: >-
            The immediate grant, the already-covered principal, or the pending
            invitation.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      status:
                        type: string
                        const: granted
                        description: >-
                          The email belongs to an existing account; the editor
                          grant was created immediately.
                      grant:
                        type: object
                        properties:
                          websiteId:
                            type: string
                            description: Id of the website the grant applies to.
                          principalId:
                            type: string
                            description: Id of the principal holding the grant.
                          role:
                            type: string
                            enum:
                              - full
                              - content
                            description: >-
                              `full` allows full website editing; `content`
                              allows content editing only.
                          createdAt:
                            description: When the grant was created.
                            type: string
                            format: date-time
                        required:
                          - websiteId
                          - principalId
                          - role
                          - createdAt
                        additionalProperties: false
                    required:
                      - status
                      - grant
                    additionalProperties: false
                  - type: object
                    properties:
                      status:
                        type: string
                        const: already_inherited
                        description: >-
                          The account already inherits website access through
                          its organization role; nothing changed.
                      principalId:
                        type: string
                        description: Id of the principal that already has access.
                    required:
                      - status
                      - principalId
                    additionalProperties: false
                  - type: object
                    properties:
                      status:
                        type: string
                        const: pending
                        description: >-
                          No account exists for the email; a pending invitation
                          was created and emailed.
                      invitation:
                        type: object
                        properties:
                          id:
                            type: string
                            description: Unique invitation id.
                          email:
                            type: string
                            description: Invited email address, normalized to lowercase.
                          role:
                            type: string
                            enum:
                              - full
                              - content
                            description: >-
                              Editor role granted when the invitation is
                              accepted.
                          status:
                            type: string
                            enum:
                              - pending
                              - accepted
                              - canceled
                            description: Lifecycle status of the invitation.
                          expiresAt:
                            description: When the invitation can no longer be accepted.
                            type: string
                            format: date-time
                          createdAt:
                            description: When the invitation was created.
                            type: string
                            format: date-time
                        required:
                          - id
                          - email
                          - role
                          - status
                          - expiresAt
                          - createdAt
                        additionalProperties: false
                    required:
                      - status
                      - invitation
                    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'
        '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.

````