Control API

aimock exposes a small HTTP control surface under the /__aimock/* prefix for inspecting recorded traffic and resetting server state between test runs — no restart required.

All control routes are exact-match and live alongside your mocked LLM endpoints on the same port. They are intended for use from test harnesses (directly via fetch / curl, or through the aimock-pytest client).

Route Overview

Reset Routes

aimock keeps several kinds of in-memory state between requests: the loaded fixtures, the per-provider generation state (video and fal.ai jobs, plus the Gemini interaction and event-id counters), the fixture match-counts (sequence position), and the request journal (recorded requests). Two routes clear it: POST /__aimock/reset clears all of it, and POST /__aimock/reset/journal clears only the recorded requests and leaves everything else intact. A third, POST /__aimock/reset/fixtures, is a deprecated alias for the full reset.

POST /__aimock/reset

Full reset. Returns the server to a pristine, fixture-free state. It clears the in-memory fixtures, the journal entries and the per-test fixture match-counts (so sequenced fixtures rewind to their first response), the video and fal.ai job and queue state, and the Gemini interaction and event-id counters.

$ curl -X POST http://localhost:4010/__aimock/reset

{ "reset": true }

POST /__aimock/reset/journal

Journal only. Clears only the request journal entries. Your loaded fixtures, generation state, and fixture match-counts (sequence position) are preserved, so the next request still matches. This is the recommended call for a clean read between test runs.

$ curl -X POST http://localhost:4010/__aimock/reset/journal

{ "reset": true }

POST /__aimock/reset/fixtures (Deprecated)

Deprecated alias for /__aimock/reset. The name promises a fixtures-only reset, but it performs the same full reset — journal, match-counts, job state and counters all go with it. It additionally sets a Deprecation: true response header and adds deprecated / deprecation fields to the body. Use /reset for a full reset, or /reset/journal for a journal-only one; to clear fixtures and nothing else, use DELETE /__aimock/fixtures.

$ curl -i -X POST http://localhost:4010/__aimock/reset/fixtures

// Deprecation: true   (response header)
{
  "reset": true,
  "deprecated": true,
  "deprecation": "POST /__aimock/reset/fixtures is deprecated; use POST /__aimock/reset (full reset) or POST /__aimock/reset/journal (journal only)"
}

Inspection

GET /__aimock/health

A simple liveness probe. Returns 200 once the server is accepting requests.

$ curl http://localhost:4010/__aimock/health

{ "status": "ok" }

GET /__aimock/journal

Returns a read-only snapshot of the recorded request entries as a JSON array. The journal records each incoming request so tests can assert on what was sent. Clearing it does not affect fixtures — see /__aimock/reset/journal above.

$ curl http://localhost:4010/__aimock/journal

[
  /* recorded request entries */
]

Fixtures

GET /__aimock/fixtures

Read-only: how many fixtures are currently registered. Useful for asserting a CI job or test harness actually loaded its tape before it starts making requests, without having to send a probe request and infer the answer from the reply. Returns the count only — fixtures hold predicate functions, so nothing about their contents is serialized.

$ curl http://localhost:4010/__aimock/fixtures

{ "count": 2 }

POST /__aimock/fixtures

Add fixtures at runtime without restarting the server. The body is an object with a "fixtures" array of fixtures to register. Returns the number of fixtures added.

$ curl -X POST http://localhost:4010/__aimock/fixtures \
  -H "Content-Type: application/json" \
  -d '{ "fixtures": [{ "match": { ... }, "response": { ... } }] }'

{ "added": 1 }

DELETE /__aimock/fixtures

Clears all registered fixtures. Generation state and the journal are left untouched. To clear everything at once, use /__aimock/reset instead.

$ curl -X DELETE http://localhost:4010/__aimock/fixtures

{ "cleared": true }

Error Injection

POST /__aimock/error

Queues a one-shot error injection. The next matching request returns the queued error instead of a normal response, after which the injection is consumed. See Error Injection for the full request shape and options.

$ curl -X POST http://localhost:4010/__aimock/error \
  -H "Content-Type: application/json" \
  -d '{ "status": 429, "body": { "message": "rate limited", "type": "rate_limit_error" } }'

{ "queued": true }