API Reference

Base URL

https://api.mockra.io

---

Authentication

All API endpoints require an Authorization header.

Auth0 JWT (dashboard users):

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

API key (CI/CD, automation):

Authorization: Bearer mra_a3f9b2c1d4e5...

API keys have the prefix mra_. See API Keys & CI/CD for how to create them.

---

Workspaces

List workspaces

GET /workspaces

Returns all workspaces owned by the authenticated user.

Response:

[
  {
    "id": "ws_abc123",
    "name": "My Project",
    "namespace": "sunny-fox-4a2b",
    "tier": "pro",
    "monthly_request_count": 12400,
    "monthly_request_limit": 1000000,
    "created_at": "2025-01-15T10:00:00Z"
  }
]

Create workspace

POST /workspaces

Body:

{ "name": "My Project" }

Response: 201 Created with the new workspace object.

---

Schemas

Upload schema

POST /workspaces/{workspace_id}/schemas

Accepts multipart file upload, URL fetch, or raw body.

File upload (multipart/form-data):

curl -X POST https://api.mockra.io/workspaces/{id}/schemas \
  -H "Authorization: Bearer {token}" \
  -F "file=@openapi.yaml"

URL fetch:

curl -X POST https://api.mockra.io/workspaces/{id}/schemas \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/openapi.yaml" }'

Raw body:

curl -X POST https://api.mockra.io/workspaces/{id}/schemas \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "raw": "openapi: 3.0.0\ninfo:\n  ..." }'

Response: 201 Created with the schema object and endpoint_count.

List schemas

GET /workspaces/{workspace_id}/schemas

Get schema

GET /workspaces/{workspace_id}/schemas/{schema_id}

Returns schema details including all parsed endpoints.

List endpoints

GET /workspaces/{workspace_id}/schemas/{schema_id}/endpoints

Returns all endpoints with their mock URLs.

Response:

[
  {
    "id": "mc_xyz",
    "method": "GET",
    "path": "/users",
    "mock_url": "https://mock.mockra.io/sunny-fox-4a2b/users",
    "status_code": 200
  }
]

Delete schema

DELETE /workspaces/{workspace_id}/schemas/{schema_id}

Deletes the schema and all associated mock configs. Returns 204 No Content.

---

Mock Configs

Update mock config

PUT /mock-configs/{id}

Body:

{
  "status_code": 200,
  "body": { "id": 1, "name": "Alice" },
  "headers": {
    "X-Request-Id": "abc-123"
  },
  "latency_ms": 200
}

All fields are optional — only include the ones you want to change.

Notes:

• latency_ms requires Pro or Enterprise tier
• body with template syntax ({body.x}) requires Pro or Enterprise tier
• Returns 403 if the update includes Pro features on a Free or Starter workspace

Response: 200 OK with the updated mock config.

---

State Configs

Get state sequence

GET /mock-configs/{id}/state

Returns the state sequence for a mock config, or 404 if none is configured.

Response:

{
  "id": "sc_abc",
  "mock_config_id": "mc_xyz",
  "sequence": [
    { "status_code": 202, "body": { "status": "pending" }, "repeat": 1 },
    { "status_code": 200, "body": { "status": "complete" }, "sticky": true }
  ]
}

Create or update state sequence

PUT /mock-configs/{id}/state

Body:

{
  "sequence": [
    { "status_code": 202, "body": { "status": "pending" } },
    { "status_code": 200, "body": { "status": "complete" }, "sticky": true }
  ]
}

Each step supports:

Field	Type	Required	Description
status_code	integer	Yes	HTTP status code
body	any	No	Response body
headers	object	No	Custom headers
repeat	integer	No	Times to repeat before advancing (default: 1)
sticky	boolean	No	Stay on this step forever

Response: 200 OK with the state config.

Delete state sequence

DELETE /mock-configs/{id}/state

Removes stateful behavior. The endpoint reverts to its static mock config.

Reset endpoint state

POST /mock-configs/{id}/reset-state

Resets a single endpoint to step 0 (first step in the sequence).

Reset workspace state

POST /workspaces/{workspace_id}/reset-state

Resets all stateful endpoints in the workspace to step 0.

---

API Keys

List API keys

GET /workspaces/{workspace_id}/api-keys

Response:

