Skip to main content

API Endpoints Reference

All operations of the new SailOps API, organized by area.

Base URL: https://app.sailops.io

Requests authenticate with a session cookie or an API key — see the API Overview. Parameters and schemas for each operation are in the Interactive API Reference.


Organizations​

Organizations and their lifecycle.

MethodPathDescription
PUT/api/v3/meSync your account
POST/api/v3/me/trialStart your free trial
GET/api/v3/organization-name-suggestionSuggest an organization name
POST/api/v3/organizationsCreate an organization (requires acceptedTermsVersion)
GET/api/v3/organizationsList organizations you belong to
GET/api/v3/organizations/{organizationId}Get an organization
DELETE/api/v3/organizations/{organizationId}Archive an organization
GET/api/v3/organizations/{organizationId}/billingGet an organization's billing details
PATCH/api/v3/organizations/{organizationId}/billingUpdate an organization's billing information
GET/api/v3/organizations/{organizationId}/planRead an organization's support plan
PUT/api/v3/organizations/{organizationId}/planChange an organization's support plan
POST/api/v3/organizations/{organizationId}/plan/customAsk about a negotiated plan
GET/api/v3/organizations/{organizationId}/termsRead the organization's terms of service status
POST/api/v3/organizations/{organizationId}/terms/{version}/acceptAccept a version of the terms of service
POST/api/v3/organizations/{organizationId}/terms/{version}/refuseRefuse the next version of the terms of service

syncMe records your account at sign-in and returns what the console needs to decide where to take you: hasMemberships (whether you belong to at least one organization) and trialAvailable (whether you can still start a free trial). Call it once per sign-in.

startTrial creates a trial organization you own, under the name you choose, and returns it. Each person gets one trial; a second call answers CONFLICT, even once the first trial has ended. Both startTrial and createOrganization require acceptedTermsVersion — the version of the terms of service in force.

suggestOrganizationName returns a name you can give a new organization. Each call suggests a different one; it is not reserved.

A listed organization carries the scopes you hold on it — what the dashboard hides and shows is read from that list rather than deduced from your role. It also carries member (whether you hold a role in this organization or in one of its projects), role (your organization-level role, absent for project-only members), projectCount (projects you can see), and initialTrialCredit (the trial credit the organization started with, in cents — present only during the trial phase).

The plan decides how large a workload may be, how long logs are kept (maxLogRetentionDays) and how far back resource metrics may look (maxMetricRetentionDays). Changing it takes effect immediately for what the plan unlocks; billing changes from the next invoice. A negotiated plan (CUSTOM) cannot be entered or left self-serve — use the /plan/custom endpoint to tell our sales team, and they will arrange it.

The organization terms endpoints return where the organization stands on the current and any upcoming version, every past decision, and a canDecide flag that tells the caller whether they may accept or refuse on behalf of the organization. Only organization owners can decide; holding the terms:update scope alone is not enough. Viewing requires terms:get.


Projects​

Projects and their lifecycle.

MethodPathDescription
GET/api/v3/organizations/{organizationId}/projectsList an organization's projects
POST/api/v3/organizations/{organizationId}/projectsCreate a project
PUT/api/v3/organizations/{organizationId}/projects/orderSet the order of an organization's projects
GET/api/v3/projects/{projectId}Get a project
DELETE/api/v3/projects/{projectId}Delete a project
POST/api/v3/projects/{projectId}/restoreRestore a project scheduled for deletion
GET/api/v3/locationsList the locations a project can be created in

Each project carries a position — the place the organization gave it in its own ordering. The listing returns projects in ascending position order.

Creating a project answers 202 with the project in the provisioning phase and a Location header naming the operation to follow. The project is ready when that operation succeeds, and failed if it does not. The location (provider and region) is permanent — it cannot be changed after the project is created.

Deleting schedules the project for removal after a grace period, stops its workloads and answers 202. The project must be empty — delete its resources first, or the call answers 409 naming what is left. Adding force=true removes the project at once: no grace period and no way back. Restoring cancels a scheduled removal; the project comes back suspended and its workloads resume a moment later. Restoring is never possible after a forced deletion. Both return a Location to follow.

The listing accepts a phase filter: provisioning, active, failed, suspended or pendingDeletion.

setProjectOrder replaces the whole order: projectIds lists every project of the organization, first to last. The list must name exactly the current projects, each once; otherwise the call answers 409. Requires the projects/order:update scope (MAINTAINER and OWNER roles). Accessible with a session or an API key.


Operations​

The progress of an asynchronous mutation.

Mutations that reach a cluster — creating a project, deleting one, restoring one — answer 202 and name the operation to follow in their Location header. Poll it until status is terminal (succeeded, failed or superseded), then stop.

MethodPathDescription
GET/api/v3/projects/{projectId}/operations/{operationId}Read the progress of an asynchronous mutation

