# Throughline API

Facts version 2026-11-13.1, checked against hosted service source (`d8d2f2c`), installed on 2026-11-12. Public routes, authentication boundaries and an existing account's noncharged usage passed. Real browser approval and paid checkout flows require their own tests. Examples are illustrative.

Throughline is a read-only HTTP feed that says which news articles are relevant to which Polymarket contracts, and why. Coverage starts with the most actively traded markets and will expand. It publishes no forecasts, probabilities, positions or trade instructions.

- Base URL: `https://api.throughline.markets`
- Get a key: https://api.throughline.markets/account (Google and GitHub sign-in), or let a program ask for one and approve it there (see Connecting a program)
- Key location: the `THROUGHLINE_API_KEY` environment variable
- Agent setup: https://throughline.markets/agents.md
- OpenAPI 3.1: https://throughline.markets/openapi.json
- JSON Schema: https://throughline.markets/schema/throughline-v3.json
- Fact sheet these documents are checked against: https://throughline.markets/facts.json
- The `throughline` command and the Python and JavaScript clients: https://github.com/mokn/throughline
- Changes: https://throughline.markets/changelog

## First request

```sh
curl -sS 'https://api.throughline.markets/v1/news?cursor=0&limit=1' \
  -H "Authorization: Bearer $THROUGHLINE_API_KEY"
```

`curl` places the key on a command line, which other processes on the same machine can read. That is fine for a first look on your own computer. In a program, read the variable and send the header from inside the process; https://throughline.markets/agents.md has a Python example that does this.

A 200 looks like this. This is an illustrative sample with an invented article and market; the shape is exact.

```json
{
  "items": [
    {
      "cursor": 2,
      "envelope": {
        "schema": "ThroughlinePublicationV3",
        "stream_id": "example_stream",
        "sequence": 2,
        "operation": "upsert",
        "record_id": "d8d7ed58df866df1ad9484d1613d09844839fef1cda249e947a29817d5c03bcb",
        "record": {
          "report_id": "report-1",
          "source_revision_id": "revision-1",
          "source_revision_kind": "captured_feed_revision",
          "publisher": "Example News",
          "title": "Illustrative: border framework talks scheduled",
          "url": "https://news.example/article",
          "language": "en",
          "published_at": "2026-11-03T12:00:00Z",
          "received_at": "2026-11-03T12:00:03Z",
          "source_clock_status": "reported",
          "captured_content": "body",
          "publisher_completeness": "unknown",
          "market": {
            "venue": "polymarket",
            "condition_id": "0x1111111111111111111111111111111111111111111111111111111111111111",
            "title": "Illustrative: border agreement signed by deadline?",
            "url": null,
            "rules_sha256": "2222222222222222222222222222222222222222222222222222222222222222",
            "deadline_at": "2027-06-30T23:59:59Z"
          },
          "relevance": {
            "stage": "scout",
            "assessed_at": "2026-11-03T12:00:15Z",
            "verdict": "relevant",
            "novelty": "new",
            "why_relevant": "Illustrative reason: the article names the parties and the process this contract is about.",
            "explanation_kind": "public_explanation"
          },
          "analysis": {
            "stage": "analyst",
            "assessed_at": "2026-11-03T12:04:40Z",
            "report_status": "reported",
            "impact": 3,
            "why_relevant": "Illustrative reason: the article reports a scheduled negotiating round, a step this contract's rules name as a precondition.",
            "explanation_kind": "public_explanation"
          },
          "evidence": [
            {
              "report_id": "report-1",
              "source_revision_id": "revision-1",
              "url": "https://news.example/article"
            }
          ]
        }
      }
    }
  ],
  "next_cursor": 2,
  "has_more": false
}
```

## Routes

All feed routes are `GET`, need `Authorization: Bearer <key>`, and take no body.

| Route | Query | Returns |
|---|---|---|
| `/v1/news` | `cursor`, `limit`, `market_id` | A page of changes, oldest first |
| `/v1/markets/{condition_id}/news` | `cursor`, `limit` | The same feed for one contract |
| `/v1/news/{record_id}` | `stream_id` | The current head of one match, including a withdrawal |
| `/v1/coverage` | none | Supplied coverage facts, unknowns explicit |
| `/v1/usage` | none | The account's plan and today's usage: `{plan, usage}` |

- `cursor`: digits, or the exact word `latest`. `0`, the default, replays from the start of retained history. Otherwise send the `next_cursor` from your last response. `latest` captures the current head once (see Starting from now). There is no snapshot route.
- `limit`: digits. Defaults to the server page size and may not exceed it. The installed default and maximum are 20 changes per page.
- `market_id`: one exact condition ID, `0x` followed by 64 lower-case hexadecimal characters. Not a slug, event ID or token ID. Anything else, in the query or in the market route's path, is `400 invalid_market_id`.
- `stream_id`: only for `/v1/news/{record_id}`, when the answer is `409 ambiguous_record`.
- Any other parameter, or a repeated one, is `400 invalid_query`. There is no server-side filter by stage, novelty or impact.

