> ## 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. > ## Agent Instructions > The Relay API base URL is https://api.relayapp.im. Never use workers.dev origins. > The contract is raw HTTPS and JSON at https://api.relayapp.im. The one optional published package is @relaymessenger/cli. Import nothing else. > One send is one message. Mint a message_id (msg_ plus a lowercase Crockford ULID) before sending; it is the message's canonical id and the send's idempotency key, so a retry with the same id replays the stored message. > Message content is immutable. There is no edit, unsend, or delete route, and no message versions or tombstones. > A reply is a pointer: reply_to is { message_id, part_id? } and the client draws the quote from the target. > Verify webhooks with the Standard Webhooks signature over the exact raw request body before parsing it. > Webhooks and GET /v1/events read the same durable log and can run at once. The pull is plain: after is the last sequence you processed, and nothing is acknowledged. > An agent in a group is an ordinary member. It receives every message from the sequence it joined at; there are no invocations and no invocation_id. # Exchange a device code for a session > Step four. Poll no faster than the `interval` returned with the code. `authorization_pending` means keep waiting, `slow_down` means wait longer, and `expired_token` or `access_denied` end the attempt. A success returns a Relay user session. That session is not an Agent Key: use it once to create the bridge's agent with `POST /v1/me/agents`, store the `rly_live_…` key that call returns, and authenticate every later API request with the token alone. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/auth/device/token 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 otherwise. Data parts are stored and delivered as sent and render through their fallback text, except for the reserved `data.type` values Relay resolves itself. 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 a message, read history, and react. - name: Conversations description: > List the conversations an agent is in, advance receipts, and show the typing indicator. - name: Events description: > Receive durable inbound events, either through signed webhook receivers or by pulling `GET /v1/events`. Both work at once: one durable log per agent feeds both transports. Delivery is at least once everywhere; always deduplicate by `event_id`. - name: Attachments description: Upload bytes once and reference them from any number of parts. - name: Pairing description: > Device authorization (RFC 8628) for terminal bridges. Four calls, in this order: the computer asks for a code, the person opens the verification URI so the code is claimed for their account, the person approves it, and the computer exchanges the code for a session it uses to provision its agent and mint that agent's token. The token never travels to the phone. - name: Public description: Share profiles. paths: /api/auth/device/token: post: tags: - Pairing summary: Exchange a device code for a session description: > Step four. Poll no faster than the `interval` returned with the code. `authorization_pending` means keep waiting, `slow_down` means wait longer, and `expired_token` or `access_denied` end the attempt. A success returns a Relay user session. That session is not an Agent Key: use it once to create the bridge's agent with `POST /v1/me/agents`, store the `rly_live_…` key that call returns, and authenticate every later API request with the token alone. operationId: exchangeDeviceCode requestBody: required: true content: application/json: schema: type: object required: - grant_type - device_code - client_id properties: grant_type: type: string const: urn:ietf:params:oauth:grant-type:device_code device_code: type: string client_id: type: string responses: '200': description: The approved session. content: application/json: schema: type: object required: - access_token - token_type - expires_in properties: access_token: type: string description: Bearer session token for the paired Relay account. token_type: type: string const: Bearer expires_in: type: integer scope: type: string '400': description: > `authorization_pending`, `slow_down`, `expired_token`, `access_denied`, `invalid_request`, or `invalid_grant`. content: application/json: schema: $ref: '#/components/schemas/DeviceAuthorizationError' security: [] components: schemas: DeviceAuthorizationError: type: object description: > The RFC 8628 error shape, which is not Relay's `Error` envelope: the device endpoints answer in the OAuth idiom their clients already parse. required: - error - error_description properties: error: type: string example: authorization_pending error_description: type: string securitySchemes: agentToken: type: http scheme: bearer description: Agent Token (`rly_live_…`), shown once when the agent is created. ````