> ## 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. # Long-poll for events > Drain the agent's durable event log past `cursor` (Telegram getUpdates model). When no newer events exist the request holds open up to `timeout` seconds and returns as soon as one lands. Passing a cursor durably acknowledges every event at or below it. Before making the next request, atomically persist this page's events to the engine queue together with `next_cursor`; never advance the cursor before the events are durable. While any webhook endpoint is enabled this endpoint returns `409 conflict`; the check runs per request and on every wake, so around a registration or disable both paths may briefly observe the same events — deduplicate by `event_id`. One consumer per agent: starting a newer poll terminates an older held-open request with `409 terminated_by_other_consumer`. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/events 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/events: get: tags: - Events summary: Long-poll for events description: > Drain the agent's durable event log past `cursor` (Telegram getUpdates model). When no newer events exist the request holds open up to `timeout` seconds and returns as soon as one lands. Passing a cursor durably acknowledges every event at or below it. Before making the next request, atomically persist this page's events to the engine queue together with `next_cursor`; never advance the cursor before the events are durable. While any webhook endpoint is enabled this endpoint returns `409 conflict`; the check runs per request and on every wake, so around a registration or disable both paths may briefly observe the same events — deduplicate by `event_id`. One consumer per agent: starting a newer poll terminates an older held-open request with `409 terminated_by_other_consumer`. operationId: pollEvents parameters: - name: cursor in: query schema: type: integer minimum: 0 default: 0 description: > The `next_cursor` from a previous response. It durably acknowledges that handed-out page and advances message delivery receipts; Relay rejects values above the highest cursor it has delivered. `0` starts from the beginning of the retained log. - name: timeout in: query required: true schema: type: integer minimum: 0 maximum: 30 description: >- Seconds to hold the request open when no events are pending. 0 returns immediately with any pending events (nonblocking poll). - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 100 responses: '200': description: Events past the cursor, oldest first, and the cursor to persist. content: application/json: schema: type: object additionalProperties: false required: - events - next_cursor properties: events: type: array maxItems: 100 items: $ref: '#/components/schemas/Event' next_cursor: type: integer description: >- Pass as `cursor` on the next poll; equal to the request cursor when empty. '401': $ref: '#/components/responses/Unauthorized' '409': description: > `conflict` — a webhook endpoint is enabled; disable or delete your webhooks to poll. `terminated_by_other_consumer` — a newer poll with this Agent Token took over the consumer slot. content: application/json: schema: $ref: '#/components/schemas/Error' '410': description: > `cursor_expired` — the requested cursor precedes the seven-day retained event log. Reconcile canonical conversation history, persist the recovered state, and resume from a current cursor. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: > Cursor, timeout, or limit does not satisfy its exact integer bounds, or cursor acknowledges a sequence Relay has not delivered. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Event: type: object additionalProperties: false required: - event_id - event_type - agent_id - created_at - data properties: event_id: type: string description: Deduplicate on this — delivery is at least once. example: evt_01JZE9M2XW event_type: $ref: '#/components/schemas/WebhookEventType' example: message.received agent_id: type: string example: agt_01JZRELAY created_at: type: string format: date-time data: oneOf: - $ref: '#/components/schemas/MessageEventData' - $ref: '#/components/schemas/MessageEditedEventData' - $ref: '#/components/schemas/MessageUnsentEventData' - $ref: '#/components/schemas/GroupLifecycleEventData' - $ref: '#/components/schemas/GroupInviteEventData' - $ref: '#/components/schemas/ReactionEventData' - $ref: '#/components/schemas/ReceiptEventData' 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 WebhookEventType: type: string enum: - message.received - message.edited - message.unsent - conversation.added - conversation.updated - conversation.removed - reaction.added - reaction.removed - message.delivered - message.read - group.invite.joined - group.invite.declined - group.invite.completed - group.invite.expired MessageEventData: type: object additionalProperties: false required: - message properties: message: $ref: '#/components/schemas/Message' invocation_id: $ref: '#/components/schemas/InvocationId' MessageEditedEventData: type: object additionalProperties: false required: - message - revision_count properties: message: $ref: '#/components/schemas/EditedMessage' revision_count: type: integer minimum: 1 maximum: 5 MessageUnsentEventData: type: object additionalProperties: false required: - message_id - conversation_id - sequence properties: message_id: type: string pattern: ^msg_ conversation_id: type: string pattern: ^cnv_ sequence: type: integer minimum: 1 GroupLifecycleEventData: type: object additionalProperties: false required: - conversation_id - actor - membership_version - system_mutation - message properties: conversation_id: type: string pattern: ^cnv_ actor: type: object required: - kind - id properties: kind: type: string const: user id: type: string pattern: ^usr_ affected_participant: type: object description: >- Present when the lifecycle mutation adds, removes, or records the departure of one participant; omitted for metadata updates. required: - kind - id properties: kind: type: string enum: - user - agent id: type: string pattern: ^(usr|agt)_ membership_version: type: integer minimum: 1 system_mutation: type: object required: - type - mutation - actor - changes properties: type: type: string const: group.mutation mutation: type: string enum: - group.created - metadata.updated - membership.added - membership.removed - membership.left actor: type: object affected_participant: type: object changes: type: object message: $ref: '#/components/schemas/Message' GroupInviteEventData: oneOf: - title: Group invite join type: object additionalProperties: false required: - invite_id - conversation_id - user_id properties: invite_id: type: string pattern: ^inv_ conversation_id: type: string pattern: ^cnv_ user_id: type: string pattern: ^usr_ - title: Group invite decline type: object additionalProperties: false required: - invite_id - user_id properties: invite_id: type: string pattern: ^inv_ user_id: type: string pattern: ^usr_ - title: Completed group invite type: object additionalProperties: false required: - invite_id - conversation_id properties: invite_id: type: string pattern: ^inv_ conversation_id: type: string pattern: ^cnv_ - title: Expired group invite type: object additionalProperties: false required: - invite_id properties: invite_id: type: string pattern: ^inv_ ReactionEventData: type: object additionalProperties: false required: - reaction properties: reaction: type: object ReceiptEventData: type: object additionalProperties: true required: - message_id - conversation_id - through_sequence - at properties: message_id: type: string pattern: ^msg_ conversation_id: type: string pattern: ^cnv_ through_sequence: type: integer minimum: 1 at: type: string format: date-time Message: oneOf: - $ref: '#/components/schemas/VisibleMessage' - $ref: '#/components/schemas/DeletedMessageTombstone' InvocationId: type: string pattern: ^ivk_[0-9a-hjkmnp-tv-z]{26}$ example: ivk_01k1m4q9vn2r7t9b4c6qdh8xwy description: > One pending, agent-specific group invocation. It is bound to the agent's current membership period and becomes invalid on removal. EditedMessage: allOf: - $ref: '#/components/schemas/VisibleMessage' - type: object required: - edited_at - revisions properties: edited_at: type: string format: date-time revisions: type: array minItems: 1 maxItems: 5 items: $ref: '#/components/schemas/MessageRevision' VisibleMessage: type: object additionalProperties: false required: - id - conversation_id - sequence - sender - parts - fallback_text - status - created_at properties: id: type: string example: msg_01JZM3T8AH conversation_id: type: string example: cnv_01JZC7K4RQ sequence: type: integer description: Order inside the conversation. It is unrelated to webhook event IDs. sender: $ref: '#/components/schemas/Sender' parts: type: array items: $ref: '#/components/schemas/Part' reply_to: $ref: '#/components/schemas/ReplyRef' invoked_agents: type: array uniqueItems: true items: type: string description: Agents explicitly invoked by this human group message. suggestions: type: array maxItems: 8 description: > Agent-attached quick-reply chips. Clients render them only while this message is the newest in the conversation. items: $ref: '#/components/schemas/Suggestion' reactions: type: array description: >- Current reactions. History and bootstrap projections include this array. items: $ref: '#/components/schemas/ProjectedReaction' fallback_text: type: string description: Plain-language representation used by notifications and search. status: type: string enum: - sent - delivered - read - completed - failed example: sent delivered_at: type: string format: date-time read_at: type: string format: date-time edited_at: type: string format: date-time description: >- Time of the latest edit. Omitted when the message has never been edited. revisions: type: array maxItems: 5 description: > Prior canonical parts and fallback text, ordered from oldest to newest. History and bootstrap projections include an empty array for unedited messages. items: $ref: '#/components/schemas/MessageRevision' created_at: type: string format: date-time DeletedMessageTombstone: type: object additionalProperties: false required: - id - conversation_id - sequence - sender - status - created_at properties: id: type: string example: msg_01JZM3T8AH conversation_id: type: string example: cnv_01JZC7K4RQ sequence: type: integer minimum: 1 sender: $ref: '#/components/schemas/Sender' status: type: string const: deleted created_at: type: string format: date-time MessageRevision: type: object additionalProperties: false required: - parts - fallback_text - replaced_at properties: parts: type: array items: $ref: '#/components/schemas/Part' fallback_text: type: string replaced_at: type: string format: date-time description: Time this snapshot stopped being the canonical content. Sender: type: object required: - kind - id properties: kind: type: string enum: - user - agent - system id: type: string example: usr_01JZU1F0BD Part: oneOf: - $ref: '#/components/schemas/TextPart' - $ref: '#/components/schemas/MediaPart' - $ref: '#/components/schemas/VoiceMemoPart' - $ref: '#/components/schemas/LinkPreviewPart' - $ref: '#/components/schemas/DataPart' discriminator: propertyName: type ReplyRef: type: - object - 'null' properties: message_id: type: string example: msg_01JZM3T8AH part_index: type: integer example: 0 Suggestion: type: object additionalProperties: false required: - text properties: text: type: string minLength: 1 maxLength: 96 description: Chip label; also the exact text sent when the user taps it. example: Everyone ProjectedReaction: type: object additionalProperties: false required: - part_index - emoji - actor_kind - actor_id properties: part_index: type: - integer - 'null' minimum: 0 emoji: type: string actor_kind: type: string enum: - user - contact actor_id: type: string pattern: ^(usr|agt)_ TextPart: type: object additionalProperties: false required: - part_index - type - text properties: part_index: type: integer minimum: 0 type: type: string const: text text: type: string MediaPart: type: object additionalProperties: false required: - part_index - type - url properties: part_index: type: integer minimum: 0 type: type: string const: media url: type: string format: uri attachment_id: type: string pattern: ^att_ VoiceMemoPart: type: object additionalProperties: false required: - part_index - type - url properties: part_index: type: integer minimum: 0 type: type: string const: voice_memo url: type: string format: uri attachment_id: type: string pattern: ^att_ duration_ms: type: integer minimum: 0 LinkPreviewPart: type: object additionalProperties: false required: - part_index - type - url properties: part_index: type: integer minimum: 0 type: type: string const: link_preview url: type: string format: uri maxLength: 2048 DataPart: type: object additionalProperties: false required: - part_index - type - data properties: part_index: type: integer minimum: 0 type: type: string const: data data: anyOf: - $ref: '#/components/schemas/GroupInviteComponentData' - description: Other integration-defined JSON data. GroupInviteComponentData: type: object additionalProperties: false description: > Internal consent card committed by POST /v1/groups/invites. Ordinary agent message sends cannot supply this component. required: - type - invite_id - title - expires_at - members properties: type: type: string const: group_invite invite_id: type: string pattern: ^inv_ title: type: string minLength: 1 maxLength: 100 reason: type: string minLength: 1 maxLength: 200 expires_at: type: string format: date-time conversation: type: object additionalProperties: false required: - id - title properties: id: type: string pattern: ^cnv_ title: type: string minLength: 1 maxLength: 100 members: type: array minItems: 1 maxItems: 24 items: $ref: '#/components/schemas/GroupInviteMember' GroupInviteMember: type: object additionalProperties: false required: - user_id - display_name - avatar_url - state properties: user_id: type: string pattern: ^usr_ display_name: type: string avatar_url: type: - string - 'null' state: type: string enum: - invited - accepted - declined description: > invited has not answered yet, accepted is in the live conversation, and declined answered no. responses: Unauthorized: description: Token is absent or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: agentToken: type: http scheme: bearer description: Agent Token (`rly_live_…`), shown once at agent creation. ````