`GET /v1/usage` is not counted against the news allowance. It has its own separate allowance, sends no `X-RateLimit` headers and takes no query string and no body.

The pairing and account routes are described under Connecting a program and Account routes below.

`GET /` on the API host needs no key and is not charged. It returns four public pointers: `name`, `account`, `docs` and `agents`.

`GET /account/` and `GET /account` with any query string answer `303` to the fixed `/account`. The query is discarded, never copied into the redirect.

## Connecting a program

A program asks for access with a pairing. One signed-in person opens the link, checks the code, chooses the permissions and approves or denies. The program then collects a receipt with key and connection details.

The `throughline` command in the public client repository does all of this and keeps the secrets in private files. Install it from the repository, pinned to one commit (there is no package-registry release):

```
python3 -m pip install "git+https://github.com/mokn/throughline@df5cd8a0bc6aa063bd9da9ca37c33115f54096f2"
```

Then `throughline login --name "<name>"` starts a pairing and `throughline login --wait` collects the result. It prints one JSON object and never a credential. https://throughline.markets/agents.md is the step-by-step version for a coding agent.

What happens on the wire:

1. The program generates the feed key itself and, when it asks for more than `news:read`, a management credential. It sends only their SHA-256 hashes. Throughline activates the hashes on approval. The program sends the credentials as HTTPS bearer tokens when it uses them.
2. `POST /auth/v1/pairings`, no credential, JSON body with exactly `name`, `scopes`, `feed_key_hash` and `management_token_hash`. `management_token_hash` is `null` exactly when `scopes` is `["news:read"]`. The two hashes must differ. The answer has `pairing_id`, `device_code`, `user_code`, `expires_in`, `interval`, `verification_uri` and `verification_uri_complete`.
3. The program shows the person `verification_uri_complete` and `user_code`. `device_code` is a secret and is never shown.
4. The person opens the link, signs in, checks that the code on the page is the same code, chooses what to allow and approves or denies. They can also start the seven-day trial as part of approving. This step needs a browser sign-in session; no key or management credential can do it.
5. `POST /auth/v1/token`, no credential, JSON body with exactly `device_code`, no more often than `interval` seconds. Every answer that is not a delivery is HTTP `400`, told apart by `error`:
   - `authorization_pending` (the body also has `"status": "pending"`): nobody has decided yet. Poll again after `interval` seconds.
   - `access_denied`: the person said no. Definitive: nothing is active.
   - `expired_token`: the code is unknown or its window has ended. See below.
   - `200` with `"status": "delivered"`: approved. The receipt has `key` (`id`, `name`, `created_at`) and `connection` (`id`, `name`, `scopes`, `created_at`, `expires_at`), and no secret. The key the program generated now works.

**`expired_token` is not proof that nobody approved.** If approval happened and the receipt was not collected in time, the key is active. A program that started a pairing and then gets `expired_token` must keep its pending secrets, report that delivery is unknown, and ask the person to look under "Your connections" in the account page and revoke the named connection if it is not wanted. The `throughline` command reports this as `"status": "delivery_unknown"` with exit code 4. Do not report that nothing was activated.

Permissions (scopes):

| Scope | Allows |
|---|---|
| `news:read` | A feed API key for the news, coverage and usage routes. Always part of a pairing. |
| `account:read` | GET /account/v1/me, without its billing fields. |
| `keys:read` | GET /account/v1/keys. |
| `keys:write` | POST /account/v1/keys and DELETE /account/v1/keys/{key_id}. Account-wide: it can revoke any key on the account, including ones made in the account page, and new keys use the account's shared key slots. |
| `billing:read` | GET /account/v1/billing/read. |

- The person may grant fewer scopes than were asked for. `news:read` is always part of a pairing.
- A management credential is sent as `Authorization: Bearer <management credential>`, only to the account routes that name its scope, and never with an `Origin` header. Without the scope the answer is `403 scope_forbidden`.
- `expires_in` is the approval window. `connection.expires_at` is when the management credential stops working. A feed key issued through a pairing has no expiry of its own; it works until it or its connection is revoked.
- The running configuration has a ten-minute approval window, a five-second poll interval, a 24-hour receipt window and a 30-day management credential, verified 2026-11-12. Read `expires_in`, `interval` and `connection.expires_at` from the responses.
- Payment is never delegated. Checkout and the billing portal need the person's own browser session.

The `throughline` command prints one of these statuses: `ok`, `pending`, `delivered`, `denied`, `slow_down`, `cancelled`, `delivery_unknown`, `error`. Exit codes: 0 success; 2 pending or slow down; run again later; 3 denied or cancelled; 4 error or delivery unknown. It keeps the feed key in `.env`, a pairing that is still waiting in `.throughline/pending.json` and the management credential in `.throughline/credentials.json`. It refuses to write until `.env` and `.throughline/` are ignored by git, and it never edits `.gitignore` itself.