attemptCount and nextAttemptAt let a client say "retrying in 30 s" rather than appear frozen during a backoff. A superseded operation was absorbed by a later request to the same resource; supersededBy names the one that will run.

Finished operations are kept for 90 days, then removed. Store the outcome on your side if you need it longer.


Members​

Who has access to an organization or a project, and with what role.

A role on an organization reaches every project inside it. A role on one project reaches that project alone and says nothing about the organization — the two are granted, changed and revoked separately, which is why each operation below exists twice.

MethodPathDescription
GET/api/v3/organizations/{organizationId}/membersList organization members
POST/api/v3/organizations/{organizationId}/membersAdd an organization member
PUT/api/v3/organizations/{organizationId}/members/{memberId}Change an organization member's role
DELETE/api/v3/organizations/{organizationId}/members/{memberId}Remove an organization member
GET/api/v3/projects/{projectId}/membersList project members
POST/api/v3/projects/{projectId}/membersAdd a project member
PUT/api/v3/projects/{projectId}/members/{memberId}Change a project member's role
DELETE/api/v3/projects/{projectId}/members/{memberId}Remove a project member

Adding a member always creates an invitation, whether or not the address already has a SailOps account — the person joins once they accept it.


Invitations​

Access offered to an address that has not accepted it yet.

MethodPathDescription
GET/api/v3/invite/{token}Read an invitation from its link
GET/api/v3/me/invitationsList invitations sent to you
POST/api/v3/me/invitations/{invitationId}/acceptAccept an invitation
POST/api/v3/me/invitations/{invitationId}/declineDecline an invitation
GET/api/v3/organizations/{organizationId}/invitationsList organization invitations
DELETE/api/v3/organizations/{organizationId}/invitations/{invitationId}Revoke an organization invitation
GET/api/v3/projects/{projectId}/invitationsList project invitations
DELETE/api/v3/projects/{projectId}/invitations/{invitationId}Revoke a project invitation

GET /api/v3/invite/{token} is what the invitation link opens. It names the organization and the role offered so the page can be shown before signing in.

An invitation's status is one of pending, declined or expired. Declining marks the invitation so the organization sees the refusal; revoking (the DELETE endpoints) removes the invitation immediately. Adding a member always creates an invitation, whether or not the address has a SailOps account — the person joins once they accept it.


API keys​

Keys for scripts and CI, bounded by the subject they belong to.

A key belongs to one of three subjects — you, an organization, or a project — and what it reaches follows from that subject. The secret is returned once, by the create call, and never again. See the API Keys guide.

When you create or update a key you choose the scopes it holds, bounded by what you hold yourself. Omit scopes for the default set, which is the DEVELOPER expansion for organization and project keys, or your own access for a personal key. The response reports what the key ended up with.

Personal keys​

MethodPathDescription
GET/api/v3/me/apikeysList your personal API keys
POST/api/v3/me/apikeysCreate a personal API key
PATCH/api/v3/me/apikeys/{label}Update a personal API key
DELETE/api/v3/me/apikeys/{label}Delete a personal API key

A personal key acts as you: it reaches whatever you reach at the moment of each request. Lose a role and the key loses it with you. It never carries platform administration.

Organization keys​

MethodPathDescription
GET/api/v3/organizations/{organizationId}/apikeysList organization API keys
POST/api/v3/organizations/{organizationId}/apikeysCreate an organization API key
PATCH/api/v3/organizations/{organizationId}/apikeys/{label}Update an organization API key
DELETE/api/v3/organizations/{organizationId}/apikeys/{label}Delete an organization API key

An organization key reaches every project of the organization. It has no bearer, so it keeps what you give it even if your own access changes later.

Project keys​

MethodPathDescription
GET/api/v3/projects/{projectId}/apikeysList project API keys
POST/api/v3/projects/{projectId}/apikeysCreate a project API key
PATCH/api/v3/projects/{projectId}/apikeys/{label}Update a project API key
DELETE/api/v3/projects/{projectId}/apikeys/{label}Delete a project API key

A project key reaches only the project it was created in. Anything an organization answers for stays out of its reach, whatever scopes you pick.


Permissions​

The catalogue of permissions a key can hold, and the presets it can start from.

MethodPathDescription
GET/api/v3/scopesList the permissions a key can be given

Each entry names a permission, describes what it allows, says whether any operation accepts it today, and lists the operations it opens. A permission that is not served yet can still be given to a key — it starts working when the operation arrives, without the key being reissued.

The response also carries presets — ready-made permission sets a key can start from. Each preset has a stable name (e.g. DEVELOPER, READ_ONLY), a human label, a description and the full list of scopes it contains. A preset is a starting point, not a link: what a key holds is the set written when it was created, so a preset redefined later leaves every existing key unchanged.


Alert Center​

The unified incident investigation and alert configuration API. All endpoints use the alert-center/ scope family. Organization endpoints read across every authorized project; project endpoints are scoped to one project.

