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

# Rotate an agent token

> Disables every enabled token for one of the caller's agents and mints a replacement. The old token stops working immediately, so update the bridge before the next request.




## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/me/agents/{agent_id}/tokens/rotate
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:
  /v1/me/agents/{agent_id}/tokens/rotate:
    post:
      tags:
        - Pairing
      summary: Rotate an agent token
      description: >
        Disables every enabled token for one of the caller's agents and mints a
        replacement. The old token stops working immediately, so update the
        bridge before the next request.
      operationId: rotateAgentToken
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^agt_
      responses:
        '201':
          description: New token minted; store it now.
          content:
            application/json:
              schema:
                type: object
                required:
                  - agent_id
                  - token
                properties:
                  agent_id:
                    type: string
                    pattern: ^agt_
                  token:
                    type: string
                    pattern: ^rly_live_
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No agent with this id belongs to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - userSession: []
components:
  responses:
    Unauthorized:
      description: The token or session is absent or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: invalid_request
            message:
              type: string
              example: chat_id is required
  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.

````