Get started

Quickstart: API

Five minutes, one terminal, curl. You will check your key, create a Hives project, store a secret in it, list it and clean up.

1. Create an API key

In the Console, open API keys → Create. Give it a name and the scopes hives:read and hives:write. Copy the secret; it is shown once.

export GENESIS_API_KEY="sk_..."
export GENESIS_BASE_URL="https://os.one.ml/api"

2. Check the gateway and your key

/v1/status needs no key. /v1/whoami returns the organization, principal and scopes the gateway sees for your key.

curl "$GENESIS_BASE_URL/v1/status"

curl "$GENESIS_BASE_URL/v1/whoami" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Response

{
  "object": "principal",
  "kind": "api_key",
  "org": "o_01...",
  "principal": "api_key_01...",
  "scopes": ["hives:read", "hives:write"]
}

3. Create a project

curl -X POST "$GENESIS_BASE_URL/v1/hives/projects" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "quickstart", "kind": "function"}'

The answer is 201 with the project. Keep its id:

Response (abridged)

{
  "id": "prj_1de8079b884f4cca8bfc109a01514a3e",
  "name": "quickstart",
  "kind": "function",
  "status": "creating",
  "created_at": "2026-10-20T06:40:29.650658Z"
}

export PROJECT_ID="prj_..."

4. Store a secret and list it

Secrets are encrypted at rest. Listing returns names and versions, never values.

curl -X POST "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/secrets" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "DATABASE_URL", "value": "postgres://example"}'

curl "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/secrets" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Response

{
  "data": [
    { "id": "sec_...", "name": "DATABASE_URL", "description": null, "version": 1,
      "created_at": "2026-10-20T06:40:30.330652Z", "updated_at": "2026-10-20T06:40:30.330652Z" }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1, "has_next": false, "has_prev": false }
}

5. Clean up

curl -X DELETE "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

The project moves to deleting and finishes in the background. Until it does, its name stays taken: creating another quickstart meanwhile answers 409, so pick a new name for a second run.

When something fails

The HTTP status always tells you what kind of failure it is. Errors the gateway raises carry a stable code, a request_id, and on a 403 the required_scope that was missing:

{
  "error": {
    "type": "forbidden",
    "code": "SCOPE_MISSING",
    "message": "The credential lacks the scope named in required_scope.",
    "request_id": "02f92096-3625-4ff2-a6ff-87df16d75e0f",
    "docs_url": "https://os.one.ml/api/v1/errors#SCOPE_MISSING",
    "required_scope": "hives:write"
  }
}

A service's own refusal comes back as the service sent it, with the same x-request-id header. See Errors and the full list of error codes.

Every Hives operation: Hives API.
The same flow in code: Quickstart: SDK.
Retrying writes safely: Idempotency.

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