## Account routes

| Route | Who can call it | Does |
|---|---|---|
| `GET /account/v1/me` | sign-in session, or `account:read` | Plan, trial, pricing, usage and the account's `activation` summary. A management credential does not get the billing fields or `activation`. |
| `GET /account/v1/keys` | sign-in session, or `keys:read` | Lists keys with `last_used_at`, never a secret. |
| `POST /account/v1/keys` | sign-in session, or `keys:write` | Creates a key. The secret is in this one response. |
| `DELETE /account/v1/keys/{key_id}` | sign-in session, or `keys:write` | Revokes a key. |
| `GET /account/v1/billing/read` | sign-in session, or `billing:read` | Billing state from the service's own records: `configured`, `live`, `status`, `paid_through`, `cancel_at_period_end`. |
| `GET /account/v1/pairings/{user_code}` | sign-in session only | Shows a pairing request before deciding. |
| `POST /account/v1/pairings/{user_code}` | sign-in session only | Approves or denies it: exactly `decision` (`approve` or `deny`), `scopes` and `start_trial`. |
| `GET /account/v1/connections` | sign-in session only | Lists connections newest first with their scopes, keys and last use. `next_cursor` is `null` on the last page. |
| `DELETE /account/v1/connections/{connection_id}` | sign-in session only | Revokes the connection, its management credential and every key it holds. |
| `POST /account/v1/trial` | sign-in session only | Starts the seven-day trial. |
| `GET /account/v1/billing/status`, `POST /account/v1/billing/checkout`, `POST /account/v1/billing/portal` | sign-in session only | Provider billing status, checkout and the billing portal. |

A feed API key cannot call any account route. The sign-in session belongs to the account page; these routes are listed so that the behaviour is documented, not as an invitation to script a browser session.

## Reading forward

1. Request `/v1/news?cursor=<saved cursor>`.
2. Apply every item in order (rules below).
3. Save the records and `next_cursor` together, then use it for the next request. Do not advance the cursor before saving.
4. `has_more: true` means read again now. `has_more: false` means you are at the head: wait before the next poll.

### Starting from now

A new consumer that does not want retained history can capture the head once, on `/v1/news` or `/v1/markets/{condition_id}/news`:

1. Request `?cursor=latest`. The reply is a successful empty page: `items: []`, `has_more: false`, and `next_cursor` set to the current head as a number.
2. Save that number before you poll. After a restart, reuse the saved number.
3. Poll with the number from then on.

- Send `latest` once per consumer. Never send `latest` on every poll: each repeat skips whatever arrived in between.
- The head is the head of the whole feed, also with `market_id` or on the market route.
- The capture is a `200` and counts as one news response.
- Only the exact lower-case word is accepted; anything else that is not digits is `400 invalid_pagination`.
- Replay from `cursor=0`, and the default when `cursor` is omitted, are unchanged.
- Reference-client helpers that start from now (`start_from_now` in Python, `startFromNow` in JavaScript) send this call and need a server running this release.

With `market_id`, the filter is applied after the page is cut, so a page can have `items: []` with `has_more: true` and a larger `next_cursor`. Keep reading; that is not the end.

## Applying changes

- A match is identified by the pair `(stream_id, record_id)`, not `record_id` alone.
- `operation: "upsert"` is a complete replacement. Overwrite the stored record; do not merge fields.
- `operation: "withdraw"` has `record: null`. Remove the match from current views and keep the change. A later upsert can reinstate it.
- Never infer a withdrawal from absence. A client that ignores withdrawals keeps wrong matches forever.

An illustrative withdrawal item:

```json
{
  "cursor": 3,
  "envelope": {
    "schema": "ThroughlinePublicationV3",
    "stream_id": "example_stream",
    "sequence": 3,
    "operation": "withdraw",
    "record_id": "bcb323369c19d5588ad21a383362643f72235e55cb399d362ed8d740fe8bd1dd",
    "record": null
  }
}
```

## Words on the site and values on the wire

| Site word | On the wire |
|---|---|
| preliminary | `operation: "upsert"`, `record.analysis: null`. Only `relevance` (`stage: "scout"`) is present. |
| assessed | `operation: "upsert"`, `record.analysis.stage: "analyst"`. |
| withdrawn | `operation: "withdraw"`, `record: null`. |
| trial | `plan: "evaluation"` in account responses. |

A stage is not a truth certification. Assessed means examined, not verified. Not every preliminary match gets a closer reading.

## Record fields

