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#
| Method | Path | Description |
|---|---|---|
GET | /whoami | The user (or organization agent) behind the token. |
GET | /version | Server version. |
GET | /api-keys | Your personal API keys (prefixes only). |
POST | /api-keys | Create 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#
| Method | Path | Description |
|---|---|---|
GET | /repos?sort=name|updated|created | Repositories you can access. |
POST | /repos | Create 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}/transfer | Move it to another organization: {"to_organization": "slug"}. |
POST | /{owner}/{name}/archive | Archive it: every write except unarchive, transfer, and delete then gets 403 (org owners and admins). |
POST | /{owner}/{name}/unarchive | Make an archived repo writable again (org owners and admins). |
GET | /{owner}/{name}/size | Storage the repository uses. |
Branches#
| Method | Path | Description |
|---|---|---|
GET | /{owner}/{name}/branches | List branches, with descriptions, heads, and status. |
POST | /{owner}/{name}/branches | Create 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}/merge | Squash-merge onto the parent. See below. |
POST | /{owner}/{name}/branches/{branch}/sync | Merge the parent into the branch. 409 with code: "branch_moved" (retryable) if it received new commits meanwhile. |
POST | /{owner}/{name}/branches/{branch}/close | Close a branch. Idempotent. |
POST | /{owner}/{name}/branches/{branch}/reopen | Reopen a closed branch. |
POST | /{owner}/{name}/branches/{branch}/rename | Temporarily 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.
| Status | Meaning |
|---|---|
200 | Merged. The body has commit_hash (the new commit on main) and merge_parent_hash (the branch tip). |
409 with conflict_paths | The 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#
| Method | Path | Description |
|---|---|---|
POST | /{owner}/{name}/commits/info | Commits 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}/revert | Land 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#
| Method | Path | Description |
|---|---|---|
GET | /orgs | Your organizations. |
POST | /orgs | Create 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}/members | Members and roles. |
POST | /orgs/{slug}/members | Add 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}/groups | Groups, with their kind (public, members or custom), members, maintainers, agents (organization agents) and repos. (/orgs/{slug}/teams is the old name.) |
POST | /orgs/{slug}/groups | Create 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}/access | Who 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/groups | The groups you're in, across your organizations. |
GET | /orgs/{slug}/storage | Storage used against the quota. |
GET | /orgs/{slug}/audit | The 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#
| Method | Path | Description |
|---|---|---|
GET | /orgs/{slug}/agents | List them, each with the groups it's on. |
POST | /orgs/{slug}/agents | Create one: {"name", "display_name"?}. |
PATCH | /orgs/{slug}/agents/{name} | {"disabled": true|false}. |
DELETE | /orgs/{slug}/agents/{name} | Delete it. |
GET | /orgs/{slug}/agents/{name}/keys | Its keys. |
POST | /orgs/{slug}/agents/{name}/keys | Create 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#
| Method | Path | Description |
|---|---|---|
GET | /{owner}/{name}/webhooks | A repo's webhooks. |
POST | /{owner}/{name}/webhooks | Create one: {"url", "secret"?, "events"?: ["push", "merge", …]}, using the names in Webhooks. |
DELETE | /{owner}/{name}/webhooks/{id} | Delete one. |
Payloads and signatures: Webhooks.
Pages#
| Method | Path | Description |
|---|---|---|
GET | /pages/names/{name} | Whether a site name is free: {"name", "available", "reason"}. ?org=SLUG checks it for that organization. |
GET | /{owner}/{name}/pages/sites | The repo's sites: {"sites": [...]}. |
POST | /{owner}/{name}/pages/sites | Create 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}/deployments | Deployment 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}/domains | Add one: {"domain"}. 201 when added. Org owner or admin. |
POST | /{owner}/{name}/pages/sites/{site}/domains/{domain}/verify | Check 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/sites | Every 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.
| Method | Path | Description |
|---|---|---|
GET | /releases | Published CLI versions. |
GET | /releases/latest | The latest version. |
GET | /releases/{version}/{platform} | Download a binary. |
GET | /releases/{version}/{platform}/sha256 | Its SHA-256. |
GET | /releases/{version}/{platform}/minisig | Its 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.