Stateful CRUD mock API

Create and inspect a collection

POST /api/mocks with name, routes and crud. crud contains a single collection path and a seed array. routes may be empty, or contain non-overlapping static routes. Save the returned managementToken, accessToken, resource ID and expiry. Private is the default. GET /api/mocks/{id}, authenticated for management, returns configuration and crudState containing live records and revision.

Collection paths use one segment starting with a letter, followed by letters, digits, underscores or hyphens, with at most 40 characters excluding the slash. IDs use 1–80 letters, digits, underscores or hyphens. Omitted seed IDs become seed_1, seed_2 and so on; omitted POST IDs receive a generated rec_ identifier. Duplicate IDs return 409.

{
  "name": "Tasks API",
  "routes": [],
  "crud": {
    "path": "/tasks",
    "seed": [
      {
        "id": "task_1",
        "name": "Review the checkout",
        "status": "todo"
      }
    ]
  }
}

Record operations

The base record URL is /mock/{id}{crud.path}. Use Content-Type: application/json for writes. Private callers send X-Access-Token, or use workspace authorization with resources:read for reads and resources:write for mutations. Management tokens alone cannot call private record endpoints.

Pagination, search and revision guards

Collection GET accepts limit=1..100 (default 50), offset=0..200, q up to 200 characters, sort as a top-level field name, and order=asc|desc. Search is case-insensitive across the record JSON. Numeric values sort numerically; other values sort as strings. Missing or null sort fields appear last.

CRUD responses expose X-Mock-Revision. Send X-Mock-If-Revision with a nonnegative integer on writes to require an exact collection revision. A mismatch returns 409 without changing records. Successful mutations advance the revision; validation failures do not. CORS supports browser requests with explicit caller headers and exposes the revision header.

SDK, CLI, SSH and MCP

SDK request accepts a relative /mock/ path and uses its fourth argument as the caller access token. The CLI api command follows the same rule for --token; /api/ management requests continue to use the management token. The SSH command gateway accepts the same CLI command. Do not put credentials in URLs.

MCP create_mock_api accepts the same CRUD configuration. call_mock_api takes id, method, path, optional accessToken, optional object body and optional numeric revision. Its result includes status, body and the available revision. For management, resource_request supports inspect, update, reset, sharing, renew and delete. reset requires kind=mocks and management access. These operations use the HTTP handlers and their access and storage checks.

const record = await socket.request("POST", `/mock/${id}/tasks`,
  { name: "Check the receipt", status: "todo" }, accessToken);

// CLI / SSH: provide a caller token separately
// socket-help api GET /mock/<id>/tasks --token <access-token>

Reset, replace and expire

POST /api/mocks/{id}/reset restores the saved seed, advances the collection revision and returns {reset,records,revision}. PUT /api/mocks/{id} replaces the configuration and resets live data to its new seed. Replacing an existing CRUD configuration advances its revision as well. Neither operation extends expiry.

Renewal, persistent-resource eligibility, deletion, sharing and storage follow the existing resource lifecycle and plan limits. A reset discards live changes but leaves the endpoint and sharing configuration in place. Export configuration and live records separately when you need both. PostgreSQL deployments retain live records across application restarts until expiry or deletion.

Validation and limits

A record must be a JSON object with at most 40 top-level fields, 4 KiB of JSON and eight levels of nesting. Reserved prototype keys and unsafe numeric integers are rejected; keep large identifiers as strings. Seed data fits in 64 KiB, the complete mock configuration in 80 KiB, and live records in 128 KiB. Both seed and live collections allow at most 200 records.

The mock endpoint permits up to 120 requests per minute per API. Existing global and account resource storage limits also apply; a rejected allocation does not partially commit a write. Validation errors return 400, stale revisions or duplicate IDs 409, unsupported media types 415, and missing, expired or unauthorized resources 404. A malformed record never changes the collection.