// API REFERENCE

API reference

The Segal Cloud REST API. One bearer-authenticated surface across every service. In this build the API is mock-first: requests resolve against the in-memory adapters (SEGAL_DATA_MODE=mock). This document is the single source of truth for the reference docs, the SDK, and in-docs samples.

One bearer-authenticated REST surface across every service. This reference is generated from a single OpenAPI 3.1.0 document — the same source that drives the SDK and the in-docs samples, so it never drifts from the API.

Mock-first in this build

Requests resolve against the in-memory adapters (SEGAL_DATA_MODE=mock). The sandbox on each endpoint page uses a fixed demo key and never accepts a production key.

Base URL

bash

https://api.segalcompute.com

Authentication

Authenticate every request with a scoped API key in the Authorization header. Keys are prefixed sk_segal_ and are created per project in the console. Never embed a key in client-side code.

bash

curl https://api.segalcompute.com/api/v1/domains \
  -H "Authorization: Bearer sk_segal_..."

Errors

Failures use standard HTTP status codes and return a consistent JSON envelope. The request_id correlates with the X-Request-Id response header — include it when contacting support.

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "name_required",
    "message": "name is required",
    "request_id": "req_8sd9f2"
  }
}

400 — invalid request (missing or malformed fields)
401 — missing or invalid API key
429 — rate limited; retry after the window resets
451 — export-control restricted for the chosen region

Pagination

List endpoints are cursor-paginated. Pass limit to size a page and cursor to fetch the next one. Responses carry has_more and next_cursor — keep requesting until has_more is false.

Param	Type	Required	Description
limit (query) = 20	integer	no	Page size.
cursor (query)	string	no	Opaque pagination cursor from a prior response.

Rate limits

Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. When you exhaust the window the API returns 429; back off and retry once the window resets.

Idempotency

Make resource-creating POST requests safe to retry by sending an Idempotency-Key header. Replaying the same key returns the original result instead of creating a duplicate.

bash

curl -X POST https://api.segalcompute.com/api/v1/domains \
  -H "Authorization: Bearer sk_segal_..." \
  -H "Idempotency-Key: a1b2c3" \
  -H "Content-Type: application/json" \
  -d '{"name":"acme.dev"}'

Webhooks

Subscribe to lifecycle events (for example a domain becoming active or a deploy finishing) instead of polling. Signed delivery and the event catalog are on the roadmap for this surface.

Not yet in the mock API

Webhook delivery is not wired into the mock build. This section documents the intended model; endpoints will appear here once published to the spec.

Versioning

The API is versioned in the path — every route is under /api/v1. Additive changes (new fields, new endpoints) ship within v1; breaking changes ship a new version. The spec is published at version 1.0.0.

Services

Each service exposes its own resource endpoints. Pick one to see parameters, responses, multi-language samples, and a mock-backed sandbox.

Domains

2 endpoints

Domain registration, transfer, and WHOIS privacy.

DNS

2 endpoints

Authoritative DNS zones and records.

Sites

2 endpoints

Git-connected web hosting.

Databases

2 endpoints

Managed SQL, KV, and Vector databases.

VPN

2 endpoints

WireGuard private networking.