Resources​

MethodPathDescription
GET/api/v3/organizations/{organizationId}/alert-center/resourcesList resources in the alert center
GET/api/v3/projects/{projectId}/alert-center/resourcesList resources in the alert center

Returns the resources you can access with their immutable identifiers and project names, for use in resource filters.

Incidents​

MethodPathDescription
GET/api/v3/organizations/{organizationId}/alert-center/incidentsList organization incidents
GET/api/v3/projects/{projectId}/alert-center/incidentsList project incidents
GET/api/v3/projects/{projectId}/alert-center/incidents/{incidentId}Get incident details
POST/api/v3/projects/{projectId}/alert-center/incidents/{incidentId}/acknowledgeAcknowledge an incident
PUT/api/v3/projects/{projectId}/alert-center/incidents/{incidentId}/readMark an incident read or unread

The listing returns incidents ordered by severity then newest start time. The default view is attention; available views are attention, acknowledged, unknown, history, executions and all. Filter by resourceId, severity, resourceType, resourceName, suspended and search. Use since and until for time bounds; reuse the first page's until on later pages to retain a stable cutoff.

Getting an incident returns its evidence, latest 500 timeline events and latest 100 notification deliveries. Read state is personal; acknowledgment is shared. A historical alert identifier can also identify its incident.

Acknowledging records responsibility without changing the observed condition. Marking read or unread is personal and never acknowledges or resolves.

Summary​

MethodPathDescription
GET/api/v3/organizations/{organizationId}/alert-center/summaryGet organization incident counts
GET/api/v3/projects/{projectId}/alert-center/summaryGet project incident counts

Returns counts by condition and acknowledgment, with the caller's personal unread count and a canConfigure flag. Resource filters apply to every count.

Rules (Thresholds)​

MethodPathDescription
GET/api/v3/organizations/{organizationId}/alert-center/rulesList organization rules
PUT/api/v3/organizations/{organizationId}/alert-center/rules/{ruleKey}Update an organization rule
DELETE/api/v3/organizations/{organizationId}/alert-center/rules/{ruleKey}Reset an organization rule to inherited
POST/api/v3/organizations/{organizationId}/alert-center/rules/{ruleKey}/activateActivate notifications for an organization rule
GET/api/v3/projects/{projectId}/alert-center/rulesList project rules
PUT/api/v3/projects/{projectId}/alert-center/rules/{ruleKey}Update a project rule
DELETE/api/v3/projects/{projectId}/alert-center/rules/{ruleKey}Reset a project rule to inherited
POST/api/v3/projects/{projectId}/alert-center/rules/{ruleKey}/activateActivate notifications for a project rule

Rules return effective thresholds, inherited values and notification eligibility. Pass resourceId to read one resource's rules instead of the scope defaults. Update replaces the override using a revision for concurrency; delete restores parent settings. Activation requires seven observation days, complete measurements and an enabled destination.

Destinations (Notification Channels)​

MethodPathDescription
GET/api/v3/organizations/{organizationId}/alert-center/destinationsList organization destinations
POST/api/v3/organizations/{organizationId}/alert-center/destinationsCreate an organization destination
PUT/api/v3/organizations/{organizationId}/alert-center/destinations/{destinationId}Update an organization destination
DELETE/api/v3/organizations/{organizationId}/alert-center/destinations/{destinationId}Delete an organization destination
POST/api/v3/organizations/{organizationId}/alert-center/destinations/{destinationId}/testTest an organization destination
GET/api/v3/projects/{projectId}/alert-center/destinationsList project destinations
POST/api/v3/projects/{projectId}/alert-center/destinationsCreate a project destination
PUT/api/v3/projects/{projectId}/alert-center/destinations/{destinationId}Update a project destination
DELETE/api/v3/projects/{projectId}/alert-center/destinations/{destinationId}Delete a project destination
POST/api/v3/projects/{projectId}/alert-center/destinations/{destinationId}/testTest a project destination

Named destinations carry a channel (slack, teams, discord, mattermost, webhook), a delivery group (primary or backup), enabled severities and a write-only HTTPS URL. Testing returns accepted, failed or uncertain. All mutations use revisions for concurrency control.

Subscriptions (Email)​

MethodPathDescription
GET/api/v3/organizations/{organizationId}/alert-center/subscriptionGet your organization email subscription
PUT/api/v3/organizations/{organizationId}/alert-center/subscriptionUpdate your organization email subscription
GET/api/v3/projects/{projectId}/alert-center/subscriptionGet your project email subscription
PUT/api/v3/projects/{projectId}/alert-center/subscriptionUpdate your project email subscription

Personal email subscription for alert notifications. Enabling requires a verified email. Requires a member identity — API keys have no personal subscription state.

Maintenance Windows​

