> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swisstools.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Mocks Endpoints Reference

> Create and manage mock HTTP endpoints per project, then call them via a dedicated subdomain to simulate real API responses during development.

API mocks let you define a fake HTTP endpoint — method, path, status code, response headers, and body — that Swisstools serves at a stable subdomain URL. You point your application or tests at that URL during development instead of a real upstream API.

Each mock is served at:

```
https://<team_referenceId>-<project_slug>.swisstools.dev/api/mock/<endpoint>
```

For example, if your team's `referenceId` is `aB3cD4eF` and your project slug is `payments-api`, a mock with endpoint `/users` is reachable at:

```
https://aB3cD4eF-payments-api.swisstools.dev/api/mock/users
```

All management endpoints (list, create, update, delete) require session authentication. The mock invocation URL itself is public — no auth needed.

## List Mocks

`GET /api/projects/:projectId/mocks`

Returns all mock endpoints defined for the specified project.

**Path Parameters**

<ParamField path="projectId" type="string" required>
  The UUID of the project.
</ParamField>

**Request**

```bash theme={null}
curl https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/mocks \
  -b cookies.txt
```

**Response**

```json theme={null}
[
  {
    "id": "018e6c4d-3e5f-9d0a-b1c2-4d5e6f7a8b9c",
    "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
    "name": "List Users",
    "description": "Returns a paginated list of users.",
    "method": "GET",
    "endpoint": "/users",
    "responseBody": "[{\"id\": 1, \"name\": \"Alice\"}, {\"id\": 2, \"name\": \"Bob\"}]",
    "responseHeaders": {"Content-Type": "application/json"},
    "statusCode": 200,
    "createdAt": "2024-02-10T11:00:00.000Z",
    "updatedAt": "2024-02-10T11:00:00.000Z"
  }
]
```

## Create Mock

`POST /api/projects/:projectId/mocks`

Creates a new mock endpoint for the project.

**Path Parameters**

<ParamField path="projectId" type="string" required>
  The UUID of the project.
</ParamField>

**Request Body**

<ParamField body="name" type="string" required>
  A human-readable name for the mock, used in the dashboard.
</ParamField>

<ParamField body="method" type="string" required>
  The HTTP method this mock responds to. Accepted values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. Defaults to `GET`.
</ParamField>

<ParamField body="endpoint" type="string" required>
  The path this mock handles, relative to `/api/mock/`. For example, `/users` or `/orders/123`.
</ParamField>

<ParamField body="responseBody" type="string" required>
  The raw response body to return. JSON must be provided as a string. Defaults to `{}`.
</ParamField>

<ParamField body="responseHeaders" type="object">
  Key-value pairs of HTTP response headers. Defaults to an empty object.
</ParamField>

<ParamField body="statusCode" type="integer">
  The HTTP status code the mock returns. Defaults to `200`.
</ParamField>

<ParamField body="description" type="string">
  An optional description of what this mock simulates.
</ParamField>

**Request**

```bash theme={null}
curl -X POST https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/mocks \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "name": "List Users",
    "method": "GET",
    "endpoint": "/users",
    "responseBody": "[{\"id\": 1, \"name\": \"Alice\"}]",
    "responseHeaders": {"Content-Type": "application/json"},
    "statusCode": 200,
    "description": "Returns a list of users."
  }'
```

**Response** — `201 Created`

```json theme={null}
{
  "id": "018e6c4d-3e5f-9d0a-b1c2-4d5e6f7a8b9c",
  "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "name": "List Users",
  "description": "Returns a list of users.",
  "method": "GET",
  "endpoint": "/users",
  "responseBody": "[{\"id\": 1, \"name\": \"Alice\"}]",
  "responseHeaders": {"Content-Type": "application/json"},
  "statusCode": 200,
  "createdAt": "2024-02-10T11:00:00.000Z",
  "updatedAt": "2024-02-10T11:00:00.000Z"
}
```

## Get Mock

`GET /api/projects/:projectId/mocks/:mockId`

Returns a single mock endpoint by its ID.

**Path Parameters**

<ParamField path="projectId" type="string" required>
  The UUID of the project.
</ParamField>

<ParamField path="mockId" type="string" required>
  The UUID of the mock.
