Skip to main content
Everything the console does is available under the REST API at /api/v1. This page covers the conventions that hold across every endpoint; for the exact request and response shape of each one, use the interactive reference served by your own workspace host.

​
Base URL

Every endpoint lives under your workspace host. Set it once and the examples throughout these docs work as written:
REST endpoints are then "$AGENTOPS_URL/api/v1/...".
The same host exposes a few sibling surfaces: /internal/mcp (the MCP server), /gateway/mcp (the MCP Gateway), /a2a/... for agent-to-agent traffic, and /auth/....

​
The interactive reference

The full, always-current reference is served at /api/docs on your workspace host, and the API link in the top navigation points there. Because it is generated from the running service, it is authoritative in a way a written page cannot be — you can try requests against your own workspace from the browser.

​
Authentication

Send an API key as a bearer token on every request:
A key acts either as a service account — preferred for automation — or as the person who created it. Console requests use the signed session from single sign-on instead. Either way the request is bound to one identity in one workspace, and what it may do is governed by that identity’s roles and grants.

​
Errors

An unauthenticated request gets a JSON 401. Other failures return a standard status with a JSON body carrying a readable message:
A 404 can mean “exists, but not in your workspace”. Resources are scoped to the workspace the request resolved to, so a cross-workspace read is a not-found rather than a forbidden — which is what keeps one workspace from confirming another’s resources exist.

​
Pagination

List endpoints that can return large result sets accept limit, and offset where supported. The exact parameters and any cursor or count fields are documented per endpoint in the interactive reference.

​
Input shapes worth knowing

  • Invoke and schedule endpoints wrap the run parameters under an "input" key.
  • Inbound endpoints are different: the whole request body is handed to the agent as its input.

​
Next steps

API keys

Issue, reveal, and revoke the tokens these calls use.

MCP server

The same capabilities as tools, for a model to call.

Python SDK

Building the agents these endpoints invoke.

Limits & quotas

The caps a 409 is telling you about.