| Field | Values | Notes |
|---|---|---|
| `report_id`, `source_revision_id` | text | The article and the captured revision of it. |
| `source_revision_kind` | `captured_feed_revision` | Fixed. |
| `publisher`, `title`, `url`, `language` | text | `url` is metadata. The API never fetches it. |
| `published_at` | timestamp or `null` | What the source says. `null` exactly when `source_clock_status` is `missing`. |
| `received_at` | timestamp | When the revision was received. |
| `source_clock_status` | `reported`, `unreliable`, `missing` | Whether the source's own time can be relied on. |
| `captured_content` | `headline_only`, `summary`, `body` | What text the assessment had. A reason drawn from `headline_only` is worth less. |
| `publisher_completeness` | `unknown` | Always unknown. Complete capture of a publisher is not claimed. |
| `market.venue`, `market.condition_id`, `market.title` | text | The exact contract. |
| `market.url` | URL or `null` | Often `null`. |
| `market.rules_sha256` | 64 hex | Hash of the rule text the match was made against. If the venue's rules change, this tells you the match predates it. |
| `market.deadline_at` | timestamp or `null` | |
| `relevance.stage` | `scout` | The first pass. Always present. |
| `relevance.verdict` | `relevant`, `uncertain` | Irrelevant articles are not published. |
| `relevance.novelty` | `new`, `update`, `repeat`, `uncertain` | |
| `relevance.why_relevant` | text or `null` | `null` exactly when `explanation_kind` is `unavailable`. |
| `relevance.explanation_kind` | `unavailable`, `public_explanation` | |
| `analysis` | object or `null` | `null` until, and unless, a closer reading is published. |
| `analysis.report_status` | `reported`, `unverified`, `contradicted`, `repeat`, or `null` | |
| `analysis.impact` | integer 0-4 | A model's reading of how much the story bears on the contract. Not a probability and not calibrated confidence. |
| `analysis.why_relevant`, `analysis.explanation_kind` | as for `relevance` | |
| `evidence` | list of exactly one `{report_id, source_revision_id, url}` | The record's own article revision. |

Timestamps are RFC 3339 with an explicit `Z` or offset. The three clocks (`published_at`, `received_at`, `assessed_at`) are different events; do not collapse them. The `cursor` is an ordering token, not a time. `record_id` is the SHA-256 of the canonical JSON array `["ThroughlineLinkV1", report_id, venue, condition_id]`, so one article matched to one contract keeps one identity across corrections.

## Coverage

`GET /v1/coverage` currently answers like this (illustrative values for the two supplied fields):

```json
{
  "schema": "ThroughlineCoverageV1",
  "declared_scope": null,
  "publisher_availability": null,
  "screened_coverage": null,
  "screened_coverage_status": "unknown",
  "meaning": "Publisher-supplied availability and declared scope; a last match does not establish a last screen.",
  "source_policy": {
    "start": "activation",
    "historical_backfill": false,
    "match_evidence": "primary_article_alone",
    "unsupported_evidence": [
      "related_article_only",
      "mixed_articles",
      "previous_article_only"
    ],
    "source_loss_before_public_commit": "possible",
    "dynamic_source_status": "unknown",
    "research_archive": false
  }
}
```

Read it literally:

- `screened_coverage_status: "unknown"`: the service cannot currently tell you which contracts were screened or when. An empty feed is not evidence of a quiet market.
- `historical_backfill: false` and `start: "activation"`: the feed begins when the publisher was switched on. There is no archive of earlier news.
- `source_loss_before_public_commit: "possible"`: an article can be lost before it is published here.
- `publisher_availability` entries, when present, carry `status` of `available`, `delayed`, `unavailable` or `unknown`.

There is no availability, latency or coverage commitment. None has been measured.

An empty result has four possible meanings: the contract is in declared scope; it was actually screened, and when; processing is delayed or unavailable; or it was screened and nothing matched. Only the last means nothing is happening.

First-pass matching spans politics, geopolitics, economics and finance, technology, commodities and science contracts. Closer readings are reserved for contracts with substantial trading in the past 24 hours, so a thinly traded contract can stay preliminary. Sports, crypto and entertainment markets are not covered. The coverage endpoint does not yet report this selection as declared scope. Coverage is intended to expand; no date or market list is committed.

## Limits, pricing and polling

| Plan | Price | News responses per UTC day |
|---|---|---|
| Free | USD 0 | 100 |
| Trial (seven days, no card, started explicitly in the account page) | USD 0 | 5,000 |
| Builder | USD 29/month | 5,000 |

- Each `200` from a news route counts once, however many items it carries. An empty page counts.
- Error responses are not counted.
- `/v1/coverage` and `/v1/usage` each have their own separate allowance.
- All keys on an account share one allowance. A new key does not reset it.
- The allowance resets at 00:00 UTC. News responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds). Coverage responses carry the same three headers; they report the news allowance, not the coverage allowance, and a coverage read does not reduce them.
- There are no automatic overage charges. At the limit you get `429 account_quota_exceeded` with `Retry-After`, `reset_at` and `upgrade_url`.
- Plans differ in allowance only: the service has no plan-based delay, and every plan reads the same records from the same feed. Builder cancels at the end of the paid month; an unpaid renewal returns to Free.

Polling arithmetic:

