Control API reference#

Use the Agents API for Agent, Session, Turn, Item, environment, Vault, File, Skill and Artifact operations. The official SDK uses the deployment's Agents endpoint, including live SSE. The control endpoint below owns IAM-authenticated integration installation, provider bindings, schedules and Session artifact publications.

The deployment's /openapi.json is authoritative for installed routes. Signed provider ingress resolves the binding creator as Session owner and retains the provider sender separately. See provider bindings.

Authentication and ownership#

Deployment discovery and contract documents (GET /health, GET /.well-known/rat-things, GET /openapi.json, and GET /schemas/*.json) are public and contain no owner data. Publication share redemption uses its own bearer grant. Every other integration/application control route requires an IAM principal supplied by API Gateway through its userArn or callerId.

The handler derives ownerId from that value. A caller cannot supply or select its owner. The X-Runtime-Owner escape hatch works only when ALLOW_OWNER_HEADER=true; this is for isolated local testing and must be false in a deployed stack.

The included Terraform module configures AWS_IAM on owner-scoped control routes and no authorization on the discovery/contract routes. The handler contains a JWT sub extraction hook for a separately maintained transport adapter, but v1 discovery/OpenAPI does not advertise bearer authentication; it is not a supported direct-client surface in the provided stack.

Resources are readable, listable and cancellable only by their derived owner. Provider Sessions belong to the authenticated creator of the matching source binding.

Routes#

The standard Agents transport supports live SSE and saved Items. Callers do not select private MicroVM execution IDs or receive AWS-issued proxy tokens. Trusted Session orchestration owns continuation and cancellation. Provider receipts identify the accepted integration input; they do not expose private execution records.

Integration connection contract#

GET /v1/integrations/plugins is the form and tool-generation contract. Each manifest declares one or more authentication schemes with exact credential fields, plus typed operations with access, risk, required provider scopes, and input-schema metadata.

Connection creation accepts only:

{
  "version": "1",
  "pluginId": "stripe",
  "authScheme": "api-key",
  "credential": { "api_key": "..." },
  "grant": { "version": "1", "preset": "read-only" }
}

alias is the only optional setup field. The server verifies the credential before creating a secret and derives the label, provider tenant/subject, access, and scopes. Callers cannot submit those claims or an owner ID. A verification failure is 400 invalid_request and creates no connection; provider throttling, 5xx, or network failure is retryable 503 integration_unavailable. Repeating the request with another credential creates another independently permissioned account for the same plugin.

Connection creation does not accept an idempotency key. If its response is lost, reconcile provider-derived identity from the owner list before retrying.

The CLI implements the manual contract as rat-things connect PLUGIN --credential-file FILE [--auth-scheme SCHEME] [--access PRESET] and configured self-hosted OAuth as rat-things connect PLUGIN --oauth [--wait] [--no-browser] [--access PRESET]. --wait keeps the CLI attached until the callback installs and verifies the new connection; without it, the CLI returns the short-lived authorization URL immediately. Credential rotation uses rat-things rotate ACCOUNT --credential-file FILE. The unified management form is rat-things connection reconnect ACCOUNT --credential-file FILE for manual credentials or rat-things connection reconnect ACCOUNT --oauth [--wait] [--no-browser] for OAuth. The server preserves the connection ID, alias, grant, and consumers, and verifies that the replacement resolves to the same provider tenant/subject before replacing it. See the complete Integration Contract v1.

Connection operations have direct CLI parity: rat-things connection show ACCOUNT, connection test ACCOUNT, connection consumers ACCOUNT, connection rename ACCOUNT --name NAME, and connection reconnect ACCOUNT. test runs only in the authenticated host control plane, may refresh an expiring OAuth record through the trusted broker, and persists only status/code/timestamps. It is not available to an agent as a dynamic tool. consumers reads owner-scoped definitions without opening the credential vault. The AWS reference deployment also checks a rotating, bounded slice of stale connections on a schedule. That job has its own narrow IAM role and stores only the same bounded health projection.

For the built-in Slack channel bridge, rat-things slack-events ACCOUNT --agent-id AGENT_ID [--environment-template TEMPLATE_ID] [--json] derives the team selector from the verified Connection, creates or reuses the owner Connection Set/source binding, and rejects a second Connection that attempts to route mentions for the same workspace. The command's output is JSON; --json is accepted for consistency with other machine-oriented CLI commands.

Discovery and error contract#

Consumers should fetch /.well-known/rat-things from the deployment instead of assuming a central runtime URL. Its links are relative so custom domains and reverse proxies remain independent. The same OpenAPI and JSON Schema files are published with the documentation for generation and CI, but an installed deployment is authoritative for the capabilities it advertises.

The response also links the focused agent guide, compact llms.txt navigation, and optional operational agent corpus. Agents should read the guide and progressively follow the installed contracts; they should not load that broad corpus or guess every operation for a simple Session. See Connect an agent to Rat Things.

Installed JSON Schemas use relative $id values, so relative references resolve against the exact deployment that served them rather than silently switching to the central documentation copy. Schema maxLength is character-based preflight; runtime UTF-8 byte limits remain authoritative.

Errors use a stable envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid schedule expression",
    "retryable": false,
    "traceId": "API_GATEWAY_REQUEST_ID"
  }
}

Preserve traceId when reporting an issue. invalid_request, forbidden, not_found, and conflict are not retryable without changing state or input. Unexpected internal failures hide their details from the caller and set retryable: true; use bounded structured logs for diagnosis.

Durable files#

Use the standard Files API for uploads and Session Artifacts for retained output. Artifact downloads require the owning principal. Creating a publication is an explicit application operation that mints an expiring bearer grant; it does not change the Session resource. See durable files and sharing work.

Schedules#

Schedules target an Agent and environment using the separate schedule contract. Execution, provider ingress, and result notification remain separate stages.