HTTP API reference

The JSON API under https://oak.space/api that the CLI is built on.

Markdown

All pages

oak.space has a JSON API — the same one the oak CLI is built on. Use it to script repositories, branches, merges, marks, and organizations, or to wire Oak into your own tools and agents.

Basics#

Base URL: https://oak.space/api. Paths below are relative to it.

Authentication: send a token as a bearer header. Personal API keys, organization agent keys, and oak login sessions all work — see API keys and tokens.

curl https://oak.space/api/repos -H "Authorization: Bearer $OAK_API_KEY"

Requests without a token can read public resources only.

Format: request and response bodies are JSON (Content-Type: application/json). {owner} is an organization slug (including personal organizations, which are named after their user).

Errors use the usual status codes — 400 bad request, 401 not signed in, 403 signed in but not allowed (including a key missing a scope), 404 not found (also returned for things you can't see), 409 conflict, 412 precondition failed, 503 temporarily unavailable — with a body like:

{ "error": "human-readable message" }

Some errors add a machine-readable code and retryable: true.

Account and keys#

MethodPathDescription
GET/whoamiThe user (or organization agent) behind the token.
GET/versionServer version.
GET/api-keysYour personal API keys (prefixes only).
POST/api-keysCreate a key: {"name", "scope": "full"|"read", "repo"?: "owner/name", "expires_in"?, "org"?, "groups"?} (see API keys). Returns the full key once.
DELETE/api-keys/{id}Revoke a key.

Repositories#

MethodPathDescription
GET/repos?sort=name|updated|createdRepositories you can access.
POST/reposCreate one: {"name", "description"?, "is_public"?, "organization_slug"?}.
GET/{owner}/{name}A repository: name, visibility, head, and more.
DELETE/{owner}/{name}Delete a repository.
PATCH/{owner}/{name}/visibility{"is_public": true|false}.
POST/{owner}/{name}/transferMove it to another organization: {"to_organization": "slug"}.
POST/{owner}/{name}/archiveArchive it: every write except unarchive, transfer, and delete then gets 403 (org owners and admins).
POST/{owner}/{name}/unarchiveMake an archived repo writable again (org owners and admins).
GET/{owner}/{name}/sizeStorage the repository uses.

Branches#

MethodPathDescription
GET/{owner}/{name}/branchesList branches, with descriptions, heads, and status.
POST/{owner}/{name}/branchesCreate one: {"name", "description"?, "parent_branch"?}.
GET/{owner}/{name}/branches/{branch}One branch. Add ?record_read=1 to record that you've read it; the response includes who else has.
POST/{owner}/{name}/branches/{branch}/mergeSquash-merge onto the parent. See below.
POST/{owner}/{name}/branches/{branch}/syncMerge the parent into the branch. 409 with code: "branch_moved" (retryable) if it received new commits meanwhile.
POST/{owner}/{name}/branches/{branch}/closeClose a branch. Idempotent.
POST/{owner}/{name}/branches/{branch}/reopenReopen a closed branch.
POST/{owner}/{name}/branches/{branch}/renameTemporarily disabled — returns 503.

Branch descriptions are set by pushing (oak desc then oak push); there's no separate endpoint.

Merge responses#

POST …/merge lands one squash commit on main whose message is the branch description.

StatusMeaning
200Merged. The body has commit_hash (the new commit on main) and merge_parent_hash (the branch tip).
409 with conflict_pathsThe branch conflicts with main. Sync, resolve, and push.
409 with code: "main_moved" or "branch_moved"main or the branch changed during the merge. Nothing was merged; retry.
409 with code: "approvals_required"A path rule needs approvals the branch doesn't have yet (missing_approvals).
400 "already closed"The branch was already merged or closed.

Commits and content#

MethodPathDescription
POST/{owner}/{name}/commits/infoCommits for a list of hashes, with their trees unless "metadata_only": true. "first_parent": N with one hash walks back from it instead (up to 200; first_parent.next continues). If some directory is hidden from you, only metadata requests are answered, and commits that changed a hidden directory are left out.
POST/{owner}/{name}/commits/{hash}/revertLand a commit that undoes {hash} on its branch. 409 if the affected files have changed since.
GET/{owner}/{name}/tree/{commit}The root directory listing at a commit.
GET/{owner}/{name}/tree/{commit}/{path}A subdirectory listing.
GET/{owner}/{name}/raw/{commit}/{path}A file's bytes at a commit.

Outside the JSON API, GET https://oak.space/{owner}/{name}/download returns a zip of main.

Marks#

Marks live under /{owner}/{name}/marks, and reports on a commit under /{owner}/{name}/commits/{commit}/reports. The routes are listed in Marks.

Organizations#

MethodPathDescription
GET/orgsYour organizations.
POST/orgsCreate one: {"slug", "name", "description"?}.
GET/orgs/{slug}One organization.
PATCH/orgs/{slug}Update its name or description.
DELETE/orgs/{slug}Delete it.
GET/orgs/{slug}/membersMembers and roles.
POST/orgs/{slug}/membersAdd someone: {"username", "role"?: "member"|"admin"|"owner"}.
PATCH/orgs/{slug}/members/{username}Change a role: {"role"}.
DELETE/orgs/{slug}/members/{username}Remove a member.
GET/orgs/{slug}/groupsGroups, with their kind (public, members or custom), members, maintainers, agents (organization agents) and repos. (/orgs/{slug}/teams is the old name.)
POST/orgs/{slug}/groupsCreate a group: {"slug", "parent"?, "description"?}.
PATCH/orgs/{slug}/groups/{group}Change a group's description or parent.
DELETE/orgs/{slug}/groups/{group}Delete a group with no sub-groups and no boundaries.
PUT/orgs/{slug}/groups/{group}/members/{username}Add someone, or set {"maintainer": true}.
DELETE/orgs/{slug}/groups/{group}/members/{username}Remove someone.
PUT/orgs/{slug}/groups/{group}/agents/{name}Put one of the organization's agents on a custom group.
DELETE/orgs/{slug}/groups/{group}/agents/{name}Take it off.
POST/orgs/{slug}/groups/{group}/invite{"username", "maintainer"?}: add someone, to the organization first if they aren't in it (that part takes an owner or admin).
PUT/orgs/{slug}/groups/{group}/repos/{repo}Give the group {"role": "reader"|"writer"} on a repo (owners and admins). For public, makes the repo public.
DELETE/orgs/{slug}/groups/{group}/repos/{repo}Take it away. For public, makes the repo private.
GET/{owner}/{name}/accessWho can reach a repo: {"repo", "is_public", "grants": [{"group"?, "kind"?, "user"?, "role"}]}.
PUT/{owner}/{name}/access/users/{username}Give one person {"role"} on the repo (owners and admins).
DELETE/{owner}/{name}/access/users/{username}Take one person's access away.
GET/user/groupsThe groups you're in, across your organizations.
GET/orgs/{slug}/storageStorage used against the quota.
GET/orgs/{slug}/auditThe audit log.

Managing members and organization agents needs owner or admin. Groups are managed by owners and admins and by each group's maintainers; giving groups access to repos takes owner or admin. See Path rules for who changes rules on folders.

Organization agents#

MethodPathDescription
GET/orgs/{slug}/agentsList them, each with the groups it's on.
POST/orgs/{slug}/agentsCreate one: {"name", "display_name"?}.
PATCH/orgs/{slug}/agents/{name}{"disabled": true|false}.
DELETE/orgs/{slug}/agents/{name}Delete it.
GET/orgs/{slug}/agents/{name}/keysIts keys.
POST/orgs/{slug}/agents/{name}/keysCreate a key: {"name", "scopes": "read,write"} (some of read, write, release). Returns the key once.
DELETE/orgs/{slug}/agents/{name}/keys/{key_id}Revoke a key.

An agent reaches what its groups reach. Scopes are explained in API keys and tokens. /orgs/{slug}/service-accounts is the old name for these paths and still works.

Webhooks#

MethodPathDescription
GET/{owner}/{name}/webhooksA repo's webhooks.
POST/{owner}/{name}/webhooksCreate one: {"url", "secret"?, "events"?: ["push", "merge", …]}, using the names in Webhooks.
DELETE/{owner}/{name}/webhooks/{id}Delete one.

Payloads and signatures: Webhooks.

Pages#

MethodPathDescription
GET/pages/names/{name}Whether a site name is free: {"name", "available", "reason"}. ?org=SLUG checks it for that organization.
GET/{owner}/{name}/pages/sitesThe repo's sites: {"sites": [...]}.
POST/{owner}/{name}/pages/sitesCreate one: {"name", "source_dir"?, "spa_fallback"?}. Org owner or admin. Deploys it and returns 201 with the site.
GET/{owner}/{name}/pages/sites/{site}One site, with its live deployment (and last_failure when the newest attempt failed).
PATCH/{owner}/{name}/pages/sites/{site}Change name, source_dir, spa_fallback, or basic_auth ({"username", "password"}, or null to remove). Org owner or admin.
DELETE/{owner}/{name}/pages/sites/{site}Delete it (204). Org owner or admin.
GET/{owner}/{name}/pages/sites/{site}/deploymentsDeployment history, newest first.
POST/{owner}/{name}/pages/sites/{site}/deployments{"action": "redeploy"} or {"action": "rollback", "to"?}. Write access. A failed deploy returns 200 with "status": "failed" and a failure.
GET/{owner}/{name}/pages/sites/{site}/domains[/{domain}]The site's custom domains, each with its status and the DNS records to create.
POST/{owner}/{name}/pages/sites/{site}/domainsAdd one: {"domain"}. 201 when added. Org owner or admin.
POST/{owner}/{name}/pages/sites/{site}/domains/{domain}/verifyCheck its TXT record and start serving it. Org owner or admin.
PATCH/{owner}/{name}/pages/sites/{site}/domains/{domain}{"primary": true} makes it the site's main address. Org owner or admin.
DELETE/{owner}/{name}/pages/sites/{site}/domains/{domain}Remove it (204). Org owner or admin.
GET/orgs/{slug}/pages/sitesEvery site in an organization (members).

Unavailable names all return 409 with the same message. See Pages.

CLI releases#

Public endpoints the installer and oak upgrade use to fetch and verify binaries.

MethodPathDescription
GET/releasesPublished CLI versions.
GET/releases/latestThe latest version.
GET/releases/{version}/{platform}Download a binary.
GET/releases/{version}/{platform}/sha256Its SHA-256.
GET/releases/{version}/{platform}/minisigIts minisign signature.
GET/releases/latest/{platform}Redirects (302) to the latest version's binary for platform, such as darwin-arm64. /sha256 and /minisig after it redirect the same way.

Sync protocol#

Push, pull, and clone use content-addressed endpoints under /{owner}/{name}/ — push, pull, blobs/*, and chunks/*. They're built for the CLI, which verifies every hash, and may change between versions; use the CLI rather than calling them directly.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].