MethodPathDescription
GET/api/v3/organizations/{organizationId}/alert-center/maintenancesList organization maintenance windows
POST/api/v3/organizations/{organizationId}/alert-center/maintenancesCreate an organization maintenance window
DELETE/api/v3/organizations/{organizationId}/alert-center/maintenances/{maintenanceId}Cancel an organization maintenance window
GET/api/v3/projects/{projectId}/alert-center/maintenancesList project maintenance windows
POST/api/v3/projects/{projectId}/alert-center/maintenancesCreate a project maintenance window
DELETE/api/v3/projects/{projectId}/alert-center/maintenances/{maintenanceId}Cancel a project maintenance window

Maintenance windows pause notification delivery while observation continues. Supply a reason, start and end time. Optionally scope to a resource with resourceId. The listing returns active and upcoming windows by default; set includeHistory to include ended and cancelled windows.

See Alert Channels for destination setup and Alerts Overview for concepts.


Alerts (Legacy)​

The original project-level alert endpoints. These remain available for backward compatibility.

MethodPathDescription
GET/api/v3/organizations/{organizationId}/alertsList the alerts of every project
GET/api/v3/organizations/{organizationId}/alerts/summarySummarize the alerts of every project
GET/api/v3/projects/{projectId}/alertsList project alerts
GET/api/v3/projects/{projectId}/alerts/summarySummarize project alerts

The listing accepts diagnosticOnly, executionName and executionUid to narrow results to alerts that carry a workload diagnostic. The organization endpoints require both alerts:list and monitoring:list.

Notifications (Legacy)​

MethodPathDescription
GET/api/v3/projects/{projectId}/notificationsList where alerts are sent
PATCH/api/v3/projects/{projectId}/notifications/{severity}Change where alerts of one severity are sent
POST/api/v3/projects/{projectId}/notifications/{severity}/testSend a test notification

Use the Alert Center destination endpoints for the current notification model.


Monitoring​

The logs, events, metrics and traces of every project of an organization, in one place.

Every operation here reads across projects and requires the monitoring:list scope. Accessible with a session or an API key.

MethodPathDescription
GET/api/v3/organizations/{organizationId}/logsSearch the logs of every project
GET/api/v3/organizations/{organizationId}/logs.txtDownload the logs of every project
GET/api/v3/organizations/{organizationId}/eventsList what happened to the resources of every project
GET/api/v3/organizations/{organizationId}/metricsRead the resource usage of every project
GET/api/v3/organizations/{organizationId}/tracesList the traces of every project
GET/api/v3/organizations/{organizationId}/observability/connectionsList which workloads report telemetry

All endpoints accept projectId to narrow the results to one project, and time-window parameters since and until. A response whose partial flag is true means at least one project could not be reached; skipped names the projects left out.

The log search returns log lines most recent first, filterable by workload type, workload name, instance, container, level, stream and free-text query. The log export (logs.txt) streams the same lines as plain text, oldest first, with no pagination — a wide window is a long download.

Events are what the platform did to containers, jobs and cronjobs. They are kept for about an hour.

Metrics return one series per workload and metric (CPU, memory, storage, running instances) over a time window. stepSeconds sets the interval between points; it is widened when the window would yield too many.

Traces list the traces the organization's workloads reported. available is false when the organization sends no traces yet.

Observability connections list every workload with whether it is configured to send OpenTelemetry data, the endpoint to send to, and the variables to set.


Audit​

What was changed in an organization and its projects, by whom, and through what.

MethodPathDescription
GET/api/v3/me/auditList your own audit trail
GET/api/v3/organizations/{organizationId}/auditList the organization's audit log
GET/api/v3/projects/{projectId}/auditList the project's audit log

Your personal trail (/me/audit) returns what was done with your credentials across every organization you belong to. A personal API key acts as you, so what it did appears there beside what you did from a browser — actorType tells the two apart.

All three accept since, until, actorType, source and action to narrow the window. The organization and project listings also accept actor, operationId, resourceType and resourceName. Valid values for source are ui, mcp, bosco, public_api, internal, webhook and cli.

A change applied in the background (such as creating or deleting a project) produces two audit entries: one when the request is accepted, and one when the operation ends. The second entry's action is the operation name suffixed .applied or .failed. Both entries carry the same operationId — the id from the Location header — so filtering by operationId returns the pair. In the console, click the link icon next to an entry to show its operation.


Support tickets​

Questions and incidents raised with SailOps support.

MethodPathDescription
GET/api/v3/organizations/{organizationId}/ticketsList support tickets
POST/api/v3/organizations/{organizationId}/ticketsOpen a support ticket
GET/api/v3/organizations/{organizationId}/tickets/{ticketId}Get a support ticket
GET/api/v3/organizations/{organizationId}/tickets/{ticketId}/messagesList the messages of a ticket
POST/api/v3/organizations/{organizationId}/tickets/{ticketId}/messagesReply to a ticket
POST/api/v3/organizations/{organizationId}/tickets/{ticketId}/resolveResolve a ticket
POST/api/v3/organizations/{organizationId}/tickets/{ticketId}/reopenReopen a ticket

