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

# Poll a pairing

> Poll pairing state with the pairing's `poll_token` as the bearer credential. With `wait=true` the request holds open (≤30 s) and returns as soon as the pairing is claimed. After a claim, the computer receives the minted Agent Token. A lost response is recoverable: the same poll credential receives the same token until its first successful Agent API use or ten minutes after first delivery. Then Relay scrubs the recovery copy and returns `410`. An expired unclaimed pairing returns `404`. A newer concurrent poll terminates the older one with `409 terminated_by_other_consumer`.




## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/pairings/{pairing_id}
openapi: 3.1.0
info:
  title: Relay developer API
  version: '0.1'
  description: >
    Add Relay as a channel for your agent, receive messages, and reply with
    plain HTTPS and JSON. Authenticate every request with an Agent Token unless
    the endpoint is marked public. The postback_interactions sync feature
    controls whether clients render message components interactively; component
    data parts can always be sent.
  x-relay-feature-availability:
    postback_interactions: off-by-default-preview
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.relayapp.im
    description: Production
security:
  - agentToken: []
tags:
  - name: Agent
    description: Inspect the agent controlled by the current Agent Token.
  - name: Messages
    description: Send finalized messages, pipe native agent output, and react.
  - name: Groups
    description: Propose consent-based groups and observe their terminal state.
  - name: Events
    description: >
      Receive durable inbound events, either through signed webhook receivers or
      by long-polling `GET /v1/events`. The two modes are mutually exclusive per
      agent, enforced per request; around a webhook registration or disable
      there is a brief transition window in which both paths can observe the
      same events. Delivery is at least once everywhere — always deduplicate by
      `event_id`.
  - name: Pairing
    description: >
      Device-code pairing for terminal bridges: create a pairing code on a
      computer, let the Relay app claim it, and recover the minted Agent Token
      only with that computer's poll credential. The token never travels to the
      phone.
  - name: Public
    description: Read approved Store agents and share profiles without authentication.
paths:
  /v1/pairings/{pairing_id}:
    get:
      tags:
        - Pairing
      summary: Poll a pairing
      description: >
        Poll pairing state with the pairing's `poll_token` as the bearer
        credential. With `wait=true` the request holds open (≤30 s) and returns
        as soon as the pairing is claimed. After a claim, the computer receives
        the minted Agent Token. A lost response is recoverable: the same poll
        credential receives the same token until its first successful Agent API
        use or ten minutes after first delivery. Then Relay scrubs the recovery
        copy and returns `410`. An expired unclaimed pairing returns `404`. A
        newer concurrent poll terminates the older one with `409
        terminated_by_other_consumer`.
      operationId: pollPairing
      parameters:
        - name: pairing_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^pair_
        - name: wait
          in: query
          schema:
            type: boolean
            default: false
          description: Hold the request open until claimed or ~25 s pass.
      responses:
        '200':
          description: Current pairing state.
          content:
            application/json:
              schema:
                oneOf:
                  - title: Pending
                    type: object
                    additionalProperties: false
                    required:
                      - status
                    properties:
                      status:
                        type: string
                        const: pending
                  - title: Claimed
                    type: object
                    additionalProperties: false
                    required:
                      - status
                      - agent_token
                      - agent
                    properties:
                      status:
                        type: string
                        const: claimed
                      agent_token:
                        type: string
                        pattern: ^rly_live_
                        description: >-
                          Recoverably re-delivered only during the bounded
                          delivery window; store it now.
                      agent:
                        $ref: '#/components/schemas/AgentProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown pairing, or the code expired before it was claimed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: A newer pairing poll took over this request's consumer slot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: >-
            The Agent Token was used, revoked, or aged out of its
            delivery-recovery window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The wait query parameter is not exactly true or false.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many concurrent/long-lived pairing polls from this address.
          headers:
            Retry-After:
              description: Whole seconds before another long poll.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/PairingDeliveryUnavailable'
      security:
        - pollToken: []
components:
  schemas:
    AgentProfile:
      type: object
      additionalProperties: false
      required:
        - id
        - handle
        - display_name
        - tagline
        - avatar_url
        - visibility
        - owner_user_id
        - created_at
      properties:
        id:
          type: string
          example: agt_01JZRELAY
        handle:
          type: string
          example: scheduler
        display_name:
          type: string
          example: Scheduler
        tagline:
          type: string
          example: Finds a time that works
        avatar_url:
          type:
            - string
            - 'null'
          format: uri
          maxLength: 2048
          pattern: ^https://(?![^/?#]*@)
        visibility:
          type: string
          enum:
            - private
            - unlisted
            - public
        owner_user_id:
          type:
            - string
            - 'null'
          description: >
            The user who created and owns this agent. Gate inbound senders
            against this id instead of trusting the first sender seen. Null only
            for Relay system agents or after the owner deleted their account.
          example: usr_01JZU1F0BD
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: invalid_request
            message:
              type: string
              example: conversation_id is required
  responses:
    Unauthorized:
      description: Token is absent or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PairingDeliveryUnavailable:
      description: >-
        Relay's pairing-token encryption service is temporarily unavailable;
        retry safely.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    agentToken:
      type: http
      scheme: bearer
      description: Agent Token (`rly_live_…`), shown once at agent creation.
    pollToken:
      type: http
      scheme: bearer
      description: >
        Pairing poll token (`rlyp_…`) from `POST /v1/pairings`. Authorizes only
        polling that pairing, never the platform API.

````