> ## 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.

# Claim a device code

> Step two, and not only a read. Looking a pending `user_code` up while signed in CLAIMS it for that account, which is the binding `POST /api/auth/device/approve` requires. Skip this call and the approval answers `400 invalid_request`.

The Relay app calls this to render the approval sheet. `client_id` and `scope` come back only to the person the request is now bound to.




## OpenAPI

````yaml /api-reference/openapi.yaml get /api/auth/device
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:
    get:
      tags:
        - Pairing
      summary: Claim a device code
      description: >
        Step two, and not only a read. Looking a pending `user_code` up while
        signed in CLAIMS it for that account, which is the binding `POST
        /api/auth/device/approve` requires. Skip this call and the approval
        answers `400 invalid_request`.


        The Relay app calls this to render the approval sheet. `client_id` and
        `scope` come back only to the person the request is now bound to.
      operationId: getDeviceAuthorization
      parameters:
        - name: user_code
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Current status of the device authorization.
          content:
            application/json:
              schema:
                type: object
                required:
                  - user_code
                  - status
                properties:
                  user_code:
                    type: string
                  status:
                    type: string
                    enum:
                      - pending
                      - approved
                      - denied
                  client_id:
                    type: string
                  scope:
                    type: string
        '400':
          description: The user code is unknown or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAuthorizationError'
      security:
        - userSession: []
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.
    userSession:
      type: http
      scheme: bearer
      description: >-
        Better Auth user-session bearer used by the Relay app and by a paired
        bridge; never an Agent Token.

````