The ticket list includes a lastSupportReplyAt timestamp on each ticket where the support team has replied. Use it to detect unread replies on the client side.

A ticket also carries:

  • firstResponseAt — when a support agent first answered. Sonny's automatic reply does not count.
  • aiState — where the automatic first response stands: pending or diagnosing (Sonny is analysing the request), answered (Sonny posted its one automatic reply), handedOff (Sonny stepped aside without one). Absent when the ticket gets no automatic response. In every case a support agent takes over.

What your support plan entitles you to is covered in Getting help.


Billing​

What an organization is charged, and what it consumed to be charged that.

Usage​

How much of each metered resource an organization has consumed over a given window.

MethodPathDescription
GET/api/v3/organizations/{organizationId}/logUsageGet log storage usage
GET/api/v3/organizations/{organizationId}/observabilityUsageGet managed observability usage
GET/api/v3/organizations/{organizationId}/backupUsageGet backup storage usage

All three accept from and to (required, hour-aligned date-times) to set the window. observabilityUsage also accepts hourlyLimit to cap the number of hourly entries returned.

Costs​

Pre-aggregated cost facts, filterable by project, workload kind and resource type.

MethodPathDescription
GET/api/v3/organizations/{organizationId}/costsGet an organization's costs
GET/api/v3/projects/{projectId}/costsGet a project's costs
POST/api/v3/organizations/{organizationId}/costs.csvExport an organization's costs as CSV

from, to and granularity (day or month) control the window and bucket size. The CSV export additionally accepts format (localized or rfc4180) and arrays of exclusions (excludeProjects, excludeWorkloadKinds, excludeWorkloadIds, excludeResourceTypes).

The cost responses include an optional objectStorageIncomplete boolean, present when Object Storage usage measurements are incomplete. Costs include only the usage received so far and remain provisional until all measurements arrive.

Invoices​

MethodPathDescription
GET/api/v3/organizations/{organizationId}/invoicesList invoices
GET/api/v3/organizations/{organizationId}/invoices/{invoiceId}/pdfDownload an invoice as PDF

Invoices are finalised only — drafts, voided and uncollectible invoices are absent. The list accepts state (READY, OVERDUE, PAID), search, issuedFrom and issuedTo filters, and supports cursor pagination.

Payment methods​

MethodPathDescription
GET/api/v3/organizations/{organizationId}/paymentMethodsList payment methods
PATCH/api/v3/organizations/{organizationId}/paymentMethods/{paymentMethodId}Make a payment method the default
DELETE/api/v3/organizations/{organizationId}/paymentMethods/{paymentMethodId}Remove a payment method
POST/api/v3/organizations/{organizationId}/setupIntentStart adding a payment method
POST/api/v3/organizations/{organizationId}/confirmSetupFinish adding a payment method
POST/api/v3/organizations/{organizationId}/portalSessionOpen the billing portal

Adding a payment method is a two-step flow: setupIntent returns a client secret for the browser to collect card or mandate details, then confirmSetup records the result. The default method cannot be removed — make another one the default first.


Peerings​

Private network links between two projects of the same organization.

A peering opens one-way access from a workload (or every workload) in one project to a specific service and port in another. Both projects must belong to the same organization. The caller must hold peerings:update on both the source and the target project — opening an access into a project is a change to that project, whoever asked for it. Revocation is asymmetric: either side may close a link.

Creation and revocation answer once the row is durable; the network policy follows within a reconcile pass, and status reports where the peering has got to.

MethodPathDescription
GET/api/v3/organizations/{organizationId}/peeringsList the organization's project peerings
DELETE/api/v3/organizations/{organizationId}/peerings/{peeringId}Revoke a project peering
POST/api/v3/projects/{projectId}/peeringsOpen a project peering
GET/api/v3/projects/{projectId}/peeringCandidatesList what a project can peer from and to

The listing defaults to live peerings only — terminal ones (revoked, invalidated, failed) appear when includeTerminal is set. sourceProjectId, targetProjectId and status narrow the page further.

listPeeringCandidates answers both sides of the create form for one project: sources from the product registry (a source needs no Service — a cron job qualifies) and targets from the cluster (only the Services say which addresses and ports exist).

See Project Peerings for the concepts, statuses and UI walkthrough.


The terms of service, readable without authentication.

MethodPathDescription
GET/api/v3/legal/termsList the terms of service versions
GET/api/v3/legal/terms/{version}Read one version of the terms of service
GET/api/v3/legal/terms/{version}/pdfDownload one version of the terms of service

These endpoints are public and require no session or API key. The Markdown text returned by getTerms is the binding French version by default; pass lang=en for the English courtesy translation. The PDF is available in both languages.


Registry credentials​

The credentials a project uses to pull images from private registries.