| Poll every | Responses per day | Fits |
|---|---|---|
| 15 minutes | 96 | Free, trial, Builder |
| 30 seconds | 2,880 | Trial, Builder |

Free is for periodic checks and for building your client. Draining a backlog also spends responses: while `has_more` is true each page is one response.

The limits below were checked against the running configuration on 2026-11-12. Read the headers and handle the error codes; a plan does not bypass shared service capacity.

The API allows 240 requests per IP in a 60-second window, up to 20 changes per news page and five active keys per account. Request bodies can be up to 64 KiB and each news response up to 256 KiB. An account also has a shared 2 GiB news-response budget per UTC day.

An account can have ten active connections. A pairing waits up to ten minutes for approval, is polled no faster than every five seconds, and its approved receipt remains collectable for one day. Pairing starts allow ten per IP and 120 service-wide per hour; approval attempts allow five per account per ten-minute window. IPv6 pairing starts share a /64 bucket. Management access expires after 30 days. Successful access history retains at most 30 days and 100 rows per browser/agent class; it is not a complete event log.

## Errors

Every API error is JSON:

```json
{"error": "invalid_limit", "message": "Invalid limit.", "docs_url": "https://throughline.markets/api#errors", "request_id": "0123456789abcdef0123456789abcdef"}
```

- `error` is the stable code. Branch on the status and on `error`.
- `message` is the code in words, for people. It may change; do not parse it.
- `docs_url` is fixed.
- `request_id` identifies the request and matches the `X-Request-ID` response header, which every response from the API routes carries. Quote it when you report a problem.
- New fields may be added. Clients must ignore fields they do not know.

`account_quota_exceeded` and `account_data_limit` also carry a `usage` object, `upgrade_url` (where a person can change plan), `reset_at` (Unix seconds) and the `X-RateLimit` headers. A pairing poll that is still waiting also carries `"status": "pending"`. Every `401` carries `WWW-Authenticate: Bearer realm="throughline"`. Every `429`, and `503 service_busy`, carries `Retry-After` in seconds.

A `401` on a feed route now says which kind it is. `missing_or_malformed_key`: the header is absent or not exactly `Bearer <key>` with a well-formed key; nothing was looked up, so fix the client. `invalid_key`: a well-formed key that is unknown or revoked. A revoked key and a key that never existed get the same answer on purpose. `unauthorized` is what the account and billing routes answer when the header or sign-in session is missing or not valid; older clients that treat every `401` alike keep working.

A `404` with an empty body is not an API error. It comes from the public proxy for a path or method it does not forward, or from the account page and its files for a non-GET request, or from one of those files requested with a query string. Check the path.

### Authentication and access

| Code | Status | Where | Meaning | What to do |
|---|---|---|---|---|
| `unauthorized` | 401 | feed, account, billing | On account and billing routes: the Authorization header is missing or malformed, or the sign-in session is not valid. On a feed route it appears only when a key is revoked or its account removed while the request is being served. | Account page: sign in again. Feed: treat as invalid_key. Do not retry unchanged. |
| `missing_or_malformed_key` | 401 | feed | A feed route was called with no Authorization header, or one that is not exactly 'Bearer <key>' with a well-formed API key. Nothing was looked up. | Fix the client: read THROUGHLINE_API_KEY and send 'Authorization: Bearer <key>'. A new key is not needed. Do not retry unchanged. |
| `invalid_key` | 401 | feed, account | A well-formed credential that is unknown, revoked or expired: a feed API key on a feed route, or a connection's management credential on an account route. | Stop and tell the person. They can create a key in the account page or approve a new pairing. Do not retry unchanged. |
| `account_unavailable` | 403 | feed, account, billing, pairing | The account behind the key, session or approved pairing is disabled. | Stop. Email access@throughline.markets. |
| `origin_forbidden` | 403 | feed, account, billing, pairing | The request carried an Origin header from another website, or a management credential was sent with any Origin header. Browsers on other sites may not call the API. | Call the API from a server, script or command-line program, not from browser JavaScript. |
| `verified_identity_required` | 403 | account | A browser-only account operation was attempted without a verified sign-in session: approving a pairing or managing connections with a management credential, for example. | The person signs in at the account page and does it there. API keys and management credentials cannot. |
| `scope_forbidden` | 403 | account | The management credential does not hold the scope this route needs, or the route is never available to a management credential. | Stop and tell the person. A new pairing can ask for the scope; the person decides. Do not retry unchanged. |

### Pairing answers

| Code | Status | Where | Meaning | What to do |
|---|---|---|---|---|
| `authorization_pending` | 400 | pairing | Nobody has decided the pairing yet. Not a failure. | Wait interval seconds and poll again, until expires_in has passed. |
| `access_denied` | 400 | account, pairing | The person denied the pairing, or its connection was revoked before the receipt was collected. Definitive: nothing is active. | Stop. Discard the pending secrets. Start a new pairing only if the person asks. |
| `expired_token` | 400 | pairing | The device code is unknown or its window has ended. Not proof that the pairing was never approved. | Stop polling. If a pairing was started with this code, keep the pending secrets, report that delivery is unknown and ask the person to check Your connections in the account page and revoke the named connection if unwanted. |

