API Simulation & Automation

Turn on stateful mode in Project Settings → Advanced. You can configure:

• Stateful seed count: number of synthetic records to generate when a model is seeded (capped by your plan limit).
• TTL (days): how long stored records are kept before the store resets and reseeds (1 to 30 days, default 1).
• Pagination: when enabled, list responses include pagination metadata (current page, total pages, total records, etc.) alongside the data array.

Each REST method on an endpoint should reference a response with a model. Endpoints that share the same model share the same pool of stored records.

Every record is assigned a server-generated UUID as its id. The API returns this id alongside your model's fields and two automatic timestamps: createdAt (when the record was created) and updatedAt (when it was last modified).

If your model schema defines an id field, it is ignored on creation. The server always assigns the authoritative UUID to prevent conflicts.

On the first GET request to a collection path (e.g., /users with no trailing ID) where no records exist yet, MockAPI automatically seeds the model with synthetic data based on your seed count and model schema.

You can also seed data manually from the dashboard: navigate to the endpoint detail page and use the Clear and re-seed button, which deletes all existing records for that model and regenerates fresh data.

Seeding is per model, not per endpoint. Two endpoints that share the same model share the same backing data store.

Before generating seed data, MockAPI validates that the records produced by your model schema are within acceptable size limits. If they are not, seeding is aborted with an explanatory error message so you can adjust your model.

When stateful mode is active, each HTTP method behaves as follows:

The following query parameters are supported on collection GET requests. Reserved parameters are never treated as field filters:

When Enable pagination is set on the project, the list response wraps results with your configured pagination labels (current page, next/previous page, page size, total pages, total records) alongside the data array.

Single-record operations are identified when the final path segment is a UUID. For template paths like /actors/{id}, use /actors/<uuid> for GET, PUT, PATCH, and DELETE. Use the collection URL /actors for listing and creating records.

The dashboard automatically normalizes template paths to the collection URL when re-seeding data.

Users with Endpoint edit permission can clear all records for an endpoint’s model and immediately re-generate seed data. This is useful after schema changes or when you need a clean slate.

Triggered via the Clear and re-seed button on the endpoint detail page, or programmatically via POST /api/endpoint/{projectId}/{endpointId}/stateful-reseed.

Plan-based record limits are enforced on both auto-seeding and individual POST requests. When you attempt to create a record that would exceed your plan’s maximum, the request is rejected with HTTP 403.

When the limit is reached, POST requests return the following error body:

{
  "error": "Record limit reached (100 for your plan). Delete existing records or upgrade your plan.",
  "code": "RECORD_LIMIT_EXCEEDED"
}

Enable and configure rate limiting under Project Settings → Advanced. Set the Requests per minute threshold (default: 60). Changes take effect immediately for all endpoints in the project.

• X-RateLimit-Limit: The configured maximum requests per minute.
• X-RateLimit-Remaining: Remaining requests in the current one-minute window.
• X-RateLimit-Reset: Unix timestamp (seconds) when the current window resets.
• Retry-After: Seconds until the current rate-limit window resets. Included on every response when rate limiting is enabled.

When the request count exceeds the threshold, the API returns HTTP 429 with rate-limit headers still attached. Clients should back off until the Retry-After period elapses or use exponential backoff.

{
  "error": "Too Many Requests",
  "code": "RATE_LIMITED"
}

Configure your project's latency profile under Project Settings → Advanced. Select the mode and fill in the fields that appear (minimum delay, maximum delay, spike probability, and spike duration, as applicable). Changes apply immediately to all endpoints.

• Endpoint path with case-insensitive matching, plus an optional HTTP method filter.
• HTTP status code and an optional custom response body (JSON).
• Artificial delay in milliseconds per endpoint override.
• A latency profile override that applies to requests not matched by any endpoint-specific rule.

Scenarios are managed from the dashboard under Settings → Scenarios. You can:

• Create a new scenario with a name, description, endpoint overrides, and an optional latency override.
• Edit an existing scenario to update its overrides or configuration.
• Delete a scenario you no longer need.
• Set a default scenario that is applied automatically when no X-MockAPI-Scenario header is sent.

Each scenario is stored per project and scoped to the project’s endpoints. Only project members can create or modify scenarios.

The complete order of operations for each mock request: Authenticate → Plan access check → Rate limiting → Resolve scenario (may return early with override) → Apply scenario latency (if applicable) → Stateful CRUD or stateless generation → Attach rate-limit headers to the response.

Management keys are issued with specific scopes that control access:

• mgmt:read: List and read projects, models, and endpoints.
• mgmt:write: Create and delete models and endpoints, run OpenAPI imports.

Access is scoped to projects owned by the key’s user. Include your management key in the Authorization header as a Bearer token.

All paths below are relative to /api/v1. Write operations require mgmt:write scope; read operations require at least mgmt:read.