> ## Documentation Index > Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Upload a validated contiguous batch of remote agent events ## OpenAPI ````yaml /openapi/overlay-web.openapi.json post /api/v1/agent-environments/{environmentId}/events openapi: 3.0.3 info: title: Overlay Web API version: 1.0.0 description: >- Generated from the overlay-web route boundary registry. This first-pass reference documents stable route inventory and request shapes. servers: - url: https://getoverlay.io description: Hosted Overlay web app - url: http://localhost:3000 description: Local development web app security: [] tags: - name: Administration - name: Agent environments - name: Automations - name: Billing - name: Bootstrap - name: Chat - name: Conversations - name: Discovery - name: Files - name: Integrations - name: Knowledge - name: MCP Servers - name: Media - name: Memory - name: Model Providers - name: Models - name: Notes - name: Onboarding - name: Outputs - name: Projects - name: Settings - name: Skills - name: Tools - name: Webhooks paths: /api/v1/agent-environments/{environmentId}/events: post: tags: - Agent environments summary: Upload a validated contiguous batch of remote agent events operationId: postAgentEnvironmentsEnvironmentIdEvents parameters: - name: environmentId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: protocolVersion: type: number enum: - 1 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 events: type: array items: anyOf: - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - session_started payload: type: object properties: remoteSessionId: type: string minLength: 1 maxLength: 200 adapterId: type: string minLength: 1 maxLength: 200 required: - remoteSessionId - adapterId additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - text_checkpoint payload: type: object properties: text: type: string final: type: boolean required: - text additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - action payload: type: object properties: actionId: type: string minLength: 1 maxLength: 200 title: type: string maxLength: 2000 status: type: string enum: - started - updated - completed - failed detail: type: string maxLength: 20000 required: - actionId - title - status additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - approval_requested payload: type: object properties: requestKey: type: string minLength: 1 maxLength: 200 prompt: type: string maxLength: 20000 options: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 200 label: type: string maxLength: 500 required: - id - label additionalProperties: false minItems: 1 maxItems: 20 context: type: object additionalProperties: {} default: {} required: - requestKey - prompt - options additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - elicitation_requested payload: type: object properties: requestKey: type: string minLength: 1 maxLength: 200 prompt: type: string maxLength: 20000 requestedSchema: type: object additionalProperties: {} context: type: object additionalProperties: {} default: {} required: - requestKey - prompt - requestedSchema additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - plan payload: type: object properties: entries: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 200 title: type: string maxLength: 2000 status: type: string enum: - pending - in_progress - completed - failed required: - id - title - status additionalProperties: false maxItems: 100 required: - entries additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - commands_update payload: type: object properties: commands: type: array items: type: object properties: name: type: string minLength: 1 maxLength: 200 description: type: string maxLength: 2000 inputHint: type: string maxLength: 500 required: - name additionalProperties: false maxItems: 100 required: - commands additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - diff payload: type: object properties: diffId: type: string minLength: 1 maxLength: 200 title: type: string maxLength: 2000 patch: type: string maxLength: 200000 language: type: string maxLength: 100 required: - diffId - title - patch additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - terminal payload: type: object properties: terminalId: type: string minLength: 1 maxLength: 200 title: type: string maxLength: 2000 summary: type: string maxLength: 20000 exitCode: type: integer status: type: string enum: - running - completed - failed required: - terminalId - title - summary - status additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - artifact payload: type: object properties: name: type: string minLength: 1 maxLength: 500 mediaType: type: string minLength: 1 maxLength: 200 size: type: integer minimum: 0 sha256: type: string pattern: ^[a-f0-9]{64}$ uploadReference: type: string minLength: 1 maxLength: 200 required: - name - mediaType - size - sha256 - uploadReference additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - completed payload: type: object properties: summary: type: string maxLength: 20000 usage: type: object additionalProperties: {} default: {} additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - failed payload: type: object properties: code: type: string minLength: 1 maxLength: 200 message: type: string maxLength: 20000 retryable: type: boolean required: - code - message - retryable additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false - type: object properties: protocolVersion: type: number enum: - 1 eventId: type: string minLength: 1 maxLength: 200 environmentId: type: string minLength: 1 maxLength: 200 runId: type: string minLength: 1 maxLength: 200 sourceSequence: type: integer exclusiveMinimum: true minimum: 0 occurredAt: type: integer minimum: 0 type: type: string enum: - cancelled payload: type: object properties: reason: type: string maxLength: 2000 additionalProperties: false required: - protocolVersion - eventId - environmentId - runId - sourceSequence - occurredAt - type - payload additionalProperties: false minItems: 1 maxItems: 100 required: - protocolVersion - environmentId - runId - events additionalProperties: false responses: '200': description: >- Successful response. Stable response schemas are documented in workflow guides when available. content: application/json: schema: description: >- Response shape is route-specific and may be backed by @overlay/app-core contracts. '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid authentication. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - browserSession: [] - bearerAuth: [] components: schemas: ErrorResponse: type: object properties: error: type: string code: type: string additionalProperties: true securitySchemes: browserSession: type: apiKey in: cookie name: overlay_session description: Signed httpOnly browser session cookie. bearerAuth: type: http scheme: bearer description: WorkOS bearer access token for native or service clients. ````