API Overview
The REST API that SailOps itself runs on, opening up one resource at a time.
This is the API the SailOps dashboard calls. Everything it can do is reachable here, described by a single OpenAPI document, with one error shape and one way to page through a collection.
It is being opened up progressively. Organizations, projects, members, invitations, API keys, alerts, notifications, the audit log and support tickets are served today. Containers, databases, gateways and the rest still live in the Public API, which continues to work exactly as before.
Base URL
https://app.sailops.io
Paths are absolute and carry their own prefix, so a full URL reads https://app.sailops.io/api/v3/organizations. Everything is served over HTTPS.
Authentication
Two credentials are accepted:
- Session cookie — set when you sign in. This is what your browser uses.
- API key — sent as the
X-Api-Keyheader. A key belongs to you (personal), to an organization, or to a project, and what it reaches follows from that subject. See API keys for details.
Most operations accept both. The few that do not — managing keys themselves, for example — are session-only; the Interactive API Reference states the accepted credentials per operation.
Errors
Every failure returns the same body, whatever went wrong:
{
"code": "NOT_FOUND",
"message": "That project does not exist, or you cannot see it.",
"traceId": "4b8f2c1e9a7d30f5"
}
codeis stable. Codes are added over time, never renamed and never removed — so treat one you do not recognise as a generic error of its HTTP status, rather than failing on it.messageis written for a person to read. Do not match on it.traceIdidentifies this exact request in our logs. Quote it when you report a problem.
A REQUEST_VALIDATION failure carries an extra validations array naming each field that was rejected and why.
Codes you will meet most: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, REQUEST_VALIDATION, TOO_MANY_REQUESTS, INTERNAL. The full list, with the meaning of each, is in the Interactive API Reference under ApiErrorCode.
Not found, not forbidden
A resource you have no access to answers 404, not 403. Whether it exists is itself information, so the API does not reveal it. A 403 means the resource is there and your role does not reach this operation on it.
Pagination
Collections return a page and, when there is more, an opaque nextCursor:
{
"items": [ /* … */ ],
"nextCursor": "eyJvIjoyMCwicyI6ImE5Zj…"
}
Pass it back as ?cursor=… to get the following page, and stop when it is absent. The cursor is signed: it is not a number to compute, and an edited one is refused.
?limit= sets the page size, up to 200.
What each part covers
| Area | What lives there |
|---|---|
| Organizations | Organizations, their billing details, and creating your personal one |
| Projects | Projects, their lifecycle (create, delete, restore) and the locations they can be created in |
| Operations | The progress of an asynchronous mutation |
| Members | Who has access to an organization or a project, and with what role |
| Invitations | Access offered to an address that has not accepted it yet |
| API keys | Keys for scripts and CI, bounded by their subject (personal, organization or project) |
| Alerts | What the platform observed going wrong, and where those alerts are sent |
| Audit | What was changed, by whom, and through what |
| Support | Questions and incidents raised with SailOps support |
Versioning
New fields and new operations may appear at any time, so parse defensively and ignore what you do not know. Nothing is removed or renamed without a new version of the resource concerned.
Next
- API Endpoints Reference — every operation, by area
- Interactive API Reference — schemas and parameters, explorable