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:
Request headers
The API key goes in the header as-is, with no prefix such as
Bearer:
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:403.
Responses and errors
Responses are JSON. A successful call returns status200. 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 status429; wait for the next minute before retrying.
