Skip to main content

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-Key header. 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"
}
  • code is 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.
  • message is written for a person to read. Do not match on it.
  • traceId identifies 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​

AreaWhat lives there
OrganizationsOrganizations, their billing details, and creating your personal one
ProjectsProjects, their lifecycle (create, delete, restore) and the locations they can be created in
OperationsThe progress of an asynchronous mutation
MembersWho has access to an organization or a project, and with what role
InvitationsAccess offered to an address that has not accepted it yet
API keysKeys for scripts and CI, bounded by their subject (personal, organization or project)
AlertsWhat the platform observed going wrong, and where those alerts are sent
AuditWhat was changed, by whom, and through what
SupportQuestions 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​