# Overwing API reference

> Every endpoint, generated from the live OpenAPI document (version 0.21.0). For request and response schemas, read https://overwing.ai/api/v1/openapi.json.

## Authentication

- **Organization key**, `ow_live_...`: `Authorization: Bearer <key>`. Issued by `POST /api/v1/signup` or the dashboard.
- **Agent key**, `ow_agent_...`: for Tower operations. Created by the organization and scoped to operations.
- **No key**: the Atlas lookup, the Atlas summary, the plan catalog, and pay-per-request over x402.

## Errors

Guardrails and Atlas return `{"error": "message"}`. Tower returns `{"error": {"code", "field", "message", "retryable", "suggested_fix"}}`. A 429 carries `Retry-After` in seconds.

## Tower

Overwing Tower: clearance for agents operating legacy systems. Typed operations, per-agent keys, policy decisions (auto / review / reject), human review, signed receipts.

| Endpoint | Auth | What it does |
|---|---|---|
| `POST /api/v1/tower/template` | key | Load the starter workflow (email PO to order entry, mock IBM i). Idempotent (organization key) |
| `GET /api/v1/tower/agents` | key | List agents; keys are never returned (organization key) |
| `POST /api/v1/tower/agents` | key | Create an agent identity; the key is returned once (organization key) |
| `DELETE /api/v1/tower/agents/{id}` | key | Revoke an agent; its key stops working at once (organization key) |
| `GET /api/v1/tower/capabilities` | key | Operations this agent may call, with JSON Schema inputs (agent key) |
| `POST /api/v1/tower/decide` | key | Run the policy for an operation without side effects |
| `POST /api/v1/tower/actions` | key | Request an action; auto-executes, queues for review, or rejects. Idempotent per agent on idempotency_key |
| `GET /api/v1/tower/actions/{id}` | key | Action status and result |
| `POST /api/v1/tower/actions/{id}/compensate` | key | Run the compensating operation for an executed action (idempotent) |
| `GET /api/v1/tower/receipts/{id}` | key | One receipt by id or sequence number |
| `GET /api/v1/tower/receipts/verify` | key | Recompute hashes and check signatures over a sequence range |
| `GET /api/v1/tower/receipts/public-key` | none | Ed25519 public key that signs receipts |
| `POST /api/v1/tower/checkout` | key | Start the metered Tower subscription (organization key) |
| `GET /api/v1/tower/subscription` | key | Tower status, quota, usage this month, pricing (organization key) |
| `DELETE /api/v1/tower/subscription` | key | Cancel the Tower subscription at period end |

## Preflight

Overwing Preflight: should an agent sign this Solana transaction? Simulates the unsigned transaction, compares what it would take from the wallet against the caller's policy, and answers allow or refuse. Every verdict is published.

| Endpoint | Auth | What it does |
|---|---|---|
| `GET /api/v1/preflight` | none | What Preflight checks, the policy fields, the reason codes, the guarantee and how to call it |
| `GET /api/v1/preflight/x402` | none | How to check an x402 payment before signing it |
| `POST /api/v1/preflight/x402` | optional | Should the agent sign this x402 payment? Terms against policy, payee against the directory and the server's manifest, price against the record (10 a day keyless) |
| `POST /api/v1/preflight/checks` | key | Check one unsigned Solana transaction against a policy before an agent signs it. Counts as one evaluation; a check that cannot be made is not counted |
| `GET /api/v1/preflight/checks/{id}` | none | The public record of one verdict and of every transaction reported against it. Never the wallet, the amounts or the transaction |
| `POST /api/v1/preflight/checks/{id}/reports` | none | Report the transaction that landed after a verdict. The answer (miss or not_a_miss) is read from the chain and published. No key |
| `GET /api/v1/preflight/record` | none | The public record: counts, every miss, the latest verdicts, and what the guarantee's reserve holds |
| `POST /api/x402/preflight` | none | Check one unsigned Solana transaction and pay $0.01 in USDC (x402), no account |
| `POST /api/x402/preflight/x402` | none | Should the agent sign this x402 payment? The same check as POST /api/v1/preflight/x402, paid $0.002 in USDC (x402), no account and no daily limit |

## Beacon

Overwing Beacon: is a site reachable by agents? One paid lookup that checks robots.txt, llms.txt, MCP, A2A and OpenAPI and how the home page reads to a model. No key: pay per check.

