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). There are two types of API keys, depending on what you want to do:

• Account API key — used for account-level operations: creating, importing, updating and deleting projects. 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.
• Project API key — used for all endpoint and response operations inside a specific project. You can find it in app.mockfly.dev by clicking on the configuration button of your project.

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

Managing projects

Project operations use your account API key, since operations like creating or importing a project happen before any project exists.

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 slug and its project API key.

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 project API key of the project they belong to:

For example, to create an endpoint:

curl -X POST https://api.mockfly.dev/public/endpoints \
  -H "Authorization: <your_project_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_project_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.