Concepts

Requests and responses

One base URL, versioned paths, JSON in and out, and a request ID on every answer.

Base URL and paths

https://os.one.ml/api/v1/<service>/<resource>

Every operation lives under /v1/<service>/, for example /v1/hives/projects. The gateway's own routes are /v1/status, /v1/whoami, /v1/usage, /v1/errors and /v1/openapi.json; see Gateway.
HTTPS only. The SDK, CLI and MCP server refuse plain http:// except on loopback.

Headers you send

Header	When	Notes
`Authorization`	Every call except public routes	`Bearer <credential>`, exactly once.
`Content-Type`	Requests with a body	`application/json` unless the operation says otherwise.
`Accept`	Optional	`application/json`.
`Idempotency-Key`	Writes that take one	See Idempotency.
`X-Request-Id`	Optional	A UUID v4 of your own to correlate logs; otherwise the gateway assigns one.
`If-Match`, `If-None-Match`	Operations that use ETags	Conditional writes and reads.
`Range`	Downloads that support it	Partial content.

Other request headers are not forwarded to services.

Headers you get back

Header	Notes
`x-request-id`	On every response, and in every gateway error body. Yours if you sent a valid UUID v4.
`content-type`	Usually `application/json`.
`retry-after`	On `429`, and on some `503`s. Seconds.
`etag`, `last-modified`	Where the service versions a resource.

Bodies

Request bodies up to 2 MiB through https://os.one.ml/api, uploads included; a larger body answers 413 with BODY_TOO_LARGE.
Timestamps are ISO 8601 in UTC, for example 2026-10-20T06:40:29.650658Z.
Ids are opaque strings with a type prefix where the service has one: o_… organizations, prj_… Hives projects, sec_… secrets, api_key_… key principals.
A 204 has no body.

https://os.one.ml/api/v1/openapi.json lists every operation the gateway serves right now. The SDK ships the full document with descriptions and schemas as @lifesi/genesis/spec.json; this reference is generated from both.

import spec from '@lifesi/genesis/spec.json' with { type: 'json' }

Versions

Paths are versioned (/v1). The packages share one version number; use the same version of @lifesi/genesis, @lifesi/genesis-cli and @lifesi/genesis-mcp. What changed in each release is in the changelog.

One Superintelligence, Inc. · Built from Genesis 0.1.12 and the live gateway on 2026-10-20. Support