| Endpoint | Auth | What it does |
|---|---|---|
| `GET /api/v1/beacon` | none | What Beacon checks, what it costs, and how to call it |
| `GET /api/v1/beacon/sample` | none | A real report, free: the check of overwing.ai itself, refreshed daily |
| `POST /api/v1/beacon/checks` | optional | Start a check. Free. With a key the status address answers with the full report and the check is saved to that organization's dashboard; with no key it answers with the summary |
| `GET /api/v1/beacon/checks/{id}` | optional | The report for a check, as JSON or markdown, inline or as a file. The first request runs the check. With a key, the full report; with no key, the summary of a free check ("access" says which). A check paid over x402 is open in full to whoever holds its id |
| `GET /api/v1/beacon/saved` | key | Reports this organization has saved to its dashboard, newest first |
| `PUT /api/v1/beacon/saved/{id}` | key | Save a report to this organization's dashboard. Holding the report's id is what allows it |
| `DELETE /api/v1/beacon/saved/{id}` | key | Remove a report from the dashboard. The report stays readable at its address |
| `GET /api/x402/beacon` | none | Check whether a site is reachable by agents and pay $1 in USDC (x402), no account |
| `POST /api/x402/beacon` | none | The same check with the site in a JSON body, for clients that pay with POST |

## Atlas

Overwing Atlas: open data on AI agents. Registry, user-agent lookups, datasets, and reports. Separate product, same API key.

| Endpoint | Auth | What it does |
|---|---|---|
| `GET /api/v1/atlas` | none | Overwing Atlas overview: registry counts, datasets, tiers, endpoints |
| `GET /api/v1/atlas/agents` | none | Browse the agent registry (public fields; curated fields with Atlas Pro or Team) |
| `GET /api/v1/atlas/agents/{slug}` | none | One registry entry (with operator OSINT for Pro or Team) |
| `POST /api/v1/atlas/registrations` | key | Register your own agent in the registry. Free. Returns a value to publish at the operator's domain to prove control of it |
| `GET /api/v1/atlas/registrations` | key | This organization's registrations, newest first |
| `GET /api/v1/atlas/registrations/{id}` | key | Where one registration stands, with the verification values while it is unverified |
| `DELETE /api/v1/atlas/registrations/{id}` | key | Withdraw a registration. A published entry leaves the registry |
| `POST /api/v1/atlas/registrations/{id}/verify` | key | Look for the proof at the domain (TXT record at _overwing-atlas.<domain>, or /.well-known/overwing-atlas.txt). Found: the entry is published, or held for review when the operator name is already someone's. Safe to call again |
| `GET /api/v1/atlas/lookup` | optional | Identify a User-Agent string: what it claims to be and whether the claim can be trusted. Works with no key (10 a day per client); a key raises the limit |
| `GET /api/v1/atlas/summary` | none | Registry counts, browser-agent traffic shares, and the report summary |
| `GET /api/v1/atlas/sightings` | optional | Which registered agents visited overwing.ai, by day: requests, what they asked for, identity checks, answers (7 days keyless, 90 with a key) |
| `GET /api/v1/atlas/traffic` | none | State of agent traffic: shares by kind of client, busiest registered agents, what they ask for, identity checks, readiness panel; the whole observed period, updated nightly |
| `GET /api/v1/atlas/datasets` | none | Datasets with formats, row counts, license, and availability for your tier |
| `GET /api/v1/atlas/datasets/{id}` | key | Download a dataset (Atlas Pro or Team) |
| `GET /api/v1/atlas/report` | none | The research report as Markdown (?section=summary is free) |
| `GET /api/v1/atlas/subscription` | key | Your Atlas tier, limits, and lookups used today |
| `DELETE /api/v1/atlas/subscription` | key | Cancel the Atlas subscription at period end |
| `POST /api/v1/atlas/checkout` | key | Start an Atlas subscription (hosted Checkout URL) or switch plans in place |
| `GET /api/v1/atlas/lookup/sample` | none | A free preview of the lookup: the live answer for one fixed User-Agent. Unmetered |
| `GET /api/x402/atlas/lookup` | none | Identify a User-Agent and pay per lookup in USDC (x402), no account needed |
| `GET /api/x402/atlas/report` | none | The full Agent Consumers report as Markdown, paid once in USDC (x402) |

## CAD

Overwing CAD: describe a mechanical part, get a parametric model and STEP and STL files. Paid per part over x402.

| Endpoint | Auth | What it does |
|---|---|---|
| `POST /api/x402/cad` | none | Describe a part and get a parametric model with STEP and STL files, paid $0.50 in USDC (x402), no account |
| `GET /api/v1/cad/parts/{id}` | none | A saved part: script, measurements, assumptions and file addresses (no key; the id is the credential; kept 30 days) |
| `GET /api/v1/cad/parts/{id}/files/{name}` | none | One of a saved part's files (STEP or STL) as a download |

## Evaluate

Score text against a rule set

| Endpoint | Auth | What it does |
|---|---|---|
| `POST /api/v1/evaluate/batch` | key | Evaluate up to 50 inputs against one rule set in a single call |
| `POST /api/v1/evaluate` | optional | Evaluate text against a rule set. Works with no key (10 a day, inputs up to 2,000 characters, prebuilt rule sets); a key lifts the limits |
| `DELETE /api/v1/evaluations` | key | Bulk delete stored evaluations (all, or those before a date) |
| `GET /api/v1/evaluations` | key | List evaluations, newest first |
| `DELETE /api/v1/evaluations/{id}` | key | Delete one stored evaluation |
| `GET /api/v1/evaluations/{id}` | key | Fetch one evaluation with input and per-rule results |
| `GET /api/v1/feedback` | none | How to send feedback: what the route takes and its limits |
| `POST /api/v1/feedback` | optional | Tell Overwing what went wrong: a wrong verdict, an error you could not act on, a 402 you could not pay. No key needed; read by a person |
| `GET /api/v1/languages` | none | Input languages the prebuilt rule sets were tested in, with the date and size of the test |
| `POST /api/x402/evaluate` | none | Evaluate and pay per call in USDC (x402), no account needed |
| `POST /api/x402/execute` | none | The same paid evaluation, called as {service, params} (MoltsPay form) |

