---
title: "AgentTwin REST API reference"
description: "Integrate AgentTwin agent testing with scoped OAuth, typed OpenAPI contracts, synced project discovery and asynchronous test runs."
canonical: "https://agenttwin.si/docs/api/"
---

# AgentTwin REST API reference

Integrate AgentTwin agent testing with scoped OAuth, typed OpenAPI contracts, synced project discovery and asynchronous test runs.


AgentTwin's REST API connects agent testing results to your workspace. It exposes synced project discovery, saved workflow drafts and reviewed cloud test jobs. Discovering a workflow does not prepare a runnable test.

## Specification and authentication

The API origin is `https://api.agenttwin.si`. Use the [OpenAPI 3.1 specification](/openapi.json) for exact request and response schemas, operation IDs, permissions and errors. Start with the [authentication walkthrough](/auth/) before accessing customer resources.

Create a confidential OAuth client with an existing account credential using `POST /v1/oauth/clients`. Bind it to one synced project and grant only the needed scopes. Exchange client credentials at `POST /oauth/token`. This supports OAuth 2.0 client credentials, not OpenID Connect or an authorization-code login flow. Keep client secrets on a trusted server.

Discover supported scopes through [protected-resource metadata](https://api.agenttwin.si/.well-known/oauth-protected-resource) and [authorization-server metadata](https://api.agenttwin.si/.well-known/oauth-authorization-server). The specification declares `read:projects`, `read:discovery`, `read:runs`, `read:workflows`, `write:runs` and `write:workflows`.

## Read project context

| Operation | Purpose |
| --- | --- |
| `GET /v1/projects` | List accessible synced projects |
| `GET /v1/discovery` | Read synced repository discovery |
| `GET /v1/workflows` | Read saved workflow test drafts |
| `GET /v1/runs` | List test runs |
| `GET /v1/runs/{id}` | Inspect a run and its evidence |

Use the query parameters and pagination fields declared in OpenAPI. Synced metadata is a snapshot, not a live view of a developer's filesystem. Run `npx agenttwin sync` in the original repository to publish reviewed updates.

## Submit and inspect a test

`POST /v1/runs` submits a reviewed prepared bundle for optional cloud execution. Successful submission returns `202 Accepted`; follow the returned run reference and poll `GET /v1/runs/{id}` until completion. Submission is not a passing test result. Inspect assertions and evidence before treating a workflow as verified. Cloud execution requires configured infrastructure and quotas.

Write requests support the `Idempotency-Key` contract declared in OpenAPI. Reuse the same key for retries of the same request, never for a changed payload. Follow the [versioning and deprecation policy](/api-policy/) and the response's rate-limit hints.

## Try a local test first

The [synthetic sandbox](/sandbox/) and [quickstart](/docs/quickstart/) run without a cloud account or production provider credentials. For coding-agent tools, use the [AgentTwin MCP guide](/docs/mcp/). The [developer index](/developers/) links the CLI and machine-readable documents.