Skip to main content
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. The key is shown only once, so copy it when it is created.

Base URL

All endpoints live under /api/v1 on your instance:
To check that the API is reachable, call the ping endpoint. It is the one call in this guide that needs no API key:

Request headers

The API key goes in the header as-is, with no prefix such as Bearer:
This returns the details of the account that owns the key, which makes it a good first authenticated call.
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. Their endpoints carry the workspace ID in the path:
List the workspaces you belong to and take the ID from the response:
Then use that ID in the path. This example lists the labels used by the playbooks of a workspace:
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:
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.
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.