# Dusk State: full text

> Operational software and machine-readable intelligence. Published by Dusk State, England and Wales. Live capabilities: https://duskstate.dev/capabilities.json. Summary: https://duskstate.dev/llms.txt.

## Welcome

Source: https://docs.duskstate.dev/docs/introduction (version introduction-2026-10-06.2)

Dusk State publishes operational software and machine-readable intelligence from England and Wales. These docs are the single reference for everything it publishes: the website, the public API, the discovery files agents and crawlers read, and the rules agents work under.

## What you can use today

| Surface | Where | For |
| --- | --- | --- |
| Website | [duskstate.dev](https://duskstate.dev) | People: services, store, waiting list, articles and public records |
| Public API | `https://duskstate.dev/api/v1/` | Software and agents: products, records, policies, docs and waiting lists |
| Discovery files | [`/.well-known/dusk-state.json`](https://duskstate.dev/.well-known/dusk-state.json) and the files it links | Agents and crawlers working out what is offered |
| These docs | [docs.duskstate.dev](https://docs.duskstate.dev) | Reference for all of the above. The same pages are served as Markdown at [`/api/v1/docs`](https://duskstate.dev/api/v1/docs) |

Reading needs no account and no key. Agents that write (the agent waiting list and survey) register first; see [Agents](/docs/agents).

## How these docs are organised

- **Start**: this page, a [Quickstart](/docs/quickstart) with four requests, and the [Concepts](/docs/concepts) every record uses.
- **Discovery**: the files that describe Dusk State to software, from [`/capabilities.json`](https://duskstate.dev/capabilities.json) to `robots.txt`.
- **API reference**: conventions, errors, and one page per endpoint.
- **Agents**: the rule agents work under, how they register, and what they can submit.
- **Help**: contacts, security reports and corrections.

## What is described here

Only capabilities that work are described as available. [`/capabilities.json`](https://duskstate.dev/capabilities.json) lists them; planned work is in [`/roadmap.json`](https://duskstate.dev/roadmap.json), each item labelled. If a page here and `/capabilities.json` disagree, `/capabilities.json` is right; please tell us at hello@duskstate.dev.


## Quickstart

Source: https://docs.duskstate.dev/docs/quickstart (version quickstart-2026-10-06)

Every request below works from a terminal with `curl`. Add `| jq` for readable output.

## 1. See what works now

```bash
curl -s https://duskstate.dev/capabilities.json
```

Each capability has an `id`, an `endpoint`, a `method` and its `auth`. Anything not listed is not available, whatever else you read.

## 2. Read a public record

```bash
curl -s https://duskstate.dev/api/v1/records/dusk-state
```

A record is a list of claims. Each claim has a `statement`, a `label` (`observed`, `inferred`, `proposed`, `unknown` or `superseded`) and the `evidence` behind it. See [Concepts](/docs/concepts) and [Records](/docs/api/records).

## 3. Get the consent version forms need

```bash
curl -s https://duskstate.dev/api/v1/policies/privacy | jq -r .version
```

Every form that records consent sends this value as `consent_version`. See [Policies](/docs/api/policies).

## 4. Join the waiting list

```bash
curl -s -X POST https://duskstate.dev/api/v1/waitlist \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Ada Example",
    "email": "ada@example.com",
    "interests": ["store", "agent-services"],
    "consent": true,
    "consent_version": "<version from step 3>",
    "legend_terms_version": "legend-2026-10-04"
  }'
```

The reply is `202` with `{"status": "received", "legend": true}` or `false`. It is the same whether or not the email was already listed. If the waiting list is closed you get `503`. See [Waiting list](/docs/api/waitlist).

## Next

- [Public API](/docs/api) for conventions that apply to every endpoint.
- [Agents](/docs/agents) if you are building or running an agent.


## Concepts

Source: https://docs.duskstate.dev/docs/concepts (version concepts-2026-10-06)

## Labels

Every statement in a record or on the roadmap carries one label, so you can tell what is known from what is planned:

| Label | Meaning |
| --- | --- |
| `observed` | Seen directly, for example a response or a published file |
| `inferred` | Concluded from observed facts |
| `proposed` | Planned, not available |
| `unknown` | Not yet established |
| `superseded` | Replaced by a later statement, kept for the record |

A label changes only with new evidence. Superseded statements stay published so the history can be checked.

## Records

A public record describes one subject as a list of claims, each with its label and evidence. Records carry a `version` and an `as_of` date; a new version replaces the old one. The first record is Dusk State's record of itself, [`dusk-state`](https://duskstate.dev/records/dusk-state).

## Versions

| What | Format | Example |
| --- | --- | --- |
| API | Major version in the path and the `X-Dusk-State-Version` header | `/api/v1/`, `1` |
| Policies | `<slug>-<date>`, then `.2`, `.3` for later versions on the same day | `privacy-2026-10-04.2` |
| Docs pages | `<path with dots>-<date>`, same suffix rule | `api.errors-2026-10-06` |
| Records | `<date>.<n>` | `2026-10-04.8` |

Publishing a new version of a policy or docs page supersedes the previous one. Superseded versions are kept.

## Published

"Published" means available now. A product is published only when it can be fulfilled; a capability is listed in `/capabilities.json` only when it works. Prices are in minor units (pence for GBP).


## Discovery files

Source: https://docs.duskstate.dev/docs/discovery (version discovery-2026-10-06.2)

All files are served from `https://duskstate.dev` without authentication.

## Start here

| File | Purpose |
| --- | --- |
| [`/.well-known/dusk-state.json`](https://duskstate.dev/.well-known/dusk-state.json) | Publisher identity, contacts, API version and links to every file below |
| [`/capabilities.json`](https://duskstate.dev/capabilities.json) | Capabilities that work now, with endpoint, method and authentication |
| [`/openapi.json`](https://duskstate.dev/openapi.json) | OpenAPI 3.1 description of the public API |
| [`/.well-known/api-catalog`](https://duskstate.dev/.well-known/api-catalog) | API catalogue (RFC 9727) linking the OpenAPI description, these docs, the API policy and status |

A client that reads only `/.well-known/dusk-state.json` can reach everything else from its `links`.

## In this section

- [Machine-readable files](/docs/discovery/machine-readable): the shape of each JSON file.
- [Crawlers and search](/docs/discovery/crawlers): `robots.txt`, the sitemap, `llms.txt` and `security.txt`.
- Agent files (`/agents.json`, protected resource metadata and `/auth.md`) are covered under [Agents](/docs/agents).


## Machine-readable files

Source: https://docs.duskstate.dev/docs/discovery/machine-readable (version discovery.machine-readable-2026-10-06.2)

## Publisher: `/.well-known/dusk-state.json`

`name`, `legal_name`, `url`, `descriptor`, `jurisdiction`, `contact` (`general`, `security`), `api_version` and `links` to the OpenAPI description, capabilities, pricing, terms, status, roadmap, agents, security, corrections, `llms.txt` and these docs.

## Capabilities: `/capabilities.json`

```json
{
  "api_version": "1",
  "capabilities": [
    { "id": "policies", "description": "...", "endpoint": "https://duskstate.dev/api/v1/policies", "method": "GET", "auth": "none" }
  ]
}
```

Agent capabilities add a `scope`. A capability disappears from this file while it is closed.

## OpenAPI and schemas

[`/openapi.json`](https://duskstate.dev/openapi.json) is OpenAPI 3.1. Request and response bodies are also published as JSON Schema (2020-12) at `/schemas/<name>.json`:

| Schema | Used by |
| --- | --- |
| [`human-waitlist-entry`](https://duskstate.dev/schemas/human-waitlist-entry.json) | `POST /api/v1/waitlist` |
| [`agent-waitlist-entry`](https://duskstate.dev/schemas/agent-waitlist-entry.json) | `POST /api/v1/agents/waitlist` |
| [`agent-survey`](https://duskstate.dev/schemas/agent-survey.json) | `POST /api/v1/agents/survey` |
| [`agent-submission-accepted`](https://duskstate.dev/schemas/agent-submission-accepted.json) | Agent submission replies |
| [`audit-request`](https://duskstate.dev/schemas/audit-request.json), [`audit-request-created`](https://duskstate.dev/schemas/audit-request-created.json) | `POST /api/v1/audit-requests` |
| [`published-product`](https://duskstate.dev/schemas/published-product.json), [`product-list`](https://duskstate.dev/schemas/product-list.json) | `GET /api/v1/products` |
| [`public-record`](https://duskstate.dev/schemas/public-record.json) | `GET /api/v1/records/{id}` |
| [`published-resource`](https://duskstate.dev/schemas/published-resource.json) | `GET /api/v1/resources` |
| [`tool-record`](https://duskstate.dev/schemas/tool-record.json) | `GET /api/v1/tools` |

## Pricing: `/pricing.json`

`version`, a `note`, and `offers`: one entry per published product with `product`, `price` (`amount_minor`, `currency`, `unit`), `tax_treatment` and `effective_date`. Empty when nothing is on sale.

## Terms: `/terms.json`

The terms version in force with its `status` and `url`, `governing_law`, `provider`, and the same for `privacy`, `refunds` and `store_policy`. A `status` of `pending-owner-review` means the text is published but not yet reviewed by the owner. `policies_index` links the [Policies](/docs/api/policies) endpoint.

## Status: `/status.json`

`status`, `checked_at` and `components` (`api`, `database`). See [Status and health](/docs/api/status).

## Roadmap: `/roadmap.json`

A `note` (no dates unless committed) and `items`, each with `id`, `title`, a `state` label and an optional `note`. Proposed items are not available.

## Agents: `/agents.json`

The `principal_rule` agents work under, with links to capabilities, the roadmap and the page for people. See [Agents](/docs/agents).

## Index: `/index.json`

Everything public in one JSON document: pages, articles, policies, docs pages (with their Markdown URLs), resources when published, and links to every machine-readable file.

## Full text: `/llms-full.txt`

Every published docs page and policy in one Markdown file, each with its source URL and version. Nothing in it is generated; it is the published text.


## Crawlers and search

Source: https://docs.duskstate.dev/docs/discovery/crawlers (version discovery.crawlers-2026-10-06.2)

## `robots.txt`

All crawlers, including AI crawlers, may read the site. Two API paths are disallowed because they only accept submissions. A `Content-Signal` line states how the content may be used:

```
User-Agent: *
Content-Signal: search=yes, ai-input=yes, ai-train=no
Allow: /
Disallow: /api/v1/agents/
Disallow: /api/v1/audit-requests
```

## Content Signals

`search=yes, ai-input=yes, ai-train=no`: content may be indexed for search and used as input to AI answers, not used to train models. The same value is sent as a `Content-Signal` header on every page.

## `sitemap.xml`

[`/sitemap.xml`](https://duskstate.dev/sitemap.xml) lists the public pages of duskstate.dev. These docs have their own at [docs.duskstate.dev/sitemap.xml](https://docs.duskstate.dev/sitemap.xml).

## `llms.txt`

[`/llms.txt`](https://duskstate.dev/llms.txt) is a short summary for language models: what Dusk State is, the labels, the main pages and the key machine-readable files. It repeats the rule that only capabilities in `/capabilities.json` are available. [`/llms-full.txt`](https://duskstate.dev/llms-full.txt) carries the full text of the docs and policies.

## `security.txt`

[`/.well-known/security.txt`](https://duskstate.dev/.well-known/security.txt) (RFC 9116) names security@duskstate.dev as the contact and links the corrections page as the policy.

## The `Link` header

Every API response carries a `Link` header pointing to the OpenAPI description (`service-desc`), the publisher file (`describedby`), status (`status`) and the API policy (`service-doc`). A client that lands on any endpoint can find the rest.


## Public API

Source: https://docs.duskstate.dev/docs/api (version api-2026-10-06.3)

## Base URL

`https://duskstate.dev/api/v1/`. The full description is at [`/openapi.json`](https://duskstate.dev/openapi.json).

## Authentication

Reading needs none. The agent waiting list and survey take an agent access token; see [Agent authentication](/docs/agents/authentication). There are no API keys for the public API.

## Endpoints

| Method | Path | Page |
| --- | --- | --- |
| GET | `/api/v1/products` | [Products](/docs/api/products) |
| GET | `/api/v1/store/categories` | [Products](/docs/api/products) |
| GET | `/api/v1/records/{id}` | [Records](/docs/api/records) |
| GET | `/api/v1/policies`, `/api/v1/policies/{slug}` | [Policies](/docs/api/policies) |
| GET | `/api/v1/docs`, `/api/v1/docs/{path}` | [Docs](/docs/api/docs) |
| POST | `/api/v1/waitlist` | [Waiting list](/docs/api/waitlist) |
| POST | `/api/v1/audit-requests` | [Audit requests](/docs/api/audit-requests) (closed) |
| POST | `/api/v1/agents/waitlist` | [Agent waiting list](/docs/agents/waitlist) |
| POST | `/api/v1/agents/survey` | [Agent survey](/docs/agents/survey) |
| GET | `/api/v1/resources` | [Resources](/docs/api/resources) (when published) |
| GET | `/api/v1/tools` | [MCP server](/docs/agents/mcp) (when published) |
| GET | `/health`, `/status.json` | [Status and health](/docs/api/status) |

## Versioning

- Paths carry the major version (`/api/v1/`). Every response carries an `X-Dusk-State-Version` header.
- Within a major version, changes only add: new fields, new endpoints and new optional parameters. Ignore fields you do not recognise.
- A breaking change ships under a new major version. The previous version stays available for at least 90 days, with `Deprecation` and `Sunset` headers and a `Link` to the replacement. The policy is published at [`/api-policy`](https://duskstate.dev/api-policy).

## Requests

- Send JSON with `Content-Type: application/json`. Other content types get `415`.
- Request bodies are strict: unknown fields are rejected with `422`, and `detail` lists each failing field.
- Submissions are rate limited per client; over the limit you get `429`. Wait before retrying.
- Forms that record consent take a `consent_version`, which must be the privacy notice version in force. See [Policies](/docs/api/policies).

## Responses

Successful responses are JSON. Errors use one format, described in [Errors](/docs/api/errors). Every response carries:

| Header | Meaning |
| --- | --- |
| `X-Request-Id` | Identifies the request; quote it when you contact us |
| `X-Dusk-State-Version` | The API major version |
| `Link` | The OpenAPI description, publisher file, status and API policy |


## Errors

Source: https://docs.duskstate.dev/docs/api/errors (version api.errors-2026-10-06.2)

Errors are returned as `application/problem+json`:

```json
{
  "type": "about:blank",
  "title": "No such policy",
  "status": 404,
  "request_id": "d32c3ee9-1001-4191-9440-3b790420a589"
}
```

- `title` is a short, human-readable reason.
- `status` repeats the HTTP status.
- `detail`, when present, gives specifics: the fields that failed validation as `{ "path", "message" }` pairs, or `current_version` when the privacy notice has changed.
- `request_id` identifies the request. Quote it when you contact us.

## Statuses

| Status | Meaning | What to do |
| --- | --- | --- |
| 400 | A required header or parameter is missing or invalid, for example `Idempotency-Key` or an unknown `category` | Fix the request |
| 401 | An agent access token is required; `WWW-Authenticate` points to the protected resource metadata | Register and send a token |
| 403 | The token lacks the required scope | Request the scope |
| 404 | No such resource | Check the path |
| 409 | Already submitted for this agent registration, or the privacy notice changed since you read it | Do not resubmit; or read the notice again and resend with `detail.current_version` |
| 413 | The body is too large | Shorten it |
| 415 | The body is not JSON | Send `Content-Type: application/json` |
| 422 | The body failed validation | Fix the fields in `detail` |
| 429 | Too many requests | Wait, then retry |
| 503 | The capability is closed or temporarily unavailable | Check `/capabilities.json` and `/status.json` |


## Products

Source: https://docs.duskstate.dev/docs/api/products (version api.products-2026-10-06.2)

## Products

`GET /api/v1/products` returns the products on sale:

```json
{ "version": "2026-10-04T17:22:51.114Z", "source": "catalogue", "data": [] }
```

The list can be empty: nothing is listed until it can be fulfilled. Each product has:

| Field | Meaning |
| --- | --- |
| `id`, `name`, `description` | Identity |
| `kind` | `service`, `subscription`, `digital`, `fee` or `plugin` |
| `category`, `subcategory` | Store category, when it has one |
| `status` | Always `published` here |
| `price` | `amount_minor` (pence for GBP), `currency`, `unit` |
| `tax_treatment` | `vat_included`, `vat_excluded`, `outside_scope`, `not_vat_registered` or `unknown` |
| `effective_date` | The date the price took effect |
| `checkout` | `{ "type": "stripe_checkout", "url" }` |
| `availability`, `intake_url` | Optional notes and a form to complete before buying |

Filter by store category with `?category={id}`. An unknown category returns `400`.

## Categories

`GET /api/v1/store/categories` lists only the categories that currently have published products: `{ "data": [{ "id", "label", "count" }] }`. Category ids: `templates`, `prompts`, `automations`, `tools`, `plugins`, `snippets`, `blueprints`, `playbooks`, `starter-kits`.

## Prices

[`/pricing.json`](https://duskstate.dev/pricing.json) lists the same offers in compact form. See [Machine-readable files](/docs/discovery/machine-readable).


## Records

Source: https://docs.duskstate.dev/docs/api/records (version api.records-2026-10-06)

`GET /api/v1/records/{id}` returns one record. An unknown id returns `404`. The human page is at `https://duskstate.dev/records/{id}`.

```json
{
  "id": "dusk-state",
  "subject": "Dusk State (duskstate.dev)",
  "kind": "publisher-self-record",
  "version": "2026-10-04.8",
  "as_of": "2026-10-04",
  "publisher": "Dusk State",
  "note": "...",
  "claims": [
    { "statement": "Jurisdiction is England and Wales.", "label": "observed", "evidence": "..." }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `kind` | What the record describes |
| `version`, `as_of` | The record version and the date its claims describe |
| `claims[].label` | `observed`, `inferred`, `proposed`, `unknown` or `superseded`; see [Concepts](/docs/concepts) |
| `claims[].evidence` | Where the claim comes from: a URL, a document or a dated statement |

Records available now: [`dusk-state`](https://duskstate.dev/api/v1/records/dusk-state).


## Policies

Source: https://docs.duskstate.dev/docs/api/policies (version api.policies-2026-10-06.2)

## List

`GET /api/v1/policies` returns every published policy without its text: `slug`, `title`, `summary`, `version`, `effective_on`, `placements` and `provisional`.

`provisional: true` means the text is published but still pending owner review; the page shows a notice saying so.

## One policy

`GET /api/v1/policies/{slug}` returns the same fields plus `body`, the text in Markdown. An unknown slug returns `404`. The rendered page is at `https://duskstate.dev/{slug}`.

Policies published now: `privacy`, `terms`, `refunds`, `store-policy`.

## Versions

A version looks like `privacy-2026-10-04`, with `.2`, `.3` for later versions on the same day. Publishing a new version supersedes the previous one; superseded versions are kept for the record.

## Consent

Forms that record consent send `consent_version`. It must equal the `version` of the `privacy` policy in force at the time of submission. If the notice changed after you read it, the request fails with `409` and `detail.current_version`; read the current notice and submit again with that version.


## Docs

Source: https://docs.duskstate.dev/docs/api/docs (version api.docs-2026-10-06)

Every page on docs.duskstate.dev is also served by the API.

## Index

`GET /api/v1/docs` returns every published page without its text, in navigation form:

```json
{
  "data": [
    { "path": "api/errors", "title": "Errors", "description": "...", "section": null, "position": 21, "version": "api.errors-2026-10-06", "published_at": "2026-10-06T09:35:42.413Z" }
  ]
}
```

`section` names the sidebar heading a page starts; `position` orders siblings.

## One page

`GET /api/v1/docs/{path}`, for example [`/api/v1/docs/api/errors`](https://duskstate.dev/api/v1/docs/api/errors), returns the same fields plus `body`, GitHub-flavoured Markdown. An unknown path returns `404`. The rendered page is at `https://docs.duskstate.dev/docs/{path}`.

## Freshness

Responses may be cached for up to 60 seconds. Pages are written and published by Dusk State staff; publishing a new version supersedes the previous one, which is kept on record.


## Waiting list

Source: https://docs.duskstate.dev/docs/api/waitlist (version api.waitlist-2026-10-06)

`POST /api/v1/waitlist`. No authentication. Body: [`human-waitlist-entry`](https://duskstate.dev/schemas/human-waitlist-entry.json). The same form is at [duskstate.dev/waitlist](https://duskstate.dev/waitlist).

| Field | Required | Notes |
| --- | --- | --- |
| `name` | Yes | 1 to 200 characters |
| `email` | Yes | Up to 320 characters |
| `organisation` | No | Up to 200 characters |
| `interests` | Yes | Any of `audit`, `store`, `agent-services`, `feed`, `monitoring`, `templates`, `prompts`, `automations`, `tools`, `plugins`, `snippets`, `blueprints`, `playbooks`, `starter-kits` |
| `consent` | Yes | Must be `true` |
| `consent_version` | Yes | The `privacy` policy version in force; see [Policies](/docs/api/policies) |
| `legend_terms_version` | Yes | `legend-2026-10-04` |

## Reply

`202` with `{ "status": "received", "legend": true }`. `legend` says whether the Legend programme is open, which decides whether this entry is eligible. The reply is the same whether or not the email was already listed, so the endpoint cannot be used to check addresses.

## Errors

`415` not JSON, `422` invalid fields, `409` stale `consent_version`, `429` too many requests, `503` the waiting list is closed. See [Errors](/docs/api/errors).


## Audit requests

Source: https://docs.duskstate.dev/docs/api/audit-requests (version api.audit-requests-2026-10-06)

**State: closed (observed 6 October 2026).** The endpoint answers `503` with "Audit requests are closed" and is not listed in `/capabilities.json`. The £99 Founding Agent-Readiness Audit was withdrawn on 4 October 2026 before any sale; see the [Dusk State record](https://duskstate.dev/records/dusk-state) and [`/roadmap.json`](https://duskstate.dev/roadmap.json). This page describes the endpoint for when intake reopens.

## Request

`POST /api/v1/audit-requests` with an `Idempotency-Key` header (8 to 128 letters, digits or hyphens) and a body matching [`audit-request`](https://duskstate.dev/schemas/audit-request.json): contact details, the API in question (`endpoints`, `auth_method`, whether pricing, terms and schemas are public), `desired_outcome`, `consent: true` and `consent_version`.

## Reply

`201` with `id` and `status: "received"`, plus how to pay (`checkout` or `payment_link`). Repeating the same `Idempotency-Key` returns `200` with the original reply instead of a second request.

## Errors

`400` missing `Idempotency-Key`, `413` body over 32 KB, `415`, `422`, `409` stale consent, `429`, `503` closed, and `502` when the request was received but payment could not be started (the reply carries its `id`).


## Status and health

Source: https://docs.duskstate.dev/docs/api/status (version api.status-2026-10-06)

## Health

`GET /health` returns `{ "status": "ok" }` while the API answers. Use it for liveness checks.

## Status

`GET /status.json` reports the components behind the API:

```json
{ "status": "ok", "checked_at": "2026-10-06T10:08:28.211Z", "components": { "api": "ok", "database": "configured" } }
```

When a component is unavailable, the endpoints that depend on it answer `503` and their capabilities may drop out of `/capabilities.json`. The page for people is [duskstate.dev/status](https://duskstate.dev/status).


## Resources

Source: https://docs.duskstate.dev/docs/api/resources (version api.resources-2026-10-06)

**Published when the Resources switch is on.** While it is off, `GET /api/v1/resources` answers `404` and the capability is not in `/capabilities.json`.

`GET /api/v1/resources` returns `{ "data": [...] }`, each item with:

| Field | Meaning |
| --- | --- |
| `slug`, `title`, `summary`, `url` | What it is and where; links are always `https://` |
| `kind` | `agent`, `service`, `software`, `product`, `guide`, `mcp-directory` or `skill-directory` |
| `relationship` | `independent` (no commercial link), `referral` (Dusk State may receive credit) or `affiliate` (Dusk State may be paid) |
| `tags`, `position`, `updated_at` | Grouping, order and last change |

A listing is a pointer, not an endorsement or a trust claim. Check each resource yourself. The page for people is [duskstate.dev/resources](https://duskstate.dev/resources), where referral and affiliate links are labelled and marked `rel="sponsored"`.


## Agents

Source: https://docs.duskstate.dev/docs/agents (version agents-2026-10-06.3)

## Rule

An agent always acts for a person or organisation. An untrusted agent cannot spend, hold keys or write beyond one waiting-list entry and one survey. The rule is published in [`/agents.json`](https://duskstate.dev/agents.json).

## What an agent can do today

| Action | Endpoint | Scope |
| --- | --- | --- |
| Read everything public | All `GET` endpoints and discovery files | None |
| Join the agent waiting list | `POST /api/v1/agents/waitlist` | `waitlist:write` |
| Answer the survey | `POST /api/v1/agents/survey` | `survey:write` |

Spending, holding keys and agent payments are not available; see `agent-payments` in [`/roadmap.json`](https://duskstate.dev/roadmap.json).

## Trust

Each submission reply states `trust`:

- `untrusted`: an anonymous registration, or one no person has claimed.
- `trusted`: the token names the person the agent acts for, after that person completed the claim step.

Both may submit one waiting-list entry and one survey per registration.

## In this section

- [MCP server](/docs/agents/mcp): the same capabilities as MCP tools.

- [Authentication](/docs/agents/authentication): register, claim and get a token.
- [Waiting list](/docs/agents/waitlist) and [Survey](/docs/agents/survey): fields and replies.

People join their own waiting list at [duskstate.dev/waitlist](https://duskstate.dev/waitlist); see [Waiting list](/docs/api/waitlist).


## Authentication

Source: https://docs.duskstate.dev/docs/agents/authentication (version agents.authentication-2026-10-06)

Agent identity is provided by WorkOS AuthKit. The authorisation server and scopes are published in [`/.well-known/oauth-protected-resource`](https://duskstate.dev/.well-known/oauth-protected-resource) (RFC 9728); step-by-step commands are in [`/auth.md`](https://duskstate.dev/auth.md).

## Steps

1. **Reuse a registration if you have one.** Do not register again for every task.
2. **Register.** `anonymous` needs no email and grants `waitlist:write` and `survey:write` at once. `service_auth` takes the person's email and needs the claim step.
3. **Claim (for `service_auth`; optional for `anonymous`).** You give the person a link; they sign in and read you a code; you complete the claim with it. Their identity is then attached to your token, and submissions are `trusted`.
4. **Exchange** the registration's assertion for an access token (`grant_type` JWT bearer) at the authorisation server's token endpoint.

Store secrets in the operating system's credential store and never print them.

## Using the token

Send `Authorization: Bearer <token>`.

- No token: `401` with a `WWW-Authenticate` header pointing to the protected resource metadata.
- Valid token without the scope: `403`.
- Expired token: exchange the assertion again; if the assertion has expired too, register again.

## Scopes

| Scope | Allows |
| --- | --- |
| `waitlist:write` | One agent waiting-list entry per registration |
| `survey:write` | One survey per registration |


## Agent waiting list

Source: https://docs.duskstate.dev/docs/agents/waitlist (version agents.waitlist-2026-10-06)

`POST /api/v1/agents/waitlist` with an agent token carrying `waitlist:write`. Body: [`agent-waitlist-entry`](https://duskstate.dev/schemas/agent-waitlist-entry.json).

| Field | Required | Notes |
| --- | --- | --- |
| `agent_name` | Yes | 1 to 200 characters |
| `agent_type` | Yes | What the agent is, 1 to 200 characters |
| `operator_type` | Yes | `individual`, `company` or `organisation` |
| `principal_contact` | No | How to reach the person or organisation the agent acts for |
| `use_cases` | Yes | List of short descriptions |
| `capabilities` | Yes | Any of `read`, `write`, `deploy`, `pay` |
| `tools_used` | Yes | List of tools the agent uses |
| `consent_version` | Yes | The `privacy` policy version in force; see [Policies](/docs/api/policies) |

## Reply

`201`:

```json
{ "id": "...", "status": "received", "registration_id": "...", "trust": "untrusted" }
```

## Errors

`401` no token, `403` missing scope, `409` already submitted for this registration (or stale `consent_version`; check `detail`), `422` invalid fields, `429` too many requests, `503` closed.


## Agent survey

Source: https://docs.duskstate.dev/docs/agents/survey (version agents.survey-2026-10-06)

`POST /api/v1/agents/survey` with an agent token carrying `survey:write`. Optional. Body: [`agent-survey`](https://duskstate.dev/schemas/agent-survey.json).

| Field | Required | Notes |
| --- | --- | --- |
| `current_tools` | Yes | Tools the agent uses now |
| `missing_capabilities` | Yes | What it cannot do today |
| `evidence_required` | Yes | What evidence it needs before acting |
| `payment_authority` | Yes | `none`, `within_limits`, `requires_human_approval` or `unknown` |
| `payment_limits_note` | No | Up to 500 characters |
| `preferred_formats` | Yes | Any of `json`, `markdown`, `openapi`, `mcp` |
| `feature_requests` | Yes | Up to 4,000 characters |
| `ranked_priorities` | Yes | Most important first |
| `follow_up_permission` | Yes | Whether Dusk State may contact the principal |
| `consent_version` | Yes | As for the waiting list |

## Reply and errors

As for the [agent waiting list](/docs/agents/waitlist): `201` with `id`, `status`, `registration_id` and `trust`; a second survey from the same registration gets `409`.


## MCP server

Source: https://docs.duskstate.dev/docs/agents/mcp (version agents.mcp-2026-10-06.2)

**Published when the server is live.** Until then `/api/v1/tools` answers `404` and `mcp` is not in `/capabilities.json`; check there first.

## Connect

| | |
| --- | --- |
| Endpoint | `https://mcp.duskstate.dev/mcp` |
| Transport | Streamable HTTP, stateless (JSON responses) |
| Authentication | WorkOS agent access token, as for the [waiting list](/docs/agents/authentication) |
| Resource metadata | `https://mcp.duskstate.dev/.well-known/oauth-protected-resource/mcp` (RFC 9728) |

Without a token the server answers `401` with a `WWW-Authenticate` header pointing to the resource metadata, which names the authorisation server. An anonymous registration is enough for every read tool.

## In the browser (WebMCP)

duskstate.dev runs Cloudflare's WebMCP bridge, which registers tools with the browser's `document.modelContext` for an agent using the page. It calls `https://duskstate.dev/mcp`, a read-only endpoint on the same server: no token, read tools only. The write tools are not offered there.

## Tools

| Tool | Does | Needs |
| --- | --- | --- |
| `get_capabilities` | What works now | Token |
| `list_products` | Published products, optional `category` | Token |
| `get_record` | A labelled public record by `id` | Token |
| `list_policies`, `get_policy` | Policies and their text | Token |
| `list_docs`, `get_doc` | These pages, by `path` | Token |
| `list_resources` | [Resources](/docs/api/resources), when published | Token |
| `get_roadmap` | Planned work with state labels | Token |
| `join_agent_waitlist` | The [agent waiting list](/docs/agents/waitlist) | `waitlist:write` |
| `answer_agent_survey` | The [agent survey](/docs/agents/survey) | `survey:write` |

Read tools are marked `readOnlyHint`. Each tool calls one public API endpoint, so results, limits and errors match the API; an API error comes back as a tool error with its status. Write tools pass your token to the API, which enforces consent and one submission per registration.

## Directory

`GET /api/v1/tools` lists the same tools with their JSON Schema inputs, annotations, scope and the API call each makes ([`tool-record`](https://duskstate.dev/schemas/tool-record.json)). The directory and the server are built from one definition, so the directory lists only tools the server runs.

Not available: spending, payments, keys or any write beyond the two above.


## Help and contact

Source: https://docs.duskstate.dev/docs/support (version support-2026-10-06)

| For | Contact |
| --- | --- |
| General questions, including these docs | hello@duskstate.dev |
| Security reports | security@duskstate.dev ([`security.txt`](https://duskstate.dev/.well-known/security.txt)) |
| An error in a record or page | [duskstate.dev/corrections](https://duskstate.dev/corrections) |
| Whether the API is up | [`/status.json`](https://duskstate.dev/status.json) and [duskstate.dev/status](https://duskstate.dev/status) |

Quote the `request_id` from an error, or the `X-Request-Id` header, when you report a problem with a request.

Dusk State is based in England and Wales; the [terms](https://duskstate.dev/terms) and [privacy notice](https://duskstate.dev/privacy) apply.


## Privacy notice

Source: https://duskstate.dev/privacy (version privacy-2026-10-04.2)

## Who we are

Dusk State is operated by Dusk State, the data controller for information collected on https://duskstate.dev. Jurisdiction: England and Wales. Contact: [hello@duskstate.dev](mailto:hello@duskstate.dev). Registered address and company number: not yet published.

## What we collect and why

**Audit requests.** The details you enter in the audit request form, including your contact details, company, role and the technical answers you give. We use them to respond to your request and deliver the audit. Lawful basis: steps taken at your request before entering into a contract.

**Agent waiting list and survey.** Entries submitted by software agents: the agent registration identifier, the fields submitted and, if given, a principal contact. We use them to understand demand and plan the roadmap. Lawful basis: legitimate interests. Published demand figures are aggregate counts with the sample size stated.

**Payments.** Payments are taken by Stripe, in a payment form that Stripe provides on our pages. Card details go directly to Stripe; we do not receive or store them.

**Technical data.** Our hosting provider processes IP addresses and request logs to serve the site, apply rate limits and protect it from abuse.

We record the version of this notice and the time you consented with each form submission.

## Who processes data for us

Cloudflare (hosting and security), Neon (database), WorkOS (sign-in and agent registration), Stripe (payments) and Resend (sending email). Some of these providers may process data outside the United Kingdom under their own safeguards.

## What we do not do

We do not sell personal data. We do not use advertising trackers. We do not send form text to AI providers.

## Retention

We keep audit requests and waiting-list entries while they are relevant to the purposes above, and delete them on request. A fixed retention period has not yet been set.

## Your rights

You can ask for access to, correction of or deletion of your data, or object to its use, by writing to [hello@duskstate.dev](mailto:hello@duskstate.dev). You can complain to the Information Commissioner's Office.

## Refunds and returns

Source: https://duskstate.dev/refunds (version refunds-2026-10-04.2, pending owner review)

Dusk State sells digital services and digital items only. Nothing is shipped, so there is nothing to return. This policy explains when you can cancel, how refunds work and how long they take. It adds to your statutory rights; it does not reduce them. See also our [store policy](/store-policy) and [terms](/terms).

## In short {#summary}

- Nothing has started yet: full refund.
- Consumers can cancel within 14 days, subject to the rules for services already started and digital items already accessed.
- Something we supplied is faulty or not as described: we fix it, or refund you.
- Subscriptions: cancel any time; access runs to the end of the paid period.
- Refunds go back to the original payment method within 14 days of being agreed.

## Your right to cancel (consumers) {#cancel}

If you buy as a consumer, the Consumer Contracts (Information, Cancellation and Additional Charges) Regulations 2013 give you 14 days from the day of purchase to cancel without giving a reason. To cancel, tell us clearly, for example by emailing [hello@duskstate.dev](mailto:hello@duskstate.dev?subject=Cancellation). You may use the model form below, but you do not have to.

- **Services started at your request.** If you ask us to start a check, report or audit within the 14 days and then cancel, we refund the price less a proportionate amount for what we have already done. Once the service is fully delivered at your request, the right to cancel ends.
- **Digital items and unlocked reports.** Before access starts, we ask you to agree to immediate access and to confirm that you lose the right to cancel once it starts. Your rights for faulty or misdescribed items remain.
- **Subscriptions.** You can cancel within 14 days of first subscribing and receive a refund less a proportionate amount for the days you used.

## Business customers {#business}

The statutory right to cancel does not apply to business purchases. We still refund in full before work or access starts, and we apply the fault and non-delivery commitments below to everyone.

## Faulty, incomplete or not as described {#faulty}

Under the Consumer Rights Act 2015, services must be performed with reasonable care and skill, and digital content must be as described, of satisfactory quality and fit for purpose. If something falls short, tell us within 30 days of delivery. We will put it right (for example, by re-running a check or replacing an item) or, if we cannot, refund in part or in full. If we cannot deliver what we agreed, we refund in full.

## Subscriptions {#subscriptions}

- Subscriptions renew automatically until you cancel. Cancel from your account or by email; cancellation takes effect at the end of the current period, and you keep access until then.
- For yearly plans, we email you at least 14 days before each renewal with the date and price.
- We give at least 30 days' notice of any price change, and you may cancel before it applies.
- We do not refund unused time in a period, except under your right to cancel, for a fault on our side, or where the law requires it.
- Seat changes take effect as shown at checkout. Removing a seat does not refund the current period.

## Purchases made by an agent {#agents}

A purchase an agent makes for you is your purchase and this policy applies to it. If an agent bought something you did not intend, tell us within 14 days and before delivery or access starts, and we refund in full. Agent orders are checked before payment, and we decline any we cannot fulfil.

## Duplicate or incorrect charges {#charges}

If you are charged twice or charged the wrong amount, tell us and we refund the difference as soon as we confirm it. Please contact us before raising a dispute with your bank; it is usually faster, and it does not affect your rights.

## How to ask for a refund {#how}

Email [hello@duskstate.dev](mailto:hello@duskstate.dev?subject=Refund%20request) from the address you paid with, and include your order reference or invoice number (shown on your [order page](/orders) and receipt). We reply within five working days. Agreed refunds go to the original payment method within 14 days, with no fee. Your bank may take a further 5 to 10 working days to show them. Discounted purchases are refunded at the amount you paid.

## Model cancellation form {#model-form}

> To Dusk State, hello@duskstate.dev: I hereby give notice that I cancel my contract for the supply of the following service or digital content: [description]. Ordered on: [date]. Name: [your name]. Email used for the order: [email]. Date: [date].

## Complaints {#complaints}

If you are unhappy with how we handled a refund, reply to our email and ask for a review. We respond within 14 days. This does not affect your right to go to court in England and Wales.

## Store policy

Source: https://duskstate.dev/store-policy (version store-policy-2026-10-04, pending owner review)

This policy explains how buying from Dusk State works, for people, teams and the agents acting for them. It sits alongside our [terms](/terms), [refund policy](/refunds) and [privacy notice](/privacy).

## What we sell {#what}

- Agent-readiness checks and full reports for a domain.
- Detailed audits of one tool, with scope agreed in writing first.
- Subscriptions (Dusk State Pro and Team), priced per seat.
- Digital items in the [store](/store): templates, prompts, automations, tools, plugins, snippets, blueprints, playbooks and starter kits.

We only offer something for sale when we can deliver it. Until then it is shown as opening soon, and orders for it are declined. Current prices are on the [pricing page](/pricing) and at [/pricing.json](/pricing.json).

## Prices and tax {#prices}

Prices are in pounds sterling. Dusk State is not VAT registered, so no VAT is charged. If that changes, prices shown before you pay will say whether VAT is included. The price you see at checkout is the price you pay.

## Payment {#payment}

Payments are processed by Stripe. We never see or store your full card number. Business customers can ask to pay by invoice and bank transfer. Your order is confirmed only when payment succeeds.

## Delivery {#delivery}

Everything is delivered digitally:

- Check reports: on screen as soon as payment succeeds.
- Audits: on the timetable agreed in writing before work starts.
- Subscriptions: access on your account as soon as payment succeeds.
- Store items: download or access from your account as soon as payment succeeds.

## Orders, receipts and invoices {#orders}

After you pay, Stripe emails a receipt. Your [order page](/orders) (linked from the receipt) shows the order, invoice and receipt, and is also available as JSON for agents. Signed-in customers will see their full order history on their account.

## Using digital items {#licence}

Each item states its licence on its page. Unless it says otherwise, you may use it in your own and your organisation's work, but not resell or redistribute it as it is.

## Buying through an agent {#agents}

Agents may find our products through AI shopping services. Each agent order is checked against current availability and price before payment; we decline anything we cannot fulfil. The person or organisation the agent acts for is the customer and is responsible for the purchase.

## Cancellations and refunds {#cancel}

See the [refund policy](/refunds), including your 14-day right to cancel as a consumer.

## Support and complaints {#support}

Email [hello@duskstate.dev](mailto:hello@duskstate.dev). We reply within five working days. These terms are governed by the law of England and Wales.

## Changes {#changes}

We will update the version below when this policy changes. Orders follow the version in force when you paid.

## Terms

Source: https://duskstate.dev/terms (version terms-2026-10-04)

## Who provides the service

https://duskstate.dev and its services are provided by Dusk State. These terms are governed by the law of England and Wales, and its courts have jurisdiction.

## Public records and content

Records and articles describe what we observed, when, and from which source. Each claim carries a state: observed, inferred, proposed, unknown or superseded. A record is not an endorsement, certification or guarantee of any tool. Check the evidence before you rely on it, and report errors through [corrections](/corrections).

## Paid services

No paid service is on sale yet. Each opens only when we can deliver it, with its price, scope and delivery stated before you pay. Payment is taken through Stripe. Cancellations and refunds follow our [refund policy](/refunds), and our [store policy](/store-policy) explains how buying works.

## Agents and principals

Software agents may submit a waiting-list entry and a survey. An agent acts for a person or organisation, who remains responsible for it. Agents registered without a claimed principal receive restricted access only: they cannot pay, hold keys or write anything beyond one waiting-list entry and one survey.

## Legend programme {#legend}

People who join the waiting list before public registration opens become Legend members. An agent becomes a Legend member when a Legend member claims it. Legend status is applied when the member's account is created with the same email address used on the waiting list. Perks:

- Legend label on your account, showing you joined before public registration opened.
- Dusk State Pro free for the first 12 months.
- 20% off store purchases for 12 months.
- Early access to new launches, including the feed, change monitoring and the agent store, before general release.
- One free re-check with any audit.

Time-limited perks run for 12 months from the date the account is created. Discounts apply to prices shown at the time of purchase and cannot be exchanged for cash. One Legend status per person. The programme closes when public registration opens; joining the waiting list after that date does not give Legend status. Version `legend-2026-10-04`.

## Acceptable use

Do not attempt to bypass rate limits or access controls, submit content you have no right to submit, or use the service to harm others. We may refuse or remove submissions that break these terms.

## Liability

Nothing in these terms limits liability that cannot be limited by law. Otherwise, our liability for the audit is limited to the amount you paid for it.

## Changes

We will update the date above when these terms change.