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

# Post v1agents test conversations



## OpenAPI

````yaml /api-reference/openapi.json post /v1/agents/{id}/test-conversations
openapi: 3.1.0
info:
  title: Aide API
  version: '1'
  description: >-
    Aide's public API. The dashboard, personal access tokens and the MCP server
    all use these endpoints.


    **Authentication.** `Authorization: Bearer oat_…` (a teammate's access
    token) or `Authorization: Bearer aide_live_…` (a workspace API key, created
    by an owner or admin under Settings > Developers). Either is bound to one
    account; every resource is scoped to it, and another account's id answers
    404.


    **API keys** act as the workspace, not as a teammate. Operations that list
    `apiKey` under security accept them; everything else (the session, `me`,
    members, teams, billing, conversations, saved views, notifications, helpdesk
    and widget settings, and API keys themselves) answers 403
    `api_key_not_allowed`. A key with only the `read` scope gets 403
    `insufficient_scope` on writes (every method but `GET`, except `POST
    /v1/knowledge/search`, which only reads). A revoked, expired or unknown key
    answers 401 `invalid_api_key`. Requests are rate limited per key.


    **Webhooks.** Each delivery is a `POST` of the event JSON with
    `Aide-Event-Id`, `Aide-Event-Type`, `Aide-Delivery-Attempt` and
    `Aide-Signature: t=<unix seconds>,v1=<hex>`. `v1` is the HMAC-SHA256 of
    `${t}.${raw body}` keyed with the endpoint secret (`whsec_…`, the whole
    string). For 24 h after a rotation a second `v1`, signed with the previous
    secret, is included; accept the request if any `v1` matches and `t` is
    within 5 minutes. Answer 2xx within 10 s; anything else is retried with
    exponential backoff (8 attempts over about 4 h). An endpoint is disabled
    after 25 failed attempts in a row with no success for 24 h. Deduplicate on
    the event id.


    **Responses.** Successful bodies are wrapped as `{ data }`. Page-numbered
    lists add `metadata`: `total` (exact up to 10,000, then 10,000 with
    `totalIsCapped: true`), `totalIsCapped`, `perPage`, `currentPage`,
    `lastPage` and `hasMore`. `page` runs from 1 to 500, and a page that starts
    past the first 10,000 rows answers 422 `page_too_deep`. `GET
    /v1/conversations` also takes a `cursor` (not with `page`): its
    `metadata.nextCursor` pages on in the same sort without counting, and a
    cursor page has null `total`, `currentPage` and `lastPage`. Message threads
    page with `before` and `meta.nextCursor`.


    **Errors.** Every error is `{ error: { type, code, message, requestId,
    fields? } }`. Validation failures are 422 with one entry per field in
    `fields`.


    **Rate limits.** Throttled routes return `X-RateLimit-Limit` and
    `X-RateLimit-Remaining`; a 429 adds `Retry-After` and `X-RateLimit-Reset`.
servers:
  - url: https://app-api.aide.app
    description: Aide API
security: []
tags:
  - name: Account
  - name: Agent
  - name: AgentEntryPoint
  - name: AgentLinks
  - name: AgentPanelEvent
  - name: AgentPanelSessions
  - name: AgentTestConversation
  - name: Analytics
  - name: ApiKey
  - name: Attachment
  - name: Auth
  - name: Billing
  - name: ChannelActivity
  - name: ChannelConfiguration
  - name: ChannelSettings
  - name: ConnectedApp
  - name: ContactSync
  - name: Conversation
  - name: ConversationAi
  - name: ConversationCustomerContext
  - name: ConversationDraft
  - name: ConversationMacro
  - name: ConversationOrder
  - name: CustomField
  - name: EmailMailbox
  - name: EmailPreferences
  - name: GoogleSessions
  - name: HelpdeskSetting
  - name: Integration
  - name: IntegrationAiAgentRule
  - name: IntegrationSidebar
  - name: Invitation
  - name: KnowledgeCollection
  - name: KnowledgeDocument
  - name: KnowledgeEntity
  - name: KnowledgeSource
  - name: Macro
  - name: Me
  - name: Member
  - name: MessageFeedback
  - name: MessageSender
  - name: Notification
  - name: NotificationChannel
  - name: OauthAuthorization
  - name: Order
  - name: OrderAction
  - name: Plan
  - name: PolicyQuestion
  - name: Product
  - name: ProductPairing
  - name: Proposal
  - name: ReplyTemplate
  - name: RoutingRule
  - name: SavedView
  - name: Scenario
  - name: ScenarioBackfill
  - name: Schedule
  - name: SenderClassification
  - name: SenderRule
  - name: ShopifyStaffLinks
  - name: SlaPolicy
  - name: Team
  - name: Topic
  - name: TopicSuggestion
  - name: WebhookEndpoint
  - name: Widgets