[
  {
    "id": "ak_abc",
    "name": "GitHub Actions",
    "key_prefix": "mra_a3f9b2",
    "scopes": ["mock:read", "workspace:read", "workspace:write"],
    "last_used_at": "2025-03-10T14:22:00Z",
    "expires_at": null,
    "created_at": "2025-01-20T09:00:00Z",
    "is_active": true
  }
]

The full key is never returned after creation.

Create API key

POST /workspaces/{workspace_id}/api-keys

Body:

{
  "name": "GitHub Actions",
  "scopes": ["mock:read", "workspace:read", "workspace:write"],
  "expires_at": null
}

scopes defaults to all three scopes if omitted. mock:read is always included. expires_at is an ISO 8601 timestamp or null for no expiry.

Response: 201 Created. The key field contains the full plaintext key — save it immediately.

{
  "id": "ak_abc",
  "name": "GitHub Actions",
  "key": "mra_a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
  "scopes": ["mock:read", "workspace:read", "workspace:write"],
  "expires_at": null,
  "created_at": "2025-03-15T10:00:00Z"
}

Revoke API key

DELETE /api-keys/{id}

Permanently revokes the key. Returns 204 No Content.

---

Ephemeral Namespaces

Create ephemeral namespace

POST /namespaces

Response: 201 Created

{
  "namespace": "amber-river-7f3a",
  "mock_base_url": "https://mock.mockra.io/amber-river-7f3a"
}

Delete ephemeral namespace

DELETE /namespaces/{namespace}

Deletes the namespace and all associated KV cache entries. Returns 204 No Content.

---

Drift Detection

Set source URL

PUT /workspaces/{workspace_id}/schemas/{schema_id}/source-url

Sets or updates the upstream spec URL for a schema. Required for drift detection on schemas uploaded via file or raw paste.

Body:

{ "source_url": "https://example.com/openapi.yaml" }

URL must be HTTPS. Returns 200 OK with the updated schema object.

Check for drift

POST /workspaces/{workspace_id}/schemas/{schema_id}/check-drift

Fetches the upstream spec (requires a source URL — set automatically for URL uploads, or via the Set source URL endpoint for file uploads) and compares to stored version.

Response:

{
  "drift_status": "ENDPOINT_ADDED",
  "has_unacknowledged_drift": true,
  "last_drift_checked_at": "2025-03-15T10:30:00Z",
  "diff_summary": {
    "added": [{ "method": "POST", "path": "/users/{id}/verify-email" }],
    "removed": [],
    "changed": []
  }
}

Get drift status

GET /workspaces/{workspace_id}/schemas/{schema_id}/drift

Acknowledge drift

POST /workspaces/{workspace_id}/schemas/{schema_id}/drift/acknowledge

Returns 200 OK.

---

Analytics

All tiers. Rolling 30-day window.

Get analytics

GET /workspaces/{workspace_id}/analytics

Returns request counts and mean latency aggregated over the last 30 days.

Response:

{
  "totals": {
    "last_24h": 840,
    "last_7d": 5200,
    "last_30d": 18400
  },
  "endpoints": [
    {
      "method": "GET",
      "path": "/users",
      "count": 9100,
      "mean_latency_ms": 14
    },
    {
      "method": "POST",
      "path": "/orders",
      "count": 9300,
      "mean_latency_ms": 16
    }
  ]
}

Counts are approximate — analytics are recorded asynchronously by the mock runtime. Endpoints with no traffic in the window are omitted.

---

Billing

Get billing state

GET /workspaces/{workspace_id}/billing

Response:

{
  "tier": "pro",
  "monthly_request_count": 12400,
  "monthly_request_limit": 1000000,
  "current_period_start": "2025-03-01T00:00:00Z",
  "current_period_end": "2025-03-31T23:59:59Z",
  "stripe_subscription_status": "active"
}

Create checkout session

POST /workspaces/{workspace_id}/billing/checkout?plan=starter|pro

Query param: plan — either starter or pro.

Response: { "url": "https://checkout.stripe.com/..." } — redirect the user to this URL.

Open billing portal

POST /workspaces/{workspace_id}/billing/portal

Response: { "url": "https://billing.stripe.com/..." } — redirect the user to manage their subscription.

---

Error responses

All errors follow this shape:

{
  "error": "Human-readable description of what went wrong"
}

Status	Meaning
400	Bad request — invalid input
401	Unauthorized — missing or invalid token
403	Forbidden — feature requires a higher tier
404	Not found
429	Quota exceeded — monthly request limit reached
500	Internal server error