## Rule sets

Prebuilt and custom rule sets

| Endpoint | Auth | What it does |
|---|---|---|
| `GET /api/v1/rule-sets` | key | List rule sets visible to this org |
| `POST /api/v1/rule-sets` | key | Create a custom rule set |
| `GET /api/v1/rule-sets/{slug}` | key | Fetch a rule set with its rules |
| `PATCH /api/v1/rule-sets/{slug}` | key | Update a custom rule set (rules, if given, replace the full list) |
| `DELETE /api/v1/rule-sets/{slug}` | key | Deactivate a custom rule set (soft delete) |

## Account

Keys, usage, webhooks, identity

| Endpoint | Auth | What it does |
|---|---|---|
| `GET /api/v1/usage` | key | Daily usage and remaining quota |
| `GET /api/v1/me` | key | Identify the org behind the key |
| `GET /api/v1/api-keys` | key | List API keys (prefixes only) |
| `POST /api/v1/api-keys` | key | Mint a new API key (returned once) |
| `DELETE /api/v1/api-keys/{id}` | key | Revoke an API key |
| `GET /api/v1/webhook` | key | Current webhook configuration |
| `PUT /api/v1/webhook` | key | Set or rotate the webhook; the signing secret is returned once |
| `DELETE /api/v1/webhook` | key | Remove the webhook |
| `GET /api/v1/org` | key | The organization's data settings |
| `PATCH /api/v1/org` | key | Set whether input text is stored and how long evaluations are kept |
| `DELETE /api/v1/org` | key | Delete the organization and all its data; cancels any subscription first |
| `GET /api/v1/audit-log` | key | Security-relevant events for this org (keys, webhooks, rule sets, billing, rejected keys) |

## Onboarding

Self-serve account creation

| Endpoint | Auth | What it does |
|---|---|---|
| `POST /api/v1/signup` | none | Create an account, organization and first API key in one call. With no email (an empty body is enough) it is an agent's account: a key and no login, with a domain standing in for the email (see /api/v1/org/domain) |
| `POST /api/v1/org/domain` | key | Begin proving that this organization controls a domain. For an agent's account the domain stands in for an email: it lifts the limits, opens full Beacon reports, and recovers the account if the key is lost |
| `POST /api/v1/org/domain/verify` | key | Look for the proof at the domain (TXT record at _overwing-atlas.<domain>, or /.well-known/overwing-atlas.txt). Safe to call again |
| `POST /api/v1/org/claim` | key | A person takes charge of an agent's account: attaches an email and password, which gives it a dashboard login. Keys and history are unchanged |
| `POST /api/v1/signup/recover` | none | Begin recovering an agent's account whose key is lost, by the domain it proved. No key. The answer is the same whether or not an account holds the domain |
| `POST /api/v1/signup/recover/verify` | none | Finish a recovery: with the proof at the domain, every key on the account is revoked and one new key is returned, once |

## Billing

Plans and subscriptions (Stripe)

| Endpoint | Auth | What it does |
|---|---|---|
| `GET /api/v1/plans` | none | Public plan catalog with limits and prices |
| `GET /api/v1/billing` | key | Current plan, limit and subscription status |
| `DELETE /api/v1/billing` | key | Cancel at the end of the current period |
| `POST /api/v1/billing/checkout` | key | Hosted Stripe Checkout URL for a person to complete |
| `POST /api/v1/billing/subscribe` | key | Subscribe or switch plans with no browser |
| `POST /api/v1/billing/credits/checkout` | key | One-time Checkout for a prepaid credit pack (card or stablecoin) |
| `POST /api/v1/billing/portal` | key | Stripe customer portal URL (invoices, cards, cancel) |

## Meta

Health and discovery

| Endpoint | Auth | What it does |
|---|---|---|
| `GET /api/v1/health` | none | Liveness |
| `GET /api/v1/openapi.json` | none | This document |

## Clients

- MCP server: hosted at https://overwing.ai/mcp (no install), or `npx -y overwing-mcp`
- A2A: https://overwing.ai/a2a
- JavaScript and TypeScript: `npm install overwing`
- Python: `pip install overwing`
- OpenClaw: `openclaw plugins install overwing-openclaw --force && openclaw plugins enable overwing` (the gate on every outbound message), or the ClawHub skill `overwing`
- Guide for agents: https://overwing.ai/llms.txt