paths:
  /v1/agents/{id}/test-conversations:
    post:
      tags:
        - AgentTestConversation
      operationId: agent_test_conversation.store
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  minLength: 1
                  maxLength: 20000
                customer:
                  type: object
                  properties:
                    name:
                      type: string
                      maxLength: 120
                    email:
                      type: string
                      format: email
                      maxLength: 254
                    attributes:
                      type: object
                      additionalProperties:
                        type: string
                        maxLength: 1000
                      maxProperties: 50
                  required: []
                  additionalProperties: false
              required:
                - text
      responses:
        '201':
          description: Created
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentTestConversation'
                required:
                  - data
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Error'
      security:
        - accessToken: []
components:
  headers:
    X-RateLimit-Limit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    Retry-After:
      description: Seconds until the window resets.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: When the window resets.
      schema:
        type: string
        format: date-time
  schemas:
    AgentTestConversation:
      type: object
      properties:
        object:
          type: string
          const: agent_test_conversation
        createdAt:
          type:
            - string
            - 'null'
        id:
          type: string
        agentId:
          type: string
        message:
          $ref: '#/components/schemas/ConversationMessage'
      required:
        - object
        - createdAt
        - id
        - agentId
        - message
    ConversationMessage:
      type: object
      properties:
        object:
          type: string
          const: message
        topics:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              id:
                type: string
              emoji:
                type:
                  - string
                  - 'null'
              description:
                type:
                  - string
                  - 'null'
              confidence:
                type:
                  - number
                  - 'null'
              example:
                type:
                  - object
                  - 'null'
                properties:
                  id:
                    type: string
                  isPositive:
                    type: boolean
                required:
                  - id
                  - isPositive
            required:
              - name
              - id
              - emoji
              - description
              - confidence
              - example
        attachments:
          type: array
          items:
            type: object
            properties:
              unavailable:
                type:
                  - string
                  - 'null'
                enum:
                  - blocked
                  - download_failed
                  - gone
                  - too_large
                  - unsupported
                  - null
              url:
                type:
                  - string
                  - 'null'
              name:
                type: string
              id:
                type: string
              kind:
                type: string
                enum:
                  - audio
                  - contact
                  - file
                  - image
                  - location
                  - sticker
                  - video
              size:
                type: number
              thumbnailUrl:
                type:
                  - string
                  - 'null'
              inline:
                type: boolean
              mime:
                type: string
            required:
              - unavailable
              - url
              - name
              - id
              - kind
              - size
              - thumbnailUrl
              - inline
              - mime
        createdAt:
          type:
            - string
            - 'null'
        id:
          type: string
        from:
          type:
            - object
            - 'null'
          properties:
            name:
              type:
                - string
                - 'null'
            address:
              type:
                - string
                - 'null'
          required:
            - name
            - address
        billing:
          type:
            - object
            - 'null'
          properties:
            category:
              type:
                - string
                - 'null'
            billable:
              type:
                - boolean
                - 'null'
            pricingModel:
              type:
                - string
                - 'null'
          required:
            - category
            - billable
            - pricingModel
        kind:
          type: string
        to:
          type:
            - object
            - 'null'
          properties:
            name:
              type:
                - string
                - 'null'
            address:
              type:
                - string
                - 'null'
          required:
            - name
            - address
        body:
          type:
            - string
            - 'null'
        blocks:
          type:
            - array
            - 'null'
          items:
            anyOf:
              - type: object
                properties:
                  kind:
                    type: string
                    const: resolution_check
                  answered:
                    type: string
                    enum:
                      - not_yet
                      - solved
                required:
                  - kind
              - type: object
                properties:
                  kind:
                    type: string
                    const: status_line
                  steps:
                    type: array
                    items:
                      type: string
                  done:
                    type: string
                  stepKeys:
                    type: array
                    items:
                      type: string
                      enum:
                        - articles
                        - articlesAndProducts
                        - order
                        - orderCards
                        - productCards
                        - products
                        - reading
                        - revising
                        - searching
                        - updatingOrder
                        - verifying
                        - writing
                required:
                  - kind
                  - steps
              - type: object
                properties:
                  kind:
                    type: string
                    const: text
                  text:
                    type: string
                  html:
                    type: string
                required:
                  - kind
                  - text
                  - html
              - type: object
                properties:
                  kind:
                    type: string
                    const: citation_row
                  sources:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                        title:
                          type: string
                        snippet:
                          type: string
                      required:
                        - url
                        - title
                        - snippet
                required:
                  - kind
                  - sources
              - type: object
                properties:
                  kind:
                    type: string
                    const: feedback_card
                  rating:
                    type: number
                    enum:
                      - 1
                      - 2
                      - 3
                      - 4
                      - 5
                required:
                  - kind
              - type: object
                properties:
                  kind:
                    type: string
                    const: order_card
                  order:
                    type: object
                    properties:
                      name:
                        type: string
                      total:
                        type: string
                      placedOn:
                        type: string
                      fulfillmentStatus:
                        type: string
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            title:
                              type: string
                            price:
                              type: string
                            quantity:
                              type: number
                            imageUrl:
                              type: string
                            variant:
                              type: string
                            unitPrice:
                              type: object
                              properties:
                                currency:
                                  type: string
                                amount:
                                  type: string
                              required:
                                - currency
                                - amount
                          required:
                            - title
                            - price
                            - quantity
                      status:
                        type: string
                        enum:
                          - cancelled
                          - delivered
                          - fulfilled
                          - partial
                          - unfulfilled
                      carrier:
                        type: string
                      financialStatus:
                        type: string
                      placedAt:
                        type: string
                      deliveryEstimate:
                        type: string
                      totalPrice:
                        type: object
                        properties:
                          currency:
                            type: string
                          amount:
                            type: string
                        required:
                          - currency
                          - amount
                      trackingUrl:
                        type: string
                    required:
                      - name
                      - total
                      - placedOn
                      - fulfillmentStatus
                      - items
                required:
                  - kind
                  - order
              - type: object
                properties:
                  kind:
                    type: string
                    const: product_carousel
                  products:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                        id:
                          type: string
                        title:
                          type: string
                        price:
                          type: string
                        variants:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              inStock:
                                type: boolean
                              id:
                                type: string
                              imageUrl:
                                type: string
                              options:
                                type: array
                                items:
                                  type: string
                              price:
                                type: string
                              compareAt:
                                type: string
                            required:
                              - label
                              - inStock
                        rating:
                          type: number
                        imageUrl:
                          type: string
                        options:
                          type: array
                          items:
                            type: object
                            properties:
                              values:
                                type: array
                                items:
                                  type: string
                              name:
                                type: string
                            required:
                              - values
                              - name
                        reviewCount:
                          type: number
                        priceFrom:
                          type: boolean
                        compareAt:
                          type: string
                        why:
                          type: string
                        pairs:
                          type: array
                          items:
                            type: object
                            properties:
                              url:
                                type: string
                              id:
                                type: string
                              title:
                                type: string
                              price:
                                type: string
                              variants:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    label:
                                      type: string
                                    inStock:
                                      type: boolean
                                    id:
                                      type: string
                                  required:
                                    - label
                                    - inStock
                              imageUrl:
                                type: string
                              priceFrom:
                                type: boolean
                            required:
                              - url
                              - id
                              - title
                              - price
                              - variants
                      required:
                        - url
                        - id
                        - title
                        - price
                        - variants
                required:
                  - kind
                  - products
              - type: object
                properties:
                  kind:
                    type: string
                    const: quick_replies
                  options:
                    type: array
                    items:
                      type: string
                  selected:
                    type: string
                required:
                  - kind
                  - options
              - type: object
                properties:
                  url:
                    type: string
                  kind:
                    type: string
                    const: return_link
                required:
                  - url
                  - kind
              - type: object
                properties:
                  kind:
                    type: string
                    const: tracking_card
                  tracking:
                    type: object
                    properties:
                      number:
                        type: string
                      url:
                        type: string
                      events:
                        type: array
                        items:
                          type: object
                          properties:
                            done:
                              type: boolean
                            label:
                              type: string
                            at:
                              type: string
                            detail:
                              type: string
                          required:
                            - done
                            - label
                      eta:
                        type: string
                      order:
                        type: string
                      carrier:
                        type: string
                    required:
                      - number
                      - url
                      - events
                      - eta
                      - order
                      - carrier
                required:
                  - kind
                  - tracking
        htmlBody:
          type:
            - string
            - 'null'
        knowledge:
          type: array
          items:
            type: object
            properties:
              url:
                type:
                  - string
                  - 'null'
              title:
                type:
                  - string
                  - 'null'
              feedback:
                type:
                  - boolean
                  - 'null'
              snippet:
                type: string
              documentId:
                type: string
              score:
                type:
                  - number
                  - 'null'
              sourceName:
                type:
                  - string
                  - 'null'
            required:
              - url
              - title
              - feedback
              - snippet
              - documentId
              - score
              - sourceName
        author:
          type:
            - object
            - 'null'
          properties:
            name:
              type: string
            id:
              type: string
            avatarUrl:
              type:
                - string
                - 'null'
            initials:
              type: string
          required:
            - name
            - id
            - avatarUrl
            - initials
        sender:
          type:
            - object
            - 'null'
          properties:
            reason:
              type:
                - string
                - 'null'
              enum:
                - auto_reply
                - automated_notice
                - bulk
                - calendar_invite
                - helpdesk_autoresponder
                - no_reply_sender
                - notification_sender
                - null
            outcome:
              type: string
              enum:
                - automated
                - customer
                - form_submission
                - ignore
                - transcript
            ruleId:
              type:
                - string
                - 'null'
            decidedBy:
              type: string
              enum:
                - default
                - detector
                - person
                - rule
            ruleName:
              type:
                - string
                - 'null'
            relayedBy:
              type:
                - object
                - 'null'
              properties:
                name:
                  type:
                    - string
                    - 'null'
                address:
                  type:
                    - string
                    - 'null'
              required:
                - name
                - address
          required:
            - reason
            - outcome
            - ruleId
            - decidedBy
            - ruleName
            - relayedBy
        reactions:
          type: array
          items:
            type: object
            properties:
              at:
                type: string
              emoji:
                type: string
              by:
                type: string
            required:
              - at
              - emoji
              - by
        suggestedTopic:
          type:
            - object
            - 'null'
          properties:
            name:
              type: string
            id:
              type: string
            description:
              type: string
            groupName:
              type:
                - string
                - 'null'
            messageCount:
              type: number
          required:
            - name
            - id
            - description
            - groupName
            - messageCount
        authoredBy:
          type: string
          enum:
            - aide
            - customer
            - human_agent
            - system
        public:
          type: boolean
        rendered:
          type:
            - array
            - 'null'
          items:
            anyOf:
              - type: object
                properties:
                  kind:
                    type: string
                    const: rich
                  payload:
                    type: object
                    additionalProperties:
                      anyOf:
                        - type: boolean
                        - type: number
                        - type: object
                        - type: string
                        - type: 'null'
                  element:
                    type: string
                    enum:
                      - cards
                      - csat
                      - offer_choice
                      - quick_replies
                      - resolution_check
                      - share_contact
                required:
                  - kind
                  - payload
                  - element
              - type: object
                properties:
                  kind:
                    type: string
                    const: text
                  text:
                    type: string
                required:
                  - kind
                  - text
        interaction:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
            kind:
              type: string
              enum:
                - button_reply
                - feedback
                - list_reply
                - postback
                - quick_reply
            payload:
              anyOf:
                - type: object
                  properties:
                    kind:
                      type: string
                      const: offer_choice
                    offerId:
                      type: string
                    choice:
                      type: string
                      enum:
                        - accept
                        - decline
                  required:
                    - kind
                    - offerId
                    - choice
                - type: object
                  properties:
                    kind:
                      type: string
                      const: resolution
                    choice:
                      type: string
                      enum:
                        - not_yet
                        - solved
                  required:
                    - kind
                    - choice
                - type: object
                  properties:
                    kind:
                      type: string
                      const: csat
                    choice:
                      type: number
                      enum:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                  required:
                    - kind
                    - choice
                - type: object
                  properties:
                    kind:
                      type: string
                      const: quick_reply
                    choice:
                      type: number
                  required:
                    - kind
                    - choice
                - type: object
                  properties:
                    kind:
                      type: string
                      const: handoff
                  required:
                    - kind
                - type: 'null'
            comment:
              type: string
          required:
            - id
            - kind
            - payload
        delivery:
          type:
            - object
            - 'null'
          properties:
            status:
              type: string
              enum:
                - delivered
                - failed
                - queued
                - read
                - sent
            failedReason:
              type:
                - string
                - 'null'
              enum:
                - capability
                - control_lost
                - disconnected
                - forbidden
                - invalid
                - merged
                - no_mailbox
                - no_recipient
                - no_sender
                - not_found
                - not_in_control
                - not_in_plan
                - not_queued
                - outcome_unknown
                - paused
                - permission_missing
                - rate_limited
                - reconnect_required
                - rejected
                - sending_limit
                - shadow
                - superseded
                - token_invalid
                - transient
                - unauthorized
                - unavailable
                - undeliverable
                - user_unavailable
                - window_closed
                - null
          required:
            - status
            - failedReason
      required:
        - object
        - topics
        - attachments
        - createdAt
        - id
        - from
        - billing
        - kind
        - to
        - body
        - blocks
        - htmlBody
        - knowledge
        - author
        - sender
        - reactions
        - suggestedTopic
        - authoredBy
        - public
        - rendered
        - interaction
        - delivery
    Error:
      type: object
      description: Every error response, whatever the status (app/exceptions/handler.ts).
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - api_error
                - authentication_error
                - invalid_request_error
                - permission_error
                - rate_limit_error
            code:
              type: string
              description: Stable, machine-readable error code.
            message:
              type: string
            requestId:
              type: string
            fields:
              type: array
              description: Per-field problems, on validation errors.
              items:
                type: object
                properties:
                  field:
                    type: string
                  code:
                    type: string
                  message:
                    type: string
                required:
                  - field
                  - code
                  - message
          required:
            - type
            - code
            - message
            - requestId
      required:
        - error
  responses:
    Unauthenticated:
      description: Missing or invalid credentials (`authentication_error`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The credential may not do this (`permission_error`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such resource for this credential (`not_found`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationFailed:
      description: The request has invalid fields (`validation_failed`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limited (`too_many_requests`).
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error:
      description: Any other error, in the same envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    accessToken:
      type: http
      scheme: bearer
      bearerFormat: oat_…
      description: An access token, bound to one account.

````

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