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

# Propose Agent Draft

> Sends your draft for review. Reviewers (members with `agents:review_drafts`, except you) get a notification and an email (at most one email per draft per hour) and publish it in the dashboard, or send it back. While proposed, the draft does not expire and you can still save to it. Withdraw it with Withdraw Agent Draft.



## OpenAPI

````yaml /api-reference/openapi.json post /v2/voice-agents/{voiceAgentId}/draft/propose
openapi: 3.0.1
info:
  title: Hamsa API
  description: >-
    The Hamsa API: voice agents and their calls, phone numbers, batch calls and
    knowledge bases; speech to text, text to speech, voices and AI content.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v2/voice-agents/{voiceAgentId}/draft/propose:
    post:
      summary: Propose your agent draft
      description: >-
        Sends your draft for review. Reviewers (members with
        `agents:review_drafts`, except you) get a notification and an email (at
        most one email per draft per hour) and publish it in the dashboard, or
        send it back. While proposed, the draft does not expire and you can
        still save to it. Withdraw it with Withdraw Agent Draft.
      parameters:
        - in: path
          name: voiceAgentId
          required: true
          description: ID of the voice agent.
          schema:
            type: string
            format: uuid
            example: fc6f158b-24c2-45a6-957b-c57c0a8979b5
        - in: header
          name: Idempotency-Key
          required: false
          description: >-
            Optional, up to 255 characters. Retry with the same key after a
            network error and you get the first answer back instead of the
            change being made twice (kept 10 minutes). Same key with a different
            body: 422 `IdempotencyKeyReused`. While the first request still
            runs: 409 `IdempotencyKeyInProgress`.
          schema:
            type: string
            maxLength: 255
            example: 0b6f3c1e-retry-1
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                note:
                  type: string
                  maxLength: 500
                  description: A note for the reviewers, up to 500 characters.
                  example: New opening line for Saudi callers.
            examples:
              note:
                summary: With a note
                value:
                  note: New opening line for Saudi callers.
              plain:
                summary: Without a note
                value: {}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/AgentDraftSummary'
        '400':
          description: Invalid request (for example a missing or invalid field).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '401':
          description: 'Unauthorized: missing or invalid API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '403':
          description: Your API key or role does not have the `agents:update` permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '404':
          description: Voice agent not found in this project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '409':
          description: >-
            You have no open draft or it is already proposed (`DraftNotOpen`),
            or it has no changes (`DraftHasNoChanges`). Or: Another request with
            the same `Idempotency-Key` is still running
            (`IdempotencyKeyInProgress`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '422':
          description: >-
            The `Idempotency-Key` was already used with a different body
            (`IdempotencyKeyReused`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVersionError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AgentDraftSummary:
      type: object
      description: A member's draft of the agent.
      properties:
        id:
          type: string
          format: uuid
          description: Draft ID.
          example: 9a4c1e6b-2f3d-4b8a-8e7c-5d1f0a2b3c47
        author:
          $ref: '#/components/schemas/AgentDraftAuthor'
        status:
          type: string
          enum:
            - open
            - proposed
            - published
            - discarded
            - expired
          description: >-
            `open`: being edited by its author. `proposed`: waiting for review.
            `published`: went into a version. `discarded`: thrown away.
            `expired`: left unsaved for 7 days.
          example: open
        baseVersionNumber:
          type: integer
          description: The version the draft started from.
          example: 4
        versionsBehind:
          type: integer
          description: >-
            How many versions the draft is behind the version new drafts start
            from. `0` when it is up to date; update it with `POST
            /draft/rebase`.
          example: 0
        changedPaths:
          type: array
          items:
            type: string
          description: >-
            The settings that differ from the base version, as paths in the
            agent body.
          example:
            - conversation.preamble
            - llm.temperature
        revision:
          type: string
          format: uuid
          description: >-
            The draft's current revision. Send it as `baseRevision` when you
            save, so you don't overwrite a newer save.
          example: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
        proposedAt:
          type: string
          format: date-time
          description: When it was proposed.
          example: '2026-10-28T09:15:00.000Z'
        proposalNote:
          type: string
          description: The note sent with the proposal.
          example: New opening line for Saudi callers.
        lastSentBack:
          type: object
          description: The last time a reviewer sent it back.
          properties:
            by:
              $ref: '#/components/schemas/AgentDraftAuthor'
            note:
              type: string
              example: Please keep the greeting under 10 seconds.
            at:
              type: string
              format: date-time
              example: '2026-10-28T09:15:00.000Z'
        combinedFrom:
          type: array
          description: The proposals a reviewer combined into this draft.
          items:
            type: object
            properties:
              draftId:
                type: string
                format: uuid
                example: 9a4c1e6b-2f3d-4b8a-8e7c-5d1f0a2b3c47
              revision:
                type: string
                format: uuid
                example: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
              author:
                $ref: '#/components/schemas/AgentDraftAuthor'
        expiresAt:
          type: string
          format: date-time
          description: >-
            An open draft expires 7 days after its last save. Not set while
            proposed.
          example: '2026-11-04T09:15:00.000Z'
        publishedAs:
          type: integer
          description: The version number it was published as (`published` only).
          example: 5
        closedBy:
          $ref: '#/components/schemas/AgentDraftAuthor'
          description: Who published or discarded it.
        closedAt:
          type: string
          format: date-time
          example: '2026-10-28T09:15:00.000Z'
        closedNote:
          type: string
          description: The note left when it was discarded.
          example: Covered by the new FAQ flow.
        lastVia:
          $ref: '#/components/schemas/AgentDraftVia'
          description: Where the last save came from.
        proposedVia:
          $ref: '#/components/schemas/AgentDraftVia'
          description: Where the proposal came from.
        updatedAt:
          type: string
          format: date-time
          description: When the author last saved.
          example: '2026-10-28T09:15:00.000Z'
        valueKeys:
          type: array
          items:
            type: string
          description: Names of the draft's test values, sorted. `[]` when none.
          example:
            - ORDER_ID
    AgentVersionError:
      type: object
      properties:
        code:
          type: integer
          description: Service error code (8400, 8403, 8404, 8409, ...).
          example: 8409
        message:
          type: string
          example: >-
            Your draft changed in another tab or through your API key. Reload it
            and try again.
        messageKey:
          type: string
          description: Stable error key.
          example: DraftStaleRevision
        params:
          type: object
          additionalProperties: true
          description: >-
            Details. `reason` names the case (for example `STALE_REVISION`,
            `NO_DRAFT`, `SESSION_ONLY`); `action` names a missing permission
            (for example `agents:deploy`).
          example:
            reason: STALE_REVISION
            revision: e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56
    AgentDraftAuthor:
      type: object
      description: A project member.
      properties:
        id:
          type: string
          format: uuid
          example: b7d9e979-4a16-437b-8571-4ed92a94faa8
        name:
          type: string
          example: Sara Ahmad
        email:
          type: string
          nullable: true
          example: sara@example.com
    AgentDraftVia:
      type: object
      description: Where the change came from.
      properties:
        kind:
          type: string
          enum:
            - dashboard
            - api_key
          example: api_key
        keyRef:
          type: string
          description: The API key's reference (`api_key` only).
          example: sk_live_4f2a
        keyName:
          type: string
          description: The API key's name (`api_key` only).
          example: CRM sync
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.