# Twinbay

- [Introduction](https://docs.twinbay.ai/index.md): Private, stateful copies of the APIs your agent calls
- [Quickstart](https://docs.twinbay.ai/quickstart.md): Seed a sandbox, point an SDK at it, read back what your code sent
- [Concepts](https://docs.twinbay.ai/concepts.md): Twins, sandboxes, scenarios, credentials, records, logs and time
- [Available twins](https://docs.twinbay.ai/twins.md): What each provider twin models, the scenarios it publishes, and where it stops
- [CLI](https://docs.twinbay.ai/cli.md): Provision and inspect sandboxes from a shell, a CI job, or a coding agent
- [MCP server](https://docs.twinbay.ai/mcp-server.md): Give a coding agent the sandbox operations as tools
- [Read the authenticated user](https://docs.twinbay.ai/api-reference/users/read-the-authenticated-user.md): Returns the caller, the organization their token acts in, and every organization they belong to with their role in each. A caller who has not joined an organization yet gets a null active organization, which is how the client knows to show onboarding.
- [List your organizations](https://docs.twinbay.ai/api-reference/organizations/list-your-organizations.md): Every organization the caller is a member of, with their role in each, oldest membership first. Independent of the organization the current token acts in. Paginated: walk the pages with `page` and `size`.
- [Create an organization](https://docs.twinbay.ai/api-reference/organizations/create-an-organization.md): Creates the organization in WorkOS with the caller as an admin, then mirrors it locally. The caller's current token is unchanged; refresh the AuthKit session into the new organization to act inside it.
- [Create your first organization](https://docs.twinbay.ai/api-reference/organizations/create-your-first-organization.md): Idempotent: answers with the caller's oldest organization when they already belong to one, and otherwise creates one named after them, with the caller as an admin. This is what signing up calls, so that onboarding never has to ask for a name. Refresh the AuthKit session into the organization to act…
- [Read the active organization](https://docs.twinbay.ai/api-reference/organizations/read-the-active-organization.md): The organization the access token acts in, plus the caller's role in it. Fails with 403 when the token names no organization.
- [Rename the active organization](https://docs.twinbay.ai/api-reference/organizations/rename-the-active-organization.md): Requires the **admin** role or above in the active organization.
- [List API keys](https://docs.twinbay.ai/api-reference/api-keys/list-api-keys.md): Every key of the active organization that has not been revoked, oldest first. A key that has expired is still listed, so that it can be read and cleaned up rather than vanishing unexplained; `expires_at` says which. Tokens are never included. Paginated: walk the pages with `page` and `size`.
- [Create an API key](https://docs.twinbay.ai/api-reference/api-keys/create-an-api-key.md): Mints a key for the active organization. It acts with the caller's role, read from their membership on every request, so it can never outrank them. The response is the only time the token is readable.
- [Revoke an API key](https://docs.twinbay.ai/api-reference/api-keys/revoke-an-api-key.md): The key stops working immediately. Its row stays, so a key seen in a log can still be named, and its token can never be minted again.
- [List available twins](https://docs.twinbay.ai/api-reference/twins/list-available-twins.md): Returns the registered code twins ordered by display name.
- [Retrieve a twin](https://docs.twinbay.ai/api-reference/twins/retrieve-a-twin.md)
- [List sandboxes](https://docs.twinbay.ai/api-reference/sandboxes/list-sandboxes.md)
- [Create a sandbox](https://docs.twinbay.ai/api-reference/sandboxes/create-a-sandbox.md): Records the sandbox and queues each twin for provisioning. The twins are not serving yet: poll the sandbox until each reports `ready`, then collect its API key.
- [Retrieve a sandbox](https://docs.twinbay.ai/api-reference/sandboxes/retrieve-a-sandbox.md)
- [Start a sandbox twin](https://docs.twinbay.ai/api-reference/sandboxes/start-a-sandbox-twin.md): Queues a fresh container. Its state and credentials are new.
- [Stop a sandbox twin](https://docs.twinbay.ai/api-reference/sandboxes/stop-a-sandbox-twin.md): Queues the container for destruction. Everything it holds is lost.
- [Collect the twin's API key](https://docs.twinbay.ai/api-reference/sandboxes/collect-the-twins-api-key.md): Returns the key once. A second call is refused.
- [List sandbox twin state](https://docs.twinbay.ai/api-reference/sandboxes/list-sandbox-twin-state.md)
- [Replace a sandbox twin record](https://docs.twinbay.ai/api-reference/sandboxes/replace-a-sandbox-twin-record.md)
- [Advance a deterministic twin lifecycle](https://docs.twinbay.ai/api-reference/sandboxes/advance-a-deterministic-twin-lifecycle.md)
- [List sandbox templates](https://docs.twinbay.ai/api-reference/sandboxes/list-sandbox-templates.md): Saved sandbox definitions. Start a sandbox from one by sending its id as `template` to `POST /sandboxes`.
- [Delete a sandbox template](https://docs.twinbay.ai/api-reference/sandboxes/delete-a-sandbox-template.md): Sandboxes already started from it are untouched.
- [List recent sandbox request logs](https://docs.twinbay.ai/api-reference/sandboxes/list-recent-sandbox-request-logs.md)
- [Retrieve a sandbox request log](https://docs.twinbay.ai/api-reference/sandboxes/retrieve-a-sandbox-request-log.md)
- [Read Root](https://docs.twinbay.ai/api-reference/healthchecks/read-root.md)
- [Read Health](https://docs.twinbay.ai/api-reference/healthchecks/read-health.md)

## OpenAPI Specs

- [openapi](https://api.twinbay.ai/openapi.json)