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

# Generate an Agent

> Create an inbound agent and its first flow from a prompt.

Starts asynchronous generation of a new inbound agent and its first flow from a natural-language prompt.

Send a unique `Idempotency-Key` with every logical request. Repeating the same request with the same key returns the existing generation instead of creating another agent. Reusing the key with different request data returns an idempotency conflict.

The initial response includes a `generationId` and a `Location` header. Poll that location until the status is `completed` or `failed`.

<Warning>
  Store the idempotency key until generation reaches a terminal status. Retrying a failed generation with the same request and key safely reuses its reserved agent and flow instead of provisioning duplicates.
</Warning>

## Generation statuses

| Status       | Meaning                                                  |
| ------------ | -------------------------------------------------------- |
| `queued`     | The request was accepted and is waiting to start         |
| `generating` | Phonely is building the agent and first flow             |
| `completed`  | The response includes the new `agentId` and `workflowId` |
| `failed`     | The response includes an error code and message          |

Only users with permission to edit agent design in the selected organization can generate an agent.


## OpenAPI

````yaml POST /agent-generations
openapi: 3.0.1
info:
  title: Phonely API
  description: API for Phonely services including agent management and call summaries
  version: 1.0.0
servers:
  - url: https://app.phonely.ai/api
security: []
paths:
  /agent-generations:
    post:
      summary: Generate an agent from a prompt
      description: >-
        Asynchronously create an inbound agent and its first flow from a
        natural-language prompt. Repeating the same request with the same
        idempotency key returns the existing generation.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            A unique key for this logical generation request. Maximum 128
            characters.
          schema:
            type: string
            minLength: 1
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentGenerationRequest'
      responses:
        '200':
          description: The idempotent request already completed
          headers:
            Location:
              description: Relative URL for checking generation status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentGenerationResponse'
        '202':
          description: The generation is queued or in progress
          headers:
            Location:
              description: Relative URL for checking generation status
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentGenerationResponse'
        '400':
          description: Invalid request or idempotency key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The user cannot create agents in the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The idempotency key was used for different request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Agent generation could not be started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateAgentGenerationRequest:
      type: object
      additionalProperties: false
      required:
        - orgId
        - agentName
        - source
      properties:
        orgId:
          type: string
          minLength: 1
          maxLength: 128
          description: Organization in which to create the agent
        agentName:
          type: string
          minLength: 1
          maxLength: 50
          description: Name for the generated agent
        timezone:
          type: string
          minLength: 1
          maxLength: 64
          example: America/New_York
          description: Valid IANA timezone. Defaults to UTC.
        source:
          $ref: '#/components/schemas/PromptAgentGenerationSource'
    AgentGenerationResponse:
      type: object
      required:
        - generationId
        - status
        - createdAt
        - updatedAt
      properties:
        generationId:
          type: string
          pattern: ^gen_[a-f0-9]{40}$
        status:
          type: string
          enum:
            - queued
            - generating
            - completed
            - failed
        agentId:
          type: string
          description: Generated agent identifier. Present when status is completed.
        workflowId:
          type: string
          description: Generated first-flow identifier. Present when status is completed.
        error:
          $ref: '#/components/schemas/AgentGenerationFailure'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code or identifier
        message:
          type: string
          description: Detailed error message
    PromptAgentGenerationSource:
      type: object
      additionalProperties: false
      required:
        - type
        - prompt
      properties:
        type:
          type: string
          enum:
            - prompt
        prompt:
          type: string
          minLength: 1
          maxLength: 20000
          description: Natural-language instructions for the agent and its first flow
    AgentGenerationFailure:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Authorization

````