API reference

The Sylphx API is one HTTP API for the whole platform, at https://api.sylphx.com/v1. Every page in this reference is generated from the protobuf contracts in contracts/ — the same contracts the SDKs, the CLI and the Terraform provider come from — so a method that is not here is not served, and a field that is here is a field the API takes.

#Authentication

Every call carries one key in Authorization: Bearer: a secret key (sylphx_sk_…) from a server, or a publishable key (sylphx_pk_…) from a browser or a mobile app. A publishable key reaches only the methods marked callable with a publishable key: 9 of the 536 methods in this reference.

Keys, their kinds and their scopes are in Keys and scopes; the scope a method needs is on its page.

#Names

Everything the API holds is a Resource with one canonical name (AIP-122):

orgs/{org}
orgs/{org}/projects/{project}
orgs/{org}/projects/{project}/envs/{env}
{parent}/{collection}/{id}

The collection segment is a snake_case plural, unique across the whole registry, so it identifies its service on its own. Below the environment the caller names the id on Create (database_id), and the server assigns one when it is omitted. - stands for any parent segment on List (AIP-159). The registry's Resources:

#Pagination

List methods take page_size (50 by default, at most 1000) and an opaque page_token; the answer carries the items and, when there is more, next_page_token. A token is bound to the parent, the filter, the ordering and the caller, and reusing it otherwise is INVALID_ARGUMENT (PAGE_TOKEN_MISMATCH). The paginated collections:

#Idempotency

Every mutating method accepts Idempotency-Key (1–255 printable ASCII). The first call runs; a replay of the same request within 24 hours returns the stored answer with Sylphx-Idempotent-Replay: true, a replay with a different body is IDEMPOTENCY_KEY_REUSED (422), and a replay while the first call is still running is IDEMPOTENCY_IN_PROGRESS (409), which is worth retrying.

287 of the 536 methods here have an effect other than read; 22 of them also take validate_only=true (AIP-163), which runs every check a write would run and then writes nothing.

Writes are also guarded by etags: Get answers with an ETag equal to meta.etag, Update and Delete accept If-Match or etag (AIP-154), and a mismatch is ETAG_MISMATCH (409) with the current etag in the error's details, so a client re-reads and retries.

#Errors

A failed call answers with one RFC 9457 problem body carrying a stable code, whether the failure is retryable, and what it did to your data. The body and the retry rules are in Errors; each method page here lists the codes that method can return, and the 33 codes in the registry have a page each in the index below.

#Versions

A request may pin the behaviour it was written against with Sylphx-Version: YYYY-MM-DD; the response echoes the version that was applied. The version stream is in API versions.

#Watch

Long-running work — a deploy, a database creation — is followed through the resource API's streaming surface: a list or a detail view watches GET /v1/{parent}/{collection}:watch as Server-Sent Events, and a reconnect resumes from the SSE Last-Event-ID. The contracts do not declare a watch method yet, so it is not part of this generated reference; a page here documents the request/response surface only.

#Services

#Service-level methods

A few calls belong to a service rather than to one of its collections, and have a page each:

#Error codes

Every code the platform declares, with the HTTP status a caller sees and the gRPC status the SDKs report.