Admin API¶
Everything FastMock does is controlled through the admin API: stubs, the request journal, verification, body files, imports, recording, scenarios, chaos rules and gRPC descriptors. The UI uses the same API.
- Where it lives
- OpenAPI document and Swagger UI
- Authentication
- Roles per endpoint
- Errors
- Pagination and filtering
- Stubs
- Partial updates (PATCH)
- Metadata search (WireMock compatible)
- Unused stubs
- Body files
- Audit log
- Version and info
- Limits
- Metrics
The examples use FASTMOCK_TOKEN for an editor token (an admin token where noted), the admin API on
localhost:9090 and the data plane on localhost:8080.
Where it lives¶
All routes are under /__admin on the admin listener (FASTMOCK_ADMIN_LISTEN, default 0.0.0.0:9090), which
is separate from the data plane that serves stubs. The admin listener also serves, without authentication:
| Path | Content |
|---|---|
/openapi.json |
OpenAPI 3.1 description of the admin API (no data) |
/ui, /ui/api |
web UI and the Swagger UI for the admin API |
/healthz, /readyz |
liveness and readiness |
/metrics |
Prometheus metrics |
OpenAPI document and Swagger UI¶
GET /openapi.json returns the complete OpenAPI 3.1 document of the admin API: every route, request and response
schema (the stub model included), query parameters, error responses and examples. It is served with
Cache-Control: no-cache and the same security headers as the rest of the admin listener. The same document is
kept in the repository at docs/api/openapi.json.
Open http://localhost:9090/ui/api for Swagger UI: click Authorize, paste a token, and try requests from the
browser. Use the document to generate clients:
Authentication¶
Every /__admin request needs Authorization: Bearer <token>. Tokens are configured as
name:role:sha256hex entries in FASTMOCK_ADMIN_TOKENS or FASTMOCK_ADMIN_TOKENS_FILE; the server stores only
SHA-256 hashes and compares them in constant time. Create a token and its entry with:
fastmock hash-token --generate # prints a new random token and its hash
fastmock hash-token "$FASTMOCK_TOKEN" # prints the hash of an existing token
# FASTMOCK_ADMIN_TOKENS=ci:editor:<hash>,dash:viewer:<hash>
Browser requests carrying an Origin header are accepted only from FASTMOCK_ADMIN_ALLOWED_ORIGINS or the
admin listener's own origin.
| Response | Meaning |
|---|---|
401 {"error":"unauthorized","details":[]} + WWW-Authenticate: Bearer |
token missing or unknown |
403 {"error":"forbidden","details":["requires role editor"],"required":"editor"} |
token valid, role too low |
403 {"error":"origin not allowed","details":[]} |
browser request from another origin |
Roles per endpoint¶
There are three roles, each including the one before: viewer reads, editor changes test state,
admin can additionally wipe everything and read the audit log. The rule is: GET/HEAD and read-only POSTs
need viewer, every other method needs editor; the routes marked admin need admin.
| Endpoint | Role |
|---|---|
GET /stubs, /stubs/{id}, /stubs/unused, /export |
viewer (credentials masked, see Security: redaction) |
POST /stubs/find-by-metadata, POST /stubs/validate |
viewer |
POST /stubs, PUT/PATCH/DELETE /stubs/{id}, DELETE /stubs?tag=, POST /stubs/import, POST /stubs/remove-by-metadata |
editor |
DELETE /stubs (no tag: all stubs) |
admin |
GET /requests, /requests/{id}, /requests/unmatched, /requests/count |
viewer |
POST /requests/count, /requests/near-misses, /requests/find, /verify, /verify/sequence |
viewer (bounded scans, see Verification: limits) |
DELETE /requests, POST /requests/remove |
editor |
GET /files, /files/{name} |
viewer |
PUT/DELETE /files/{name} |
editor |
POST /import, /import/openapi, /import/wiremock, /import/postman, /import/har (and the other /import/*) |
editor |
GET /recordings; POST /recordings/start, /recordings/stop, /recordings/snapshot |
viewer; editor |
GET /callbacks, /scenarios, /kv/{key}, /chaos, /grpc/descriptors |
viewer |
DELETE /callbacks, DELETE /scenarios, PUT /scenarios/{name}, PUT/DELETE /kv/{key}, PUT/DELETE /chaos, PUT/DELETE /grpc/descriptors/{name} |
editor |
GET /info, /version, /plugins |
viewer |
GET /contract-tests, /contract-tests/{id} |
viewer (verdicts only; details need editor) |
POST /contract-tests, DELETE /contract-tests/{id} |
editor; POST with secretHeaders needs admin |
POST /reset, GET /audit |
admin |
Errors¶
Every error from the admin API has the same JSON shape:
error is a single human-readable sentence; details lists individual problems when there are several (for
example the mismatches of a failed verification). Some responses add fields: 403 adds required, 422 from
/verify adds the actual count and nearMisses. Errors never contain stack traces, internal paths or database
messages; internal failures answer 500 {"error":"internal error","details":[]} and are logged with details on the
server.
| Status | When |
|---|---|
| 400 | invalid parameter, invalid stub, pattern, tag, file name or document; a request body that is not valid JSON or does not fit the schema (unknown field, wrong type); an import that yields no stub |
| 401 / 403 | see Authentication |
| 404 | the stub, request, file, key or route does not exist |
| 405 | method not allowed on this route |
| 409 | conflict: stub id exists on POST /stubs, incompatible gRPC descriptor, too many files |
| 413 | body larger than the route allows |
| 415 | POST /import cannot detect or convert the format; missing JSON content type |
| 422 | a verification that failed (/verify, /verify/sequence), or a journal scan over its work budget |
Pagination and filtering¶
List endpoints take limit (1..10000) and offset (default 0) and return the total before pagination:
curl -s -H "Authorization: Bearer $FASTMOCK_TOKEN" \
"http://localhost:9090/__admin/stubs?tag=billing&q=invoice&enabled=true&limit=20&offset=40"
| Endpoint | Filters | Default page |
|---|---|---|
GET /stubs |
tag, q (case-insensitive substring of the name, urlPath, urlPathPattern or urlPathTemplate), enabled |
all stubs, newest first |
GET /requests |
source, method, pathPrefix, correlation, bodyContains, matched, stubId, since |
100 entries, newest first |
GET /requests/unmatched |
source, since |
100 entries |
GET /audit |
action (exact, or prefix with a trailing *), principal, since |
100 events |
GET /requests answers {"requests": [...], "total": n, "offset": o, "limit": l}.
Stubs¶
curl -s -X POST http://localhost:9090/__admin/stubs \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'Content-Type: application/json' \
-d '{"name": "invoice", "request": {"method": "GET", "urlPathTemplate": "/invoices/{id}"},
"response": {"jsonBody": {"id": "{{request.pathParams.id}}"}},
"tags": ["billing"], "metadata": {"service": "billing", "owner": {"team": "payments"}}}'
POST answers 201 with the saved stub (409 when the id exists), PUT /stubs/{id} creates or replaces,
DELETE /stubs/{id} answers 204. POST /stubs/validate checks a stub without saving it and answers
{"valid": false, "error": "..."} for an invalid one. GET /export?tag= returns stubs in the format
POST /stubs/import accepts.
Partial updates (PATCH)¶
PATCH /stubs/{id} applies an RFC 7396 JSON merge patch to the stored
stub: objects merge, null removes a field, arrays and scalars replace. The id cannot change. The result is
validated like a PUT.
# disable a stub
curl -s -X PATCH http://localhost:9090/__admin/stubs/$ID \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'Content-Type: application/merge-patch+json' \
-d '{"enabled": false}'
# switch it to an error and drop its response headers
curl -s -X PATCH http://localhost:9090/__admin/stubs/$ID \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'Content-Type: application/json' \
-d '{"enabled": true, "response": {"status": 503, "headers": null}}'
application/json and application/merge-patch+json are both accepted. The response is the patched stub; 404
when the stub does not exist, 400 when the patch produces an invalid stub.
Metadata search (WireMock compatible)¶
Stubs carry free-form metadata (any JSON object). Find or delete stubs by it, with the same body WireMock uses:
curl -s -X POST http://localhost:9090/__admin/stubs/find-by-metadata \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'Content-Type: application/json' \
-d '{"matchesJsonPath": "$.service", "equalTo": "billing"}'
curl -s -X POST http://localhost:9090/__admin/stubs/remove-by-metadata \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'Content-Type: application/json' \
-d '{"matchesJsonPath": {"expression": "$.owner.team", "equalTo": "payments"}}'
| Field | Meaning |
|---|---|
matchesJsonPath |
JSONPath (RFC 9535) that must select at least one node; a string, or {"expression", "equalTo"\|"contains"\|"matches"} as in WireMock |
equalTo |
a selected node equals this value (strings compare as text, other JSON values structurally) |
contains / matches |
a selected node's text contains the string / matches the whole regular expression |
equalToJson |
the metadata equals this JSON; with ignoreExtraElements: true it only has to contain it |
find-by-metadata answers like GET /stubs ({"total", "offset", "stubs"}) and needs only viewer;
remove-by-metadata answers {"deleted": 2, "ids": [...]} and needs editor. Stubs without metadata never match.
Unused stubs¶
GET /stubs/unused?since=2026-11-01T00:00:00Z lists stubs that no journal entry matched (since the given
instant). The answer is computed from the request journal, so it covers only the journal retention window
(FASTMOCK_JOURNAL_RETENTION) and only requests made while the journal was enabled.
Body files¶
Body files are stored by the server (in PostgreSQL with the default storage) and used by stubs through
response.bodyFileName instead of inline bodies.
# upload or replace: raw body, the Content-Type is stored with the file
curl -s -X PUT http://localhost:9090/__admin/files/invoices/42.json \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'Content-Type: application/json' \
--data-binary @invoice-42.json
# {"name":"invoices/42.json","contentType":"application/json","size":812,"updatedAt":"2026-11-19T10:00:00.000Z"}
curl -s -H "Authorization: Bearer $FASTMOCK_TOKEN" http://localhost:9090/__admin/files
# {"total":1,"files":[{"name":"invoices/42.json","contentType":"application/json","size":812,"updatedAt":"..."}]}
curl -s -H "Authorization: Bearer $FASTMOCK_TOKEN" -o out.json http://localhost:9090/__admin/files/invoices/42.json
curl -s -X DELETE -H "Authorization: Bearer $FASTMOCK_TOKEN" http://localhost:9090/__admin/files/invoices/42.json
PUT answers 201 for a new file and 200 for a replaced one. Downloads come back with the stored content type,
Content-Disposition: attachment and a sandboxing Content-Security-Policy, so an uploaded HTML file is never
rendered on the admin origin.
| Rule | Value |
|---|---|
| name | [A-Za-z0-9._-/], 1..512 bytes, relative, no .., no empty or . segments |
| size | at most 10 MiB per file (413 above) |
| count | at most 10000 files (409 above) |
| content type | the request's Content-Type, default application/octet-stream, at most 255 characters |
Every upload and delete is recorded in the audit log (file.put, file.delete).
Audit log¶
Every change through the admin API is recorded with who, what and when. Admins read it with filters:
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:9090/__admin/audit?action=stub.*&principal=ci&since=2026-11-19T00:00:00Z&limit=50"
{"events": [{
"id": 912, "at": "2026-11-19T10:02:11.120Z", "principal": "ci", "role": "editor",
"action": "stub.update",
"detail": {"id": "4f0c…", "name": "invoice", "changesTruncated": false, "changes": [
{"path": "/response/status", "before": 200, "after": 503},
{"path": "/enabled", "before": true, "after": false}
]}
}]}
Stub updates (PUT, PATCH) store the changed fields as JSON Pointer paths with their old and new values (at most
100 changes, values larger than 16 KiB are replaced by {"truncated": true, "bytes": n}); stub.delete stores
the deleted stub in before. Sensitive header values and JSON fields named like secrets are masked (***) before
they are written. Other actions: stub.create, stub.delete_many, stub.delete_by_metadata, stub.import,
import.<format>, journal.clear, journal.remove, file.put, file.delete, recording.start,
recording.stop, recording.snapshot, scenario.set, scenario.reset, kv.set, kv.delete, chaos.set,
chaos.clear, grpc.descriptor.put, grpc.descriptor.delete, callbacks.clear, reset. Audit entries are also
logged with the audit tracing target.
Version and info¶
curl -s -H "Authorization: Bearer $FASTMOCK_TOKEN" http://localhost:9090/__admin/version
# {"version":"0.1.0","gitSha":"3f2c1ab","features":["grpc","kafka","sse","chaos","recording","verification","files","import-openapi","import-wiremock","import-postman","import-har"]}
gitSha is set when the binary was built with the FASTMOCK_GIT_SHA environment variable, otherwise null.
GET /info returns the version, storage kind, uptime, number of loaded stubs, plugins and the caller's identity.
Limits¶
| Limit | Value |
|---|---|
| request body on the admin API | 32 MiB (64 MiB hard limit on the listener) |
| body file | 10 MiB, 10000 files |
| stubs per import | 10000 |
limit on list endpoints |
1..10000 |
| JSONPath / regular expression in metadata search | 1024 bytes / 256 KiB compiled |
GET /audit filters |
action and principal at most 128 bytes |
Metrics¶
| Metric | Labels | Meaning |
|---|---|---|
fastmock_admin_changes_total |
action |
audited admin changes |
fastmock_admin_auth_failures_total |
reason (token, role, origin) |
rejected admin requests |
fastmock_admin_errors_total |
internal errors in admin handlers | |
fastmock_files_written_total |
body file uploads | |
fastmock_file_size_bytes |
histogram of uploaded file sizes | |
fastmock_imports_total |
format, dry_run |
imports |
fastmock_admin_verifications_total |
kind (count, sequence), result (pass, fail) |
verifications, see Verification |
fastmock_snapshot_stubs_total |
stubs generated by snapshots, see Recording |
See also: Verification, Recording, Importing.