diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml index 8c2bec4..724bacb 100644 --- a/developers/agent-api-openapi.yaml +++ b/developers/agent-api-openapi.yaml @@ -2,21 +2,25 @@ openapi: 3.0.0 info: title: Oz Agent API version: 1.0.0 - description: "API for creating, managing, and querying Oz cloud agent runs.\n\nThese endpoints allow users to programmatically spawn agents, list runs, \nand retrieve detailed run information.\n" + description: | + API for creating, managing, and querying Oz cloud agent runs. + + These endpoints allow users to programmatically spawn agents, list runs, + and retrieve detailed run information. contact: name: Warp Support - url: https://docs.warp.dev + url: 'https://docs.warp.dev' email: support@warp.dev license: name: Proprietary servers: -- url: https://app.warp.dev/api/v1 - description: Warp Server + - url: 'https://app.warp.dev/api/v1' + description: Warp Server tags: -- name: agent - description: Operations for running and managing cloud agents -- name: schedules - description: Operations for creating and managing scheduled agents + - name: agent + description: Operations for running and managing cloud agents + - name: schedules + description: Operations for creating and managing scheduled agents paths: /agent: get: @@ -26,49 +30,49 @@ paths: Agents are discovered from environments or a specific repository. operationId: listAgents tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: repo - in: query - description: | - Optional repository specification to list agents from (format: "owner/repo"). - If not provided, lists agents from all accessible environments. - required: false - schema: - type: string - - name: refresh - in: query - description: | - When true, clears the agent list cache before fetching. - Use this to force a refresh of the available agents. - required: false - schema: - type: boolean - default: false - - name: sort_by - in: query - description: | - Sort order for the returned agents. - - "name": Sort alphabetically by name (default) - - "last_run": Sort by most recently used - required: false - schema: - type: string - enum: - - name - - last_run - - name: include_malformed_skills - in: query - description: | - When true, includes skills whose SKILL.md file exists but is - malformed. These variants will have a non-empty `error` field - describing the parse failure. Defaults to false. - required: false - schema: - type: boolean - default: false + - name: repo + in: query + description: | + Optional repository specification to list agents from (format: "owner/repo"). + If not provided, lists agents from all accessible environments. + required: false + schema: + type: string + - name: refresh + in: query + description: | + When true, clears the agent list cache before fetching. + Use this to force a refresh of the available agents. + required: false + schema: + type: boolean + default: false + - name: sort_by + in: query + description: | + Sort order for the returned agents. + - "name": Sort alphabetically by name (default) + - "last_run": Sort by most recently used + required: false + schema: + type: string + enum: + - name + - last_run + - name: include_malformed_skills + in: query + description: | + When true, includes skills whose SKILL.md file exists but is + malformed. These variants will have a non-empty `error` field + describing the parse failure. Defaults to false. + required: false + schema: + type: boolean + default: false responses: '200': description: List of available agents @@ -90,9 +94,9 @@ paths: Worker presence is derived from worker websocket heartbeats and may be briefly stale. operationId: listConnectedSelfHostedWorkers tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] responses: '200': description: List of currently connected self-hosted workers @@ -112,7 +116,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/transcript: + '/agent/runs/{runId}/transcript': get: summary: Get run transcript description: | @@ -120,16 +124,16 @@ paths: Returns a 302 redirect to a time-limited download URL for the transcript. operationId: getRunTranscript tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '302': description: Redirect to a download URL for the transcript @@ -177,9 +181,9 @@ paths: The agent will be queued for execution and assigned a unique run ID. operationId: runAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] requestBody: required: true content: @@ -208,7 +212,7 @@ paths: schema: $ref: '#/components/schemas/RunAgentResponse' '400': - description: Invalid request (missing prompt, invalid config) + description: 'Invalid request (missing prompt, invalid config)' content: application/json: schema: @@ -220,7 +224,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: No permission to access referenced resources (environment, MCP servers) + description: 'No permission to access referenced resources (environment, MCP servers)' content: application/json: schema: @@ -233,9 +237,9 @@ paths: new agent runs. Behavior is identical to POST /agent/run. operationId: createRun tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] requestBody: required: true content: @@ -250,7 +254,7 @@ paths: schema: $ref: '#/components/schemas/RunAgentResponse' '400': - description: Invalid request (missing prompt, invalid config) + description: 'Invalid request (missing prompt, invalid config)' content: application/json: schema: @@ -262,7 +266,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: No permission to access referenced resources (environment, MCP servers) + description: 'No permission to access referenced resources (environment, MCP servers)' content: application/json: schema: @@ -274,171 +278,171 @@ paths: Results default to `sort_by=updated_at` and `sort_order=desc`. operationId: listRuns tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: limit - in: query - description: Maximum number of runs to return - required: false - schema: - type: integer - minimum: 1 - maximum: 500 - default: 20 - - name: cursor - in: query - description: Pagination cursor from previous response - required: false - schema: - type: string - - name: sort_by - in: query - description: | - Sort field for results. - - `updated_at`: Sort by last update timestamp (default) - - `created_at`: Sort by creation timestamp - - `title`: Sort alphabetically by run title - - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last. - required: false - schema: - type: string - enum: - - updated_at - - created_at - - title - - agent - default: updated_at - - name: sort_order - in: query - description: Sort direction - required: false - schema: - type: string - enum: - - asc - - desc - default: desc - - name: state - in: query - description: | - Filter by run state. Can be specified multiple times to match any of the given states. - required: false - schema: - type: array - items: - $ref: '#/components/schemas/RunState' - style: form - explode: true - - name: name - in: query - description: Filter by agent config name - required: false - schema: - type: string - - name: model_id - in: query - description: Filter by model ID - required: false - schema: - type: string - - name: creator - in: query - description: Filter by creator UID (user or service account) - required: false - schema: - type: string - - name: executor - in: query - description: | - Filter by the user or agent that executed the run. This will often be the - same as the creator, but not always: users may delegate tasks to agents. - required: false - schema: - type: string - - name: source - in: query - description: Filter by run source type - required: false - schema: - $ref: '#/components/schemas/RunSourceType' - - name: execution_location - in: query - description: Filter by where the run executed - required: false - schema: - $ref: '#/components/schemas/RunExecutionLocation' - - name: created_after - in: query - description: Filter runs created after this timestamp (RFC3339 format) - required: false - schema: - type: string - format: date-time - - name: created_before - in: query - description: Filter runs created before this timestamp (RFC3339 format) - required: false - schema: - type: string - format: date-time - - name: updated_after - in: query - description: Filter runs updated after this timestamp (RFC3339 format) - required: false - schema: - type: string - format: date-time - - name: environment_id - in: query - description: Filter runs by environment ID - required: false - schema: - type: string - - name: skill - in: query - description: | - Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). - Alias for skill_spec. - required: false - schema: - type: string - - name: skill_spec - in: query - description: Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md") - required: false - schema: - type: string - - name: schedule_id - in: query - description: Filter runs by the scheduled agent ID that created them - required: false - schema: - type: string - - name: ancestor_run_id - in: query - description: Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller. - required: false - schema: - type: string - - name: artifact_type - in: query - description: Filter runs by artifact type - required: false - schema: - type: string - enum: - - PLAN - - PULL_REQUEST - - SCREENSHOT - - FILE - - name: q - in: query - description: Fuzzy search query across run title, prompt, and skill_spec - required: false - schema: - type: string + - name: limit + in: query + description: Maximum number of runs to return + required: false + schema: + type: integer + minimum: 1 + maximum: 500 + default: 20 + - name: cursor + in: query + description: Pagination cursor from previous response + required: false + schema: + type: string + - name: sort_by + in: query + description: | + Sort field for results. + - `updated_at`: Sort by last update timestamp (default) + - `created_at`: Sort by creation timestamp + - `title`: Sort alphabetically by run title + - `agent`: Sort alphabetically by skill. Runs without a skill are grouped last. + required: false + schema: + type: string + enum: + - updated_at + - created_at + - title + - agent + default: updated_at + - name: sort_order + in: query + description: Sort direction + required: false + schema: + type: string + enum: + - asc + - desc + default: desc + - name: state + in: query + description: | + Filter by run state. Can be specified multiple times to match any of the given states. + required: false + schema: + type: array + items: + $ref: '#/components/schemas/RunState' + style: form + explode: true + - name: name + in: query + description: Filter by agent config name + required: false + schema: + type: string + - name: model_id + in: query + description: Filter by model ID + required: false + schema: + type: string + - name: creator + in: query + description: Filter by creator UID (user or service account) + required: false + schema: + type: string + - name: executor + in: query + description: | + Filter by the user or agent that executed the run. This will often be the + same as the creator, but not always: users may delegate tasks to agents. + required: false + schema: + type: string + - name: source + in: query + description: Filter by run source type + required: false + schema: + $ref: '#/components/schemas/RunSourceType' + - name: execution_location + in: query + description: Filter by where the run executed + required: false + schema: + $ref: '#/components/schemas/RunExecutionLocation' + - name: created_after + in: query + description: Filter runs created after this timestamp (RFC3339 format) + required: false + schema: + type: string + format: date-time + - name: created_before + in: query + description: Filter runs created before this timestamp (RFC3339 format) + required: false + schema: + type: string + format: date-time + - name: updated_after + in: query + description: Filter runs updated after this timestamp (RFC3339 format) + required: false + schema: + type: string + format: date-time + - name: environment_id + in: query + description: Filter runs by environment ID + required: false + schema: + type: string + - name: skill + in: query + description: | + Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). + Alias for skill_spec. + required: false + schema: + type: string + - name: skill_spec + in: query + description: 'Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")' + required: false + schema: + type: string + - name: schedule_id + in: query + description: Filter runs by the scheduled agent ID that created them + required: false + schema: + type: string + - name: ancestor_run_id + in: query + description: Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller. + required: false + schema: + type: string + - name: artifact_type + in: query + description: Filter runs by artifact type + required: false + schema: + type: string + enum: + - PLAN + - PULL_REQUEST + - SCREENSHOT + - FILE + - name: q + in: query + description: 'Fuzzy search query across run title, prompt, and skill_spec' + required: false + schema: + type: string responses: '200': description: List of runs @@ -458,22 +462,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}: + '/agent/runs/{runId}': get: summary: Get run details - description: "Retrieve detailed information about a specific agent run, \nincluding the full prompt, session link, and resolved configuration.\n" + description: | + Retrieve detailed information about a specific agent run, + including the full prompt, session link, and resolved configuration. operationId: getRun tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '200': description: Run details @@ -505,7 +511,55 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/conversation: + '/agent/runs/{runId}/timeline': + get: + summary: Get run timeline + description: | + Retrieve chronological setup and lifecycle timeline events for an agent run. + operationId: getRunTimeline + tags: + - agent + security: + - bearerAuth: [] + parameters: + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string + responses: + '200': + description: Run timeline events + content: + application/json: + schema: + $ref: '#/components/schemas/GetRunTimelineResponse' + '400': + description: Missing run ID + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to access run + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/agent/runs/{runId}/conversation': get: summary: Get normalized run conversation description: | @@ -515,16 +569,16 @@ paths: structured blocks. operationId: getRunConversation tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '200': description: Normalized conversation @@ -551,7 +605,7 @@ paths: schema: $ref: '#/components/schemas/Error' '404': - description: Run not found, or the run has no conversation + description: 'Run not found, or the run has no conversation' content: application/json: schema: @@ -564,7 +618,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/cancel: + '/agent/runs/{runId}/cancel': post: summary: Cancel a run description: | @@ -577,16 +631,16 @@ paths: and GitHub Action runs return 422. operationId: cancelRun tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run to cancel - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run to cancel + required: true + schema: + type: string responses: '200': description: Run cancelled successfully @@ -638,7 +692,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/runs/{runId}/followups: + '/agent/runs/{runId}/followups': post: summary: Submit a follow-up message for a run description: | @@ -649,16 +703,16 @@ paths: `GET /agent/runs/{runId}`. operationId: submitRunFollowup tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: runId - in: path - description: The unique identifier of the run - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string requestBody: required: true content: @@ -673,7 +727,10 @@ paths: schema: type: object '400': - description: Invalid request (empty message, no active sandbox without conversation ID, etc.) + description: | + Invalid request (e.g. no active sandbox without conversation ID, + malformed payload). Empty messages are accepted when continuing a + run from saved conversation context; otherwise they are rejected. content: application/json: schema: @@ -702,33 +759,38 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/conversations/{conversation_id}: + '/agent/runs/{runId}/handoff/attachments': get: - summary: Get normalized conversation + summary: List handoff snapshot attachments for a run description: | - Retrieve a conversation directly by conversation ID in Warp's - normalized task/message format. - operationId: getConversation + Return fresh presigned download URLs for handoff snapshot files uploaded + by the latest ended execution of this run. An empty list is returned + when no ended execution exists or no snapshot files were uploaded. + + This endpoint is useful for third-party harnesses that want to download + the snapshot files produced by a previous execution before starting a + handoff execution themselves. + operationId: listHandoffSnapshotAttachments tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: conversation_id - in: path - description: The unique identifier of the conversation - required: true - schema: - type: string + - name: runId + in: path + description: The unique identifier of the run + required: true + schema: + type: string responses: '200': - description: Normalized conversation + description: Handoff snapshot attachments (possibly empty) content: application/json: schema: - $ref: '#/components/schemas/ConversationResponse' + $ref: '#/components/schemas/ListHandoffSnapshotAttachmentsResponse' '400': - description: Missing conversation ID + description: Missing run ID content: application/json: schema: @@ -740,333 +802,214 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: No permission to access conversation - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '404': - description: Conversation not found + description: No permission to view the run content: application/json: schema: $ref: '#/components/schemas/Error' - '422': - description: | - Conversation format is not yet supported by the normalized endpoint - (error_code: operation_not_supported) + '500': + description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' - /agent/messages: + /agent/handoff/upload-snapshot: post: - summary: Send a message to one or more runs + summary: Prepare upload of a local-to-cloud handoff snapshot description: | - Send a point-to-point message to one or more agent runs. - Each recipient gets an independent message row with its own delivery state. - Requires the OrchestrationV2 feature flag. - operationId: sendAgentMessage - x-internal: true + Allocate a fresh `initial_snapshot_token` and return presigned upload URLs + scoped to that token. The client uploads the snapshot files (workspace + patches, manifests, and orphan files) to those URLs and then includes the + `initial_snapshot_token` on the subsequent `POST /agent/runs` request. The + server stores the token on the new run's queued execution input; + rehydration discovery serves files from that prefix to the cloud sandbox. + Uploads are bounded by a per-file size limit. When `size_bytes` is + declared for a file, requests above the limit are rejected before upload; + the returned upload targets also include signed headers that GCS enforces + during the PUT. + + This endpoint is unscoped (no `runId`) because it is called *before* + the run is created. It is gated by the `local_to_cloud_handoff` feature + flag and returns 400 when the flag is off. + operationId: uploadLocalHandoffSnapshot tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] requestBody: required: true content: application/json: schema: - type: object - required: - - to - - subject - - body - - sender_run_id - properties: - to: - type: array - items: - type: string - description: List of recipient run IDs - subject: - type: string - maxLength: 1024 - description: Message subject - body: - type: string - maxLength: 131072 - description: Message body (max 128KB) - sender_run_id: - type: string - description: The sender's run ID + $ref: '#/components/schemas/UploadLocalHandoffSnapshotRequest' responses: '200': - description: Message sent successfully + description: Presigned upload targets and a fresh initial_snapshot_token content: application/json: schema: - type: object - properties: - message_ids: - type: array - items: - type: string - description: One message ID per recipient, in the same order as the to array - '422': - description: One or more recipients are in a terminal state - /agent/messages/{runId}: - get: - summary: List inbox message headers - operationId: listAgentMessages - x-internal: true - tags: - - agent - security: - - bearerAuth: [] - parameters: - - name: runId - in: path - required: true - schema: - type: string - - name: unread - in: query - schema: - type: boolean - - name: since - in: query - schema: - type: string - format: date-time - - name: limit - in: query - schema: - type: integer - default: 50 - maximum: 100 - responses: - '200': - description: List of message headers - content: - application/json: - schema: - type: array - items: - type: object - properties: - message_id: - type: string - sender_run_id: - type: string - subject: - type: string - sent_at: - type: string - format: date-time - delivered_at: - type: string - format: date-time - nullable: true - read_at: - type: string - format: date-time - nullable: true - /agent/messages/{messageId}/read: - post: - summary: Read a message body - description: Returns the full message body and sets read_at. - operationId: readAgentMessage - x-internal: true - tags: - - agent - security: - - bearerAuth: [] - parameters: - - name: messageId - in: path - required: true - schema: - type: string - responses: - '200': - description: Full message content + $ref: '#/components/schemas/UploadLocalHandoffSnapshotResponse' + '400': + description: Invalid request or local_to_cloud_handoff feature not enabled content: application/json: schema: - type: object - properties: - message_id: - type: string - sender_run_id: - type: string - subject: - type: string - body: - type: string - sent_at: - type: string - format: date-time - delivered_at: - type: string - format: date-time - nullable: true - read_at: - type: string - format: date-time - nullable: true - /agent/messages/{messageId}/delivered: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/agent/conversations/{conversation_id}/fork': post: - summary: Mark a message as delivered - description: Sets delivered_at if not already set. Idempotent. - operationId: markAgentMessageDelivered - x-internal: true - tags: - - agent - security: - - bearerAuth: [] - parameters: - - name: messageId - in: path - required: true - schema: - type: string - responses: - '204': - description: Delivered - /agent/events: - get: - summary: Poll for events + summary: Fork a conversation description: | - Batch poll for events across multiple watched runs. - Returns events ordered by monotonic sequence number. - Client advances the cursor (since parameter) on each poll. - operationId: pollAgentEvents - x-internal: true + Materialize a server-side fork of the named source conversation and + return the forked `conversation_id`. The caller can pass the returned + id as `conversation_id` on a subsequent `POST /agent/runs` request to + resume from the fork. + + Authorization: the caller must have `ViewAction` on the source + conversation. The new conversation is owned by the caller (not by the + source's owner). + operationId: forkConversation tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: run_ids - in: query - required: true - style: form - explode: true - schema: - type: array - items: + - name: conversation_id + in: path + description: The unique identifier of the source conversation to fork + required: true + schema: type: string - - name: since - in: query - schema: - type: integer - format: int64 - default: 0 - - name: limit - in: query - schema: - type: integer - default: 100 - maximum: 500 - responses: - '200': - description: List of events - content: - application/json: - schema: - type: array - items: - type: object - properties: - event_type: - type: string - run_id: - type: string - ref_id: - type: string - nullable: true - execution_id: - type: string - nullable: true - occurred_at: - type: string - format: date-time - sequence: - type: integer - format: int64 - /agent/events/{runId}: - post: - summary: Report a lifecycle event - description: | - Client reports a lifecycle event for a run. - This is the canonical mechanism for all lifecycle events. - operationId: reportAgentEvent - x-internal: true - tags: - - agent - security: - - bearerAuth: [] - parameters: - - name: runId - in: path - required: true - schema: - type: string requestBody: - required: true + required: false content: application/json: schema: - type: object - required: - - event_type - properties: - event_type: - type: string - enum: - - run_in_progress - - run_succeeded - - run_failed - - run_errored - - run_blocked - - run_cancelled - execution_id: - type: string - description: Client-assigned execution ID for correlation - ref_id: - type: string - description: Event-type-specific reference (e.g., message ID for new_message events) + $ref: '#/components/schemas/ForkConversationRequest' responses: '200': - description: Event recorded + description: Forked conversation id content: application/json: schema: - type: object - properties: - sequence: - type: integer - format: int64 - /agent/schedules: - post: - summary: Create a scheduled agent - description: | - Create a new scheduled agent that runs on a cron schedule. - The agent will be triggered automatically based on the cron expression. - operationId: createScheduledAgent - tags: - - schedules - security: - - bearerAuth: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateScheduledAgentRequest' - examples: - simple: + $ref: '#/components/schemas/ForkConversationResponse' + '400': + description: 'Invalid conversation ID, or source conversation data is not ready to fork' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to view the source conversation + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Source conversation not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/agent/conversations/{conversation_id}': + get: + summary: Get normalized conversation + description: | + Retrieve a conversation directly by conversation ID in Warp's + normalized task/message format. + operationId: getConversation + tags: + - agent + security: + - bearerAuth: [] + parameters: + - name: conversation_id + in: path + description: The unique identifier of the conversation + required: true + schema: + type: string + responses: + '200': + description: Normalized conversation + content: + application/json: + schema: + $ref: '#/components/schemas/ConversationResponse' + '400': + description: Missing conversation ID + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to access conversation + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Conversation not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '422': + description: | + Conversation format is not yet supported by the normalized endpoint + (error_code: operation_not_supported) + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /agent/schedules: + post: + summary: Create a scheduled agent + description: | + Create a new scheduled agent that runs on a cron schedule. + The agent will be triggered automatically based on the cron expression. + operationId: createScheduledAgent + tags: + - schedules + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateScheduledAgentRequest' + examples: + simple: summary: Simple daily schedule value: name: Daily Code Review @@ -1090,7 +1033,7 @@ paths: schema: $ref: '#/components/schemas/ScheduledAgentItem' '400': - description: Invalid request (missing required fields, invalid cron expression) + description: 'Invalid request (missing required fields, invalid cron expression)' content: application/json: schema: @@ -1114,9 +1057,9 @@ paths: Results are sorted alphabetically by name. operationId: listScheduledAgents tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] responses: '200': description: List of scheduled agents @@ -1136,7 +1079,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/schedules/{scheduleId}: + '/agent/schedules/{scheduleId}': get: summary: Get scheduled agent details description: | @@ -1144,16 +1087,16 @@ paths: including its configuration, history, and next scheduled run time. operationId: getScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent details @@ -1192,16 +1135,16 @@ paths: All fields except agent_config are required. operationId: updateScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string requestBody: required: true content: @@ -1245,16 +1188,16 @@ paths: Delete a scheduled agent. This will stop all future scheduled runs. operationId: deleteScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent deleted successfully @@ -1286,23 +1229,23 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/schedules/{scheduleId}/pause: + '/agent/schedules/{scheduleId}/pause': post: summary: Pause a scheduled agent description: | Pause a scheduled agent. The agent will not run until resumed. operationId: pauseScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent paused successfully @@ -1334,7 +1277,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/schedules/{scheduleId}/resume: + '/agent/schedules/{scheduleId}/resume': post: summary: Resume a scheduled agent description: | @@ -1342,16 +1285,16 @@ paths: according to its cron schedule. operationId: resumeScheduledAgent tags: - - schedules + - schedules security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: scheduleId - in: path - description: The unique identifier of the scheduled agent - required: true - schema: - type: string + - name: scheduleId + in: path + description: The unique identifier of the scheduled agent + required: true + schema: + type: string responses: '200': description: Scheduled agent resumed successfully @@ -1392,23 +1335,23 @@ paths: or has accessed via link sharing. operationId: listEnvironments tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: sort_by - in: query - required: false - description: | - Sort order for the returned environments. - - `name`: alphabetical by environment name - - `last_updated`: most recently updated first (default) - schema: - type: string - enum: - - name - - last_updated - default: last_updated + - name: sort_by + in: query + required: false + description: | + Sort order for the returned environments. + - `name`: alphabetical by environment name + - `last_updated`: most recently updated first (default) + schema: + type: string + enum: + - name + - last_updated + default: last_updated responses: '200': description: List of accessible environments @@ -1438,9 +1381,9 @@ paths: currently disabled (and why). operationId: listModels tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] responses: '200': description: List of available models @@ -1460,7 +1403,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/artifacts/{artifactUid}: + '/agent/artifacts/{artifactUid}': get: summary: Get artifact details description: | @@ -1469,16 +1412,16 @@ paths: the current plan content inline. operationId: getArtifact tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: artifactUid - in: path - description: The unique identifier (UUID) of the artifact - required: true - schema: - type: string + - name: artifactUid + in: path + description: The unique identifier (UUID) of the artifact + required: true + schema: + type: string responses: '200': description: Artifact details with download information @@ -1504,8 +1447,526 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - '404': - description: Artifact not found or unsupported artifact type + '404': + description: Artifact not found or unsupported artifact type + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /harness-support/external-conversation: + post: + summary: Create external conversation + description: | + Create a new external conversation record for a harness. Returns a conversation ID + for bookkeeping. + + This may only be called from within a cloud agent execution environment. + operationId: createExternalConversation + tags: + - harness-support + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateExternalConversationRequest' + responses: + '200': + description: External conversation created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/CreateExternalConversationResponse' + '400': + description: Invalid request (missing or unsupported format) + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to modify the task + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /harness-support/report-artifact: + post: + summary: Report an artifact + description: | + Report an artifact (e.g., a pull request) created by a third-party harness back to + the Oz platform. The artifact is associated with the current task's conversation. + + This may only be called from within a cloud agent execution environment. + operationId: reportArtifact + tags: + - harness-support + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReportArtifactRequest' + responses: + '200': + description: Artifact reported successfully + content: + application/json: + schema: + $ref: '#/components/schemas/ReportArtifactResponse' + '400': + description: Invalid request (missing or unsupported artifact type) + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to modify the task + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /harness-support/resolve-prompt: + post: + summary: Resolve effective prompt + description: | + Resolve the effective prompt for the current task, including optional skill content + and attachment references. This may only be called from within a cloud agent execution + environment. + operationId: resolvePrompt + tags: + - harness-support + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ResolvePromptRequest' + responses: + '200': + description: Resolved prompt + content: + application/json: + schema: + $ref: '#/components/schemas/ResolvePromptResponse' + '400': + description: Invalid request + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to access the task + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /harness-support/transcript: + post: + summary: Prepare upload of a conversation transcript + description: | + Allocates and returns a storage slot for uploading the raw conversation transcript. + The caller should make an HTTP request to the target with the transcript contents + as the request body. + + This may only be called from within a cloud agent execution environment. + operationId: getTranscriptUploadTarget + tags: + - harness-support + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/GetUploadTargetRequest' + responses: + '200': + description: Presigned upload target for the transcript + content: + application/json: + schema: + $ref: '#/components/schemas/UploadTarget' + '400': + description: Invalid request or conversation format does not support transcript uploads + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to modify the conversation + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Conversation or transcript slot not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + get: + summary: Download the raw third-party harness transcript + description: | + Redirects to a signed download URL for the raw third-party harness transcript + (e.g. `claude_code.json`) of the current task's conversation. Only supported + for conversations produced by non-Oz harnesses; Oz conversations 400. + + This may only be called from within a cloud agent execution environment whose + task already has an associated conversation (e.g. on a resumed run). + operationId: getTranscriptDownload + tags: + - harness-support + security: + - bearerAuth: [] + responses: + '307': + description: Redirect to a signed download URL for the transcript + '400': + description: 'Task has no conversation, or conversation format does not support transcript downloads' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to access the conversation + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Conversation or transcript not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /harness-support/notify-user: + post: + summary: Send a progress notification + description: | + Send a progress update message to the task's originating platform + (e.g., Slack thread, Linear comment). + + This may only be called from within a cloud agent execution environment. + operationId: notifyUser + tags: + - harness-support + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/NotifyUserRequest' + responses: + '200': + description: Notification sent successfully + content: + application/json: + schema: + type: object + '400': + description: Invalid request (missing message) + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to modify the task + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /harness-support/finish-task: + post: + summary: Report task completion + description: | + Report that the task has finished (successfully or not) with a summary. + This transitions the task state and sends a formatted output notification + to the originating platform. + + This may only be called from within a cloud agent execution environment. + operationId: finishTask + tags: + - harness-support + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/FinishTaskRequest' + responses: + '200': + description: Task completion reported successfully + content: + application/json: + schema: + type: object + '400': + description: Invalid request (missing required fields) + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to modify the task + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /harness-support/upload-snapshot: + post: + summary: Prepare upload of handoff snapshot files + description: | + Return presigned upload URLs for handoff snapshot files for the active + execution of the current ambient task. Files are keyed in storage as + `snapshots/{run_id}/{execution_id}/{uuid}_{filename}`. + Uploads are bounded by a per-file size limit. When `size_bytes` is + declared for a file, requests above the limit are rejected before upload; + the returned upload targets also include signed headers that GCS enforces + during the PUT. + + This may only be called from within a cloud agent execution environment, + and the run must have an active execution. + operationId: uploadHandoffSnapshot + tags: + - harness-support + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UploadSnapshotRequest' + responses: + '200': + description: 'Presigned upload targets, aligned by index with the request files' + content: + application/json: + schema: + $ref: '#/components/schemas/UploadSnapshotResponse' + '400': + description: Invalid request or no active execution for the run + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to modify the task + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /harness-support/report-shutdown: + post: + summary: Report agent shutdown + description: | + Report that the agent process is shutting down so the active execution can + be finalized and compute usage can be recorded. + + This may only be called from within a cloud agent execution environment, + and the run must have an active execution. + operationId: reportShutdown + tags: + - harness-support + security: + - bearerAuth: [] + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/ReportShutdownRequest' + responses: + '200': + description: Shutdown report processed successfully + content: + application/json: + schema: + type: object + '400': + description: Invalid request or no active execution for the run + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to modify the task + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /harness-support/block-snapshot: + post: + summary: Prepare upload of a block snapshot + description: | + Allocates and returns a storage slot for uploading an output snapshot. + The caller should make an HTTP request to the target with the serialized snapshot + as the request body. + + This may only be called from within a cloud agent execution environment. + operationId: getBlockSnapshotUploadTarget + tags: + - harness-support + security: + - bearerAuth: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/GetUploadTargetRequest' + responses: + '200': + description: Presigned upload target for the block snapshot + content: + application/json: + schema: + $ref: '#/components/schemas/UploadTarget' + '400': + description: Invalid request or conversation format does not support block snapshot uploads + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '401': + description: Authentication required + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No permission to modify the conversation + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '404': + description: Conversation or block snapshot slot not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: Internal server error content: application/json: schema: @@ -1518,9 +1979,9 @@ paths: Agents can be used as the execution principal for team-owned runs. operationId: createAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] requestBody: required: true content: @@ -1535,7 +1996,7 @@ paths: schema: $ref: '#/components/schemas/AgentResponse' '400': - description: Invalid request (empty name, user on multiple teams, or on no team) + description: 'Invalid request (empty name, user on multiple teams, or on no team)' content: application/json: schema: @@ -1547,7 +2008,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: Only human users can manage agents, or plan limit exceeded + description: 'Only human users can manage agents, or plan limit exceeded' content: application/json: schema: @@ -1566,9 +2027,9 @@ paths: and may be used for runs. operationId: listAgents tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] responses: '200': description: List of agents @@ -1577,7 +2038,7 @@ paths: schema: $ref: '#/components/schemas/ListAgentIdentitiesResponse' '400': - description: User on multiple teams, or on no team + description: 'User on multiple teams, or on no team' content: application/json: schema: @@ -1600,7 +2061,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/identities/{uid}: + '/agent/identities/{uid}': get: summary: Retrieve an agent description: | @@ -1609,16 +2070,16 @@ paths: is within the team's plan limit and may be used for runs. operationId: getAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The unique identifier of the agent - required: true - schema: - type: string + - name: uid + in: path + description: The unique identifier of the agent + required: true + schema: + type: string responses: '200': description: Agent details @@ -1650,16 +2111,16 @@ paths: Update an existing agent. operationId: updateAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The unique identifier of the agent - required: true - schema: - type: string + - name: uid + in: path + description: The unique identifier of the agent + required: true + schema: + type: string requestBody: required: true content: @@ -1686,7 +2147,7 @@ paths: schema: $ref: '#/components/schemas/Error' '403': - description: Only human users can manage agents, or plan limit exceeded + description: 'Only human users can manage agents, or plan limit exceeded' content: application/json: schema: @@ -1710,16 +2171,16 @@ paths: agent are deleted atomically. operationId: deleteAgent tags: - - agent + - agent security: - - bearerAuth: [] + - bearerAuth: [] parameters: - - name: uid - in: path - description: The unique identifier of the agent - required: true - schema: - type: string + - name: uid + in: path + description: The unique identifier of the agent + required: true + schema: + type: string responses: '204': description: Agent deleted successfully @@ -1753,7 +2214,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /agent/sessions/{sessionUuid}/redirect: + '/agent/sessions/{sessionUuid}/redirect': get: summary: Get session redirect description: | @@ -1767,15 +2228,15 @@ paths: conversation link-sharing. operationId: getSessionRedirect tags: - - agent + - agent security: [] parameters: - - name: sessionUuid - in: path - description: The UUID of the shared session - required: true - schema: - type: string + - name: sessionUuid + in: path + description: The UUID of the shared session + required: true + schema: + type: string responses: '200': description: | @@ -1795,6 +2256,48 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + '/agent/conversations/{conversationId}/redirect': + get: + summary: Get conversation redirect + description: | + Check whether a conversation should redirect to a live shared session. + Returns a session_id if the underlying ambient agent task still has a + live shared session, or an empty object if no redirect is needed. + + This endpoint is public (no authentication required) so that anonymous + viewers can resolve a publicly-shared conversation link before signing + in. Access to the underlying live session is still gated by the + session-sharing service ACLs. + operationId: getConversationRedirect + tags: + - agent + security: [] + parameters: + - name: conversationId + in: path + description: The ID of the conversation + required: true + schema: + type: string + responses: + '200': + description: | + Redirect information. Contains session_id if redirect is needed, + otherwise an empty object. + content: + application/json: + schema: + type: object + properties: + session_id: + type: string + description: The shared session UUID to redirect to (only present when redirect is needed) + '500': + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' components: securitySchemes: bearerAuth: @@ -1807,13 +2310,15 @@ components: type: object description: | Request body for creating a new agent run. - Either prompt or skill (via skill field, config.skill_spec, or config.skills) is required. + Either prompt or skill (via skill field, config.skill_spec, or config.skills) is required, + except for handoff requests that set conversation_id. properties: prompt: type: string description: | The prompt/instruction for the agent to execute. Required unless a skill is specified via the skill field, config.skill_spec, or config.skills. + Handoff requests may omit prompt when conversation_id is set. mode: $ref: '#/components/schemas/AgentRunMode' description: | @@ -1840,10 +2345,11 @@ components: description: | Whether to create a team-owned run. Defaults to true for users on a single team. - x-go-type-skip-optional-pointer: false agent_identity_uid: type: string - description: "Optional agent identity UID to use as the execution principal for the run.\nThis is only valid for runs that are team owned. \n" + description: | + Optional agent identity UID to use as the execution principal for the run. + This is only valid for runs that are team owned. conversation_id: type: string description: | @@ -1869,9 +2375,9 @@ components: RunAgentResponse: type: object required: - - run_id - - task_id - - state + - run_id + - task_id + - state properties: run_id: type: string @@ -1879,7 +2385,6 @@ components: task_id: type: string deprecated: true - x-stainless-deprecation-message: Use run_id instead. description: Unique identifier for the task (same as run_id). Deprecated - use run_id instead. state: $ref: '#/components/schemas/RunState' @@ -1894,15 +2399,15 @@ components: - plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution. - orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved. enum: - - normal - - plan - - orchestrate + - normal + - plan + - orchestrate default: normal ListRunsResponse: type: object required: - - runs - - page_info + - runs + - page_info properties: runs: type: array @@ -1913,13 +2418,13 @@ components: RunItem: type: object required: - - run_id - - task_id - - title - - state - - prompt - - created_at - - updated_at + - run_id + - task_id + - title + - state + - prompt + - created_at + - updated_at properties: run_id: type: string @@ -1927,7 +2432,6 @@ components: task_id: type: string deprecated: true - x-stainless-deprecation-message: Use run_id instead. description: Unique identifier for the task (typically matches run_id). Deprecated - use run_id instead. title: type: string @@ -1947,6 +2451,10 @@ components: type: string format: date-time description: Timestamp when the run was last updated (RFC3339) + run_time: + type: string + format: duration + description: 'Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions.' started_at: type: string format: date-time @@ -1968,7 +2476,7 @@ components: trigger_url: type: string format: uri - description: URL to the run trigger (e.g. Slack thread, Linear issue, schedule) + description: 'URL to the run trigger (e.g. Slack thread, Linear issue, schedule)' creator: $ref: '#/components/schemas/RunCreatorInfo' executor: @@ -1990,16 +2498,66 @@ components: type: array items: $ref: '#/components/schemas/ArtifactItem' - description: Artifacts created during the run (plans, pull requests, etc.) + description: 'Artifacts created during the run (plans, pull requests, etc.)' agent_skill: $ref: '#/components/schemas/AgentSkill' scope: $ref: '#/components/schemas/Scope' + GetRunTimelineResponse: + type: object + description: Response body for listing run timeline events. + required: + - events + properties: + events: + type: array + items: + $ref: '#/components/schemas/AIRunTimelineEvent' + AIRunTimelineEvent: + type: object + description: A setup or lifecycle event recorded for an agent run. + required: + - event_uuid + - run_id + - event_type + - occurred_at + properties: + event_uuid: + type: string + description: Unique client- or server-generated identifier for this event. + run_id: + type: string + description: Run that owns this event. + execution_id: + type: integer + format: int64 + description: 'Run execution associated with this event, when available.' + event_type: + $ref: '#/components/schemas/AIRunTimelineEventType' + occurred_at: + type: string + format: date-time + description: Timestamp when the event occurred. + payload: + type: object + additionalProperties: true + description: Optional event-specific JSON payload. + AIRunTimelineEventType: + type: string + description: Type of timeline event recorded for a run. + enum: + - oz_run_created + - oz_run_claimed + - worker_container_ready + - shared_session_started + - agent_started + - oz_run_finished + - oz_run_failure ConversationResponse: type: object required: - - conversation_id - - steps + - conversation_id + - steps properties: conversation_id: type: string @@ -2012,9 +2570,9 @@ components: ConversationStep: type: object required: - - id - - messages - - steps + - id + - messages + - steps properties: id: type: string @@ -2046,8 +2604,8 @@ components: ConversationMessage: type: object required: - - role - - content + - role + - content properties: message_ids: type: array @@ -2056,7 +2614,7 @@ components: type: string request_id: type: string - description: Request identifier shared by transcript messages from the same request, when available + description: 'Request identifier shared by transcript messages from the same request, when available' role: $ref: '#/components/schemas/ConversationMessageRole' timestamp: @@ -2071,16 +2629,16 @@ components: type: string description: Role of the normalized message enum: - - user - - assistant - - tool - - system + - user + - assistant + - tool + - system ConversationContentBlock: oneOf: - - $ref: '#/components/schemas/TextContentBlock' - - $ref: '#/components/schemas/ActionContentBlock' - - $ref: '#/components/schemas/ActionResultContentBlock' - - $ref: '#/components/schemas/EventContentBlock' + - $ref: '#/components/schemas/TextContentBlock' + - $ref: '#/components/schemas/ActionContentBlock' + - $ref: '#/components/schemas/ActionResultContentBlock' + - $ref: '#/components/schemas/EventContentBlock' discriminator: propertyName: type mapping: @@ -2091,16 +2649,16 @@ components: TextContentBlock: type: object required: - - type - - text + - type + - text properties: type: type: string enum: - - text + - text message_id: type: string - description: Underlying transcript message ID that produced this content block, when available + description: 'Underlying transcript message ID that produced this content block, when available' text: type: string description: Plain text content @@ -2108,38 +2666,38 @@ components: type: string description: High-level category of an action performed during the conversation enum: - - command - - files - - search - - integration - - documents - - computer - - review - - skill + - command + - files + - search + - integration + - documents + - computer + - review + - skill ActionState: type: string description: State of an action result enum: - - running - - completed - - failed - - denied + - running + - completed + - failed + - denied ActionContentBlock: type: object required: - - type - - id - - category - - name - - input + - type + - id + - category + - name + - input properties: type: type: string enum: - - action + - action message_id: type: string - description: Underlying transcript message ID that produced this content block, when available + description: 'Underlying transcript message ID that produced this content block, when available' id: type: string description: Unique identifier for the action @@ -2147,7 +2705,7 @@ components: $ref: '#/components/schemas/ActionCategory' name: type: string - description: Public action name, such as run_command or edit_files + description: 'Public action name, such as run_command or edit_files' input: type: object additionalProperties: true @@ -2155,20 +2713,20 @@ components: ActionResultContentBlock: type: object required: - - type - - action_id - - category - - name - - state - - output + - type + - action_id + - category + - name + - state + - output properties: type: type: string enum: - - action_result + - action_result message_id: type: string - description: Underlying transcript message ID that produced this content block, when available + description: 'Underlying transcript message ID that produced this content block, when available' action_id: type: string description: Identifier of the corresponding action @@ -2186,17 +2744,17 @@ components: EventContentBlock: type: object required: - - type - - name - - data + - type + - name + - data properties: type: type: string enum: - - event + - event message_id: type: string - description: Underlying transcript message ID that produced this content block, when available + description: 'Underlying transcript message ID that produced this content block, when available' name: type: string description: Event type for intentionally exposed non-core transcript events @@ -2206,10 +2764,10 @@ components: description: Minimal structured metadata for the event ArtifactItem: oneOf: - - $ref: '#/components/schemas/PlanArtifact' - - $ref: '#/components/schemas/PullRequestArtifact' - - $ref: '#/components/schemas/ScreenshotArtifact' - - $ref: '#/components/schemas/FileArtifact' + - $ref: '#/components/schemas/PlanArtifact' + - $ref: '#/components/schemas/PullRequestArtifact' + - $ref: '#/components/schemas/ScreenshotArtifact' + - $ref: '#/components/schemas/FileArtifact' discriminator: propertyName: artifact_type mapping: @@ -2220,14 +2778,14 @@ components: PlanArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - PLAN + - PLAN description: Type of the artifact created_at: type: string @@ -2238,14 +2796,14 @@ components: PullRequestArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - PULL_REQUEST + - PULL_REQUEST description: Type of the artifact created_at: type: string @@ -2256,14 +2814,14 @@ components: ScreenshotArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - SCREENSHOT + - SCREENSHOT description: Type of the artifact created_at: type: string @@ -2274,14 +2832,14 @@ components: FileArtifact: type: object required: - - artifact_type - - created_at - - data + - artifact_type + - created_at + - data properties: artifact_type: type: string enum: - - FILE + - FILE description: Type of the artifact created_at: type: string @@ -2292,11 +2850,11 @@ components: PlanArtifactData: type: object required: - - document_uid + - document_uid properties: artifact_uid: type: string - description: Unique identifier for the plan artifact, usable with the artifact retrieval endpoint + description: 'Unique identifier for the plan artifact, usable with the artifact retrieval endpoint' document_uid: type: string description: Unique identifier for the plan document @@ -2313,8 +2871,8 @@ components: PullRequestArtifactData: type: object required: - - url - - branch + - url + - branch properties: url: type: string @@ -2326,8 +2884,8 @@ components: ScreenshotArtifactData: type: object required: - - artifact_uid - - mime_type + - artifact_uid + - mime_type properties: artifact_uid: type: string @@ -2341,10 +2899,10 @@ components: FileArtifactData: type: object required: - - artifact_uid - - filepath - - filename - - mime_type + - artifact_uid + - filepath + - filename + - mime_type properties: artifact_uid: type: string @@ -2365,14 +2923,13 @@ components: type: integer format: int64 description: Size of the uploaded file in bytes - x-go-type-skip-optional-pointer: false ScheduleInfo: type: object description: Information about the schedule that triggered this run (only present for scheduled runs) required: - - schedule_id - - schedule_name - - cron_schedule + - schedule_id + - schedule_name + - cron_schedule properties: schedule_id: type: string @@ -2386,7 +2943,7 @@ components: PageInfo: type: object required: - - has_next_page + - has_next_page properties: has_next_page: type: boolean @@ -2400,7 +2957,7 @@ components: Status message for a run. For terminal error states, includes structured error code and retryability info from the platform error catalog. required: - - message + - message properties: message: type: string @@ -2435,8 +2992,8 @@ components: type: type: string enum: - - user - - service_account + - user + - service_account description: Type of the creator principal uid: type: string @@ -2454,15 +3011,15 @@ components: RunState: type: string enum: - - QUEUED - - PENDING - - CLAIMED - - INPROGRESS - - SUCCEEDED - - FAILED - - BLOCKED - - ERROR - - CANCELLED + - QUEUED + - PENDING + - CLAIMED + - INPROGRESS + - SUCCEEDED + - FAILED + - BLOCKED + - ERROR + - CANCELLED description: | Current state of the run: - QUEUED: Run is waiting to be picked up @@ -2477,15 +3034,15 @@ components: RunSourceType: type: string enum: - - LINEAR - - API - - SLACK - - LOCAL - - SCHEDULED_AGENT - - WEB_APP - - GITHUB_ACTION - - CLOUD_MODE - - CLI + - LINEAR + - API + - SLACK + - LOCAL + - SCHEDULED_AGENT + - WEB_APP + - GITHUB_ACTION + - CLOUD_MODE + - CLI description: | Source that created the run: - LINEAR: Created from Linear integration @@ -2500,8 +3057,8 @@ components: RunExecutionLocation: type: string enum: - - LOCAL - - REMOTE + - LOCAL + - REMOTE description: | Where the run executed: - LOCAL: Executed in the user's local Oz environment @@ -2520,9 +3077,6 @@ components: model_id: type: string description: LLM model to use (uses team default if not specified) - x-stainless-naming: - python: - method_argument: llm_id base_prompt: type: string description: Custom base prompt for the agent @@ -2557,7 +3111,6 @@ components: description: | Controls whether computer use is enabled for this agent. If not set, defaults to false. - x-go-type-skip-optional-pointer: false idle_timeout_minutes: type: integer format: int32 @@ -2567,7 +3120,6 @@ components: Number of minutes to keep the agent environment alive after task completion. If not set, defaults to 10 minutes. Maximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier). - x-go-type-skip-optional-pointer: false worker_host: type: string description: | @@ -2586,12 +3138,11 @@ components: description: Memory stores to attach to this run. inference_providers: allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' + - $ref: '#/components/schemas/InferenceProvidersConfig' description: | Optional inference provider settings for this run. Run-level config takes precedence over the agent's stored config and the workspace's admin-configured defaults. - x-go-type-skip-optional-pointer: false SessionSharingConfig: type: object description: | @@ -2605,8 +3156,8 @@ components: public_access: type: string enum: - - VIEWER - - EDITOR + - VIEWER + - EDITOR description: | Grants anyone-with-link access at the specified level to the run's shared session and backing conversation. @@ -2623,10 +3174,10 @@ components: type: type: string enum: - - oz - - claude - - gemini - - codex + - oz + - claude + - gemini + - codex description: | The harness type identifier. - oz: Warp's built-in harness (default) @@ -2691,10 +3242,10 @@ components: Additional extension members (e.g., `auth_url`, `provider`) may be present depending on the error code. required: - - type - - title - - status - - error + - type + - title + - status + - error properties: type: type: string @@ -2705,7 +3256,7 @@ components: See PlatformErrorCode for the list of possible error codes. title: type: string - description: A short, human-readable summary of the problem type (RFC 7807) + description: 'A short, human-readable summary of the problem type (RFC 7807)' status: type: integer description: The HTTP status code for this occurrence of the problem (RFC 7807) @@ -2731,9 +3282,9 @@ components: description: OpenTelemetry trace ID for debugging and support requests ArtifactResponse: oneOf: - - $ref: '#/components/schemas/PlanArtifactResponse' - - $ref: '#/components/schemas/ScreenshotArtifactResponse' - - $ref: '#/components/schemas/FileArtifactResponse' + - $ref: '#/components/schemas/PlanArtifactResponse' + - $ref: '#/components/schemas/ScreenshotArtifactResponse' + - $ref: '#/components/schemas/FileArtifactResponse' discriminator: propertyName: artifact_type mapping: @@ -2744,10 +3295,10 @@ components: type: object description: Response for retrieving a plan artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - artifact_uid + - artifact_type + - created_at + - data properties: artifact_uid: type: string @@ -2755,7 +3306,7 @@ components: artifact_type: type: string enum: - - PLAN + - PLAN description: Type of the artifact created_at: type: string @@ -2765,12 +3316,12 @@ components: $ref: '#/components/schemas/PlanArtifactResponseData' PlanArtifactResponseData: type: object - description: Response data for a plan artifact, including current markdown content. + description: 'Response data for a plan artifact, including current markdown content.' required: - - document_uid - - notebook_uid - - content - - content_type + - document_uid + - notebook_uid + - content + - content_type properties: document_uid: type: string @@ -2795,10 +3346,10 @@ components: type: object description: Response for retrieving a screenshot artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - artifact_uid + - artifact_type + - created_at + - data properties: artifact_uid: type: string @@ -2806,7 +3357,7 @@ components: artifact_type: type: string enum: - - SCREENSHOT + - SCREENSHOT description: Type of the artifact created_at: type: string @@ -2816,11 +3367,11 @@ components: $ref: '#/components/schemas/ScreenshotArtifactResponseData' ScreenshotArtifactResponseData: type: object - description: Response data for a screenshot artifact, including a signed download URL. + description: 'Response data for a screenshot artifact, including a signed download URL.' required: - - download_url - - expires_at - - content_type + - download_url + - expires_at + - content_type properties: download_url: type: string @@ -2832,7 +3383,7 @@ components: description: Timestamp when the download URL expires (RFC3339) content_type: type: string - description: MIME type of the screenshot (e.g., image/png) + description: 'MIME type of the screenshot (e.g., image/png)' description: type: string description: Optional description of the screenshot @@ -2840,10 +3391,10 @@ components: type: object description: Response for retrieving a file artifact. required: - - artifact_uid - - artifact_type - - created_at - - data + - artifact_uid + - artifact_type + - created_at + - data properties: artifact_uid: type: string @@ -2851,7 +3402,7 @@ components: artifact_type: type: string enum: - - FILE + - FILE description: Type of the artifact created_at: type: string @@ -2861,13 +3412,13 @@ components: $ref: '#/components/schemas/FileArtifactResponseData' FileArtifactResponseData: type: object - description: Response data for a file artifact, including a signed download URL. + description: 'Response data for a file artifact, including a signed download URL.' required: - - download_url - - expires_at - - content_type - - filepath - - filename + - download_url + - expires_at + - content_type + - filepath + - filename properties: download_url: type: string @@ -2893,14 +3444,13 @@ components: type: integer format: int64 description: Size of the uploaded file in bytes - x-go-type-skip-optional-pointer: false AttachmentInput: type: object description: A base64-encoded file attachment to include with the prompt required: - - file_name - - mime_type - - data + - file_name + - mime_type + - data properties: file_name: type: string @@ -2917,13 +3467,13 @@ components: ScheduledAgentItem: type: object required: - - id - - name - - cron_schedule - - enabled - - prompt - - created_at - - updated_at + - id + - name + - cron_schedule + - enabled + - prompt + - created_at + - updated_at properties: id: type: string @@ -2933,7 +3483,7 @@ components: description: Human-readable name for the schedule cron_schedule: type: string - description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC) + description: 'Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)' enabled: type: boolean description: Whether the schedule is currently active @@ -2943,17 +3493,16 @@ components: last_spawn_error: type: string nullable: true - description: Error message from the last failed spawn attempt, if any + description: 'Error message from the last failed spawn attempt, if any' agent_config: $ref: '#/components/schemas/AmbientAgentConfig' agent_uid: type: string format: uuid - x-go-type-skip-optional-pointer: false description: UID of the agent that this schedule runs as environment: allOf: - - $ref: '#/components/schemas/CloudEnvironmentConfig' + - $ref: '#/components/schemas/CloudEnvironmentConfig' description: Resolved environment configuration (if agent_config references an environment_id) created_at: type: string @@ -2991,15 +3540,15 @@ components: Request body for creating a new scheduled agent. Either prompt or agent_config.skill_spec or agent_config.skills is required. required: - - name - - cron_schedule + - name + - cron_schedule properties: name: type: string description: Human-readable name for the schedule cron_schedule: type: string - description: Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC) + description: 'Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)' prompt: type: string description: | @@ -3018,7 +3567,6 @@ components: agent_uid: type: string format: uuid - x-go-type-skip-optional-pointer: false description: | Agent UID to use as the execution principal for this schedule. Only valid for team-owned schedules. @@ -3029,16 +3577,15 @@ components: description: | Whether to create a team-owned schedule. Defaults to true for users on a single team. - x-go-type-skip-optional-pointer: false UpdateScheduledAgentRequest: type: object description: | Request body for updating a scheduled agent. Either prompt or agent_config.skill_spec or agent_config.skills is required. required: - - name - - cron_schedule - - enabled + - name + - cron_schedule + - enabled properties: name: type: string @@ -3063,7 +3610,6 @@ components: agent_uid: type: string format: uuid - x-go-type-skip-optional-pointer: false description: | Agent UID to use as the execution principal for this schedule. Only valid for team-owned schedules. @@ -3072,7 +3618,7 @@ components: ListScheduledAgentsResponse: type: object required: - - schedules + - schedules properties: schedules: type: array @@ -3082,7 +3628,7 @@ components: DeleteScheduledAgentResponse: type: object required: - - success + - success properties: success: type: boolean @@ -3100,7 +3646,7 @@ components: description: Optional description of the environment docker_image: type: string - description: Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag") + description: 'Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag")' github_repos: type: array items: @@ -3131,12 +3677,12 @@ components: type: object description: GCP Workload Identity Federation settings required: - - project_number - - workload_identity_federation_pool_id - - workload_identity_federation_provider_id + - project_number + - workload_identity_federation_pool_id + - workload_identity_federation_provider_id externalDocs: description: Google documentation on Workload Identity Federation - url: https://docs.cloud.google.com/iam/docs/workload-identity-federation + url: 'https://docs.cloud.google.com/iam/docs/workload-identity-federation' properties: project_number: type: string @@ -3147,14 +3693,17 @@ components: workload_identity_federation_provider_id: type: string description: Workload Identity Federation provider ID + service_account_email: + type: string + description: Optional GCP service account email to impersonate AwsProviderConfig: type: object description: AWS IAM role assumption settings externalDocs: description: AWS documentation on IAM OIDC federation - url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html + url: 'https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html' required: - - role_arn + - role_arn properties: role_arn: type: string @@ -3166,11 +3715,11 @@ components: agent or run. externalDocs: description: AWS documentation on IAM OIDC federation - url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html + url: 'https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html' properties: disabled: type: boolean - description: If true, opt out of Bedrock at this layer. + description: 'If true, opt out of Bedrock at this layer.' role_arn: type: string description: IAM role ARN to assume when calling Bedrock. @@ -3180,8 +3729,8 @@ components: GitHubRepo: type: object required: - - owner - - repo + - owner + - repo properties: owner: type: string @@ -3192,7 +3741,7 @@ components: ListAgentsResponse: type: object required: - - agents + - agents properties: agents: type: array @@ -3202,7 +3751,7 @@ components: ListConnectedSelfHostedWorkersResponse: type: object required: - - workers + - workers properties: workers: type: array @@ -3212,10 +3761,10 @@ components: ConnectedSelfHostedWorker: type: object required: - - worker_host - - connection_count - - connected_at - - last_seen_at + - worker_host + - connection_count + - connected_at + - last_seen_at properties: worker_host: type: string @@ -3234,8 +3783,8 @@ components: AgentListItem: type: object required: - - name - - variants + - name + - variants properties: name: type: string @@ -3248,11 +3797,11 @@ components: AgentListVariant: type: object required: - - id - - description - - base_prompt - - source - - environments + - id + - description + - base_prompt + - source + - environments properties: id: type: string @@ -3287,9 +3836,9 @@ components: AgentListSource: type: object required: - - owner - - name - - skill_path + - owner + - name + - skill_path properties: owner: type: string @@ -3309,8 +3858,8 @@ components: AgentListEnvironment: type: object required: - - uid - - name + - uid + - name properties: uid: type: string @@ -3322,14 +3871,14 @@ components: type: object description: Ownership scope for a resource (team or personal) required: - - type + - type properties: type: type: string enum: - - User - - Team - description: Type of ownership ("User" for personal, "Team" for team-owned) + - User + - Team + description: 'Type of ownership ("User" for personal, "Team" for team-owned)' uid: type: string description: UID of the owning user or team @@ -3360,32 +3909,210 @@ components: - `resource_unavailable` — Transient infrastructure issue (retryable) - `internal_error` — Unexpected server-side error (retryable) enum: - - insufficient_credits - - feature_not_available - - external_authentication_required - - not_authorized - - invalid_request - - resource_not_found - - budget_exceeded - - integration_disabled - - integration_not_configured - - operation_not_supported - - environment_setup_failed - - content_policy_violation - - conflict - - authentication_required - - resource_unavailable - - internal_error + - insufficient_credits + - feature_not_available + - external_authentication_required + - not_authorized + - invalid_request + - resource_not_found + - budget_exceeded + - integration_disabled + - integration_not_configured + - operation_not_supported + - environment_setup_failed + - content_policy_violation + - conflict + - authentication_required + - resource_unavailable + - internal_error + CreateExternalConversationRequest: + type: object + description: Request body for creating a new external conversation for a third-party harness. + required: + - format + properties: + format: + type: string + description: | + The conversation format identifying the harness type. + CreateExternalConversationResponse: + type: object + required: + - conversation_id + properties: + conversation_id: + type: string + description: The unique identifier of the newly created conversation. + ResolvePromptRequest: + type: object + description: Request body for resolving the effective prompt for a task. + properties: + skill: + type: object + description: Optional skill metadata to prepend to the prompt. + required: + - name + - content + properties: + name: + type: string + description: Human-readable name of the skill + content: + type: string + description: The resolved skill content + path: + type: string + description: Full path to SKILL.md (optional) + attachments_dir: + type: string + description: Directory where attachments were downloaded locally + ResolvePromptResponse: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The resolved prompt + system_prompt: + type: string + description: Optional system prompt addition for the harness + resumption_prompt: + type: string + description: | + Optional user-turn preamble for resumed third-party harness sessions. When + non-empty, the client should surface this to the harness alongside the user's + current turn (e.g. by prepending it to the prompt that the harness CLI reads). + Each harness decides exactly how to inject it, since the right placement varies + per CLI. Empty when no resumption is in effect. + context: + type: string + description: | + Optional server-retrieved context (e.g. agent memories) relevant to the + task prompt. When non-empty, the client should surface this alongside the + prompt so the harness can use it to inform its response. Each harness + decides how to inject this — typically by prepending it to the user-turn + prompt after any resumption preamble. + GetUploadTargetRequest: + type: object + description: Request body for obtaining a conversation-scoped upload target. + required: + - conversation_id + properties: + conversation_id: + type: string + description: The conversation ID to associate the uploaded data with. + UploadTarget: + type: object + description: | + A description of where and how to upload a blob. + + The caller should make an HTTP request to the given `url`, with the requested + HTTP `method` and all returned `headers`. + + For GET and PUT, the blob to upload should be the request body. + + For POST, use the `fields` to construct a multipart form body. The field order must + be preserved by the caller. + required: + - url + - method + - headers + - fields + properties: + url: + type: string + format: uri + description: The presigned URL to upload the blob to. + method: + type: string + enum: + - PUT + - POST + description: The HTTP method to use for the upload. + headers: + type: object + additionalProperties: + type: string + description: | + HTTP headers that must be included in the upload request. Some signed + URLs require validation headers such as `X-Goog-Content-Length-Range`; + omitting or changing those headers can cause storage to reject the upload. + fields: + type: array + items: + $ref: '#/components/schemas/UploadField' + description: | + Ordered multipart form fields for POST uploads. + UploadFieldValue: + oneOf: + - $ref: '#/components/schemas/StaticUploadFieldValue' + - $ref: '#/components/schemas/ContentCRC32CFieldValue' + - $ref: '#/components/schemas/ContentDataFieldValue' + discriminator: + propertyName: kind + mapping: + static: '#/components/schemas/StaticUploadFieldValue' + content_crc32c: '#/components/schemas/ContentCRC32CFieldValue' + content_data: '#/components/schemas/ContentDataFieldValue' + description: | + The value of a multipart form field in a presigned POST upload target. + StaticUploadFieldValue: + type: object + description: A literal string value. + required: + - kind + - value + properties: + kind: + type: string + enum: + - static + value: + type: string + ContentCRC32CFieldValue: + type: object + description: | + Marker for the client to provide a CRC32C checksum of the upload content. + + The checksum should be serialized as a base64-encoded big-endian 4-byte value. + required: + - kind + properties: + kind: + type: string + enum: + - content_crc32c + ContentDataFieldValue: + type: object + description: | + Marker for the client to provide the upload content. + required: + - kind + properties: + kind: + type: string + enum: + - content_data + UploadField: + type: object + description: | + A single name/value pair for a multipart form field in a presigned POST upload. + A field with a ContentDataFieldValue must be the last entry. + required: + - name + - value + properties: + name: + type: string + value: + $ref: '#/components/schemas/UploadFieldValue' RunFollowupRequest: type: object description: Request body for submitting a follow-up message to an existing run. - required: - - message properties: message: type: string - x-oapi-codegen-extra-tags: - binding: required description: The follow-up message to send to the run. mode: $ref: '#/components/schemas/AgentRunMode' @@ -3393,11 +4120,170 @@ components: Optional query mode for the follow-up. Defaults to `normal` when omitted. The server does not infer mode from prompt prefixes such as `/plan`. + HandoffSnapshotAttachmentInfo: + type: object + description: A handoff snapshot attachment exposed for download. + required: + - attachment_id + - filename + - download_url + properties: + attachment_id: + type: string + description: Identifier for the snapshot attachment within the run. + filename: + type: string + description: Original filename of the snapshot attachment. + download_url: + type: string + format: uri + description: Time-limited signed URL to download the snapshot attachment. + mime_type: + type: string + description: 'MIME type of the snapshot attachment, if known.' + ListHandoffSnapshotAttachmentsResponse: + type: object + description: Response body for listing handoff snapshot attachments. + required: + - attachments + properties: + attachments: + type: array + items: + $ref: '#/components/schemas/HandoffSnapshotAttachmentInfo' + description: | + Handoff snapshot attachments exposed by the latest ended execution. + Empty when no ended execution exists or no files were uploaded. + SnapshotUploadFileInfo: + type: object + description: A single file to upload as part of a handoff snapshot. + required: + - filename + properties: + filename: + type: string + description: Original filename for the snapshot file. + mime_type: + type: string + description: | + Optional MIME type to associate with the upload. Defaults to + `application/octet-stream` when omitted. + size_bytes: + type: integer + format: int64 + minimum: 0 + description: | + Optional declared file size in bytes. When present, the server rejects + files above the configured snapshot upload limit before returning upload + targets. Storage enforces the same limit during the PUT. + UploadSnapshotRequest: + type: object + description: Request body for requesting handoff snapshot upload targets. + required: + - files + properties: + files: + type: array + minItems: 1 + maxItems: 25 + items: + $ref: '#/components/schemas/SnapshotUploadFileInfo' + description: Files to upload. Up to 25 files may be requested per call. + UploadSnapshotResponse: + type: object + description: | + Response body for the handoff snapshot upload endpoint. The `uploads` + array is aligned by index with the `files` array in the request, so + callers can match each upload target back to the filename they + requested. + required: + - uploads + properties: + uploads: + type: array + items: + $ref: '#/components/schemas/UploadTarget' + description: Presigned upload targets aligned by index with the request files. + UploadLocalHandoffSnapshotRequest: + type: object + description: | + Request body for requesting upload targets for a local-to-cloud + handoff snapshot. Used before the cloud run is created; the server + mints a fresh `initial_snapshot_token` and returns presigned upload URLs + scoped to that token. + required: + - files + properties: + files: + type: array + minItems: 1 + maxItems: 100 + items: + $ref: '#/components/schemas/SnapshotUploadFileInfo' + description: | + Files to upload as part of the handoff snapshot. The per-call cap + mirrors the per-run snapshot file cap and must stay in sync with + `MaxHandoffSnapshotFiles` in `router/handlers/public_api/agent_handoff.go`. + UploadLocalHandoffSnapshotResponse: + type: object + description: | + Response body for the local-to-cloud handoff snapshot upload endpoint. + The `uploads` array is aligned by index with the `files` array in the + request, so callers can match each upload target back to the filename + they requested. The `initial_snapshot_token` is the server-minted token + that scopes the uploads to a `handoff/{token}/` GCS + prefix and is later passed back on `POST /agent/runs`. + required: + - initial_snapshot_token + - expires_at + - uploads + properties: + initial_snapshot_token: + type: string + description: | + Token to include on the subsequent `POST /agent/runs` request. + The server stores it on the queued execution's input so rehydration + discovery serves files from `handoff/{token}/`. + expires_at: + type: string + format: date-time + description: | + Time after which the presigned upload URLs are no longer valid. + The token itself is consumed by the subsequent `/agent/runs` call; + late uploads after `expires_at` will be rejected by GCS. + uploads: + type: array + items: + $ref: '#/components/schemas/UploadTarget' + description: Presigned upload targets aligned by index with the request files. + ForkConversationRequest: + type: object + description: | + Optional request body for the conversation fork endpoint. + properties: + title: + type: string + description: | + Optional title for the forked conversation. When omitted, + the fork inherits the source conversation's title. + ForkConversationResponse: + type: object + description: | + Response body for the conversation fork endpoint. + required: + - forked_conversation_id + properties: + forked_conversation_id: + type: string + description: | + ID of the newly materialized conversation, owned by the calling + principal. Pass this back as `conversation_id` (resume semantics) + on the subsequent `POST /agent/runs` request. ListModelsResponse: type: object required: - - default_model_id - - models + - default_model_id + - models properties: default_model_id: type: string @@ -3410,10 +4296,10 @@ components: ModelInfo: type: object required: - - id - - display_name - - provider - - vision_supported + - id + - display_name + - provider + - vision_supported properties: id: type: string @@ -3424,10 +4310,10 @@ components: provider: type: string enum: - - OPENAI - - ANTHROPIC - - GOOGLE - - UNKNOWN + - OPENAI + - ANTHROPIC + - GOOGLE + - UNKNOWN description: The LLM provider vision_supported: type: boolean @@ -3437,15 +4323,91 @@ components: description: Optional extra descriptor for the model reasoning_level: type: string - description: Reasoning level descriptor, if any (e.g. "low", "medium", "high") + description: 'Reasoning level descriptor, if any (e.g. "low", "medium", "high")' disable_reason: type: string enum: - - PROVIDER_OUTAGE - - OUT_OF_REQUESTS - - ADMIN_DISABLED - - REQUIRES_UPGRADE - description: If set, the model is currently unavailable for the given reason + - PROVIDER_OUTAGE + - OUT_OF_REQUESTS + - ADMIN_DISABLED + - REQUIRES_UPGRADE + description: 'If set, the model is currently unavailable for the given reason' + NotifyUserRequest: + type: object + description: Request body for sending a progress notification to the task's originating platform. + required: + - message + properties: + message: + type: string + description: | + The progress update message to send. Supports Markdown formatting. + FinishTaskRequest: + type: object + description: | + Request body for reporting task completion or failure. + Pull request links and branches are derived automatically from artifacts + previously reported via /harness-support/report-artifact. + required: + - success + - summary + properties: + success: + type: boolean + description: Whether the task completed successfully. + summary: + type: string + description: | + A summary of what was accomplished. If there are artifacts like + pull requests, describe what was created. + ReportArtifactRequest: + oneOf: + - $ref: '#/components/schemas/ReportPullRequestArtifactRequest' + discriminator: + propertyName: artifact_type + mapping: + PULL_REQUEST: '#/components/schemas/ReportPullRequestArtifactRequest' + ReportPullRequestArtifactRequest: + type: object + description: Request body for reporting a pull request artifact. + required: + - artifact_type + - data + properties: + artifact_type: + type: string + enum: + - PULL_REQUEST + description: Type of artifact being reported. + data: + $ref: '#/components/schemas/PullRequestArtifactData' + ReportArtifactResponse: + type: object + required: + - artifact_uid + properties: + artifact_uid: + type: string + description: Unique identifier for the created artifact + ReportShutdownRequest: + type: object + description: Request body for reporting that the agent process is shutting down. + properties: + error: + allOf: + - $ref: '#/components/schemas/ReportShutdownError' + ReportShutdownError: + type: object + description: Error reported by the shutting-down agent process. + properties: + category: + type: string + maxLength: 64 + description: Machine-readable shutdown error category. + message: + type: string + maxLength: 1024 + description: Human-readable error message. AgentSkill: type: object description: | @@ -3467,7 +4429,7 @@ components: ListEnvironmentsResponse: type: object required: - - environments + - environments properties: environments: type: array @@ -3478,10 +4440,10 @@ components: type: object description: A cloud environment for running agents required: - - uid - - config - - last_updated - - setup_failed + - uid + - config + - last_updated + - setup_failed properties: uid: type: string @@ -3513,7 +4475,7 @@ components: description: | Reference to a managed secret by name. required: - - name + - name properties: name: type: string @@ -3522,9 +4484,9 @@ components: type: object description: Reference to a memory store to attach to an agent. required: - - uid - - access - - instructions + - uid + - access + - instructions properties: uid: type: string @@ -3532,8 +4494,8 @@ components: access: type: string enum: - - read_write - - read_only + - read_write + - read_only description: Access level for the store. instructions: type: string @@ -3541,7 +4503,7 @@ components: CreateAgentRequest: type: object required: - - name + - name properties: name: type: string @@ -3585,7 +4547,7 @@ components: Optional base model for runs executed by this agent. inference_providers: allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' + - $ref: '#/components/schemas/InferenceProvidersConfig' description: | Optional inference provider settings for this agent. Agent-level config takes precedence over the workspace's @@ -3605,7 +4567,7 @@ components: Optional default harness for runs executed by this agent. harness_auth_secrets: allOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' + - $ref: '#/components/schemas/HarnessAuthSecrets' description: | Optional per-harness authentication secrets for this agent. Each field names a managed secret for the corresponding harness. @@ -3626,20 +4588,17 @@ components: nullable: true description: | Replacement description. Omit or pass `null` to leave unchanged, or use an empty value to clear. - x-go-type-skip-optional-pointer: false prompt: type: string nullable: true description: | Replacement prompt. Omit or pass `null` to leave unchanged, or use an empty value to clear. - x-go-type-skip-optional-pointer: false environment_id: type: string nullable: true description: | Replacement default cloud environment ID. Omit or pass `null` to leave unchanged, or pass an empty string to clear. - x-go-type-skip-optional-pointer: false secrets: type: array nullable: true @@ -3649,7 +4608,6 @@ components: Replacement list of secrets. Omit to leave unchanged, pass an empty array to clear, or pass a non-empty array to replace. Duplicate names are rejected. - x-go-type-skip-optional-pointer: false skills: type: array nullable: true @@ -3658,14 +4616,12 @@ components: description: | Replacement list of skill specs. Omit to leave unchanged, pass an empty array to clear, or pass a non-empty array to replace. - x-go-type-skip-optional-pointer: false base_model: type: string nullable: true description: | Replacement base model. Omit or pass `null` to leave unchanged, or pass an empty string to clear. - x-go-type-skip-optional-pointer: false memory_stores: type: array nullable: true @@ -3674,44 +4630,40 @@ components: description: | Replacement list of memory stores. Omit to leave unchanged, pass an empty array to clear, or pass a non-empty array to replace. - x-go-type-skip-optional-pointer: false inference_providers: type: object allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' + - $ref: '#/components/schemas/InferenceProvidersConfig' nullable: true description: | Replacement inference provider settings for this agent. Agent-level config takes precedence over the workspace's admin-configured defaults. Omit or pass `null` to leave unchanged. Pass an empty object `{}` to clear. - x-go-type-skip-optional-pointer: false base_harness: type: string nullable: true description: | Replacement default harness. Omit or pass `null` to leave unchanged, or pass an empty string to clear. - x-go-type-skip-optional-pointer: false harness_auth_secrets: allOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' + - $ref: '#/components/schemas/HarnessAuthSecrets' nullable: true description: | Replacement per-harness authentication secrets. Omit or pass `null` to leave unchanged, or pass an empty object to clear all secrets. - x-go-type-skip-optional-pointer: false AgentResponse: type: object required: - - uid - - name - - available - - created_at - - updated_at - - secrets - - skills - - memory_stores + - uid + - name + - available + - created_at + - updated_at + - secrets + - skills + - memory_stores properties: uid: type: string @@ -3768,7 +4720,7 @@ components: 3. The team's default model inference_providers: allOf: - - $ref: '#/components/schemas/InferenceProvidersConfig' + - $ref: '#/components/schemas/InferenceProvidersConfig' description: | The agent's stored inference provider settings. May be overridden by run-level config; if empty, falls back to the workspace's @@ -3789,7 +4741,7 @@ components: 3. Oz harness_auth_secrets: allOf: - - $ref: '#/components/schemas/HarnessAuthSecrets' + - $ref: '#/components/schemas/HarnessAuthSecrets' description: | Per-harness authentication secrets configured on this agent. Each field names a managed secret for the corresponding harness. @@ -3797,7 +4749,7 @@ components: ListAgentIdentitiesResponse: type: object required: - - agents + - agents properties: agents: type: array @@ -3807,11 +4759,11 @@ components: type: object description: Summary of the most recently created task for an environment required: - - id - - title - - state - - created_at - - updated_at + - id + - title + - state + - created_at + - updated_at properties: id: type: string @@ -3833,4 +4785,4 @@ components: type: string format: date-time nullable: true - description: When the task started running (RFC3339), null if not yet started + description: 'When the task started running (RFC3339), null if not yet started'