> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inbox.adraa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add an agent

> Adds an agent to the workspace. If no Adraa Inbox account exists for the email, one is created — no invite email is sent; the person signs in at the console with a one-time code sent to that email. If an account already exists, it is added to the workspace with the given role (the existing display name is kept).

Members added with role `agent` receive the workspace's default zero-permission "Agent" custom role (own conversations only); an admin can change their role from Settings → Members. Admins are unrestricted.

Rate limit: 30 requests per minute.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/agents
openapi: 3.1.0
info:
  title: Adraa Inbox API
  description: >-
    Public REST API for Adraa Inbox. Assign agents to conversations and send
    messages from your own systems. Authenticate every request with a workspace
    API token.
  version: 1.0.0
  contact:
    email: support@adraa.ai
servers:
  - url: https://api.inbox.adraa.ai
    description: Production
security:
  - apiToken: []
paths:
  /api/v1/agents:
    post:
      summary: Add an agent
      description: >-
        Adds an agent to the workspace. If no Adraa Inbox account exists for the
        email, one is created — no invite email is sent; the person signs in at
        the console with a one-time code sent to that email. If an account
        already exists, it is added to the workspace with the given role (the
        existing display name is kept).


        Members added with role `agent` receive the workspace's default
        zero-permission "Agent" custom role (own conversations only); an admin
        can change their role from Settings → Members. Admins are unrestricted.


        Rate limit: 30 requests per minute.
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: The agent's sign-in email.
                  example: sara@acme.com
                nickname:
                  type: string
                  maxLength: 60
                  description: >-
                    Display name, unique across Adraa Inbox. Generated from the
                    email when omitted. Ignored if the email already has an
                    account.
                  example: sara
                role:
                  type: string
                  enum:
                    - agent
                    - admin
                  default: agent
                  description: >-
                    Workspace role. `agent` members start with the default
                    zero-permission "Agent" custom role (own conversations
                    only).
      responses:
        '201':
          description: Agent added to the workspace
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Email already a member, or display name taken
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                alreadyMember:
                  summary: Email already belongs to a workspace member
                  value:
                    error:
                      code: AGENT_ALREADY_MEMBER
                      message: >-
                        An agent with this email is already a member of the
                        workspace
                nicknameTaken:
                  summary: Display name already in use
                  value:
                    error:
                      code: NICKNAME_TAKEN
                      message: That display name is already in use
components:
  schemas:
    Agent:
      type: object
      properties:
        id:
          type: string
          description: Agent ID — use it for assignment.
          example: cmbxgwq1e0000ph01i0j1k2l3
        email:
          type: string
          format: email
          example: sara@acme.com
        nickname:
          type: string
          description: Display name shown in conversations.
          example: sara
        role:
          type: string
          enum:
            - agent
            - admin
            - ai
          description: Workspace role. The workspace AI identity is reported as `ai`.
          example: agent
        isOnline:
          type: boolean
          example: true
        lastSeen:
          type: string
          format: date-time
          example: '2026-06-12T10:25:00.000Z'
        createdAt:
          type: string
          format: date-time
          example: '2026-05-02T08:14:00.000Z'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable explanation.
            details:
              description: Field-level details for validation errors.
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
  responses:
    Unauthorized:
      description: Missing, invalid, or revoked API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_API_TOKEN
              message: Invalid or revoked API token
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      description: >-
        Workspace API token created in Settings → API. Tokens start with
        `adraa_`.

````