{ "openapi": "3.1.0", "info": { "title": "Ephemeral API", "version": "1.0.0", "summary": "Run AI agents on demand: start a task, follow it, read the result.", "description": "The Ephemeral engine API. Start agent runs (inline or from saved workflows), follow them with polling, server-sent events or signed callbacks, schedule workflows, upload files, configure connections to the APIs and MCP servers runs call, and read the model catalog.\n\n**Authentication.** Send an organization API key as `Authorization: Bearer `. Hosted keys start with `eak_`, self-hosted keys with `eph_`. A key belongs to one organization and has one of two roles, `member` or `admin`; each operation below states the role it needs (`x-required-role`). `GET /v1/models` needs no key.\n\n**Errors.** Every failure is JSON: `{\"error\": \"\", \"code\": \"\"}`, including unknown routes (404) and wrong methods (405).\n\n**Rate limits.** Requests with an API key are limited to 600 per minute per key; requests without one (such as `GET /v1/models`) to 120 per minute per client address. Every response carries `RateLimit-Policy`, `RateLimit`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Past the limit the API answers 429 (`code`: `rate_limited`) with `Retry-After` in seconds.\n\n**Money.** Fields ending in `_micros` are integer millionths of a US dollar. Timestamps are RFC 3339 in UTC. Unknown request fields are rejected with 400.\n\n**Versioning and deprecation.** The API is versioned in its path (`/v1`). Within a version changes are additive only. A breaking change ships as a new version under a new path; the previous version keeps working for at least six months, and while it is deprecated its responses carry `Deprecation` and `Sunset` headers. Policy: https://ephemer.al/docs/api#versioning-and-deprecation\n\nNot described here: the organization API at https://ephemer.al/v1 (members, invitations, keys, billing, licenses), which needs a signed-in user rather than an API key.", "termsOfService": "https://ephemer.al/legal/terms", "contact": { "name": "Ephemeral", "url": "https://ephemer.al" }, "license": { "name": "Ephemeral terms of service", "url": "https://ephemer.al/legal/terms" }, "x-api-catalog": "https://ephemer.al/.well-known/api-catalog" }, "externalDocs": { "description": "API reference", "url": "https://ephemer.al/docs/api" }, "servers": [ { "url": "https://app.ephemer.al", "description": "Hosted service" }, { "url": "https://{host}", "description": "Self-hosted engine, on your deployment's domain.", "variables": { "host": { "default": "ephemeral.example.com" } } } ], "tags": [ { "name": "Runs", "description": "Start agent runs, follow them and read their results." }, { "name": "Workflows", "description": "Saved run definitions that runs and schedules start by name." }, { "name": "Schedules", "description": "Start workflows on a cron timetable." }, { "name": "Files", "description": "Files runs can read in their working directory." }, { "name": "Connections", "description": "The HTTP APIs and MCP servers runs call through the engine." }, { "name": "Models", "description": "The models runs can use and their prices." }, { "name": "Organization", "description": "The organization behind the key." }, { "name": "Self-hosted administration", "description": "Endpoints that exist only on self-hosted engines." } ], "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "paths": { "/v1/me": { "get": { "operationId": "getCurrentOrganization", "tags": [ "Organization" ], "summary": "Get the organization and role behind the key", "description": "Returns the organization the credential belongs to, its role, the deployment mode and the settings that affect budgets. A cheap way to check that a key works.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "responses": { "200": { "description": "The organization and role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInfo" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/runs": { "post": { "operationId": "createRun", "tags": [ "Runs" ], "summary": "Start a run", "description": "Creates a run and queues it. Send a `prompt`, or the name of a saved `workflow`. If the run has an `input_schema` (its own or its workflow's), the `input` is validated first and a mismatch is refused with 400 and a readable message, such as `input.city: required`. The response is the new run in progress; follow it with `getRun`, `streamRunEvents` or a `callback`. On the hosted service the run's budget (`max_cost_micros`) is reserved from the organization's credits first.\n\nWith an `Idempotency-Key` that was used before, the existing run is returned with status 200 and nothing is created.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Up to 200 characters. If a run with this key already exists in the organization, it is returned with status 200 instead of creating another one. Ephemeral matches on the key alone and does not compare request bodies, so use a fresh key (such as a UUID) for each distinct run.", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "description": "The run definition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequest" } } } }, "responses": { "200": { "description": "A run with this `Idempotency-Key` already exists; it is returned unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "202": { "description": "The run was created and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "402": { "description": "Not enough available credits for the budget, or a licensed self-hosted installation has used its monthly run allowance (`code`: `payment_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "callbacks": { "onRunFinished": { "{$request.body#/callback/url}": { "post": { "operationId": "receiveRunCallback", "summary": "A run reached a final status", "description": "Sent once to `callback.url` after the run reaches a final status. The body is the run object. Any 2xx response counts as delivered; anything else, including a timeout or a redirect, is retried after 10 seconds, with the delay doubling up to about 43 minutes. Deliveries are stored durably and can arrive more than once: deduplicate by `X-Ephemeral-Run`. If `billing_pending` is true, read the run again later for its final cost.\n\nVerify the signature: compute HMAC-SHA256 over the string `.` keyed with `callback.secret`, compare `sha256=` with `X-Ephemeral-Signature` in constant time, and reject old timestamps (for example older than 5 minutes).", "parameters": [ { "name": "X-Ephemeral-Run", "in": "header", "required": true, "description": "The run ID.", "schema": { "type": "string" } }, { "name": "X-Ephemeral-Timestamp", "in": "header", "required": true, "description": "Unix time in seconds when this attempt was signed.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "X-Ephemeral-Signature", "in": "header", "required": true, "description": "`sha256=` followed by the lowercase hex HMAC-SHA256 of `.` keyed with the callback secret.", "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCallbackPayload" } } } }, "responses": { "2XX": { "description": "Delivered." }, "4XX": { "description": "Rejected by your endpoint. The delivery is retried with backoff." }, "5XX": { "description": "Failed on your side. The delivery is retried with backoff." } }, "security": [] } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" }, "get": { "operationId": "listRuns", "tags": [ "Runs" ], "summary": "List runs", "description": "Returns runs, newest first, optionally filtered by status or schedule. Pagination is opt-in: pass `limit` or `cursor` to get pages. Cursors are opaque and valid only with the same `status` and `schedule` filters. Runs listed never include output of a zero-data-retention run.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100. Turns on paginated responses.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Return only runs with this status.", "schema": { "type": "string", "enum": [ "reserving", "queued", "starting", "running", "succeeded", "failed", "cancelled", "timed_out", "interrupted" ] } }, { "name": "schedule", "in": "query", "required": false, "description": "Return only runs started by this schedule.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Without `limit` or `cursor`: a plain array of the 100 most recent matching runs. With either: a page object with `items` and `next_cursor`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, { "$ref": "#/components/schemas/RunPage" } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "`status`, `schedule`, `limit` or `cursor` is invalid (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/runs/{id}": { "get": { "operationId": "getRun", "tags": [ "Runs" ], "summary": "Get a run", "description": "Returns the run: status, output, error and cost. Poll until the status is final, or use events or a callback. For a zero-data-retention run, the first read after it finishes returns the output and deletes it; later reads omit it and report `output_available: false`.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The run does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/runs/{id}/cancel": { "post": { "operationId": "cancelRun", "tags": [ "Runs" ], "summary": "Cancel a run", "description": "Cancels a run that is `reserving`, `queued`, `starting` or `running` and returns it. A run that has already finished is returned unchanged. Cancelling stops the worker; it does not undo anything the agent already did through a connection.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The run, now cancelled or unchanged if it was already final.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The run does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/runs/{id}/events": { "get": { "operationId": "streamRunEvents", "tags": [ "Runs" ], "summary": "Stream a run's events", "description": "A server-sent event stream. It replays every recorded event, then sends new ones as they happen. Each message has `id`, `event` (the event type) and `data` (an Event object as JSON). When the run is final the stream sends an event named `done` whose data is the Run object, and closes. Lines starting with a colon are comments; a heartbeat comment arrives every 15 seconds. Disconnecting does not cancel the run; reconnect with `Last-Event-ID`.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run ID.", "schema": { "type": "string" } }, { "name": "Last-Event-ID", "in": "header", "required": false, "description": "Resume after this event ID, for example when reconnecting after a dropped connection.", "schema": { "type": "integer", "minimum": 0, "format": "int64" } } ], "responses": { "200": { "description": "An event stream (`text/event-stream`).", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE messages: `id: `, `event: `, `data: `; the last is `event: done` with the Run.", "x-message-data": { "oneOf": [ { "$ref": "#/components/schemas/Event" }, { "$ref": "#/components/schemas/Run" } ] } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "`Last-Event-ID` is not a non-negative integer (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The run does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/runs/{id}/definition": { "get": { "operationId": "getRunDefinition", "tags": [ "Runs" ], "summary": "Get the definition a run used", "description": "Returns the resolved definition the run actually used, prepared for review before running it again: files by ID, saved workflow fields filled in, workflow name and callback removed, and credentials stripped from inline connections (listed in `requires_credentials`). To run it again, restore those credentials and send `request` to `createRun`. The definition keeps the prompt, input and inline file contents as sent.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The run ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The definition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunDefinition" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The run does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "410": { "description": "The run was a zero-data-retention run, whose definition is not kept (`code`: `gone`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/workflows": { "get": { "operationId": "listWorkflows", "tags": [ "Workflows" ], "summary": "List saved workflows", "description": "Returns the organization's saved workflows as an array of objects. Each has the `name`. With `detail=true` each also has its `description`, `input_schema` and `output_schema` when set, so a client can discover what a workflow expects and returns without reading its prompt. Without it only the names are returned (a plain list is cheaper).\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "detail", "in": "query", "required": false, "description": "`true` adds `description`, `input_schema` and `output_schema` to each workflow.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The workflows.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowSummary" } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/workflows/{name}": { "get": { "operationId": "getWorkflow", "tags": [ "Workflows" ], "summary": "Get a saved workflow", "description": "Returns the workflow's definition. Credentials in its inline connections are removed.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The workflow name: 1 to 128 characters, letters, digits, `_`, `.` or `-`, starting with a letter or digit.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$" } } ], "responses": { "200": { "description": "The workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The workflow does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" }, "put": { "operationId": "saveWorkflow", "tags": [ "Workflows" ], "summary": "Create or replace a workflow", "description": "Saves a workflow under this name, replacing it if it exists. `input_schema` and `output_schema` must be valid JSON Schema objects of at most 32 KiB, and `description` at most 500 characters; otherwise the request is refused with 400 and nothing is saved. Credentials already stored for an inline connection are kept when the update leaves them out and the connection's endpoint is unchanged.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The workflow name: 1 to 128 characters, letters, digits, `_`, `.` or `-`, starting with a letter or digit.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$" } } ], "requestBody": { "required": true, "description": "The workflow definition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDefinition" } } } }, "responses": { "200": { "description": "Saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowName" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" }, "delete": { "operationId": "deleteWorkflow", "tags": [ "Workflows" ], "summary": "Delete a workflow", "description": "Deletes the saved workflow. Runs already started are not affected.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The workflow name: 1 to 128 characters, letters, digits, `_`, `.` or `-`, starting with a letter or digit.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The workflow does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/schedules": { "get": { "operationId": "listSchedules", "tags": [ "Schedules" ], "summary": "List schedules", "description": "Returns the organization's schedules, optionally only those that start one workflow.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "workflow", "in": "query", "required": false, "description": "Return only schedules of this workflow.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The schedules.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Schedule" } } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" }, "post": { "operationId": "createSchedule", "tags": [ "Schedules" ], "summary": "Create a schedule", "description": "Creates a schedule that starts a saved workflow on a cron timetable, in a time zone. Each slot starts a run like `createRun`, once. Slots missed while the engine was down run once, then the timetable resumes. The schedule pauses after 5 failed starts in a row. An organization can have 50 schedules.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "requestBody": { "required": true, "description": "`workflow` and `cron` are required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" } }, "/v1/schedules/preview": { "post": { "operationId": "previewSchedule", "tags": [ "Schedules" ], "summary": "Preview a timetable", "description": "Checks a cron expression and time zone and returns the next 5 start times, without saving anything.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "requestBody": { "required": true, "description": "The timetable to check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "cron" ], "properties": { "cron": { "type": "string", "examples": [ "0 9 * * 1-5" ] }, "timezone": { "type": "string", "default": "UTC", "examples": [ "Europe/Madrid" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The next start times, in UTC.", "content": { "application/json": { "schema": { "type": "object", "required": [ "next" ], "properties": { "next": { "type": "array", "items": { "type": "string", "format": "date-time" } } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/schedules/{id}": { "get": { "operationId": "getSchedule", "tags": [ "Schedules" ], "summary": "Get a schedule", "description": "Returns the schedule with its next and last run.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The schedule ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The schedule does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" }, "patch": { "operationId": "updateSchedule", "tags": [ "Schedules" ], "summary": "Update a schedule", "description": "Applies the fields present. A new timetable, or turning the schedule back on, counts from now; turning it on also clears the failures that paused it.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The schedule ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "The fields to change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleRequest" } } } }, "responses": { "200": { "description": "The updated schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The schedule does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" }, "delete": { "operationId": "deleteSchedule", "tags": [ "Schedules" ], "summary": "Delete a schedule", "description": "Deletes the schedule. Runs it already started are not affected.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The schedule ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The schedule does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" } }, "/v1/schedules/{id}/run": { "post": { "operationId": "runScheduleNow", "tags": [ "Schedules" ], "summary": "Start a schedule's workflow now", "description": "Starts the schedule's workflow immediately, outside its timetable, with the schedule's input and budget. Counts as the schedule's latest run.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The schedule ID.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "The run was created and queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "402": { "description": "Not enough available credits for the budget, or the monthly run allowance is used (`code`: `payment_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The schedule does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/files": { "get": { "operationId": "listFiles", "tags": [ "Files" ], "summary": "List uploaded files", "description": "Returns the organization's uploaded files.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "responses": { "200": { "description": "The files.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" }, "post": { "operationId": "uploadFile", "tags": [ "Files" ], "summary": "Upload a file", "description": "Stores a file of up to 1 MiB, which runs and workflows can place in the agent's working directory by `id` or name.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "requestBody": { "required": true, "description": "Multipart form data.", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FileUpload" } } } }, "responses": { "201": { "description": "Stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/files/{id}": { "get": { "operationId": "downloadFile", "tags": [ "Files" ], "summary": "Download a file", "description": "Returns the file's contents as an attachment with its detected content type.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file contents.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The file does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" }, "patch": { "operationId": "renameFile", "tags": [ "Files" ], "summary": "Rename a file", "description": "Changes the file's name (a relative path, up to 240 characters).\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "The new name.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 240 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Renamed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The file does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" }, "delete": { "operationId": "deleteFile", "tags": [ "Files" ], "summary": "Delete a file", "description": "Deletes the file and its contents.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The file ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The file does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1/connections": { "get": { "operationId": "listConnections", "tags": [ "Connections" ], "summary": "List saved connections", "description": "Returns the organization's saved connections with their public settings. Credentials are never included. Members can list what is available with `listConnectionCatalog`.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "responses": { "200": { "description": "The connections.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionSummary" } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" } }, "/v1/connections/{name}": { "get": { "operationId": "getConnection", "tags": [ "Connections" ], "summary": "Get a saved connection", "description": "Returns the connection with credentials removed.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The connection name: 1 to 128 characters, letters, digits, `_`, `.` or `-`, starting with a letter or digit.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$" } } ], "responses": { "200": { "description": "The connection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The connection does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" }, "put": { "operationId": "saveConnection", "tags": [ "Connections" ], "summary": "Create or replace a connection", "description": "Saves a connection under this name, replacing it if it exists. Credentials already stored are kept when the update leaves them out and the type is unchanged. The URL must be HTTPS and resolve to a public address.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The connection name: 1 to 128 characters, letters, digits, `_`, `.` or `-`, starting with a letter or digit.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$" } } ], "requestBody": { "required": true, "description": "The connection. `type` (`http` or `mcp`) is required; `ref` is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" } } } }, "responses": { "200": { "description": "Saved.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "http", "mcp" ] } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" }, "delete": { "operationId": "deleteConnection", "tags": [ "Connections" ], "summary": "Delete a connection", "description": "Deletes the saved connection. Workflows that reference it fail validation until updated.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The connection name: 1 to 128 characters, letters, digits, `_`, `.` or `-`, starting with a letter or digit.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$" } } ], "responses": { "204": { "description": "Deleted.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The connection does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" } }, "/v1/connections/{name}/oauth/start": { "post": { "operationId": "startConnectionOAuth", "tags": [ "Connections" ], "summary": "Begin OAuth authorization for a connection", "description": "For a connection whose `auth.type` is `oauth2`. Returns the provider's authorization URL; send a person there to approve access. The provider redirects to the engine's `/oauth/callback`, which stores the tokens.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "The connection name: 1 to 128 characters, letters, digits, `_`, `.` or `-`, starting with a letter or digit.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$" } } ], "responses": { "200": { "description": "Where to send the person.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The connection does not use OAuth, or its OAuth settings are invalid (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The connection does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" } }, "/v1/catalog/connections": { "get": { "operationId": "listConnectionCatalog", "tags": [ "Connections" ], "summary": "List the connections runs can reference", "description": "A member-safe view of the saved connections: name, type, allowed methods and tools, and whether it has credentials. URLs and authentication settings are left out.\n\nWorks with an API key of either role, `member` or `admin`, or (hosted service) an OAuth access token of either scope.", "responses": { "200": { "description": "The catalog.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionSummary" } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "member" ] }, { "oauth2": [ "member" ] } ], "x-required-role": "member" } }, "/v1": { "get": { "operationId": "getApiIndex", "tags": [ "Models" ], "summary": "API index", "description": "The API's base URL. Returns where to read about the API: the documentation, this OpenAPI description, the MCP server and the versioning and deprecation policy. No API key is needed.", "security": [], "x-required-role": "none", "responses": { "200": { "description": "Links to the API's documentation and machine-readable descriptions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "documentation": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "mcp": { "type": "string", "format": "uri" }, "versioning_policy": { "type": "string", "format": "uri" } }, "required": [ "name", "version" ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/models": { "get": { "operationId": "listModels", "tags": [ "Models" ], "summary": "List supported models", "description": "The models runs can use, with the provider's prices, and the default model. This is public information: no API key is needed (a key, if sent, is ignored). On the hosted service the list is filtered to models that support tools and have known pricing; a self-hosted engine returns its configured model and allows custom ones.", "security": [], "x-required-role": "none", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Return only models whose id or name contains this text, ignoring case.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCatalog" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "405": { "description": "Only GET is accepted (`code`: `method_not_allowed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "The model list is temporarily unavailable (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } } } }, "/v1/keys": { "get": { "operationId": "listApiKeys", "tags": [ "Self-hosted administration" ], "summary": "List API keys (self-hosted)", "description": "Self-hosted engines only. The hosted service manages keys through the signed-in organization API and answers 400 here.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "responses": { "200": { "description": "The keys, without their secrets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" }, "post": { "operationId": "createApiKey", "tags": [ "Self-hosted administration" ], "summary": "Create an API key (self-hosted)", "description": "Self-hosted engines only. Creates a key for the organization. The key is shown once in the response.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "requestBody": { "required": true, "description": "The key's name and role.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "member", "admin" ], "default": "member" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewApiKey" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" } }, "/v1/keys/{id}": { "delete": { "operationId": "deleteApiKey", "tags": [ "Self-hosted administration" ], "summary": "Revoke an API key (self-hosted)", "description": "Self-hosted engines only. Revokes the key immediately.\n\nRequires an API key with the `admin` role, or (hosted service) an OAuth access token with the `admin` scope; the person who authorized it must be an organization owner or admin.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The key ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revoked.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "401": { "description": "The API key or OAuth access token is missing, invalid, expired or revoked (`code`: `unauthorized`). On the hosted service the `WWW-Authenticate` header names the protected resource metadata, and carries `error=\"invalid_token\"` when a credential was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The credential's role cannot perform this action, or the organization is suspended (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "The key does not exist in this organization (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "A service Ephemeral depends on is temporarily unavailable. Retry with backoff (`code`: `unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } } }, "security": [ { "apiKey": [ "admin" ] }, { "oauth2": [ "admin" ] } ], "x-required-role": "admin" } }, "/admin/organizations": { "post": { "operationId": "bootstrapOrganization", "tags": [ "Self-hosted administration" ], "summary": "Create an organization and its first owner key (self-hosted)", "description": "Self-hosted engines only, answers 404 on the hosted service. The deployment administrator creates an organization and receives its first owner key; an organization that already has an active key answers 409. Authenticated with the deployment administrator key (`EPHEMERAL_ADMIN_KEY`), which authorizes only this endpoint.", "security": [ { "deploymentAdminKey": [] } ], "x-required-role": "deployment-admin", "requestBody": { "required": true, "description": "The organization ID.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$" } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string", "description": "The first owner key, shown once." } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "400": { "description": "The request is invalid. `error` names the problem; nothing was changed (`code`: `invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "403": { "description": "The deployment administrator key is required (`code`: `forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "404": { "description": "This is the hosted service (`code`: `not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "409": { "description": "The organization already has an active API key (`code`: `conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Ephemeral API key (eak_… hosted, eph_… self-hosted)", "description": "An organization API key sent as `Authorization: Bearer `. A key has one of two roles, which act as the permission scopes of this API:\n\n- `member`: start, follow, cancel and read runs; use saved workflows and connections by reference; list the connection catalog; read and manage workflows and files; read schedules, preview timetables and start a schedule now.\n- `admin`: everything a member can, plus create, change and delete connections and schedules, start OAuth for a connection, and (self-hosted) manage API keys.\n\nEach operation lists the role it needs in its `security` requirement (the array holds the role name, as OpenAPI 3.1 allows for non-OAuth schemes) and in the `x-required-role` extension. A key with a lower role gets 403. The key is created in the dashboard (or `POST /v1/keys` on a self-hosted engine) with its role chosen at creation. Applications that sign people in use the `oauth2` scheme instead. Machine-readable role list: https://app.ephemer.al/.well-known/oauth-protected-resource (RFC 9728 protected resource metadata, `scopes_supported`).", "x-roles": [ "member", "admin" ], "x-protected-resource-metadata": "https://app.ephemer.al/.well-known/oauth-protected-resource" }, "oauth2": { "type": "oauth2", "description": "OAuth 2.1 authorization for the hosted service, for applications that act on behalf of a person (MCP clients, integrations). The person signs in at Ephemeral, picks an organization and approves; the application receives an access token (`eoa_…`, valid one hour) and a rotating refresh token (`eor_…`, thirty days) and sends the access token as `Authorization: Bearer `, exactly where an API key goes. The token acts in that one organization with the granted scope: `member`, or `admin` (offered only to organization owners and admins). Authorization code flow with PKCE (`S256` is required); clients register themselves (RFC 7591) at `https://ephemer.al/oauth/register` or use a client ID they already hold. Tokens are bound to the resource `https://app.ephemer.al` (RFC 8707 `resource` parameter). People review and revoke authorized applications on their Account page; applications revoke with RFC 7009 at `https://ephemer.al/oauth/revoke`. Self-hosted engines accept API keys only. Authorization server metadata (RFC 8414): https://ephemer.al/.well-known/oauth-authorization-server.", "flows": { "authorizationCode": { "authorizationUrl": "https://ephemer.al/oauth/authorize", "tokenUrl": "https://ephemer.al/oauth/token", "refreshUrl": "https://ephemer.al/oauth/token", "scopes": { "member": "Start, follow, cancel and read runs; use workflows, files and saved connections in one organization.", "admin": "Everything member can, plus manage connections and schedules. Granted only to organization owners and admins." } } }, "x-authorization-server-metadata": "https://ephemer.al/.well-known/oauth-authorization-server", "x-registration-endpoint": "https://ephemer.al/oauth/register", "x-protected-resource-metadata": "https://app.ephemer.al/.well-known/oauth-protected-resource" }, "deploymentAdminKey": { "type": "http", "scheme": "bearer", "description": "Self-hosted only: the deployment administrator key (`EPHEMERAL_ADMIN_KEY`). It authorizes only `bootstrapOrganization`." } }, "headers": { "RateLimitPolicy": { "description": "The quota policy, per the IETF RateLimit header draft: `q` is the requests allowed per window and `w` the window in seconds. 600 per minute per API key; 120 per minute per client address for requests without a key.", "schema": { "type": "string" }, "example": "\"default\";q=600;w=60" }, "RateLimit": { "description": "Your current standing: `r` requests remaining in the window and `t` seconds until it resets.", "schema": { "type": "string" }, "example": "\"default\";r=598;t=41" }, "XRateLimitLimit": { "description": "Requests allowed per window (the same number as `q` in `RateLimit-Policy`).", "schema": { "type": "integer" }, "example": 600 }, "XRateLimitRemaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0 }, "example": 598 }, "XRateLimitReset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "minimum": 1, "maximum": 60 }, "example": 41 }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1, "maximum": 60 }, "example": 41 } }, "responses": { "RateLimited": { "description": "The rate limit was reached: 600 requests per minute per API key, 120 per minute per client address without a key (`code`: `rate_limited`). Wait `Retry-After` seconds.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "description": "Every error the engine returns is JSON with this shape, including unknown routes and wrong methods under /v1. `error` is a human-readable message that may change; `code` is a stable name for the HTTP status.", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "What went wrong, and usually what to change.", "examples": [ "timeout_seconds must be between 1 and 3600" ] }, "code": { "type": "string", "description": "Machine-readable name of the failure class.", "enum": [ "invalid_request", "unauthorized", "payment_required", "forbidden", "not_found", "method_not_allowed", "conflict", "gone", "rate_limited", "unavailable", "internal_error" ] } } }, "Run": { "type": "object", "description": "A run: one agent task, from queue to final answer and cost.", "required": [ "id", "status", "created_at", "billing_pending", "zero_data_retention" ], "properties": { "id": { "type": "string", "examples": [ "run_4abb0f420c6623a12d2889610eb67284" ] }, "status": { "type": "string", "enum": [ "reserving", "queued", "starting", "running", "succeeded", "failed", "cancelled", "timed_out", "interrupted" ], "description": "`reserving`, `queued`, `starting` and `running` are in progress; the rest are final." }, "output": { "type": "string", "description": "The agent's final answer. Omitted until there is one. Up to 1 MiB." }, "error": { "type": "string", "description": "Why the run did not succeed. Omitted when empty." }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "description": "When the run left the queue." }, "finished_at": { "type": "string", "format": "date-time", "description": "When the run reached a final status." }, "max_cost_micros": { "type": "integer", "format": "int64", "description": "The run's budget, in millionths of a US dollar." }, "cost_micros": { "type": "integer", "format": "int64", "description": "Cost so far, in millionths of a US dollar. Provisional until `billing_pending` is false on a finished run. Omitted when zero." }, "billing_pending": { "type": "boolean", "description": "Whether the cost still has to be settled." }, "schedule_id": { "type": "string", "description": "The schedule that started the run, when one did." }, "zero_data_retention": { "type": "boolean", "description": "True for a zero-data-retention run, whose content is not recorded." }, "surcharge_percent": { "type": "integer", "description": "The surcharge rate of a zero-data-retention run on the hosted service." }, "surcharge_micros": { "type": "integer", "format": "int64", "description": "The part of `cost_micros` added by the zero-data-retention surcharge. Omitted when zero." }, "output_available": { "type": "boolean", "description": "Zero-data-retention runs only: whether the output is still held for retrieval." }, "output_expires_at": { "type": "string", "format": "date-time", "description": "Zero-data-retention runs only: when a held output is deleted if nobody has read it." } } }, "RunPage": { "type": "object", "description": "A page of runs, newest first.", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "next_cursor": { "type": "string", "description": "Pass as `cursor` to get the next page. Empty on the last page." } } }, "RunRequest": { "type": "object", "description": "The definition of a run. Send a `prompt`, or the name of a saved `workflow` (other fields then override the saved ones). Unknown fields are rejected with 400.", "properties": { "description": { "type": "string", "maxLength": 500, "description": "What the workflow does and what input it expects, for people and agents. Up to 500 characters." }, "input_schema": { "type": "object", "description": "A JSON Schema (draft 2020-12, or draft 7 and earlier with `$schema`; up to 32 KiB; references only within the schema, such as `#/$defs/x`). The run's `input` must match it, or the run is refused with 400 and the path and reason of each problem, such as `input.city: required`. A run with no `input` is checked as `null`. Schedules are checked when created or updated and each time they start." }, "output_schema": { "type": "object", "description": "A JSON Schema (same dialect and limits as `input_schema`) the run's output must match. The agent is told the schema and asked to reply with JSON only, and to correct a reply that does not match (twice at most). When the run finishes, the engine checks the output again: a mismatch ends the run `failed` with `error` such as `output did not match output_schema: output.temp: required`, and the output text is kept for debugging (a zero-data-retention run keeps it only for its short delivery window and names no detail in `error`). A valid output is the JSON text, without any wrapping code fence." }, "prompt": { "type": "string", "maxLength": 131072, "description": "The task. Required unless `workflow` is set; with a workflow it replaces the saved prompt. Up to 128 KiB." }, "workflow": { "type": "string", "description": "Name of a saved workflow." }, "input": { "description": "Data for the task, passed to the agent as JSON. Any JSON value, up to 1 MiB." }, "model": { "type": "string", "description": "Model ID from `listModels`. Defaults to `default_model` there." }, "files": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/FileRef" }, "description": "Files placed in the agent's working directory." }, "connections": { "type": "object", "maxProperties": 16, "additionalProperties": { "$ref": "#/components/schemas/Connection" }, "description": "Connections keyed by the name the agent sees: `{\"ref\": \"\"}` or an inline definition." }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 3600, "default": 300, "description": "How long the run may take." }, "shell": { "type": "boolean", "default": true, "description": "Lets the agent run shell commands and write files in its working directory." }, "web": { "$ref": "#/components/schemas/Web" }, "zero_data_retention": { "type": "boolean", "default": false, "description": "Records nothing of the run's content: no stored events, no definition, and an output that is returned once. Hosted runs cost more." }, "max_cost_micros": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100000000, "description": "Budget in millionths of a US dollar. Defaults to `default_max_cost_micros` from `getCurrentOrganization`. On the hosted service it must cover the compute charge for the full timeout." }, "callback": { "$ref": "#/components/schemas/Callback" } }, "additionalProperties": false }, "WorkflowDefinition": { "type": "object", "description": "A saved workflow: a run definition without `workflow`, `input`, `max_cost_micros` and `callback`. Unknown fields are rejected with 400.", "required": [ "prompt" ], "properties": { "description": { "type": "string", "maxLength": 500, "description": "What the workflow does and what input it expects, for people and agents. Up to 500 characters." }, "input_schema": { "type": "object", "description": "A JSON Schema (draft 2020-12, or draft 7 and earlier with `$schema`; up to 32 KiB; references only within the schema, such as `#/$defs/x`). The run's `input` must match it, or the run is refused with 400 and the path and reason of each problem, such as `input.city: required`. A run with no `input` is checked as `null`. Schedules are checked when created or updated and each time they start." }, "output_schema": { "type": "object", "description": "A JSON Schema (same dialect and limits as `input_schema`) the run's output must match. The agent is told the schema and asked to reply with JSON only, and to correct a reply that does not match (twice at most). When the run finishes, the engine checks the output again: a mismatch ends the run `failed` with `error` such as `output did not match output_schema: output.temp: required`, and the output text is kept for debugging (a zero-data-retention run keeps it only for its short delivery window and names no detail in `error`). A valid output is the JSON text, without any wrapping code fence." }, "prompt": { "type": "string", "maxLength": 131072 }, "model": { "type": "string" }, "files": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/FileRef" } }, "connections": { "type": "object", "maxProperties": 16, "additionalProperties": { "$ref": "#/components/schemas/Connection" } }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "shell": { "type": "boolean" }, "web": { "$ref": "#/components/schemas/Web" }, "zero_data_retention": { "type": "boolean" } }, "additionalProperties": false }, "Web": { "description": "Web access for the run through the engine: `true` for fetch and search on every public domain, `false` for none, or an object to limit it. Default off.", "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "allow": { "type": "array", "maxItems": 50, "items": { "type": "string" }, "description": "Domains the agent may reach, such as `api.github.com` or `*.example.com`. Empty allows every public domain." }, "search": { "type": "boolean", "default": true, "description": "Set to false to allow fetching but not searching." } }, "additionalProperties": false } ] }, "FileRef": { "type": "object", "description": "A file for the run's working directory: either an uploaded file (`file`) or inline `content`, never both.", "required": [ "path" ], "properties": { "file": { "type": "string", "description": "ID or name of an uploaded file." }, "path": { "type": "string", "description": "Relative path in the working directory. Unique within the run. Defaults to the uploaded file's name." }, "content": { "type": "string", "maxLength": 1048576, "description": "Inline contents, up to 1 MiB. Inline files total at most 4 MiB." } }, "additionalProperties": false }, "Callback": { "type": "object", "description": "Where to send a signed request when the run ends. See the `onRunFinished` callback of `createRun` for the delivery.", "required": [ "url", "secret" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Your HTTPS endpoint. It must resolve to a public address; redirects are not followed." }, "secret": { "type": "string", "minLength": 24, "maxLength": 1024, "writeOnly": true, "description": "Signs each delivery. Never returned by any read." } }, "additionalProperties": false }, "Auth": { "type": "object", "description": "How a connection authenticates to the API behind it. Secret fields are write-only: reads return only the public part.", "properties": { "type": { "type": "string", "enum": [ "none", "bearer", "header", "basic", "oauth2" ] }, "token": { "type": "string", "writeOnly": true, "description": "For `bearer` and `header`." }, "header": { "type": "string", "description": "For `header`: the header name, such as `X-API-Key`." }, "username": { "type": "string", "description": "For `basic`. Cannot contain a colon." }, "password": { "type": "string", "writeOnly": true, "description": "For `basic`." }, "client_id": { "type": "string", "description": "For `oauth2`." }, "client_secret": { "type": "string", "writeOnly": true, "description": "For `oauth2` clients that have one." }, "authorization_url": { "type": "string", "description": "For `oauth2`: the provider's authorization endpoint (HTTPS)." }, "token_url": { "type": "string", "description": "For `oauth2`: the provider's token endpoint (HTTPS)." }, "token_auth_method": { "type": "string", "enum": [ "client_secret_basic", "client_secret_post", "none" ] }, "resource": { "type": "string", "description": "Optional resource indicator sent with the authorization request." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes of the *connected service* to request." }, "access_token": { "type": "string", "writeOnly": true }, "refresh_token": { "type": "string", "writeOnly": true }, "expires_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "Connection": { "type": "object", "description": "A connection to an HTTP API or an MCP server that runs call through the engine, which adds the credentials. Saved connections have `type` and `url`; inside a run, `{\"ref\": \"\"}` uses a saved one.", "properties": { "ref": { "type": "string", "description": "Name of a saved connection. Only inside a run or workflow, never when saving." }, "type": { "type": "string", "enum": [ "http", "mcp" ] }, "url": { "type": "string", "description": "HTTPS base URL of the API, or the MCP server's Streamable HTTP endpoint. Must resolve to a public address." }, "auth": { "$ref": "#/components/schemas/Auth" }, "allowed_methods": { "type": "array", "items": { "type": "string" }, "description": "HTTP connections: methods runs may use, such as `[\"GET\"]`. Empty allows all." }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "MCP connections: tool names runs may call. Empty allows all." }, "instructions": { "type": "string", "maxLength": 4000, "description": "How the agent should use the API. Shown to the agent, so keep secrets out." } }, "additionalProperties": false }, "ConnectionSummary": { "type": "object", "description": "A saved connection as listed. Credentials are never included.", "required": [ "name", "type", "authenticated" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "http", "mcp" ] }, "allowed_methods": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_tools": { "type": [ "array", "null" ], "items": { "type": "string" } }, "authenticated": { "type": "boolean", "description": "Whether the connection has credentials." }, "url": { "type": "string", "description": "Omitted by the member catalog. Secrets in the URL are removed." }, "auth": { "$ref": "#/components/schemas/Auth", "description": "The public part of the authentication settings. Omitted by the member catalog." } } }, "Event": { "type": "object", "description": "One entry of a run's trace.", "required": [ "id", "type", "data", "created_at" ], "properties": { "id": { "type": "integer", "format": "int64", "description": "Increasing. Send as `Last-Event-ID` to resume." }, "type": { "type": "string", "description": "Common types: `status`, `worker_started`, `connection_ready`, `tool_start`, `tool_end`, `text_delta`, `model_usage`, `usage`, `connection`, `web_request`, `web_search`, `web_refused`, `result`, `model_call_refused`, `output_limit`, `output_truncated`, `events_skipped`, `worker_error`, `microvm_starting`, `microvm_ready`, `microvm_terminated`. New types may be added; ignore ones you do not know." }, "data": { "description": "Type-specific JSON." }, "created_at": { "type": "string", "format": "date-time" } } }, "RunDefinition": { "type": "object", "required": [ "request", "requires_credentials" ], "properties": { "request": { "$ref": "#/components/schemas/RunRequest", "description": "The resolved definition the run used. Workflow name and callback are left out; saved connections keep only their reference and allowlists; inline connections lose their credentials and secrets in their URL." }, "requires_credentials": { "type": "array", "items": { "type": "string" }, "description": "Inline connections that need credentials or their original URL restored before the request is sent again." } } }, "Workflow": { "type": "object", "description": "A saved workflow as returned by a read: credentials in its inline connections are removed.", "allOf": [ { "$ref": "#/components/schemas/WorkflowDefinition" } ] }, "WorkflowName": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "WorkflowSummary": { "type": "object", "description": "A workflow in a detailed list: its name, and the description and schemas when it has them.", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string", "maxLength": 500, "description": "What the workflow does and what input it expects, for people and agents. Up to 500 characters." }, "input_schema": { "type": "object", "description": "A JSON Schema (draft 2020-12, or draft 7 and earlier with `$schema`; up to 32 KiB; references only within the schema, such as `#/$defs/x`). The run's `input` must match it, or the run is refused with 400 and the path and reason of each problem, such as `input.city: required`. A run with no `input` is checked as `null`. Schedules are checked when created or updated and each time they start." }, "output_schema": { "type": "object", "description": "A JSON Schema (same dialect and limits as `input_schema`) the run's output must match. The agent is told the schema and asked to reply with JSON only, and to correct a reply that does not match (twice at most). When the run finishes, the engine checks the output again: a mismatch ends the run `failed` with `error` such as `output did not match output_schema: output.temp: required`, and the output text is kept for debugging (a zero-data-retention run keeps it only for its short delivery window and names no detail in `error`). A valid output is the JSON text, without any wrapping code fence." } } }, "File": { "type": "object", "description": "An uploaded file (up to 1 MiB).", "required": [ "id", "name", "size", "content_type", "created_at" ], "properties": { "id": { "type": "string", "examples": [ "file_9c41d2a07be35f1e8a6c0d4b9e2f7a13" ] }, "name": { "type": "string", "description": "A relative path, up to 240 characters." }, "size": { "type": "integer", "format": "int64", "description": "Bytes." }, "content_type": { "type": "string", "description": "Detected from the contents." }, "created_at": { "type": "string", "format": "date-time" } } }, "FileUpload": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file, up to 1 MiB." }, "name": { "type": "string", "maxLength": 240, "description": "Relative path to store it under. Defaults to the uploaded file's name." } } }, "Model": { "type": "object", "description": "A model runs can use, with the provider's published prices.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "examples": [ "anthropic/claude-sonnet-4.5" ] }, "name": { "type": "string" }, "context_length": { "type": "integer", "format": "int64" }, "pricing": { "type": "object", "additionalProperties": true, "description": "The provider's price per token (and per request, image and so on), as decimal strings in US dollars." }, "supported_parameters": { "type": "array", "items": { "type": "string" } }, "top_provider": { "type": "object", "properties": { "context_length": { "type": "integer", "format": "int64" }, "max_completion_tokens": { "type": "integer", "format": "int64" } } } } }, "ModelCatalog": { "type": "object", "required": [ "items", "default_model", "custom_models_allowed" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "default_model": { "type": "string", "description": "Used when a run names no model." }, "custom_models_allowed": { "type": "boolean", "description": "False on the hosted service, which accepts only catalog models." } } }, "Schedule": { "type": "object", "description": "A saved workflow started on a cron timetable.", "required": [ "id", "workflow", "cron", "timezone", "skip_if_running", "enabled", "next_run_at", "failures", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "examples": [ "sch_0f3a9c2b5d7e41a8b6c0d9e2f1a37b54" ] }, "workflow": { "type": "string", "description": "The saved workflow it starts." }, "name": { "type": "string", "maxLength": 128 }, "cron": { "type": "string", "description": "Five fields (minute hour day-of-month month day-of-week) or a descriptor such as `@daily` or `@every 15m`. At most once a minute.", "examples": [ "0 9 * * 1-5" ] }, "timezone": { "type": "string", "default": "UTC", "description": "An IANA zone name such as `Europe/Madrid`.", "examples": [ "Europe/Madrid" ] }, "input": { "description": "JSON passed to every run it starts, up to 1 MiB." }, "max_cost_micros": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 100000000, "description": "Budget of each run. 0 or omitted uses the default." }, "skip_if_running": { "type": "boolean", "default": true, "description": "Skip a start while the previous run is still going." }, "enabled": { "type": "boolean", "default": true }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Null while disabled." }, "last_run_at": { "type": "string", "format": "date-time" }, "last_run_id": { "type": "string" }, "last_error": { "type": "string", "description": "Why the last start failed or was skipped." }, "failures": { "type": "integer", "description": "Consecutive failed starts. The schedule pauses after 5." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ScheduleRequest": { "type": "object", "description": "Create requires `workflow` and `cron`. Update applies only the fields that are present. Unknown fields are rejected.", "properties": { "workflow": { "type": "string" }, "name": { "type": "string", "maxLength": 128 }, "cron": { "type": "string" }, "timezone": { "type": "string" }, "input": { "description": "Any JSON value, up to 1 MiB." }, "max_cost_micros": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 100000000 }, "skip_if_running": { "type": "boolean" }, "enabled": { "type": "boolean" } }, "additionalProperties": false }, "OrganizationInfo": { "type": "object", "required": [ "organization_id", "role", "mode" ], "properties": { "organization_id": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "What the credential may do. An API key is `admin` or `member`; a signed-in user may also be `owner`." }, "mode": { "type": "string", "enum": [ "hosted", "self-hosted" ] }, "compute_micros_per_second": { "type": "integer", "format": "int64", "description": "Compute rate used to charge and authorize runs." }, "default_max_cost_micros": { "type": "integer", "format": "int64", "description": "Budget applied when a run request has no `max_cost_micros`." }, "zdr_surcharge_percent": { "type": "integer" }, "zdr_event_window_seconds": { "type": "integer", "format": "int64" }, "zdr_output_window_seconds": { "type": "integer", "format": "int64" } } }, "ApiKey": { "type": "object", "required": [ "id", "name", "role" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "member", "admin" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "NewApiKey": { "type": "object", "required": [ "id", "name", "role", "key" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "member", "admin" ] }, "key": { "type": "string", "description": "The key. Shown once; store it now." } } }, "RunCallbackPayload": { "description": "The body of a callback delivery: the run object as it is at delivery time.", "allOf": [ { "$ref": "#/components/schemas/Run" } ] } } } }