A project holds one credential per registry. The registry host is canonicalised on the way in (ghcr.io, https://ghcr.io/v2/ and GHCR.IO all resolve to the same entry), and cannot be changed after creation — remove the credential and add another for a different registry.

Mutations store the credential and answer immediately. The pull secret appears in the project within seconds; status tracks progress: PENDING (stored, not yet usable), ACTIVE (in the project), FAILED (could not be installed, still retried) or REMOVING (on its way out). Passwords are never returned.

MethodPathDescription
GET/api/v3/projects/{projectId}/registryCredentialsList the registry credentials a project holds
POST/api/v3/projects/{projectId}/registryCredentialsAdd a registry credential to a project
PUT/api/v3/projects/{projectId}/registryCredentials/{credentialId}Replace a registry credential
DELETE/api/v3/projects/{projectId}/registryCredentials/{credentialId}Remove a registry credential
POST/api/v3/projects/{projectId}/registryCredentials/{credentialId}/testTest a registry credential the project holds
POST/api/v3/projects/{projectId}/registryCredentials/testTest a registry credential without storing it

Both test endpoints authenticate against the registry and report the result, including provider detection and scope verification for GitHub and GitLab tokens. They are rate-limited per organization.

The stored-credential test (/{credentialId}/test) uses the saved password — nothing needs to be entered again. The standalone test (/test) takes the full credential in the request body.

Both accept an optional image field. When given, the registry is also asked for the image's manifest, which proves the credential can pull it — on any registry, where without an image only GitHub and GitLab tokens can have their permissions inspected.

See Docker Registry for the UI guide and provider-specific configuration.


DNS providers​

The registrars a project publishes its DNS records through.

A DNS provider stores credentials for one of the supported registrars and, once installed, runs a controller that keeps the project's DNS records in sync with its gateways and websites. The controller appears within a minute of creation; status tracks where it has got to (PENDING, ACTIVE, FAILED, REMOVING), and sync carries what it reports about its own synchronisation — health, error code, last sync times and managed record count — sampled periodically and published with the instant it was taken.

Credentials are sealed at rest and never returned. The response carries settings instead: the non-secret half of the configuration (region, endpoint, whether Cloudflare proxies).

A project holds one provider per name. Neither the name nor the type can change after creation — remove the provider and add another one instead.

MethodPathDescription
GET/api/v3/projects/{projectId}/dnsProvidersList the DNS providers a project uses
POST/api/v3/projects/{projectId}/dnsProvidersAdd a DNS provider to a project
PUT/api/v3/projects/{projectId}/dnsProviders/{providerId}Replace a DNS provider's credentials and zones
DELETE/api/v3/projects/{projectId}/dnsProviders/{providerId}Remove a DNS provider

Creating answers 201 with the provider in PENDING status. The update (PUT) replaces credentials and the optional domain filter; it resets sync because what the previous controller reported no longer applies. Deleting answers 200 with the provider in REMOVING status; the controller and its credentials leave the project within a minute, after which its records are no longer updated. Records already published to the registrar are left as they are. The provider stays listed, and its name stays reserved, until its controller is gone.

The domains array restricts which zones the provider manages. Leave it out (or empty) to let it manage every zone its credentials can reach.

Supported provider types: CLOUDFLARE, OVH, AWS, AZURE, GANDI, GODADDY, DIGITAL_OCEAN, IONOS, SCALEWAY. Each type has its own credential shape, sent as a discriminated union keyed by type in the credentials field. See the Interactive API Reference for the full schema of each.

See DNS Providers for the UI guide and provider-specific configuration.


Valkey​

The Valkey instances a project runs.

An instance is addressed by name — the name is unique per project and cannot be changed after creation. Every write answers 202 and names an operation to follow in its Location header, because every write reaches a cluster member. The instance is ready when the operation succeeds.

MethodPathDescription
GET/api/v3/projects/{projectId}/valkeyList a project's Valkey instances
POST/api/v3/projects/{projectId}/valkeyCreate a Valkey instance
GET/api/v3/projects/{projectId}/valkey/{name}Get a Valkey instance
PUT/api/v3/projects/{projectId}/valkey/{name}Replace a Valkey instance's configuration
DELETE/api/v3/projects/{projectId}/valkey/{name}Delete a Valkey instance
GET/api/v3/projects/{projectId}/valkey/{name}/metricsRead what a Valkey instance is doing
GET/api/v3/projects/{projectId}/valkey/{name}/adminCredentialsRead the credentials of the admin interface
POST/api/v3/projects/{projectId}/valkey/{name}/adminCredentials/rotateRotate the credentials of the admin interface

Creating answers 202 with the instance in the pending phase. The Location header names the operation to follow; the instance accepts connections when that operation succeeds, and reads failed if it does not.

Replacing sends the whole configuration: what you send is what the instance becomes, and a field you leave out returns to its default. Two things cannot change — the version is fixed at creation, and storage may grow but never shrink. Omit auth.password to keep the current one; send a new one to rotate it.

Deleting destroys the instance and its data with no restore. While anything connects to it, the call answers 409 and names what does — remove those connections first.

The listing is not paged — a project holds a handful of instances. state is read when you ask: it says what the platform observes at that moment. Phases are pending, running, stopped, degraded, failed and deleting.

Metrics return a window of measurements: processor and memory of each shard, and what the engine reports — connections, operations, keyspace, persistence. A point whose observed is false carries no measurement and must not be read as zero. Parameters: since, until and stepSeconds (widened when the window would yield too many points).

Admin credentials return the user and password for the Valkey Admin web interface, available while admin.enabled is true. Rotating replaces them; the previous ones stop working once the operation succeeds.

All Valkey endpoints use the valkey:list, valkey:update or valkey:delete scope family. Accessible with a session or an API key.

See Cache Overview for the concepts and Cache Configuration for the options.


MariaDB​

The MariaDB instances a project runs, their users and their schemas.

An instance is addressed by name — the name is unique per project and cannot be changed after creation. Every write answers 202 and names an operation to follow in its Location header, because every write reaches a cluster member. The instance is ready when the operation succeeds.

MethodPathDescription
GET/api/v3/projects/{projectId}/mariadbList a project's MariaDB instances
POST/api/v3/projects/{projectId}/mariadbCreate a MariaDB instance
GET/api/v3/projects/{projectId}/mariadb/{name}Get a MariaDB instance
PUT/api/v3/projects/{projectId}/mariadb/{name}Replace a MariaDB instance's configuration
DELETE/api/v3/projects/{projectId}/mariadb/{name}Delete a MariaDB instance
GET/api/v3/projects/{projectId}/mariadb/{name}/usersList the users of a MariaDB instance
POST/api/v3/projects/{projectId}/mariadb/{name}/usersAdd a user to a MariaDB instance
DELETE/api/v3/projects/{projectId}/mariadb/{name}/users/{userName}Remove a user from a MariaDB instance
POST/api/v3/projects/{projectId}/mariadb/{name}/users/{userName}/resetPasswordReset a MariaDB user's password
GET/api/v3/projects/{projectId}/mariadb/{name}/schemasList the schemas of a MariaDB instance
POST/api/v3/projects/{projectId}/mariadb/{name}/schemasAdd a schema to a MariaDB instance
DELETE/api/v3/projects/{projectId}/mariadb/{name}/schemas/{schemaName}Delete a schema from a MariaDB instance
GET/api/v3/projects/{projectId}/mariadb/{name}/backupsList the backups of a MariaDB instance
POST/api/v3/projects/{projectId}/mariadb/{name}/backupsTake a backup of a MariaDB instance
GET/api/v3/projects/{projectId}/mariadb/{name}/backups/{backupId}Get a backup of a MariaDB instance
POST/api/v3/projects/{projectId}/mariadb/{name}/backups/{backupId}/downloadGet a link to download a backup
POST/api/v3/projects/{projectId}/mariadb/{name}/backups/{backupId}/encryptedDownloadDownload a backup, encrypted
POST/api/v3/projects/{projectId}/mariadb/{name}/restoreRestore a MariaDB instance from a backup
GET/api/v3/projects/{projectId}/mariadb/{name}/logsRead the logs of a MariaDB instance
GET/api/v3/projects/{projectId}/mariadb/{name}/metricsRead what a MariaDB instance is doing

Creating answers 202 with the instance in the pending phase. At least one user and one schema are required at creation — an instance with no user is a database nobody can reach. Afterwards users and schemas are added and removed through their own operations, and a replacement of the configuration does not mention them.

Replacing sends the whole configuration: what you send is what the instance becomes, and a field you leave out returns to its default. Two things cannot change — the version is fixed at creation, and storage may grow but never shrink.

Deleting destroys the instance, every schema it holds and every backup ever taken of it. While anything connects to it, the call answers 409 and names what does — remove those connections first.

The listing is not paged — a project holds a handful of instances. state is read when you ask: it says what the platform observes at that moment. Phases are pending, running, stopped, degraded, failed and deleting.

Users can sign in and hold privileges per schema. Passwords are never returned; reset one to set a new password. A grant naming a schema the instance does not hold is refused. A user another service of the project created carries readOnly: true and managedBy (kind and name of that service); deleting it or resetting its password answers CONFLICT.

Schemas hold the character set and collation fixed at creation. Deleting a schema destroys every table in it — it is the one operation on an instance that loses data without destroying the instance. A schema another service manages carries readOnly: true and managedBy; deleting it answers CONFLICT.

Backups are kept for as long as backup.retentionDays says, and every backup of an instance is destroyed with the instance. The plain download answers a presigned link; the encrypted download streams an AES-256 encrypted ZIP with the password you send.

Restore replaces the contents of the instance with the backup's. Everything written since that backup was taken is lost.

Logs return log lines within a time window. They can carry statement text, which is why reading them requires the mariadb/logs:list scope rather than mariadb:list.

Metrics return a window of measurements: processor, memory and disk of the nodes, and what the engine reports — connections, statements, the InnoDB buffer pool, the network and replication. A point whose observed is false carries no measurement and must not be read as zero. Parameters: since, until and stepSeconds (widened when the window would yield too many points).

All MariaDB endpoints use the mariadb:list, mariadb:update, mariadb:delete or mariadb/logs:list scope family. Accessible with a session or an API key.

See MariaDB Overview for the concepts and Database Configuration for the options.


Kafka​

The Kafka clusters a project runs, their topics and their users.

A cluster is addressed by name — the name is unique per project and cannot be changed after creation. Every write answers 202 and names an operation to follow in its Location header, because every write reaches a cluster member. The cluster is ready when the operation succeeds.

MethodPathDescription
GET/api/v3/projects/{projectId}/kafkaList a project's Kafka clusters
POST/api/v3/projects/{projectId}/kafkaCreate a Kafka cluster
GET/api/v3/projects/{projectId}/kafka/{name}Get a Kafka cluster
PUT/api/v3/projects/{projectId}/kafka/{name}Replace a Kafka cluster's configuration
DELETE/api/v3/projects/{projectId}/kafka/{name}Delete a Kafka cluster
GET/api/v3/projects/{projectId}/kafka/{name}/topicsList the topics of a Kafka cluster
POST/api/v3/projects/{projectId}/kafka/{name}/topicsAdd a topic to a Kafka cluster
PUT/api/v3/projects/{projectId}/kafka/{name}/topics/{topicName}Replace a topic's configuration
DELETE/api/v3/projects/{projectId}/kafka/{name}/topics/{topicName}Delete a topic from a Kafka cluster
GET/api/v3/projects/{projectId}/kafka/{name}/usersList the users of a Kafka cluster
POST/api/v3/projects/{projectId}/kafka/{name}/usersAdd a user to a Kafka cluster
PUT/api/v3/projects/{projectId}/kafka/{name}/users/{userName}Change what a Kafka user may do
DELETE/api/v3/projects/{projectId}/kafka/{name}/users/{userName}Remove a user from a Kafka cluster
POST/api/v3/projects/{projectId}/kafka/{name}/users/{userName}/resetPasswordReset a Kafka user's password
GET/api/v3/projects/{projectId}/kafka/{name}/uiCredentialsRead the credentials of the Kafka UI
POST/api/v3/projects/{projectId}/kafka/{name}/uiCredentials/rotateRotate the credentials of the Kafka UI
GET/api/v3/projects/{projectId}/kafka/{name}/metricsRead what a Kafka cluster is doing

Creating answers 202 with the cluster in the pending phase. Topics and users are added through their own operations, and those can be sent right away — they wait for the cluster to run. The name is how the cluster is addressed afterwards and cannot be changed.

Replacing sends the whole configuration: what you send is what the cluster becomes, and a field you leave out returns to its default. The version, the node count and the storage class are fixed at creation. Processor, memory and storage may grow and never shrink — a smaller flavor or a smaller disk is refused. A change of flavor or compute class restarts the nodes one at a time.

Deleting destroys the cluster, every topic and every message it holds. Kafka keeps no backup. While anything connects to it, the call answers 409 and names what does — remove those connections first.

The listing is not paged. state is read when you ask: it says what the platform observes at that moment. Phases are pending, running, stopped, degraded, failed and deleting.

Topics are created through the API; a topic a client created directly against the brokers is not listed. Partitions can be added and never removed. The replication factor is fixed at creation. A name that differs from an existing topic's only by . and _ is refused, as Kafka refuses it. Names starting with __ are Kafka's own and refused. Deleting a topic destroys every message in it.

Users authenticate with SCRAM-SHA-512 as the username the response carries, which is derived from the name, not the name itself. Access levels are readonly, readwrite and full, applied to every topic and consumer group. Passwords are never returned; reset one to set a new password. Names starting with connection- are reserved.

UI credentials return the user and password for the Kafka UI web interface, available while ui.enabled is true. Rotating replaces them; the previous ones stop working once the operation succeeds.

Metrics return a window of measurements: processor, memory, disk and how many nodes were running. A point whose observed is false carries no measurement and must not be read as zero. Parameters: since, until and stepSeconds (widened when the window would yield too many points).

All Kafka endpoints use the kafka:list, kafka:update or kafka:delete scope family. Accessible with a session or an API key.

See Apache Kafka for the concepts.


Not here yet​

Containers, websites, jobs, PostgreSQL, gateways and the Stack Engine are served by the Public API, which is unchanged and stays supported. Creating, archiving, billing and changing the plan of an organization, and the project lifecycle (create, delete, restore), are no longer served by the v1 API. The remaining resources move here one at a time; this page grows as they do.