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

# Making REST API calls

> The base URL, the headers every request needs, and what responses and errors look like.

Cymph exposes a REST API that offers the same functionality as the web application. This guide shows how to make your first calls with an API key.

## Before you start

You need two things:

* **The address of your Cymph instance**, the same one you open in the browser — for example `https://client1.cymph.io`.
* **An API key.** Create one from your settings, as described in [API access](https://docs.cymph.io/settings/api-access.md). The key is shown only once, so copy it when it is created.

## Base URL

All endpoints live under `/api/v1` on your instance:

```
https://<your-cymph-instance>/api/v1
```

To check that the API is reachable, call the ping endpoint. It is the one call in this guide that needs no API key:

```bash theme={"system"}
curl https://<your-cymph-instance>/api/v1/misc/ping
```

```json theme={"system"}
{ "status": "OK", "version": "..." }
```

## Request headers

| Header | Value | When to send it |
| - | - | - |
| `x-cymph-api-key` | Your API key, exactly as it was displayed | Every request |
| `Content-Type` | `application/json` | Requests that carry a JSON body (`POST`, `PUT`, `PATCH`) |

The API key goes in the header as-is, with no prefix such as `Bearer`:

```bash theme={"system"}
curl https://<your-cymph-instance>/api/v1/account \
  -H "x-cymph-api-key: <your-api-key>"
```

This returns the details of the account that owns the key, which makes it a good first authenticated call.

> [!WARNING]
>
> Do not send an `Authorization` header together with `x-cymph-api-key`. A request that carries both is rejected with status `400`.

## What a key can access

A key acts on behalf of the user who created it. It has that user's role and workspace membership: anything the user cannot do in the web application, the key cannot do through the API.

API keys themselves are the exception. They can only be created, renamed and deleted from the web application, not with another API key.

## Workspace-scoped endpoints

Playbooks, assets, executions, integrations and most other resources belong to a [workspace](https://docs.cymph.io/key-features/workspaces.md). Their endpoints carry the workspace ID in the path:

```
/api/v1/workspaces/{workspace_id}/playbooks/...
/api/v1/workspaces/{workspace_id}/assets/...
/api/v1/workspaces/{workspace_id}/executions/...
```

List the workspaces you belong to and take the ID from the response:

```bash theme={"system"}
curl https://<your-cymph-instance>/api/v1/workspaces \
  -H "x-cymph-api-key: <your-api-key>"
```

Then use that ID in the path. This example lists the labels used by the playbooks of a workspace:

```bash theme={"system"}
curl https://<your-cymph-instance>/api/v1/workspaces/<workspace_id>/playbooks/tags \
  -H "x-cymph-api-key: <your-api-key>"
```

A workspace you are not a member of returns status `403`.

## Responses and errors

Responses are JSON. A successful call returns status `200`. Every error has the same shape:

```json theme={"system"}
{
  "message": "input validation failed",
  "errors": [
    {
      "type": "field",
      "msg": "value is missing",
      "path": "name",
      "location": "body"
    }
  ]
}
```

`message` is always present. For validation errors, `errors` lists each rejected field; otherwise it is an empty array. An error passed on from an integrated product can also include `code`, the status code that product returned.

| Status | Meaning |
| - | - |
| `400` | The request failed validation, the body is not valid JSON, or the `x-cymph-api-key` header is missing |
| `401` | The API key is invalid or expired, or the account that owns it is disabled |
| `403` | The key is valid, but its user lacks the permission or workspace membership the endpoint requires |
| `404` | The resource does not exist |
| `429` | Too many requests — see [Rate limits](#rate-limits) |
| `500` | Unexpected server error |

> [!NOTE]
>
> A request with no `x-cymph-api-key` header returns `400`, not `401`. If you get a `400` on a call that has no body, check the header first.

## Rate limits

By default, each client IP address is limited to 1000 requests per minute. Requests over the limit return status `429`; wait for the next minute before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.