# WOOL WOOL (Web Operations Orchestration Layer) runs AI agents from your prompts on your users' accounts on other websites, after each user authorizes your product to use that account. WOOL is for developers. Its authorization layer lets your users grant your product access to their accounts, which a chat agent a person runs on their own accounts can't offer. Your user authorizes at https://connect.trywool.com/v1/oauth/authorize, you exchange the code at POST https://api.trywool.com/v1/oauth/token for a connection access token, and you run an agent from a prompt with POST /v1/applications/{id}/executions. Contract: https://api.trywool.com/v1/openapi.yaml. A COMPLETED execution succeeded and holds a result; a FAILED one names its reason in terminal.status. Every page below is also available as Markdown by appending .md to its URL; the whole set is at /llms-full.txt. # WOOL - **Get started** - [Overview](/docs): WOOL runs AI agents from your prompts on your users' accounts on websites they authorize your product to use. - [Quickstart](/docs/quickstart): Connect a user's account and run your first execution from a public client. - [Server-side quickstart](/docs/quickstart-server): Connect and run from a backend that holds a client secret. - [Console](/docs/console): Where your applications, credentials, auth links, and test runs live. - **Concepts** - [Applications and clients](/docs/concepts/applications): What an application is, which client type to choose, and how redirect URIs and icons work. - [Identifiers and credentials](/docs/concepts/identifiers): The two credentials and four ids you'll handle, and which one history follows. - [Connections and authorization](/docs/concepts/connections): How a user's website account becomes a connection, and what happens to it afterwards. - [Executions](/docs/concepts/executions): The lifecycle of a run, what a completed run returns, and the eleven ways a run can fail. - [Results and evidence](/docs/concepts/results): What a completed run gives you, the evidence that comes with it, and why a run WOOL can't confirm fails. - [Isolation and security](/docs/concepts/isolation): The guarantees WOOL makes about your users' accounts. - [Data](/docs/concepts/data): What WOOL stores about your users, what it returns, and what you can delete. - **Guides** - [Writing prompts that succeed](/docs/guides/prompts): How to phrase a prompt so the agent does the right thing and the run completes. - [PKCE in a browser app](/docs/guides/pkce): Prove the code exchange without a secret, from a browser or native app. - [Confidential flow on a server](/docs/guides/confidential): Hold the secret on your backend and bind connections to your own user ids. - [Polling and history](/docs/guides/polling-and-history): Read a run while it's pending, and list a connection's runs afterwards. - [Handling failures](/docs/guides/failures): What your code should do for each of the eleven ways a run can fail. - [Structured results](/docs/guides/structured-results): Ask for JSON in a shape you choose, and read it from result.extracted. - [Re-authorization](/docs/guides/reauthorization): What to do when a website signs a user out. - [Idempotency](/docs/guides/idempotency): Make creating an execution safe to retry. - [Errors](/docs/guides/errors): The error envelope, every code, and what to do about each. - [Billing](/docs/guides/billing): Credits, what a run costs, what isn't charged, and how to keep a balance topped up. - [Testing with the playground](/docs/guides/playground): Try prompts against a real connection before you write code. - **Reference** - [Conventions](/docs/reference/conventions): How the API is shaped, so the generated reference reads without surprises. - OAuth - [The auth link](/docs/reference/oauth/authorize): The auth link. Send a user here to connect a website account to your application. The connect site, rather than the API, serves this page. It shows your application's name and icon and the website, asks the user to approve, and signs them in. It then redirects to `redirect_uri` with `code` and `state`, or with `error` (`access_denied` when the user declines, `server_error` when the sign-in fails) and `state`. An authorization expires 15 minutes after it starts; a code must be exchanged within 30 minutes. PKCE (`code_challenge` with S256) is optional for every client and recommended for public ones, because without a secret it is the only thing that ties the code exchange to the app that started it. - [Exchange a code for a token](/docs/reference/oauth/exchangeCode): Exchanges an authorization code for a connection access token. If your application is public, send `client_id` in the form body, plus the PKCE `code_verifier` when you sent a `code_challenge` on the auth link. If it's confidential, authenticate with HTTP Basic `client_id:client_secret`. The token is long-lived and doesn't refresh; issuing a new one for the same connection revokes the previous one. An invalid, expired, or used code returns `400 invalid_grant`. - [Revoke a token](/docs/reference/oauth/revokeToken): Revoke a connection access token. For a public application, send its `client_id` in the form body. For a confidential application, authenticate with HTTP Basic using `client_id:client_secret`. Use the application the token belongs to. The endpoint returns `200` whether or not the token was valid. The connection itself stays; revoke it from the console to delete its saved sign-in. - Executions - [Create an execution](/docs/reference/executions/createExecution): Starts an execution on the connection identified by your bearer access token and returns it as `QUEUED`. Send `Idempotency-Key` (1–255 characters) and reuse it with the same request body and connection on retries to retrieve the original execution. The same key with a different body returns `409 IDEMPOTENCY_KEY_REUSED`. If the connection needs the user to sign in again, you'll get `409 CONNECTION_REAUTHORIZATION_REQUIRED`; if your credit balance is empty, `402 INSUFFICIENT_CREDITS`. Use the returned `execution.id` to poll `GET /v1/applications/{applicationId}/executions/{executionId}` with the same access token until its `status` is `COMPLETED`, which means it succeeded and `result` is set, or `FAILED`, where `terminal.status` names the reason. - [Get an execution](/docs/reference/executions/getExecution): Return the execution identified by `executionId`, using the access token for its connection. - [List executions](/docs/reference/executions/listExecutions): Lists the connection's executions, newest first. The connection is the one your access token belongs to. A connection that needs re-authorization still lists its history, so you can show users what happened before they reconnect. - Contract - [Get the contract](/docs/reference/contract/getOpenApi): Return the OpenAPI document describing the WOOL API's routes, request fields, and responses. - **More** - [For coding agents](/docs/agents): The machine-readable surfaces of these docs and the API, for the AI agent writing your integration. - [Changelog](/docs/changelog): Changes to the API contract, newest first.