> ## 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.

# Projects API Reference

> Create, read, update, and delete projects within a team. Projects group all your mocks, webhooks, feature flags, and release notes.

Projects are the container for all Swisstools resources — API mocks, webhook inboxes, feature flags, and release notes all belong to a project. A project's `slug` and its team's `referenceId` together form the subdomain used to serve mock and webhook traffic.

All project endpoints require session authentication. See [Authentication](/api-reference/authentication) for details.

## List Projects

`GET /api/teams/:teamId/projects`

Returns all projects that belong to the specified team.

**Path Parameters**

<ParamField path="teamId" type="string" required>
  The UUID of the team.
</ParamField>

**Request**

```bash theme={null}
curl https://swisstools.dev/api/teams/018e4f2a-1c3d-7b8e-9f0a-2b3c4d5e6f7a/projects \
  -b cookies.txt
```

**Response**

```json theme={null}
[
  {
    "id": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
    "teamId": "018e4f2a-1c3d-7b8e-9f0a-2b3c4d5e6f7a",
    "name": "Payments API",
    "slug": "payments-api",
    "description": "Mock endpoints and webhooks for the payments service.",
    "createdAt": "2024-02-01T10:00:00.000Z",
    "updatedAt": "2024-02-01T10:00:00.000Z"
  }
]
```

## Create Project

`POST /api/teams/:teamId/projects`

Creates a new project within the specified team.

**Path Parameters**

<ParamField path="teamId" type="string" required>
  The UUID of the team that will own the project.
</ParamField>

**Request Body**

<ParamField body="name" type="string" required>
  The display name of the project.
</ParamField>

<ParamField body="slug" type="string" required>
  A URL-friendly identifier. Used as part of the subdomain for mock and webhook URLs. Must be unique within the team.
</ParamField>

<ParamField body="description" type="string">
  An optional description of the project.
</ParamField>

**Request**

```bash theme={null}
curl -X POST https://swisstools.dev/api/teams/018e4f2a-1c3d-7b8e-9f0a-2b3c4d5e6f7a/projects \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments API",
    "slug": "payments-api",
    "description": "Mock endpoints and webhooks for the payments service."
  }'
```

**Response** — `201 Created`

```json theme={null}
{
  "id": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "teamId": "018e4f2a-1c3d-7b8e-9f0a-2b3c4d5e6f7a",
  "name": "Payments API",
  "slug": "payments-api",
  "description": "Mock endpoints and webhooks for the payments service.",
  "createdAt": "2024-02-01T10:00:00.000Z",
  "updatedAt": "2024-02-01T10:00:00.000Z"
}
```

## Get Project

`GET /api/teams/:teamId/projects/:projectId`

Returns a single project by its ID.

**Path Parameters**

<ParamField path="teamId" type="string" required>
  The UUID of the team.
</ParamField>

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

**Request**

```bash theme={null}
curl https://swisstools.dev/api/teams/018e4f2a-1c3d-7b8e-9f0a-2b3c4d5e6f7a/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b \
  -b cookies.txt
```

**Response**

```json theme={null}
{
  "id": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "teamId": "018e4f2a-1c3d-7b8e-9f0a-2b3c4d5e6f7a",
  "name": "Payments API",
  "slug": "payments-api",
  "description": "Mock endpoints and webhooks for the payments service.",
  "createdAt": "2024-02-01T10:00:00.000Z",
  "updatedAt": "2024-02-01T10:00:00.000Z"
}
```

## Update Project

`PUT /api/teams/:teamId/projects/:projectId`

Updates the name, slug, or description of an existing project.

**Path Parameters**

<ParamField path="teamId" type="string" required>
  The UUID of the team.
</ParamField>

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

**Request Body**

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

<ParamField body="slug" type="string">
  Updated URL-friendly slug. Changing the slug also changes the subdomain used for mocks and webhooks.
</ParamField>

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

**Request**

```bash theme={null}
curl -X PUT https://swisstools.dev/api/teams/018e4f2a-1c3d-7b8e-9f0a-2b3c4d5e6f7a/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"name": "Payments API v2", "description": "Updated description."}'
```

**Response**

```json theme={null}
{
  "id": "018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b",
  "teamId": "018e4f2a-1c3d-7b8e-9f0a-2b3c4d5e6f7a",
  "name": "Payments API v2",
  "slug": "payments-api",
  "description": "Updated description.",
  "createdAt": "2024-02-01T10:00:00.000Z",
  "updatedAt": "2024-03-15T14:30:00.000Z"
}
```

## Delete Project

`DELETE /api/teams/:teamId/projects/:projectId`

Permanently deletes a project and all of its resources — mocks, webhooks, feature flags, API keys, and release notes are all removed. This action cannot be undone.

**Path Parameters**

<ParamField path="teamId" type="string" required>
  The UUID of the team.
</ParamField>

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

**Request**

```bash theme={null}
curl -X DELETE https://swisstools.dev/api/teams/018e4f2a-1c3d-7b8e-9f0a-2b3c4d5e6f7a/projects/018e5a3b-2d4e-8c9f-a0b1-3c4d5e6f7a8b \
  -b cookies.txt
```

**Response**

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

## Project Object

<ResponseField name="id" type="string">
  UUID that uniquely identifies the project. Use this in all API paths that accept `:projectId`.
</ResponseField>

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

<ResponseField name="name" type="string">
  The display name of the project.
</ResponseField>

<ResponseField name="slug" type="string">
  URL-friendly identifier. Combined with the team's `referenceId` to form the subdomain: `<referenceId>-<slug>.swisstools.dev`.
</ResponseField>

<ResponseField name="description" type="string">
  Optional free-text description of the project.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the project was created.
</ResponseField>

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