</ParamField>

**Request**

```bash theme={null}
curl https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/mocks/018e6c4d-3e5f-9d0a-b1c2-4d5e6f7a8b9c \
  -b cookies.txt
```

**Response**

```json theme={null}
{
  "id": "018e6c4d-3e5f-9d0a-b1c2-4d5e6f7a8b9c",
  "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "name": "List Users",
  "description": "Returns a list of users.",
  "method": "GET",
  "endpoint": "/users",
  "responseBody": "[{\"id\": 1, \"name\": \"Alice\"}]",
  "responseHeaders": {"Content-Type": "application/json"},
  "statusCode": 200,
  "createdAt": "2024-02-10T11:00:00.000Z",
  "updatedAt": "2024-02-10T11:00:00.000Z"
}
```

## Update Mock

`PUT /api/projects/:projectId/mocks/:mockId`

Updates one or more fields of an existing mock endpoint.

**Path Parameters**

<ParamField path="projectId" type="string" required>
  The UUID of the project.
</ParamField>

<ParamField path="mockId" type="string" required>
  The UUID of the mock to update.
</ParamField>

**Request Body**

<ParamField body="name" type="string">
  Updated display name.
</ParamField>

<ParamField body="method" type="string">
  Updated HTTP method.
</ParamField>

<ParamField body="endpoint" type="string">
  Updated endpoint path.
</ParamField>

<ParamField body="responseBody" type="string">
  Updated response body string.
</ParamField>

<ParamField body="responseHeaders" type="object">
  Updated response headers.
</ParamField>

<ParamField body="statusCode" type="integer">
  Updated HTTP status code.
</ParamField>

<ParamField body="description" type="string">
  Updated description.
</ParamField>

**Request**

```bash theme={null}
curl -X PUT https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/mocks/018e6c4d-3e5f-9d0a-b1c2-4d5e6f7a8b9c \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "statusCode": 404,
    "responseBody": "{\"error\": \"User not found\"}"
  }'
```

**Response**

```json theme={null}
{
  "id": "018e6c4d-3e5f-9d0a-b1c2-4d5e6f7a8b9c",
  "projectId": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "name": "List Users",
  "description": "Returns a list of users.",
  "method": "GET",
  "endpoint": "/users",
  "responseBody": "{\"error\": \"User not found\"}",
  "responseHeaders": {"Content-Type": "application/json"},
  "statusCode": 404,
  "createdAt": "2024-02-10T11:00:00.000Z",
  "updatedAt": "2024-03-01T08:15:00.000Z"
}
```

## Delete Mock

`DELETE /api/projects/:projectId/mocks/:mockId`

Permanently removes a mock endpoint.

**Path Parameters**

<ParamField path="projectId" type="string" required>
  The UUID of the project.
</ParamField>

<ParamField path="mockId" type="string" required>
  The UUID of the mock to delete.
</ParamField>

**Request**

```bash theme={null}
curl -X DELETE https://swisstools.dev/api/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b/mocks/018e6c4d-3e5f-9d0a-b1c2-4d5e6f7a8b9c \
  -b cookies.txt
```

**Response**

```json theme={null}
{"success": true}
```

## Mock Object

<ResponseField name="id" type="string">
  UUID that uniquely identifies the mock.
</ResponseField>

<ResponseField name="projectId" type="string">
  UUID of the project that owns this mock.
</ResponseField>

<ResponseField name="name" type="string">
  Display name shown in the dashboard.
</ResponseField>

<ResponseField name="description" type="string">
  Optional description of what this mock simulates.
</ResponseField>

<ResponseField name="method" type="string">
  HTTP method this mock responds to (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`).
</ResponseField>

<ResponseField name="endpoint" type="string">
  The path relative to `/api/mock/` at which this mock is served on the subdomain.
</ResponseField>

<ResponseField name="responseBody" type="string">
  The raw string returned as the response body when the mock is invoked.
</ResponseField>

<ResponseField name="responseHeaders" type="object">
  Key-value HTTP response headers returned when the mock is invoked.
</ResponseField>

<ResponseField name="statusCode" type="integer">
  HTTP status code returned when the mock is invoked.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of creation.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of the last update.
</ResponseField>