### Not found, method, conflict

| Code | Status | Where | Meaning | What to do |
|---|---|---|---|---|
| `not_found` | 404 | feed, account, billing, pairing | No match has that record ID, no key or connection on this account has that ID, the pairing code is unknown, expired, already decided against or not addressed to a route, or the path is not a route. A withdrawn match returns its withdrawal, not this. | Check the ID or code. Do not retry unchanged. |
| `method_not_allowed` | 405 | feed | Feed routes accept GET only. | Use GET. |
| `ambiguous_record` | 409 | feed | More than one stream has a match with that record ID. | Repeat with ?stream_id=<stream_id> taken from the envelope. |
| `active_key_limit` | 409 | account | The account already has the maximum number of active keys. Keys issued through pairings count. | Revoke a key you no longer use, then create the new one. |
| `connection_capacity` | 409 | account | The account already has the maximum number of live agent connections. | The person revokes a connection they no longer use in the account page, then approves again. |
| `consent_conflict` | 409 | account | The pairing was already decided differently: approved with other permissions, or approved after a denial was sent. | Reload the account page and look at Your connections. Start a new pairing if the first one is not there. |
| `key_creation_conflict` | 409 | account | A recoverable issuance conflicts with an existing/revoked key. | Keep pending state, inspect its ID and never create a blind replacement. |
| `credential_conflict` | 409 | account | A credential hash in the pairing is already in use by another key or connection. | The program starts a new pairing with freshly generated secrets. |
| `trial_unavailable` | 409 | account | The account's plan cannot start the seven-day trial. | None needed; continue on the current plan. |
| `builder_already_active` | 409 | account | The trial was requested on an account that already has Builder. | None needed; Builder already has the higher allowance. |
| `billing_subscription_exists` | 409 | billing | Checkout was requested for an account that already has a subscription or paid time remaining. | Open the billing portal from the account page instead. |
| `billing_checkout_needs_recovery` | 409 | billing | An earlier checkout attempt has an unknown outcome and is too old to resume automatically. | Do not start another. Email access@throughline.markets. |
| `billing_checkout_needs_refresh` | 409 | billing | The saved checkout link has expired or was never issued. | Reload the account page and start checkout again. |
| `billing_customer_unavailable` | 409 | billing | The billing portal was requested for an account with no billing customer yet. | Start checkout first. |
| `billing_attempt_unknown` | 409 | billing | The checkout attempt being resumed does not exist. | Reload the account page and start checkout again. |

### Bad request

| Code | Status | Where | Meaning | What to do |
|---|---|---|---|---|
| `invalid_request` | 400 | feed, account, billing, pairing | The request could not be parsed, or a JSON body has missing or extra fields. | Fix the request. Do not retry unchanged. |
| `invalid_path` | 400 | feed | The path is not valid UTF-8 text. | Use one of the documented routes. |
| `invalid_query` | 400 | feed, account | An unknown, repeated or malformed query parameter. | Send only the documented parameters, each once. |
| `invalid_pagination` | 400 | feed | cursor is neither digits nor the exact word latest, or limit is not digits. | Send digits, for example cursor=0. To start at the head, send cursor=latest once. |
| `invalid_limit` | 400 | feed | limit is zero or larger than the server page size. | Omit limit to get the server default, or send a smaller number. |
| `invalid_cursor` | 400 | feed, account | The cursor is out of range or not one the service issued. On a newest-first key listing, the cursor is not a key on this account. | Use the next_cursor from your last response, or 0 to replay from the start. |
| `invalid_stream` | 400 | feed | stream_id is not 1-64 letters, digits, underscores or hyphens. | Copy stream_id exactly from the envelope. |
| `conflicting_market` | 400 | feed | The market in the path and the market_id parameter disagree. | Send one or the other. |
| `invalid_market_id` | 400 | feed | A market filter is not 0x followed by 64 lower-case hexadecimal characters. | Send the market's condition ID in that form, not a slug, event ID or token ID. |
| `invalid_content_length` | 400 | feed, account, billing, pairing | The Content-Length header is malformed. | Fix the client; GET requests need no body. |
| `unexpected_body` | 400 | feed, account, billing | A body was sent to a route that takes none. | Remove the body. |
| `invalid_body` | 400 | account, pairing | The body is shorter than Content-Length or could not be read. | Send the documented JSON object with a correct Content-Length. |
| `invalid_key_name` | 400 | account, pairing | The key or connection name is empty, longer than 64 characters or contains control characters; a pairing name must also be printable ASCII. | Choose a 1-64 character name. |
| `invalid_scopes` | 400 | account, pairing | scopes is not a list of distinct known scopes that includes news:read, or the approved scopes are not a subset of the requested ones. | Send scopes from the documented list, each once, always with news:read. |
| `invalid_credential_hash` | 400 | pairing | A credential hash is not 64 lower-case hexadecimal characters, the two hashes are equal, or management_token_hash does not match the scopes. | Send SHA-256 hashes of two different secrets; send management_token_hash as null when the only scope is news:read. |
| `content_length_required` | 411 | account, pairing | A write was sent without Content-Length. | Send Content-Length. |
| `request_too_large` | 413 | feed, account, billing, pairing | The request body exceeds the server limit. | Feed reads have no body; remove it. |
| `request_target_too_large` | 414 | feed, account, pairing | The URL is too long. | Shorten the request; send only documented parameters. |
| `json_required` | 415 | account, pairing | A write body was not sent as application/json. | Set Content-Type: application/json. |

