REST API

REST API overview

Locate Agent Studio's OpenAPI document, interactive API documentation, and resource references.

Use Agent Studio's OpenAPI 3.0 document to discover the supported REST surface and its operation-specific request contracts. Choose the interactive Swagger UI for exploration or fetch the JSON document for an OpenAPI-compatible client.

Documentation entry points

Both entry points are served from the Agent Studio origin. Replace https://agent-studio.example.com with the origin for your deployment.

Entry point	Format	Use it for
`/docs`	Interactive Swagger UI	Browse operations and inspect their schemas in a browser.
`/api/docs`	OpenAPI 3.0 JSON	Generate a client, import the contract into an API tool, or inspect it programmatically.

The JSON route allows cross-origin reads and sends Cache-Control: public, max-age=3600. A client or intermediary can therefore retain the document for up to one hour. Fetch it again when you need to confirm a recently changed contract.

ℹ️The OpenAPI document describes the generated REST contract. It does not establish that one authentication method works for every route. Check the selected operation and API authentication, errors, and limits before sending a request.

Fetch the OpenAPI document

Request the document from the same deployment you intend to call:

bash

curl --fail-with-body \
  --header 'Accept: application/json' \
  'https://agent-studio.example.com/api/docs' \
  --output agent-studio-openapi.json

The saved file is suitable for OpenAPI-compatible tooling. Keep generated clients tied to the document from their target deployment, and regenerate them when a relevant operation or schema changes.

To inspect the document without saving it, open /api/docs in a browser. To browse a rendered view, open /docs; the page is titled API Documentation — Agent Studio.

Resource groups

The REST reference is organized by reader-facing capability. Use the group that owns the operation you want to call.

Resource group	Coverage
Skills and canvas API	Skills, versions, and visual agent graphs.
Executions and approvals API	Workflow runs, execution state, and human approval requests.
MCP and OpenAPI API reference	Model Context Protocol servers and imported REST integrations.
Knowledge, evaluations, and benchmarks API	RAG collections, retrieval quality, evaluation datasets, and model benchmarks.
Organization and operations API	Organization administration and operational endpoints.

A2A protocol routes are documented separately because their discovery, streaming, auction, and debate workflows use protocol-specific behavior. Start with Discover A2A agents.

Read an operation contract

For each operation, confirm all of the following in the current OpenAPI document before implementing a client:

Use the exact HTTP method and path shown for the operation.
Supply every required path, query, header, and body parameter with the documented type.
Set the declared request content type, normally through the Content-Type header when the operation has a body.
Apply only the authentication mechanism documented for that route. Do not assume that an API key, browser session, or bearer token is accepted everywhere.
Handle the documented success and error statuses as separate response shapes.
Respect any operation-specific limits, defaults, and pagination fields rather than deriving them from another resource.

⚠️Do not send real secrets through Swagger UI examples, copied cURL commands, or shared API clients. Use visibly synthetic values until the request target and authentication boundary are verified.

Request example pattern

The following pattern is intentionally generic because the method, path, authentication header, and body differ by operation. Replace every placeholder with values from the selected operation—not values copied from another endpoint.

bash

curl --fail-with-body --request METHOD \
  --header 'Content-Type: application/json' \
  --header 'Authorization: AUTH_SCHEME AUTH_VALUE' \
  --data '{"field":"example-value"}' \
  'https://agent-studio.example.com/OPERATION_PATH'

Remove the Authorization header only when the operation explicitly permits an unauthenticated request. Remove Content-Type and --data for operations without a request body.

Response handling

Treat the operation definition as the source for response status and schema. A JSON error from one resource does not guarantee that every resource uses the same fields or retry behavior. Preserve the HTTP status and response body in development logs, while redacting tokens, cookies, authorization headers, and sensitive payload data.

When a response differs from the current document, first confirm that /api/docs came from the same origin as the request and that a cached copy is not being used. Then compare the operation in /docs with the deployed response before changing the client.

Next steps

Read API authentication, errors, and limits, then open the resource-group reference for the first operation your integration needs.