# AGENTS.md - Nopaque / TotalPath

Instructions for AI coding agents integrating with Nopaque.

Nopaque Ltd builds **TotalPath**, an on-demand voice testing platform for contact centres. TotalPath maps, tests, and load-tests IVRs and AI voice agents from the customer's perspective by placing **real outbound PSTN phone calls**.

That last sentence is the whole reason this file exists. Several operations below dial real phone numbers and bill the workspace per second, with a 30-second minimum per call. Read the cost and consent section before you write any code that calls them.

## Read this first: cost and consent

**Some Nopaque operations spend the user's money and place real phone calls to real phone numbers. Never invoke them without explicit user confirmation for that specific run.**

The billable, call-placing operations are:

- **Starting a mapping run** (the `startMapping` MCP tool, REST `POST /mapping/{id}/start`, or the web app) - dials the target number and walks its menu tree, potentially many times. Creating the job (`createMapping`, `POST /mapping`) only saves it, idle, and places no call.
- **Running a scripted test, a mission test or a compliance test** (`runTest`, `runMissionTest`, `runComplianceTest`, or the REST equivalents) - dials the target and holds a scripted conversation.
- **Running a chatbot test** (`runDigitalTest`) - places no phone call, but holds a conversation with the target chatbot and is billed in AI tokens from the workspace's allowance or credit.
- **Starting a load test** - dials the target with many concurrent calls, by design.

Rules an agent must follow:

1. **Confirm before every run, not once per session.** "The user asked me to test their IVR" is not consent to run it again an hour later, or against a different number.
2. **Echo the target number back to the user before dialling.** A typo in a phone number means calling a stranger. There is no undo on a placed call.
3. **Never guess a phone number.** If the number is not something the user explicitly gave you for this run, stop and ask.
4. **Treat load tests as the highest-risk operation.** They generate concurrent traffic against a live contact centre and can degrade a production phone system. Confirm the concurrency and duration explicitly.
5. **Read operations are safe.** Listing jobs, fetching results, reading the catalogue and checking usage place no calls and cost nothing. Prefer them.

The MCP tool descriptions carry this warning for MCP clients. This file is what an agent working directly against the REST API reads instead.

## REST API

- Base URL: `https://api.nopaque.co.uk`
- OpenAPI 3.1 (JSON): <https://api.nopaque.co.uk/openapi.json>
- OpenAPI 3.1 (YAML): <https://api.nopaque.co.uk/openapi.yaml>

Fetch the OpenAPI document with `GET`. The API gateway answers `HEAD` with 404 on routes that serve 200 on `GET`, so a `HEAD` probe will mislead you into thinking an endpoint does not exist.

Endpoints cover mapping, testing, load testing, compliance, audio, billing and workspaces.

## Authentication

Authenticate with a **workspace-scoped API key** in the `x-api-key` header:

```
x-api-key: <your-workspace-api-key>
```

**No key yet?** Register your own workspace. The MCP server at <https://mcp.nopaque.co.uk> exposes a `registerWorkspace` tool that needs no credential: it creates a workspace and returns a scoped API key, once. The workspace can create records immediately but cannot place a call until a human has verified a mobile number for it and, on the Free plan, added a card. Call `requestAnchorCode` with the person's mobile in E.164 format, ask them for the code that arrives by SMS, and submit it with `verifyAnchorCode`. That gives the workspace its free calling capacity, unless the response says `freeGrantOutcome: not-owed`, which means that number already spent its one free allocation. In that case the human is still verified and `getClaimLink` is how they pay for capacity. Then call `getClaimLink`: it mints a one-hour link for the person to open in a browser and take the workspace over, after which they add a card on the Verify page (`/verify`; it is not charged on the Free plan) and can buy more capacity. A run attempted before the card is added is refused with HTTP 402 and `errorCode: "VERIFICATION_REQUIRED"`. The anchor and claim steps are also REST routes in the OpenAPI document (`/anchors/request-code`, `/anchors/verify-code`, `/claim`); registration itself is through the MCP tool.

**Every tier can create a key in the web app, including free.** If you are working on behalf of someone who already has an account, they can issue you one themselves. Registering your own workspace as above is for when there is no account to work from.

People create and manage keys at <https://www.nopaque.co.uk/docs/authentication>.

## Two integration mistakes that cost people hours

### 1. Mapping jobs never reach `completed`

Mapping **jobs** cycle between `running` and `idle`. They do **not** progress to `completed` - ever. Only individual **runs** reach `completed`.

Polling a job's status waiting for `completed` is an infinite loop. Poll the run instead: take `currentRun.id` from the job, then check that run's status.

### 2. Cross-workspace requests return 404, not 403

Requesting a resource that belongs to a different workspace returns **404 Not Found**, not 403 Forbidden. This is deliberate - a 403 would confirm the resource exists.

So a 404 does not mean "retry later" or "the ID is wrong". Do not retry it. Check which workspace the API key belongs to.

## MCP server

- Server URL: <https://mcp.nopaque.co.uk>
- Server card: <https://www.nopaque.co.uk/.well-known/mcp/server-card.json>

Enumerate the available tools with a JSON-RPC `tools/list` call against the server URL, or read the server card, which lists every tool an API key can call (88) with its description. Authentication is the same workspace API key in the `x-api-key` header. `registerWorkspace` is the one tool that runs without a key, because it is how an agent obtains one. Seven more read tools, for billing, plan, usage by source and alerting, serve only a person signed in to the web app: they refuse an API key, a `tools/list` sent with a key leaves them out, and one sent without a key marks them `_meta["co.uk.nopaque/auth"] = "session"`. `createMapping` saves an idle mapping job and places no call; a run is started with the `startMapping` tool or REST `POST /mapping/{id}/start`. The `create*` tools save a record and place no call; the `run*` and `start*` tools are the ones that do.

## SDKs

Both are open source and published:

- **Python**: <https://github.com/nopaque/python-sdk>
- **Node**: <https://github.com/nopaque/node-sdk>

Each repo has its own `AGENTS.md` covering how to work *on* that SDK. This file covers how to work *with* the API.

## Where the facts live

Do not hardcode prices, rates or free-tier allowances into generated code or documentation. They are published and they change:

- **Pricing**: <https://www.nopaque.co.uk/pricing.md> - every plan, every per-minute rate, the free-tier breakdown
- **Product facts**: <https://www.nopaque.co.uk/llms.txt> (summary) and <https://www.nopaque.co.uk/llms-full.txt> (detail)
- **Machine-readable discovery**: <https://www.nopaque.co.uk/.well-known/ai-catalog.json>
- **Human docs**: <https://www.nopaque.co.uk/docs>

Billing is per second after a 30-second minimum per connected call; rates are displayed per minute. A 10-second call is billed as 30 seconds, a 90-second call as 90 seconds, and an unanswered call is not billed.

## Company

Nopaque Ltd, 86-90 Paul Street, London, EC2A 4NE, United Kingdom.
Contact: info@nopaque.co.uk