### Limits

| Code | Status | Where | Meaning | What to do |
|---|---|---|---|---|
| `account_quota_exceeded` | 429 | feed | The account has used its news responses for this UTC day. | Stop polling and tell the person. The daily news allowance is used and resets at 00:00 UTC; reset_at, Retry-After and X-RateLimit-Reset give the time and upgrade_url is where the person can change plan. Poll less often or change plan. Do not sleep until the reset and do not make another key: keys share one allowance. |
| `account_data_limit` | 429 | feed | The account has used its response-byte allowance for this UTC day. | Stop and tell the person, as for account_quota_exceeded. Afterwards use a smaller limit and avoid replaying from zero. |
| `coverage_quota_exceeded` | 429 | feed | The separate allowance for GET /v1/coverage is used up. | Stop reading coverage and report it; Retry-After gives the reset. News reads are not affected. Read coverage less often than news. |
| `usage_quota_exceeded` | 429 | feed | The separate allowance for GET /v1/usage is used up. | Stop reading usage and report it; Retry-After gives the reset. News reads are not affected. The X-RateLimit headers on news responses carry the same numbers. |
| `management_quota_exceeded` | 429 | account | Too many account operations in this window. Revoking a key or connection from the account page is not held back by this. | Stop and tell the person; Retry-After gives the reset. Do not retry in a loop. |
| `agent_quota_exceeded` | 429 | account | This connection, or all connections together, made too many account requests in this window. Separate from the person's own account-page allowance. | Stop and tell the person; Retry-After gives the reset. Do not retry in a loop. |
| `approval_limited` | 429 | account | Too many pairing codes were tried on this account in a short time. | Stop and tell the person; Retry-After gives the wait. Check the code shown by the program before trying again. |
| `pairing_capacity` | 429 | pairing | Too many pairings were started from this network, or across the service, in this window. | Stop and tell the person; Retry-After gives the wait. Do not start pairings in a loop. |
| `billing_quota_exceeded` | 429 | billing | Too many billing operations in this window. | Stop and tell the person; Retry-After gives the reset. Do not retry in a loop. |
| `burst_limited` | 429 | feed, account, billing, pairing | Too many requests from this network address in a short window. Not charged against the daily allowance. | If Retry-After is short, wait that long and retry a bounded number of times, then slow down. If it is not short, stop and report it. |
| `burst_capacity` | 429 | feed, account, billing, pairing | The short-window limiter is tracking too many addresses to admit a new one. | If Retry-After is short, wait that long and retry a bounded number of times. Otherwise stop and report it. |
| `server_capacity` | 429 | feed, account, billing | The whole service has reached its own allowance for this window. Not specific to your account. | Not specific to your account, and another key does not help. Retry only if Retry-After is short; otherwise stop and report it. |

### Server

| Code | Status | Where | Meaning | What to do |
|---|---|---|---|---|
| `internal_error` | 500 | feed, account, billing, pairing | An unexpected failure. No detail is returned by design. | Do not retry automatically. Keep your cursor and let the next scheduled poll try again. If it persists, email access@throughline.markets with the request_id, the time and the route. |
| `billing_provider_unavailable` | 503 | billing | The payment provider did not give a usable answer. | Retry later. No charge follows from this response alone. |
| `billing_payment_conflict` | 503 | billing | A payment record disagrees with one already stored. | Stop. Email access@throughline.markets. |
| `service_busy` | 503 | feed, account, billing, pairing | All request slots are in use. | Wait Retry-After seconds (1) and retry a bounded number of times. |
| `service_unavailable` | 503 | feed, account, billing, pairing | Storage was unavailable for this request. | Retry a bounded number of times with short waits. Keep your cursor; nothing was consumed. For a pairing poll, keep the pending secrets and poll again. |
| `response_too_large` | 503 | feed, account, billing | The response would exceed the server's size limit. | On a feed read, repeat with a smaller limit. Elsewhere, retry later. |

These tables cover the feed, account, billing and pairing routes you can call. "Where" names the route family: a family's codes are shared possibilities, and not every code can arise on every operation in it.

