> ## 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. # Claim a pairing > App-internal authenticated claim. Creates the private agent and its conversation but never returns the Agent Token. Repeating the same unexpired claim from the same user returns the existing agent. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/pairings/{code}/claim 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/{code}/claim: post: tags: - Pairing summary: Claim a pairing description: > App-internal authenticated claim. Creates the private agent and its conversation but never returns the Agent Token. Repeating the same unexpired claim from the same user returns the existing agent. operationId: claimPairing parameters: - name: code in: path required: true schema: type: string pattern: ^[A-Za-z]+-[A-Za-z]+-[A-Za-z]+-[0-9]{4}$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PairingClaimInput' responses: '200': description: Idempotent replay by the user who already claimed this pairing. content: application/json: schema: $ref: '#/components/schemas/PairingClaimResponse' '201': description: Pairing claimed and agent created. content: application/json: schema: $ref: '#/components/schemas/PairingClaimResponse' '401': $ref: '#/components/responses/Unauthorized' '404': description: Unknown or expired pairing code. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Pairing belongs to another user, or the requested handle is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Body is malformed, contains unknown fields, or fails field validation. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Too many pairing claims for this user or address. headers: Retry-After: description: Whole seconds before another claim attempt. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/Error' '503': $ref: '#/components/responses/PairingDeliveryUnavailable' security: - userSession: [] components: schemas: PairingClaimInput: type: object additionalProperties: false required: - display_name properties: display_name: type: string minLength: 1 maxLength: 80 pattern: .*\S.* handle: type: string pattern: ^[a-z][a-z0-9_]{2,31}$ avatar_url: type: - string - 'null' format: uri maxLength: 2048 pattern: ^https://(?![^/?#]*@) PairingClaimResponse: type: object additionalProperties: false required: - pairing_id - status - agent - conversation_id properties: pairing_id: type: string pattern: ^pair_ status: type: string const: claimed agent: allOf: - $ref: '#/components/schemas/Agent' - type: object required: - installation conversation_id: type: string pattern: ^cnv_ 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 Agent: type: object description: > Consumer-safe agent identity. Installation is present only on an installed-agent projection. Owner identity, prompts, provider/model, runtime, credentials, and backend configuration are never included. additionalProperties: false required: - id - handle - displayName - tagline - capabilities - visibility - status - createdAt properties: id: type: string pattern: ^agt_ example: agt_01JZRELAY handle: type: string pattern: ^[a-z][a-z0-9_]{2,31}$ example: relay displayName: type: string example: Relay tagline: type: string example: Your built-in Relay agent avatarUrl: type: string format: uri maxLength: 2048 pattern: ^https://(?![^/?#]*@) accentColor: type: string example: '#0B75FF' capabilities: type: array uniqueItems: true items: type: string enum: - text - image - voice - video - files visibility: type: string enum: - private - unlisted - public installation: $ref: '#/components/schemas/AgentInstallation' status: type: string enum: - active - suspended - retired createdAt: type: string format: date-time AgentInstallation: type: object description: > User-agent messaging relationship, not a runtime connection. A false canRemove hides and rejects ordinary removal; Block and Report remain available as safety overrides. additionalProperties: false required: - id - state - source - conversationId - canRemove properties: id: type: string pattern: ^ins_ state: type: string enum: - installed - removed source: type: string enum: - system - owner_create - store - share_link - exact_handle conversationId: type: string pattern: ^cnv_ canRemove: type: boolean 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. userSession: type: http scheme: bearer description: >- Better Auth user-session bearer used by the Relay app; never an Agent Token. ````