Mockfly Public API

Mockfly provides a public REST API so you can manage your projects, endpoints and responses programmatically: create projects from a script, import a whole project from your CI pipeline, or keep your mocks in sync with your codebase without opening the dashboard.

The base URL for all requests is https://api.mockfly.dev.

OpenAPI specification

The whole API is also described by a machine-readable OpenAPI 3.1 specification:

https://mockfly.dev/openapi.json

Point a client generator, an IDE or an AI agent at that URL and it gets every operation, its parameters, its request and response schemas and its error codes without having to read this page. If you prefer to explore and run the requests interactively instead, the Postman collection covers the same API.

Authentication

All requests require the Authorization header with an API key as its raw value (no Bearer prefix). Use your account API key (mf_…): it gives access to every project you are a member of, for project, endpoint and response operations alike. You can create and manage your account API keys in app.mockfly.dev/api-keys. For security reasons, the full key is only shown once at creation time, so make sure to copy it right away.

curl https://api.mockfly.dev/public/projects \
  -H "Authorization: <your_account_api_key>"

Managing projects

List your projects

curl https://api.mockfly.dev/public/projects \
  -H "Authorization: <your_account_api_key>"

Returns the _id, name and slug of every project you are a member of. Use the _id as the projectId of the endpoint operations.

Create a project

curl -X POST https://api.mockfly.dev/public/projects \
  -H "Authorization: <your_account_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My project", "tags": [{"name": "backend", "color": "#48cfad"}]}'

name is required, tags is optional. The response includes the new project with its _id and its slug.

Import a project

Creates a project together with all its endpoints and responses in a single call. The payload is the same JSON produced by the dashboard's "Export to JSON" feature, so you can export an existing project and re-import it programmatically. See Import Project from JSON for the full payload structure and field descriptions.

curl -X POST https://api.mockfly.dev/public/projects/import \
  -H "Authorization: <your_account_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "project": {"name": "Imported project"},
    "endpoints": [
      {
        "path": "/users",
        "method": "GET",
        "responses": [
          {"name": "OK", "status": 200, "body": {"users": []}, "isEnabled": true}
        ]
      }
    ]
  }'

A few things to keep in mind:

• Every endpoint must include path, method and a responses array (empty is allowed).
• When the endpoint's content type is JSON (the default), bodyExample and each response body must be JSON objects or arrays, not strings.
• The import is all-or-nothing: if any endpoint fails validation, nothing is created.

Update a project

curl -X PATCH https://api.mockfly.dev/public/projects/:projectId \
  -H "Authorization: <your_account_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed project"}'

Delete a project

curl -X DELETE https://api.mockfly.dev/public/projects/:projectId \
  -H "Authorization: <your_account_api_key>"

Only the project admin can update or delete a project.

Managing endpoints and responses

Endpoint and response operations use the same account API key. Listing endpoints needs the project as a projectId query parameter (GET /public/endpoints?projectId=<your_project_id>), and creating one needs it in the body; the rest of the routes find the project from the endpoint id:

For example, to create an endpoint:

curl -X POST https://api.mockfly.dev/public/endpoints \
  -H "Authorization: <your_account_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "<your_project_id>", "path": "/users", "method": "GET"}'

The request and response schemas for every route are described in the OpenAPI specification, and the Postman collection has a runnable example for each of them.

Conditional rules

PUT /public/endpoints/:endpointId/responses/:responseId/rules replaces the whole rule set of a response (sending an empty array clears it). Each entry of rules is either a single rule — source, property, comparator and value, plus an optional andConditions array of extra rules that must all hold — or a group: an operator set to and or or and a conditions array whose entries are rules or nested groups, up to 3 levels deep. For example:

curl -X PUT https://api.mockfly.dev/public/endpoints/<endpoint_id>/responses/<response_id>/rules \
  -H "Authorization: <your_account_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "operator": "or",
        "conditions": [
          { "source": "header", "property": "x-country", "comparator": "equal", "value": "ES" },
          { "source": "jsonPath", "property": "$.items[0].sku", "comparator": "startsWith", "value": "ES-" }
        ]
      }
    ]
  }'

Note where each expression travels: for the jsonPath source it goes in property, while for xmlTag and xPath it goes in value. The 16 available comparators — including which ones take no value, which need a numeric one and that regex needs a valid pattern — are documented in the conditional responses docs. An invalid rule makes the whole request fail with a 400 and leaves the existing rules untouched.

Errors and limits

Errors are returned as JSON with a descriptive message:

{
  "error": "Error: Project not found"
}

Free plan limits also apply through the API: 1 project as admin, 4 endpoints per project and 2 responses per endpoint. Upgrade to premium to remove these limits.