Three more codes are provider-webhook-only. `invalid_webhook` (400) answers the sign-in provider's deliveries; `invalid_stripe_event` (400) and `billing_event_conflict` (400) answer the payment provider's. Customers never call those routes, so the codes are not in the schema or the OpenAPI file and you will not see them.

Retry rule:

- **Allowance used up** (`account_quota_exceeded`, `account_data_limit`, `coverage_quota_exceeded`, `usage_quota_exceeded`, `management_quota_exceeded`, `agent_quota_exceeded`, `billing_quota_exceeded`) or **too many attempts** (`pairing_capacity`, `approval_limited`): stop at once and report the code, the reset time and what a person can do. Never sleep until the next day, and never make or switch keys to get around it.
- **Short-lived** (`burst_limited`, `burst_capacity`, `server_capacity`, and `503 service_busy` or `service_unavailable`): wait `Retry-After` and try again, only while the total wait stays short: a few attempts inside about a minute, then give up and report it.
- **`500`**: not retried automatically. Keep your cursor; the next scheduled poll can try again.
- **`authorization_pending`**: not a failure. Poll again after `interval` seconds, until `expires_in` has passed.
- **Any other `4xx`**: never retry unchanged.

## Keys

- A key is created in the account page (the secret is shown once), by approving a pairing (the program generated the key locally), or by a connection that was granted `keys:write`.
- Send the key only in the `Authorization` header. Keep it out of URLs, logs, chat and client-side code.
- A feed key reads the feed, coverage and usage, and nothing else. It cannot manage the account.
- Revoke a key in the account page. Revoking a connection under "Your connections" revokes every key it holds. `keys:write` is account-wide: a connection holding it can revoke any key on the account.
- To confirm revocation works: revoke the key in the account page, repeat the first request, and expect `401 invalid_key`.
- A revoked key and an unknown key give the same answer on purpose.

`GET /account/v1/keys` lists keys for the account page's sign-in session or a management credential with `keys:read`. Listings include revoked keys and never a secret.

- Without `order`: ID order. `next_cursor` is the last ID on the page; continue until a page has no items.
- `order=newest`: newest first, by creation time then ID, both descending. `next_cursor` is `null` on the last page. `newest` is the only value.
- `cursor`: a 32-character lower-case hexadecimal key ID taken from `next_cursor`. With `order=newest` it must be a key on the same account, otherwise `400 invalid_cursor`.

Each key has `last_used_at`: the server time of its most recent successful news request, or `null`. `GET /account/v1/me` has `activation`, one summary for the account: how it got its first key (`portal`, `pairing` or `unknown`), when the account and its first key were created, the first recorded and most recent successful news request, and running counts of successful news requests, failed requests from a valid key, and allowance stops. `complete_since_signup` is `true` when the account was created after recording began. When it is `false`, earlier requests were never counted and `first_news_at` is only the first success seen since recording began, not the account's first. `activation` is `null` when the server is not recording it and is returned to the sign-in session only. Time before the account existed is not measured. There is no per-request history.

## Not published

Forecasts, probabilities, positions, financial eligibility and trade instructions. Throughline is operated by Michael O'Rourke (access@throughline.markets), who also trades these markets. His trading system processes news matches before API customers receive them. No interval has been measured, not every match leads to a trade, and delivery at the same moment is not offered. The feed carries only price-independent fields. Terms: https://throughline.markets/terms. Privacy: https://throughline.markets/privacy.

Contact: access@throughline.markets

## Managing an agent connection

The published 0.3.0 command at the pinned install above includes:

```sh
throughline whoami
throughline doctor
throughline audit
throughline keys pending
```

`doctor` does not spend a news response. When the person asks to disconnect
this integration, `throughline disconnect` revokes its connection and linked
keys. An unknown acknowledgement reports `disconnect_unknown` and retains local
material for portal reconciliation; expiry alone is not proof of revocation.

A management credential can inspect its own grant at `GET /account/v1/connection` and surrender it with `DELETE /account/v1/connection`. No scope is added: these operate on that credential's own connection only. Disconnect revokes every linked feed key, including keys it created. Feed-only pairings have no management credential; their owner revokes them in the portal. Management expires after 30 days; feed keys keep working until revoked. Renewal always requires new human approval.

`GET /account/v1/audit` returns successful access changes newest first,20 per page, with `next_cursor` or null and `retention` describing the bounded history. A browser owner sees the account; an agent sees only its own actions. It is not a complete request log.

For recoverable key issuance, an authorized `keys:write` agent may POST exactly `{name,id,key_hash}` to `/account/v1/keys`. Generate and privately persist the feed secret before sending its SHA-256 hash; use a random32hex ID. The same account/connection/ID/name/hash returns the original `{id,name,created_at}` receipt even at the active-key cap. A conflicting or revoked ID returns409 `key_creation_conflict`; never replace another operation or reactivate it. The portal's ordinary `{name}` request still returns a one-time secret. Safe rotation creates and verifies the replacement, switches the consumer, then explicitly revokes the old ID.
