OpenAPI import

1. On the Endpoints page, open the More actions menu (⋯) and choose Import OpenAPI.
2. Paste the spec, upload a .json, .yaml or .yml file, or give its URL.
3. Select Preview. You see the spec's title and version, the endpoints by method, any Resources, and warnings such as operations with no example.
4. Select Import. Everything goes into a folder named after the spec's info.title.

curl -i https://<your-workspace>.apimock.dev/pets/1

HTTP/2 200
content-type: application/json

{ "id": 1, "name": "Rex", "species": "dog" }

Paths keep their shape: /pets/{petId} becomes the route /pets/:petId. $refs are resolved, including ones that point at other documents over HTTPS. A URL import resolves relative $refs against the spec's own address.

Each operation becomes one static Endpoint. APIMock picks the response it serves like this:

Bodies come only from examples in the spec. APIMock doesn't make up data from the schema, so an operation with no example imports with an empty body and a warning. Add one in the editor, or turn on response templates to generate it.

The operation's other examples aren't lost. Other named examples, and the example of each other status code, become response variants you select with a Prefer header:

Prefer: example=notFound   # another named example
Prefer: code=404           # another status's example

Imported endpoints start with no auth, no delay, CORS open to every origin and templates off. HEAD, OPTIONS and TRACE operations are skipped with a warning.

A pair of paths becomes a stateful Resource when it looks like a list and its items:

• a collection path, such as /api/todos, whose GET returns { data: [...], meta } in its schema or example, which is the shape a Resource's list returns;
• and an item path below it with one parameter, such as /api/todos/{id}, that has a GET.

The collection's POST and the item's PATCH, PUT and DELETE join the same Resource, so creates, updates and deletes persist and later reads return them. The last path segment is the Resource's name and has to be lowercase letters, digits and hyphens, starting with a letter. The OpenAPI spec you can export from an APIMock Resource has this shape.

Fields come from the POST body schema, keeping its required list. Without one, APIMock reads the PATCH or PUT body, then the item schema. id, createdAt, updatedAt and readOnly properties are left out. The records in the list example become seed data.

Anything that isn't a clean match imports as static Endpoints that serve the spec's examples exactly:

Each imported operation keeps its request body schema. To reject bodies that don't match it, open the endpoint and turn on Validate request body under Request validation. The section only appears on endpoints imported with a request schema, and validation is off until you turn it on.

curl -i -X POST https://<your-workspace>.apimock.dev/pets \
  -H "Content-Type: application/json" \
  -d '{"name": 42}'

HTTP/2 422
{
  "error": "Request body failed validation",
  "errors": [
    { "path": "(root)", "message": "must have required property 'species'", "keyword": "required" },
    { "path": "/name", "message": "must be string", "keyword": "type" }
  ]
}

Every problem is listed, not just the first. A body that isn't valid JSON gets a 422 with must be valid JSON. Validation runs after auth and before response variants, and it uses JSON Schema with formats such as email and date-time. If a schema can't be compiled, the endpoint skips validation rather than failing every request.

Importing a spec with the same info.title into the same workspace updates the first import instead of making a copy. Operations are matched by operationId, or by method and path when a spec has none:

• Operations still in the spec are updated.
• New operations are added.
• Operations removed from the spec are deleted, and so are their Resources.

The spec wins for what it describes. An updated endpoint takes the spec's status and body again, and settings changed in the editor go back to the import defaults: delay, headers, auth, templates, and request validation, which turns off. Variants you added yourself are kept; the spec's own variants are replaced. A Resource keeps its access setting and the per-field unique and sensitive flags, but its fields are rebuilt and its records go back to the spec's seed data.

An import never overwrites an endpoint it didn't create. If the workspace already has an endpoint with the same method and route, that operation is skipped and counted in the result.

The MCP server's import_openapi tool does the same import from a coding agent. Pass the spec text as spec, or a url, and it reconciles on re-import the same way.

{
  "workspace": "acme",
  "url": "https://example.com/openapi.yaml"
}

Specs and their $refs are only fetched from public addresses. Extra examples beyond the variant limits are dropped with a warning in the preview.