Skip to content

Latest commit

 

History

History
1069 lines (960 loc) · 92.7 KB

http-api.md

File metadata and controls

1069 lines (960 loc) · 92.7 KB

HTTP API Reference (v1, SDK-compatible surface)

The SDK-verified v1 contract, with implementation notes the official spec lacks. Full request/response schemas, including the parallel /api/repos/{repo_name}/... path style, are in ../upstream/openapi.yaml.

  • Base URL: https://api.{org}.code.storage/api/v1. SDKs build {apiBaseUrl}/api/v{version} with version fixed at 1.
  • Auth: every endpoint requires Authorization: Bearer <jwt> (auth spec).
  • Code-Storage-Agent header (informational): code-storage-sdk/<ver> (TypeScript), code-storage-py-sdk/<ver> (Python), code-storage-go-sdk/<ver> (Go).

Conventions

  • Pagination (all list endpoints): request cursor + limit query params (grep: pagination: {cursor, limit} in the body). Response: next_cursor (opaque string, sent only when has_more is true; grep alone sends "" when exhausted) + has_more (bool). Documented default limit 20, max 100. files and files/metadata differ (spec 2026-10-27): with no cursor and no limit (limit=0 counts as no limit), they return every entry with has_more false. With a cursor and no limit, they return pages of 1000 (files, max 5000) and 200 (files/metadata, max 1000). Notes refs default to 20.

  • Errors: {"error": "<unstable human string>"} + status code, with RFC 9457 problem-details fields alongside error: type (about:blank), title (the status text), status, code, detail (same string as error), and instance (the escaped request path the client sent, without the query string; for a /api/repos/{repo_name}/... alias, the alias path; an escaped path of more than 16384 bytes is cut to at most 16384 bytes, never inside a %XX escape, and without …). code is upstream's generic code for the status (bad_request, unauthorized, forbidden, not_found, conflict, unprocessable_entity, rate_limited, internal_error, service_unavailable, …), except for these specific upstream codes: repository_not_found (404: the repository does not exist or the token cannot access it, including a fork's source repository), insufficient_scope (403: the token, or a fork's base_repo.auth.token, lacks a required scope), repo_name_mismatch (400: the create body's repo_name differs from the token's repo claim), branch_not_found (404), ref_not_found (404: a ref, tag, or revision does not resolve; an existing ref or object whose commit git cannot read is a 500), credential_not_found (404), credential_exists (409), repository_deleted (409: DELETE /api/v1/repos/delete on a deleted repository; DELETE /api/repos/{repo_name} answers that case with 404 repository_not_found, because its name lookup skips deleted repositories), ref_guard_failed (409: a failed ref guard, with guard and current_sha: on a merge, details, on a commit write, details, on a notes write, details, and on a branch create, details), authentication_unavailable (403: the key store failed while verifying the token; retry), and route_not_found (404: no API route matches the path; a path that has routes for other methods answers 405 method_not_allowed with Allow). open.storage emits no other specific codes. It does not send repo_claim_missing: a token without a repo claim is org-wide, so a per-repo route refuses it with 403 forbidden, as it refuses repo: "org" (authentication). As upstream advises, treat an unknown code as the generic code for its status. Branch on the status code or code, not on the message. On every status, an error or detail of more than 16384 bytes, and an invalid_params name of more than 16384 bytes, is cut at a character boundary and ends with …, so that a large value in a request is not repeated whole in the answer. The limit counts the bytes of the text as the server holds it, before JSON escapes them, so a text with invalid UTF-8 or with bytes that JSON escapes takes more bytes in the answer. A text that has up to 16384 bytes is not cut, and the bytes of a message that holds request text count with the rest of the message. The same cut applies to the result.message of a commit write (commit-pack, diff-commit and restore-commit), which can repeat a content_id, a mode or a path, and to the error text of the git smart HTTP and Git LFS routes (error on a git route, message on an LFS route), which can repeat the issuer of a token. A 400 for a request body can also carry invalid_params ([{name, reason}], as upstream's ValidationProblemDetails): name is the dotted wire path of the invalid field, and reason is the rule its value breaks. open.storage sends it when a body field has the wrong JSON type (for example {"name":"default_branch","reason":"must be a string"}; nested fields such as base_repo.auth.token and array elements such as paths.0 too), when a strictly decoded body has an unknown, duplicate, or null member, or a member that must be an object, and when a body field fails a check of its own: a required field, an allowed value, a range, or a name format (for example {"name":"limits.max_lines","reason":"must be between 1 and 2000"}). It leaves the member out when it cannot name the fields: an unreadable or empty body, a JSON syntax error, a body that is not an object, an empty member name, unknown fields on the other bodies, rules across fields (such as base_repo and upstream together), and query parameters. For a body with one problem, detail is the message of that problem. For a request body that does not decode, detail never holds text of the JSON decoder, which names Go types. It states a field of the wrong JSON type as name reason, as upstream's example does (default_branch must be a string), and a body that is not valid JSON, or whose top-level value has the wrong type, as invalid JSON body. Three cases keep their own message. The two strictly decoded routes answer with invalid JSON body: and the problems that their member check found: body must be a JSON object, or one or more of unknown field "x", duplicate field "x", x must not be null and x must be a JSON object. restore-commit answers every body that does not decode with body must be {"metadata": {...}}. The upstream member, the copy form of base_repo and a branch create without target_branch refuse an unknown member, put it in detail (invalid upstream: unknown field "branch") and name no invalid_params item. A member name of more than 256 bytes is cut there to its first 256 bytes or fewer, at a character, and ends with … and its length in bytes, all counted in the decoded name (an escape counts as the character it stands for, and a byte that is not UTF-8 as the 3 bytes of U+FFFD): unknown field "xx…" (1000000 bytes). A frame of a commit-pack or diff-commit stream that has a field of the wrong type answers in the same way, in the message of its result: malformed NDJSON frame: metadata.target_branch must be a string. A body with several invalid fields gets one item for each of them, as upstream says (invalid_params "names each invalid field"). The items follow the order of the route's request body in this document, array elements by index, and a field appears once. detail then holds the message of each problem, joined by ; (a problem whose fields all appear in earlier problems adds no message). One answer holds at most 100 items, and detail ends with ; and N more when it leaves some out (not for fields of the wrong type, see below): N counts what it leaves out, one for each item and one for each problem that names no field. The cut of a long detail above can remove that ending or cut it short, and then detail ends with …. A check that needs the repository's state (for example, that a merge creates a commit and so needs an author) runs after the checks of the body, except where this paragraph or the notes on POST /repos below say otherwise. A strictly decoded body (POST /api/repos/{repo_name}/notes/append and POST /api/repos/{repo_name}/upstream/pull) is checked for its members first: the answer names each member that is unknown, repeated or null, or that must be an object and is not (an empty member name adds its message and names no field), and none of the other problems. The members of the route's request body come first, in its order in this document (the problem of an object member before the problems of the members inside it), then the unknown members in the order of the request. A member that the request repeats is named once, for its first problem. The copies of an author object that the request repeats are one object: each copy is checked for its own members (a name that one copy holds twice is repeated), and a bad member of any copy is named once, in the order above. Two members with one dotted path (an unknown member called author.name, and the name of an author object) give one item with both messages, or with one message when they say the same (an unknown member called author., and an empty member name in author). When the check reaches a JSON syntax error or trailing data, the answer names the members that it found before that point, and when there are none it is body must be a JSON object. An answer that names more than one member cuts each unknown member name, which is request text, at 32 bytes and ends it with …. Such an answer names at most 100 fields: one item each in invalid_params, and in error and in detail at most two messages each (for an unknown name in author sent again at the top level as author.<name>). JSON escapes each byte of a cut name to at most six bytes, so the answer has at most 105,203 bytes and the request path in instance. Two unknown names that are the same in their first 32 bytes give one item, for the first of them, and and N more counts the others, so that a name appears once in invalid_params. The body and author each keep their first 100 unknown member names, and and N more counts the others. N counts each member that the answer leaves out once: a member that the request repeats, or that has the dotted path of a member named or counted already, adds nothing. Past the 100 names of an object the count compares 64-bit hashes of the names, so two of them count as one in about one body of 1 MiB in a billion. An answer that names one unknown member cuts a name of more than 256 bytes as the other bodies above do, to its first 256 bytes or fewer at a character, and ends it with …: error and detail add the length in bytes of the member name, without author. (unknown field "author.xx…" (1000000 bytes)), and the invalid_params name ends with … only, as at 32 bytes. Such an answer has at most 4,923 bytes and the request path in instance. The other checks run only when the members are fine, and then the decoder of a strictly decoded body names only the first field of the wrong type ({"note":1,"object_ref":2} names note). POST /api/repos/{repo_name}/upstream/pull takes {ref?, after?} and works the same way. The pull-upstream routes that are not strict, POST /repos/pull-upstream and its deprecated path form, name both ref and after when both have the wrong type. On every other route that decodes its body as one JSON object, when the JSON decoder finds fields of the wrong type, the answer names each of them, in the order of the body (array elements by index, nested fields by their dotted path), and none of the other problems: the other checks run only when every field has its right type. A body with fields of the wrong type and fields that fail a check of their own names the wrong-type fields only. The answer names up to 100 wrong-type fields, within a work bound: the server decodes the body once more for each field it names, and stops when the decodes add up to 256 KiB. So a body of 2 KiB can name 100 fields, a body of 10 KiB about 25, and a body of more than 128 KiB only the first. The server neither names nor counts the other wrong-type fields, so detail does not end with and N more for them. A field that stays raw for a check of its own (the expected_source_sha of a merge, the target_branch of a branch create) is checked with the others. A check of the store (a credential password that starts with enc:) runs after the lookups of the route, so a missing repository or credential is 404 first. When another field of the body is invalid, the answer is 400 and names the password with the other fields. The credential routes that name the repository or credential in the path (/repos/{repo_name}/git-credentials and /repos/{repo_name}/git-credentials/{git_credential_id}) look that one up before they read the body, so on them a missing one is 404 even when the body is invalid. The merge, branch, tag and note routes look up the repository before they read the body in the same way, and so does every route on the /api/repos/{repo_name}/... path style. A grep pagination.cursor that does not decode is named with the other invalid fields when the body has any. Alone, it keeps its place after the lookup of the repository, so a missing repository is 404 first. A grep query.pattern that git refuses is found when git runs the search, after the checks of the body and the lookups of the repository and the ref, so it is named alone and a missing repository or ref is 404 first. POST /repos/merge, POST /repos/branches/create, POST /repos/tags, POST /repos, POST /repos/grep, POST /repos/archive, POST /repos/notes, DELETE /repos/notes, POST /api/repos/{repo_name}/notes/append (when its members and types are fine), POST and PUT on /repos/git-credentials and on /repos/{repo_name}/git-credentials, and PUT /repos/{repo_name}/git-credentials/{git_credential_id} give a body with several invalid fields one item for each of them. A DELETE /repos/notes problem with a query parameter, or with a missing or empty object_ref, adds its message to detail and names no field. PATCH /repo, the pull-upstream routes, DELETE /repos/branches, DELETE /repos/tags and DELETE /repos/git-credentials check one body field each (default_branch, ref, target_branch or its alias name, name, id), so they name that field (DELETE /repos/branches for a name that comes from the body: an ephemeral query parameter that is not valid answers first and names no field). The commit write routes (commit-pack, diff-commit, restore-commit) answer with upstream's CommitWriteResponse or ProblemDetails, which have no invalid_params, and the webhook routes and push-upstream are not part of upstream's API. A check on these routes can hide the checks after it. Every route that decodes its body as one JSON object names each field of the wrong type, as above, with these exceptions: the two strictly decoded bodies (POST .../notes/append and POST .../upstream/pull) name each bad member, or else the first field of the wrong type, the upstream member of POST /repos names the first bad member or the first field of the wrong type, and commit-pack, diff-commit and restore-commit follow their own rules. POST /repos decodes upstream and base_repo on their own (see its body below), and only when the fields of the body itself (repo_name, default_branch) have the right types: {"default_branch":7,"base_repo":{"owner":1}} names only default_branch. When those fields are fine, a body with several fields of the wrong type inside base_repo names each of them. These bodies have Content-Type: application/problem+json, the type upstream documents for problem details, whatever the request's Accept header says. Before #352 item 5 they were application/json: SDK 1.17.1 Go and TypeScript clients parse error JSON only for application/json, so they now show the raw body as the error message. SDK 0.1.0 (Go, Python, TypeScript) reads the body whatever the type. Result envelopes and success bodies stay application/json. status is a JSON number, as in upstream's bodies: decode the body into a struct or a map of arbitrary values, not a string-only map (such as Go's map[string]string). Every failure on every route uses the error body above, except where upstream documents another body (#352 item 3): commit-pack, diff-commit and restore-commit return the richer result envelope on the statuses that the streaming protocols list, a merge 409 for file conflicts returns upstream's MergeConflict (merge), and the 409 for a stale guard on a commit write or a notes write keeps its result envelope and adds the problem members (commit writes, notes). The commit-write result is upstream's RefUpdateResult: it has every member that the schema requires, with empty strings where there is no value: target_branch, the deprecated branch (the same value), old_sha, new_sha, success and status. A failure envelope sends commit: null, except a lost CAS on commit-pack and diff-commit. Before #665, result had no target_branch, most failures left out empty members, and failure envelopes sent no commit. A merge 409 for a failed guard (a stale expected_target_sha, or a source branch that no longer contains expected_source_sha) uses the error body above with code ref_guard_failed (details).

  • Throttling: every 429 (the gateway rate limiter and transient busy/backpressure answers) carries:

    • Retry-After (delay-seconds), which takes precedence over the RateLimit window;
    • the IETF RateLimit service-limit field, "default";r=0;t=<retry-after-secs> (current draft-ietf-httpapi-ratelimit-headers shape).

    No RateLimit-Policy is advertised.

  • Guard SHAs (expected_target_sha, expected_head_sha, expected_notes_ref_sha, expected_ref_sha, and the deprecated restore target_commit_sha) take a full 40-hex SHA in either case.

  • Booleans in query strings are literal "true" / "false".

  • Repeated params: path may repeat on diff endpoints; range may repeat on blame.

  • Paths are literal: a path param names a file or directory. Wildcards (*, ?, [) and git pathspec magic (:(...)) match only a path of that name.

  • Paths stay in the repository: on every read endpoint, a path param or grep paths entry that starts with /, or whose .. climbs above the root, is 400, and so is a path with a NUL byte. The files listings and grep check the path without its trailing /: there / alone names the root of the listing, and matches no file in grep.

  • Values that git takes as one argument must fit what Linux lets a program take as one argument: 128 KiB (131,072 bytes) with its terminating NUL, so at most 131,071 bytes with what the server puts around the value. A longer value answers 400 before git starts, on every platform: a path param or grep paths entry over 131,060 bytes (git gets it at most as :(literal)<path>/; the files listings check it without its trailing /), and a blame range or grep query.pattern over 131,071 bytes. The message names the field and its limit, and grep names the field in invalid_params. The limits on idents are with the commit writes.

  • Lists of such values have a limit for all their entries together. Linux limits all arguments and environment entries of one program together, their pointers included: a quarter of the server's stack limit, at most 6 MiB (2 MiB with the usual 8 MiB stack limit), and 128 KiB (131,072 bytes) for a stack limit from 144 KiB to 512 KiB (measured with 4 KiB pages). A smaller stack limit holds less. macOS allows 1 MiB. So the grep paths, the path params of a diff, and the blame range params may hold at most 65,536 bytes together, half of those 128 KiB, where each entry counts its length plus 32 bytes (what git gets around it: :(literal) or -L, the terminating NULs and the argument pointers). The other half is for the server's environment, which git inherits, and git's own arguments. A longer list answers 400 before git starts, once each of its entries is valid, so one entry over 65,504 bytes already answers 400 although its own limit is higher. The message names the list and the limit (invalid paths (want at most 65536 bytes for all entries, each counting 32 more); path params and range params on the query routes), and grep names paths in invalid_params. These limits do not make every request fit. Values that each fit can still pass the total, and that answer is a 500: a single value near its own limit with a stack limit of about 512 KiB or less, a value over about 64 KiB next to a list near the budget with a stack limit below about 1 MiB, or a large server environment. git also needs stack of its own: with a stack limit below about 176 KiB it can start and then crash, and that answer is a 422. Below that, even a list within the budget can fail with a 422 or a 500.

  • Path encoding: a git tree entry name can hold any byte except NUL and /, but JSON strings hold Unicode text. A response path that is not valid UTF-8 comes back twice. The path field holds one U+FFFD per invalid byte, and a sibling field <field>_base64 holds the raw bytes as standard base64 (RFC 4648 section 4, with padding). The sibling is absent when the path is valid UTF-8, so a repository with only valid names gets responses with no new key. Read the sibling, not the listed path: two names can list as the same path (a<0xff>b and a<0xfe>b both list as a\ufffdb), and the listed U+FFFD form can also be a different file whose valid UTF-8 name holds a real U+FFFD (a\ufffdb, which has no sibling). A list field gets a list sibling of the same length and order, present when any element is not valid UTF-8, and it holds the base64 of every element. The siblings are:

    • files: entries[].path_base64, and paths_base64 next to paths. Both paths and paths_base64 hold only the blob entries.
    • files/metadata: files[].path_base64.
    • diff and branches/diff: path_base64 and old_path_base64 in files[] and filtered_files[].
    • blame: path_base64, and original_path_base64 in lines[].
    • grep: path_base64 in matches[].

    The merge conflict paths (conflict_paths in the 409 body and the merge preview fields) still list U+FFFD only. To read a file by the name in a sibling, send its raw bytes percent-encoded in the path query parameter, for example file?path=a%FFb. file, files, files/metadata, commits, diff, branches/diff and blame read path byte for byte. An archive (tar member names) or a git clone gives the raw names. A JSON request body cannot hold such a name yet: grep paths and commit-pack file paths cannot name the file, and the archive and grep globs match it only through a wildcard (a?b, a*), which can match other names too. Upstream documents no path encoding, so the siblings are an extension (#587).

  • Paths that are not clean: except on a CONNECT request, a path that holds //, /./ or /../, or ends in /. or /.., gets a 307 to the clean path, and an absolute request target with no path (http://host?q) gets a 307 to /. /api gets a 307 to /api/. Location keeps the query string, and a GET also gets a short HTML body that links to it. When that Location would be longer than 16384 bytes (also for /api with a long query), the server answers 404 instead of the redirect: the route_not_found problem body (with instance cut as above) when the Location starts with /api/, else the git surface's {"error":"not a smart-http path"} (a Location of /healthz too). Send clean paths.

  • No client retries: no SDK retries; every error surfaces immediately. Python client-side timeouts: 30s default, 60s diff/grep, 180s branch-create/merge/merge-preview/commit/tag/restore-commit.

Endpoint catalog

Organization metadata (org:read)

GET /api/meta — absolute path, no /v1, and no /api/v1/meta alias.

  • Auth: org-scoped token (repo: "org", or no repo claim) with org:read for the served organization.
  • Rate limit: the ordinary pre-auth limiter.
  • Response: 200 with this exact shape:
{"ips":{"api":[],"git":[]},"provider":{"name":"","region":""}}

The arrays are empty because open.storage publishes no ingress CIDRs; provider and region are empty because it does not determine deployment location. These are the upstream contract's "unpublished/unavailable" values.

Warning

Empty arrays are not proof that ingress does not exist, nor a populated firewall allowlist. Get ingress ranges from your deployment operator before configuring a firewall.

Implements the upstream contract as documented on September 21, 2026; this says nothing about the endpoint's rollout status on upstream clusters.

Repository lifecycle (repo:write / org:read)

Method & path Scope Notes
POST /repos repo:write (repo=new id) Optional body {repo_name?, default_branch?, upstream?, base_repo?} (details below). → {repo_id, repo_name, http_url, message}. 201 = created; 200 = the name holds a finished repo the request matches; 409 = another live repo holds the name; 404 = a deleted repo holds the name; 503 = a create of the name is not finished (below).
GET /repos org:read (repo="org" or no repo) Query cursor, limit, q, prefix. q is a case-insensitive substring of repo url, and prefix a case-insensitive start of it, both trimmed (empty = no filter). With prefix set, q matches only the rest of url after the prefix: prefix=pierre/&q=sdk returns pierre/sdk-documentation, not pierre/example. A q or prefix with a NUL byte or invalid UTF-8 is a 400. A cursor that does not decode, or whose repo ID holds a NUL byte or invalid UTF-8, is a 400 invalid cursor. → {repos: [{repo_id, repo_name, url (deprecated mirror), default_branch, created_at, upstream?, base_repo?}], next_cursor, has_more}
GET /repo git:read (repo from JWT) → {repo_id, repo_name, url (deprecated mirror), default_branch, created_at, upstream?, base_repo?}; 404 → SDK returns null
PATCH /repo repo:write Update the default branch; body {default_branch} (details below). → {repo_id, id (deprecated mirror), repo_name, url (deprecated mirror), default_branch} (no created_at, per the live spec)
DELETE /repos/delete repo:write Soft delete + async cleanup. → {repo_name, repo_id (deprecated mirror), message}; 404 not found; 409 already deleted
GET /api/repo-urls/{repo_id} org:read (repo="org" or no repo) (No /v1 prefix.) Resolve internal id → {repo_id, repo_name, url (deprecated mirror)}; repo_name is the JWT repo claim value. An open.storage extension: upstream removed the route from its spec on 2026-10-05, and open.storage keeps serving it for existing clients
DELETE /repos/base repo:write Detach upstream provider; idempotent (from official docs/OpenAPI, not in SDKs). → 200 {message: "repository detached"}, also when the repo has no upstream. Deprecated upstream (2026-10-05) for DELETE /api/repos/{repo_name}/upstream, which runs the same handler; still served. Every response on both path styles, errors included, carries a Deprecation header
DELETE /api/repos/{repo_name}/upstream repo:write Path style only (spec 2026-10-05). Same handler and scope as DELETE /repos/base. → 200 {message: "repository detached"}. A repo without an upstream → 200 {message: "repository already detached"} (changelog 2026-10-07); the deprecated base routes keep repository detached in that case

POST /repos and GET /repos are also served at the canonical paths POST /api/repos and GET /api/repos (no /v1), which SDK 0.1.0 calls. They run the same handlers with the same scopes, query parameters and responses.

POST /repos body:

  • The JWT repo claim always names the new repository. The optional repo_name (it can contain /) must equal that claim exactly, with no case folding, trimming, or path normalization. A mismatch, including an empty string, returns 400 and creates nothing, for forks too. null or an omitted repo_name changes nothing.
  • default_branch is a branch name or its refs/heads/-qualified spelling, as for PATCH /repo. Any other refs/ name answers 400. A fork stores the name without the refs/heads/ prefix, so refs/heads/trunk becomes trunk.
  • Query default_branch (deprecated upstream) is a fallback, used only when the body omits it.
  • Without a default_branch in the body, in base_repo or in the query, a sync from github takes the GitHub repository's default branch (#599). The create makes no network call, so the repository starts on main, and GET /repo shows main. The first successful sync reads the upstream HEAD and records its branch before it sends repo.sync.succeeded, so GET /repo then shows that branch. If the sync cannot use HEAD (the upstream lookup fails, no HEAD branch is advertised, the branch name is not a valid branch name or starts with refs/, or the fetch did not return that branch), the repository keeps main, the server logs a WARN line, and the next successful sync tries again. Later changes of the GitHub default branch do not move it, and a PATCH /repo ends the wait. Other providers use main. The S3-WAL backend keeps main (deviation). During a rolling upgrade from a release without this rule, two limits apply. A sync that an older worker runs does not adopt the branch, so the repository keeps main until the next sync by an upgraded worker. An older replica's PATCH /repo to main before that sync looks the same as the create's main, so the sync still adopts the GitHub branch.
  • upstream (Git Sync): {provider, owner, name, access?, host?}. It creates a sync link and schedules the first sync, like the deprecated base_repo sync form. Unknown fields → 400.
    • Providers: github, gitlab, bitbucket, gitea, forgejo, codeberg, sr.ht, sourcehut. Any other value → 400. gitea and forgejo need host.
    • access applies to github only (any other provider → 400). Only access: "public" is supported: a public mirror with no stored credential. app, upstream's default when access is omitted, needs a GitHub App installation, which open.storage does not have → 400. To sync a private GitHub repository, use the deprecated base_repo sync form with auth.token.
    • host: a bare hostname[:port], or (open.storage extension) an http(s):// base URL like base_repo.upstream_host. It defaults to the provider's public host.
    • No credential is stored at create. For a private non-GitHub upstream, add one with POST /repos/git-credentials, then call pull-upstream.
    • upstream has no forward_pushes; use the deprecated base_repo sync form to opt in.
  • Setting both upstream and base_repo → 400 (upstream says not to set both and documents no error).
  • A sync create (upstream, or a base_repo sync) with a token whose ref policies carry any op → 403, and nothing is stored or scheduled: the first sync updates refs that those policies cannot police. A plain create with the same token still works.
  • base_repo copy (no provider, no operation): {name, ref?, auth: {token}} copies a repository on this server once, with no link kept. It runs the fork below: auth.token needs git:read on the source, and name must name the repository that token grants (otherwise 403). ref is a branch, tag, or commit SHA; it defaults to the source's default branch. Without a top-level default_branch, the copy's default branch takes the source's default branch name, as a fork does. Unknown fields, and the sync-only fields owner, upstream_host, forward_pushes, and auth.auth_type, → 400.
  • base_repo (deprecated sync and fork form): {provider, owner, name, operation?: "fork", auth?: {token}|{auth_type:"public"}, ref?, sha?, default_branch?, upstream_host?, forward_pushes?}.
  • A sync create whose owner, name or auth.token holds a NUL byte → 400 bad_request with invalid_params naming each such field (base_repo.owner, base_repo.name, base_repo.auth.token, upstream.owner, upstream.name), and nothing is stored. The stored text must be UTF-8 without NUL, as a PostgreSQL text value must; a request body decodes to valid UTF-8 already.
  • A sync create whose values git cannot take → 400 bad_request, and nothing is stored. An upstream URL over 131,070 bytes (https://{host}/{owner}/{name}.git; a host given with http:// or https:// is used as is, without trailing /s) names the owner, the name, and the host field when the body sent one (upstream.host, base_repo.upstream_host), each with the reason must keep the upstream URL at most 131070 bytes (message invalid upstream URL (want at most 131070 bytes)). A base_repo.auth.token over 131,042 bytes names that field (must be at most 131042 bytes). The limits are those of the sync run (Upstream sync, Git credentials).
  • Providers: code, github, gitlab, bitbucket, gitea, forgejo, codeberg, sr.ht, plus generic with upstream_host.
  • A body with several invalid fields, in any create form, gets an invalid_params item for each, in the order default_branch, then the fields of upstream or base_repo as listed above. The create decodes upstream and base_repo on their own, before it checks any field other than repo_name. When that decode fails (a field of the wrong type, an unknown field), the answer is that failure alone: it names each field of the wrong type in base_repo, the first problem of upstream (decoded strictly), and no other check of the body runs. A body that sets both members is decoded as neither. A check that needs another field is skipped when that field is invalid. A missing or unsupported provider skips the checks that need it: the rules that tie access to the provider (only github takes it, and then it must be public) and the default host. The value of access (app or public) and the shape of the host are still checked. An invalid base_repo.operation is the only base_repo problem: the operation decides which base_repo fields apply. One "are required" message names all the empty fields of upstream (provider, owner, name) or of base_repo (owner, name). A base_repo.default_branch is checked only when the body has no default_branch of its own, because a create uses the first of the two. The default_branch query parameter is no body field and names none.
  • A token whose refs claim does not parse is refused with 403 before the fields of the body are checked, after the body has been read. Three problems answer 400 first: a repo claim that holds a NUL byte (checked before the body is read), an unreadable body, and an unknown member in the base_repo of a copy body without upstream that is valid JSON with no field of the wrong type. The checks of state answer after the checks of the body fields: the ref policy (403), the egress check of the upstream host (it looks the host up), and for a copy or fork the source token (403), the source repository (404) and the fork point (400). A default_branch of the body that is the only invalid field answers after the ref policy and before the egress check for a sync create, and after the fork point for a copy or fork. When the host is denied as well, the default_branch answers first. The query parameter default_branch answers after the egress check, so a denied host answers first.
  • forward_pushes: true (default false; open.storage extension) schedules a push-upstream run after every won local push. It also inverts the sync conflict rule: local wins, and inbound syncs never force-rewind local refs. See Upstream sync.

Repeat creates (upstream spec 2026-10-07, #388):

  • A new repository → 201 Repository '<name>' created.
  • A sync create (upstream, or a base_repo sync) of a repo with the same upstream → 200 Repository '<name>' already exists, with the existing repo_id. "Same" means the same stored provider, host, owner and name, and the same forward_pushes. The request's ref, default_branch and auth are ignored, and nothing is scheduled.
  • A plain, copy or fork create of a finished repo without an upstream (a plain repo, a copy, or a fork) → 200 Repository '<name>' already exists, with the existing repo_id. It changes nothing: a copy or fork copies nothing, and it answers before it reads its source, so it succeeds after the source is deleted or its token expired. The request's ref, sha and default_branch are ignored.
  • Any other create of a live name → 409: a different upstream or forward_pushes, a sync create of a repo without an upstream, and a plain, copy or fork create of a repo with an upstream.
  • Known gaps (409 where upstream answers 200): a repo whose create was not tracked answers 409 to every repeat create, because open.storage cannot tell whether that create finished. That covers plain repos created before v0.16.0, sync repos created before v0.18.0, copies and forks created by v0.18.0 or earlier, every S3-WAL repo created by v0.18.0 or earlier (its metadata format v1 stores no create state, #335), and repos that an older server created during a rolling upgrade.
  • A deleted repo keeps its name → 404. Nothing is restored.
  • A sync create whose first sync cannot be scheduled → 503 with Retry-After. The repo, its upstream link and its credential exist, but the create is pending. Either of these finishes it, with the stored link, and needs git:write and a token without ref-policy ops: a compatible repeat create (→ 200), or POST /repos/pull-upstream (→ 202). A repeat create with repo:write only → 403, naming pull-upstream.
  • A copy or fork create is pending from its insert until its default branch is written. Meanwhile a plain, copy or fork create of the name → 503 with Retry-After, and a sync create → 409. When the fork fails, the repo is deleted and the name answers 404. When it succeeds, repeat creates answer as for any complete repo.
  • A pending create can stay pending, and repeat creates then answer the same until DELETE /repos/delete clears the name (it then answers 404):
    • a fork or copy whose server crashed, or whose last step (marking the create complete) failed and answered 500: plain, copy and fork creates → 503;
    • a sync create whose upstream link was removed (DELETE /repos/base) before its first sync was scheduled: the create that finds the link gone → 503 without Retry-After. After that the repo has no link, so a plain, copy or fork create → 503, a sync create → 409, and pull-upstream → 400.

PATCH /repo rules:

  • default_branch is required and non-empty: a plain branch name (qualified to refs/heads/<name> at hydrate time) or its refs/heads/-qualified spelling (stored verbatim).
  • Other ref namespaces (tags/notes) → 400; the default names a branch.
  • The call never creates the branch. It may be unborn; clones then see a dangling HEAD, like a fresh repo.
  • CAS against the previously read value → 409 on a concurrent change.
  • no-push ref policies covering HEAD or the target → 403.
  • Clone HEAD follows on each node's next cache hydrate.

Git credentials (generic HTTPS upstreams)

Method & path Scope Body → Response
POST /repos/git-credentials repo:write (repo=repoId) {repo_id, password, username?} → {id}; 409 = exists
PUT /repos/git-credentials repo:write (repo="org" or no repo) {id, password, username?} → {id, created_at}; 404
DELETE /repos/git-credentials repo:write (repo="org" or no repo) {id} → 200/204; 404

username is optional on create and update, on these routes and on the path-style /repos/{repo_name}/git-credentials routes. Only password is required. The server stores the username exactly as sent. An update that omits it clears the stored one.

A username or password that holds a NUL byte → 400 bad_request with invalid_params naming the field, on every credential route, and nothing is stored. So does one over 131,042 bytes (must be at most 131042 bytes), which the sync run could not hand to git. A credential id that holds a NUL byte, in the body or in the path (also invalid UTF-8 in the path), names no credential → 404 credential_not_found, as an unknown id does.

A stored username is always sent as is. Git sends no credentials when the username is empty, so for a credential with no username the sync worker sends the upstream's per-provider default from upstream's spec of 2026-10-08:

Upstream provider Sent when no username is stored
bitbucket Username x-token-auth, the token as the password
gitlab Username oauth2, the token as the password
gitea, forgejo, codeberg The token as the username, with an empty password (git cannot send a username alone)
github and every other provider Username git, the token as the password

The spec also notes that sr.ht takes no credential over HTTPS. A credential stored for an sr.ht upstream still gets the git default.

Host What to send
Gitea, Forgejo, Codeberg The token as password. The username can be omitted.
GitLab personal, project, group or OAuth token The token as password. The username can be omitted when the provider is gitlab. Otherwise send oauth2.
GitLab deploy token The deploy token's username. CI job tokens use gitlab-ci-token.
Bitbucket access token The token as password. The username can be omitted when the provider is bitbucket. Otherwise send x-token-auth.
Bitbucket app password or API token Your Bitbucket username.
Any other host The username that host expects.

The worker hands the pair to git through a credential helper that reads it from the environment. A stored username or password that contains a carriage return, line feed or NUL fails the sync as a configuration error. So does one over 131,042 bytes, before git gets it: git takes it as one environment entry, such as OPENSTORAGE_ASKPASS_PASSWORD=<password>, which must fit 128 KiB with its terminating NUL. The credential routes and POST /repos refuse such a long value, so only a value stored without that check (before it, or by an older server during an upgrade) reaches this one.

Files & trees (git:read)

Method & path Query/body Response
GET /repos/file path (req), ref, ephemeral, ephemeral_base; headers Range, If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since, If-Range Raw blob stream. Status 200/206/304/412/416. Headers: X-Blob-Sha, X-Last-Commit-Sha, ETag, Last-Modified, Accept-Ranges, Content-Range, Content-Type, Content-Length
HEAD /repos/file same headers only
GET /repos/files ref, ephemeral, path, recursive, cursor, limit {paths: [..], paths_base64?: [..], ref, entries: [{path, path_base64?, type: blob|tree|symlink|submodule, mode}], next_cursor, has_more} — trees have no trailing /; branch on type. Without recursive, with an empty recursive=, or with recursive=true, it lists the contents of every folder under path and no tree entries. recursive=false lists only the direct children of path, folders as tree entries. No cursor and no limit (or limit=0): every entry, or 422 when the listing passes the git output limit. Big trees must page: a recursive call with limit or cursor reads only the entries of its page. With a cursor it reads the folders on the cursor's path and the ones after it, each whole, and none of the folders before it, so a deep cursor costs about what the first page does plus the size of those folders and a request to git for each folder of the page: a cursor inside one folder of a million entries still reads that whole folder, but the folders before it are not read. Because they are not read, a missing or unreadable object there, or a tree nested past git's depth limit, no longer fails a page that the walk answers. A page that this does not suit is read from the start of the listing, as for a first page, and gives the same result, a failure on such an object included: trees with unusual entries, trees nested more than 128 folders deep or past a lower core.maxTreeDepth that git is set to, many folders without files, many small folders, or one very large folder, when the cursor is near the start of the listing (git reads those faster than the walk does), a git that fails on the way, and pages that come out empty. A tree that git stores out of order (one that git fsck rejects as treeNotSorted) can page in git's order and skip entries; git itself cannot look such entries up by path
GET /repos/files/metadata same {files: [{path, path_base64?, mode, size, last_commit_sha, type}], commits: {<sha>: {author, date, message, order}}, ref, next_cursor, has_more}. order is described below the table. message is the subject line only, as in the commits list (Commits). No cursor and no limit (or limit=0): every file. 429 when the files under path have more than 50,000 distinct last commits, also with limit or cursor: a retry gets the same 429 (no Retry-After), so send a narrower path. 404 on unborn branch
POST /repos/archive body {ref?, include_globs?, exclude_globs?, max_blob_size?, archive?: {prefix}} tar.gz stream
POST /repos/grep body {query: {pattern, case_sensitive?}, ref?, ephemeral?, paths?, file_filters?: {include_globs, exclude_globs, extension_filters}, context?: {before, after}, limits?: {max_lines, max_matches_per_file}, pagination?: {cursor, limit}} {query, repo: {ref, commit}, matches: [{path, path_base64?, lines: [{line_number, text, type: "match"|context}]}], next_cursor, has_more}
GET /repos/blame path (req), ref, ephemeral, range (repeatable, git blame -L specs like 1,10), detect_moves {ref, path, path_base64?, commit_sha, lines: [{line_number, commit_sha, original_line_number, original_path, original_path_base64?, previous_commit_sha?, author_name, author_email, author_time, committer_name, committer_email, committer_time, summary}]}

order in files/metadata is the commit's history-order rank relative to the resolved ref: its 0-based position in git rev-list --topo-order <resolved commit>. The ref's own commit is 0, and larger values are older. A commit always ranks higher than every one of its descendants, whatever its author or committer date. Among a folder's files, the one with the smallest order was changed most recently in the ref's history.

order is an absolute position in the ref's history, not a rank within the response. Values can have gaps, and a response contains 0 only when the ref's own commit is the last commit of a listed file. Ranks agree across pages when the requests resolve to the same commit. A branch can move between requests, so pin ref to a commit SHA to page through one snapshot.

Ties between commits that ancestry does not order follow git's topo-order walk, which ignores dates. A commit becomes eligible once all of its children reachable from the ref are ranked, and the most recently eligible commit is ranked next. When ranking a merge makes several of its parents eligible at once, they become eligible in parent order, so the line of history behind the last of them is ranked first. The same history always yields the same ranks.

order comes from the same git rev-list --topo-order walk that finds the last commits (resource limits on git reads), so it costs no extra git subprocess. A 200 response always carries the exact order of every commit; the field is never omitted or estimated.

Branches

Method & path Scope Body/query → Response
GET /repos/branches git:read cursor, limit, ephemeral → {branches: [{cursor, name, head_sha, created_at}], next_cursor, has_more}
GET /repos/branch git:read name (req), ephemeral? → {branch: {name, head_sha, created_at}} — one branch by exact short name (no pagination fields); 404 when absent
POST /repos/branches/create git:write {target_branch?, base_ref?|base_branch?(deprecated), preferred_base?, base_is_ephemeral?, target_is_ephemeral?, force?, expected_target_sha?} → {message, target_branch, target_is_ephemeral, commit_sha?}. See guarded create and move
DELETE /repos/branches git:write Query target_branch, ephemeral?. The deprecated body {target_branch (deprecated alias name), ephemeral?} still works; a query parameter that is present wins over its body field, even when empty → {target_branch, name (deprecated mirror), message, ephemeral}. Refuses default branch (persistent): 409 for the query form, 403 for the body form
GET /repos/branches/diff git:read Deprecated upstream (both path styles); still implemented. Use GET /repos/diff (migration). branch (req), base? (defaults to the repo default branch), ephemeral?, ephemeral_base?, path (repeatable) → {branch, base, merge_base_sha, stats: {files, additions, deletions, changes}, files: [FileDiff], filtered_files}; merge_base_sha is empty when the histories are unrelated (direct base..branch diff)
POST /repos/merge git:write {source_ref (bare branch name or refs/heads form; deprecated alias source_branch), target_branch, strategy: merge|ff_only|ff_prefer, source_is_ephemeral?, target_is_ephemeral?, expected_target_sha?, expected_source_sha?, commit_message? (required with squash), author?, committer?, allow_unrelated_histories?, squash?} → {result: merge_commit|fast_forward|no_op|squash, commit_sha, tree_sha, source: {ref, branch (deprecated mirror), ephemeral, sha}, target: {branch, ephemeral, old_sha, new_sha}, merge_base_sha?, promoted_commits}. File conflicts → 409 MergeConflict {error, conflict_type: merge_conflict, conflict_paths, merge_base_sha?}; a target that moved during the merge → 409 error body, code: conflict (upstream's target_moved reports a failed automatic retry, and open.storage does not retry); an ff_only merge that is not a fast-forward, and unrelated histories without allow_unrelated_histories → 412 error body, code: precondition_failed, as upstream documents. A failed expected_target_sha or expected_source_sha guard → 409 error body, code: ref_guard_failed (details). A squash without commit_message → 400, invalid_params naming commit_message. A merge commit without commit_message gets the message Merge branch '<source>' into <target>, with the branch names of the request (earlier releases wrote Merge <source> into <target>)
GET /repos/merge/preview git:read source_branch, target_branch, source_is_ephemeral?, target_is_ephemeral? (deprecated aliases source_ephemeral/target_ephemeral), include_content?, strategy?: merge|ff_only|ff_prefer (default ff_prefer), squash?, allow_unrelated_histories? → {status: clean|conflicted, result: merge_commit|fast_forward|no_op|squash|rejected, source_branch, target_branch, source_tip_sha, target_tip_sha, merge_base_sha?, conflict_paths, conflicts: [{path, result|base|ours|theirs: {oid?, content?, truncated, binary}}], filtered_conflicts: [{path, reason}]}. Read-only. result is what POST /repos/merge does with the same strategy, squash and allow_unrelated_histories on the current tips: rejected is its 412 for an ff_only merge that is not a fast-forward, and status tells whether the commit that the merge makes has conflicts (no_op, fast_forward and rejected are clean). Unrelated histories without allow_unrelated_histories → 412 error body, code: precondition_failed, as for the merge, except with ff_only: the merge checks ff_only first, so the preview answers rejected. squash with ff_only → 400. The preview decides only that result. It does not check ref policies, author, commit_message or the merge guards, and the tips can move before the merge runs, so a merge after a clean preview can still fail, for example with 403 for a ref policy, 400 for a missing author, or 409 for a failed guard

The API refuses an ephemeral branch named HEAD: branch create, commit writes and merges answer 400 (invalid target_branch) for target_branch: "HEAD" with the ephemeral flag. A persistent branch named HEAD is allowed.

A branch, tag or notes ref name that the API writes (for example in branch create, commit writes, tag writes and default_branch) is at most 255 bytes without its refs/... prefix, and its last /-separated part is at most 250 bytes, so that git can create the ref's .lock file. A longer one answers 400. Branch and tag deletes still take a stored name whose last part is longer, so a ref that an earlier version wrote can be removed. A notes ref that an earlier version wrote cannot be removed over REST (DELETE /repos/notes removes one note): the operator runs openstorage repair-refs.

Ephemeral branches are refs/namespaces/ephemeral/refs/heads/<name> in the base repository. The persistent git remote /{repo}.git hides them: git cannot fetch, list or push them there (namespaces).

Merge guards

A failed guard answers 409 with the error body before any merge work, and nothing changes. The body has code: ref_guard_failed and two more members, as upstream's RefGuardProblemDetails:

  • guard: the request field of the guard that failed, expected_target_sha or expected_source_sha.
  • current_sha: the tip of the guarded branch when the server checked the guard, or 40 zeros when the source branch does not exist. Send it as the guard of the next attempt.

Before #568, the code was conflict, without guard and current_sha.

expected_target_sha (a full 40-hex commit SHA) requires the target branch to still point at that commit. If it does not, the guard fails (detail "expected_target_sha … does not match current tip …"). v0.18.0 and earlier answered 412 precondition_failed with a result object (#532).

expected_source_sha (a full 40-hex commit SHA) makes POST /repos/merge merge that commit instead of the current tip of source_ref. Use it to merge exactly the source_tip_sha that GET /repos/merge/preview returned, even if the source branch moved on since.

  • The source branch must still contain the commit: the commit is the tip or one of its ancestors. Otherwise the guard fails (detail "source branch moved: the source branch does not contain commit …").
  • A source branch that does not exist fails the guard too, with current_sha 40 zeros. Without expected_source_sha, a missing source branch is 404.
  • source.sha in the response is the pinned commit.
  • An explicit null, "" or any value that is not a full SHA is 400.
  • expected_target_sha is checked first, after both branches are looked up. When both guards fail, the body names the target. A missing target branch is 404.

This follows the public OpenAPI of 2026-10-16 (the field) and 2026-10-27 (ref_guard_failed). On 2026-10-27 the cluster OpenAPI still served the older spec (snapshot provenance).

Migrating from branches/diff

Upstream deprecated GET /api/v1/repos/branches/diff and GET /api/repos/{repo_name}/branches/diff in favor of GET /repos/diff (same path styles). open.storage keeps serving branches/diff. To migrate, rename the parameters:

branches/diff diff
branch ref
base base_ref
ephemeral ref_is_ephemeral
ephemeral_base base_is_ephemeral
path path

With base_ref set, diff returns the same three-dot diff (merge_base_sha, stats, files, filtered_files) as branches/diff. The envelope differs: sha and base_sha (resolved commits) replace branch and base (the names you sent).

Default base: branches/diff without base diffs against the repo default branch. diff without base_ref returns the diff of the one commit ref points to. To keep the old behavior, read default_branch from GET /repo and send it as base_ref.

Server-allocated branch names (POST /repos/branches/create, both path styles):

  • Omit target_branch to allocate a new opaque name in the requested target namespace. Use the returned target_branch, commit_sha, and target_is_ephemeral; do not depend on a name format.
  • Each successful call creates a new branch, so retrying after an unknown result can create another branch. Keep the returned name and delete branches you no longer need.
  • force: true requires an explicit, valid target name (otherwise 400). Named-target force and ref-policy checks are unchanged.
  • In open.storage, explicit empty or null targets are 400, not allocation requests.
  • Allocation requests reject unknown fields with 400, so a misspelled target field cannot silently allocate a branch. Named-target requests keep their unknown-field tolerance.
  • Name collisions retry with create-only CAS and never overwrite an existing ref. Exhausting the bounded attempts returns 409. Policy denials and storage errors are not retried.

This follows the public OpenAPI/SDK contract, not demonstrated upstream cluster behavior (contract audit).

Guarded branch create and move

expected_target_sha on POST /repos/branches/create (both path styles) guards the target branch. It applies to the persistent and the ephemeral namespace:

expected_target_sha The request succeeds only when
40 zeros the target branch does not exist. The branch is created at the base.
a full commit SHA (any case) the target branch exists at that commit. The branch moves to the base. Without force the move must be a fast-forward, else 412. With force any move is allowed, subject to the token's ref policies.
omitted, "" or null always: no guard. An existing target without force answers 409 conflict ("branch already exists").
  • A failed guard answers 409 ref_guard_failed with guard: "expected_target_sha" and current_sha, the branch tip or 40 zeros when the branch does not exist. The branch does not change, with or without force.
  • When another writer changes the branch while the request runs, the guard still holds: this request changes the branch only from the guarded tip, and only to the base. A 409 leaves the branch as the other writer left it. A 200 means that the branch was at the base when the server last wrote or read it. It can also answer a request that lost the race to another writer that made the same change: the server then counts that change as this request's, and for a persistent branch a second push webhook and upstream sync poke follow. A lost create counts as won only when a storage error hid the outcome of the write. So a 40-zero guard is not a create-once lock under storage errors: then two requests that create the same branch at the same base can both answer 200.
  • A guarded or forced move of a target that already points at the base answers 200 ("branch updated") without a ref write, so no webhook or upstream sync follows. Ref policies still apply. Without a guard and without force, such a target answers 409 like any existing branch.
  • A value that is not 40 hex digits is 400 (invalid_params names expected_target_sha).
  • Without target_branch, only 40 zeros is accepted (the allocated name is new); any other guard is 400.

This follows the public OpenAPI of 2026-11-10 (5d8e1801), which the cluster OpenAPI did not serve yet (snapshot provenance).

FileDiff = {path, path_base64?, state (raw letter; SDKs normalize A/M/D/R/C/T/U), old_path?, old_path_base64?, raw (unified diff text), bytes, is_eof, additions, deletions}. filtered_files entries omit raw/counts; large files are filtered unless requested via path. Every *_base64? key is present only for a path that is not valid UTF-8 (Path encoding).

Commits

Method & path Scope Notes
GET /repos/commits git:read ref? (deprecated alias branch), cursor?, limit?, ephemeral?, path? → {commits: [CommitInfo], next_cursor, has_more}, newest first; defaults to default branch. Each entry's message is the subject line only (below the table)
GET /repos/commit git:read ref (req; deprecated alias sha; branch name, tag, short or full SHA) → {commit: CommitInfo & {signature?, payload?}} (signed commits: armored sig + exact signed payload bytes)
GET /repos/diff git:read ref (req; deprecated alias sha), base_ref? (deprecated alias baseSha), ref_is_ephemeral?, base_is_ephemeral?, git_apply_compatible? (deprecated alias gitApplyCompatible), path (repeatable) → {sha, base_sha, merge_base_sha, stats, files: [FileDiff], filtered_files}. base_sha is the commit base_ref resolved to, empty for a single-commit diff. On alias conflict the current name wins
POST /repos/commit-pack git:write NDJSON stream — see the streaming protocols. A file mode of 644 or 100664 is stored as 100644, and 755 or 100775 as 100755. A file without operation is an upsert, and a delete needs no content_id
POST /repos/diff-commit git:write NDJSON stream — see the streaming protocols
POST /repos/restore-commit git:write JSON {metadata: {target_branch, base_ref (branch, tag, or commit; deprecated alias target_commit_sha, the 40-hex id of a commit or of an annotated tag of one), author, commit_message?, expected_target_sha? (deprecated alias expected_head_sha), committer?}} → commit ack (streaming protocols). Creates a new commit restoring old tree (history preserved). A refs/... base_ref resolves verbatim. Any other name tries a branch, then a tag (annotated tags peel). Then base_ref resolves as a full or abbreviated SHA (a full SHA may be uppercase). It always resolves outside the ephemeral namespace. Extensions: target_is_ephemeral? (deprecated alias ephemeral) restores a branch in the ephemeral namespace. base_is_ephemeral (deprecated alias ephemeral_base) is accepted and ignored
POST /repos/reset-commits git:write In OpenAPI only (not in SDKs): NDJSON metadata stream; same restore-commit family

CommitInfo = {sha, parent_shas[], message, author_name, author_email, committer_name, committer_email, date (RFC3339), committer_date (RFC3339)}. date is the author timestamp and committer_date the committer timestamp, as in upstream's spec of 2026-10-08. A rebase or cherry-pick changes only committer_date. Before that spec, date carried the committer timestamp.

A push can hold a commit whose author or committer line git cannot parse, because the server runs no fsck on a push. Reads of such a commit answer 200 with git's own fallbacks:

  • If git cannot split the line into a name and an <email> (for example, a NUL byte in the name), author_name and author_email (or the committer pair) are "", as git's %an and %ae print them. Blame sends git blame's (unknown) instead. The date is 1970-01-01T00:00:00Z. git log shows neither the person nor a date for such a line.
  • If git cannot read the date (no date, a date that is not a number, no time zone), date (or committer_date) is 1970-01-01T00:00:00Z. git log shows the same epoch for such a line.
  • A date after 9999-12-31T23:59:59Z also gives 1970-01-01T00:00:00Z, because RFC 3339 cannot write it.

The files/metadata commits map and blame's author_time and committer_time follow the same rules. Blame keeps the line's time zone offset, except an offset that RFC 3339 cannot write (24 hours or more, or 60 minutes or more) or one that moves the local date past the year 9999. Then it sends UTC.

GET /repos/commit sends the full message, with trailing newlines removed. GET /repos/commits and the files/metadata commits map send only the subject line, as in upstream's docs spec of 2026-10-27: the first paragraph of the message as one line, without the body and the trailers. This is git's %s: blank lines before the first paragraph are skipped, a whitespace-only line ends it, its lines are joined with one space after their trailing whitespace is removed, and an empty message gives "". A continuation line keeps its leading whitespace, so "subj\n next" gives subj next. Before that spec, both carried the full message.

Commit messages and idents

A NUL byte in a commit_message, or in the name or email of an author or committer, answers 400 on commit-pack, diff-commit, restore-commit and POST /repos/merge. A NUL in the author of POST /repos/notes (also the deprecated body of DELETE /repos/notes) answers 400 too. git refuses a NUL in a commit message, and takes an ident as an environment value, which cannot hold a NUL. So does a name or email over 131,051 bytes: git gets it as one environment entry such as GIT_COMMITTER_EMAIL=<email>, which must fit 128 KiB with its terminating NUL. The message names the field and the limit. A commit message goes to git on standard input, so it has no such limit: the request limits bound it, 1 MiB for the body of merge and restore-commit and 8 MiB for one metadata line of commit-pack and diff-commit. merge and notes name each such field in invalid_params. commit-pack and diff-commit answer the result envelope with status invalid, as for their other invalid metadata, and restore-commit answers the plain problem body. A restore-commit without a commit_message gets a default message that names the target, and a NUL in the target is a problem of the target, not of the message. See wire compatibility.

Commit write guards

commit-pack, diff-commit and restore-commit take expected_target_sha (deprecated alias expected_head_sha, a full 40-hex commit SHA): the target branch must still point at that commit. When the target branch does not exist and a commit-pack or diff-commit names base_branch, the guard compares with the tip of base_branch. When the guard fails, no ref moves, and the answer is 409 with the result envelope plus the problem members of the error body, as upstream's CommitWriteRefGuardProblemDetails and RestoreCommitRefGuardProblemDetails:

  • code: ref_guard_failed (detail "expected_target_sha … does not match current tip …").
  • guard: expected_target_sha, also when the request sent expected_head_sha.
  • current_sha: the commit the guard was checked against, that is the tip of the target branch, or the tip of base_branch for a new branch. Send it as the guard of the next attempt.
  • result has every member of upstream's RefUpdateResult: target_branch and branch name the target branch, new_sha is empty, success is false, and status is conflict. old_sha is the tip of the target branch, so it repeats current_sha, except on a new branch, where it is 40 zeros. commit is null, as upstream's schema descriptions say.

The content type is application/problem+json, as for every body with the problem members. A CAS race lost at publish time is a different 409, an application/json result envelope without the problem members (streaming protocols). Before #647, a failed guard answered 412 precondition_failed with the result envelope only.

Tags

Method & path Scope Body/query
GET /repos/tags git:read cursor, limit → {tags: [{cursor, name, sha}], next_cursor, has_more} — lexical order; sha dereferenced to commit
GET /repos/tag git:read name (req) → {tag: {name, sha}} — one tag by exact short name, sha dereferenced to commit; 404 when absent
POST /repos/tags git:write {name, ref (deprecated alias target)} → {name, sha, message} — lightweight only; name must not start with refs/
DELETE /repos/tags git:read+git:write {name} → {name, message} — resolves stored ref for lightweight & annotated
DELETE /api/repos/{repo_name}/tags/{tag_name} git:read+git:write Path style only (the form SDK 0.1.0 calls). Same handler, scopes and responses as DELETE /repos/tags, with the tag name from the path (a / in it is sent as %2F). A request body is not read

Notes

Method & path Scope Body/query
GET /repos/notes git:read object_ref (req; deprecated alias sha), notes_ref? (deprecated alias ref) → {sha, note, ref_sha}
POST /repos/notes git:write {object_ref (deprecated alias sha), action: "add"|"append" (deprecated upstream), note, notes_ref? (deprecated alias ref), expected_notes_ref_sha? (deprecated alias expected_ref_sha), author?} → {sha, notes_ref, target_ref (deprecated mirror), base_commit?, new_ref_sha, result: {success, status, message?}}. add fails if note exists; append creates or appends
POST /api/repos/{repo_name}/notes/append git:write Path style only (spec 2026-10-05). {object_ref (deprecated alias sha), note, notes_ref? (deprecated alias ref), expected_notes_ref_sha? (deprecated alias expected_ref_sha), author?}, decoded strictly: action, any unknown field, or a null → 400. Appends, or creates the note when the object has none → 201 with the same envelope. A stale guard → 409 ref_guard_failed and nothing is appended
DELETE /repos/notes git:write Query object_ref, notes_ref?, expected_notes_ref_sha?. The deprecated body {object_ref (deprecated alias sha), notes_ref?, expected_notes_ref_sha?, author?} still works; a query parameter that is present wins over its body field, even when empty → same envelope
GET /repos/notes/refs git:read prefix? (default refs/notes/), cursor, limit → {refs: [{cursor, ref, sha}], prefix, next_cursor, has_more}. A bare prefix goes under refs/notes/. A prefix that starts with refs/ but not with refs/notes/ is a 400
  • Default notes ref: refs/notes/commits. Bare names resolve to refs/notes/<name>.
  • object_ref: a full object SHA (commit, tree, blob, or annotated tag), or a branch, tag, full ref name (refs/...), or short SHA (at least 4 lowercase hex digits) that resolves to a commit. Other revisions, such as main~1, main^ or the symbolic HEAD, do not resolve here, though upstream documents them for notes writes (deviation). Unresolvable → 404.
  • Responses echo the resolved object id in sha.
  • A stale expected_notes_ref_sha → 409 on every form: POST .../notes, POST .../notes/append, and DELETE .../notes with the guard in the query or in the deprecated body. Before #647, the POST .../notes and DELETE body forms answered 412 precondition_failed with the note envelope and no problem members.
  • Every other note-write failure is the plain error body (no note envelope), as upstream documents. A notes ref that moves while the write runs (a lost CAS) → 409 conflict.
  • The stale-guard 409 keeps the note envelope (result.status conflict) and adds the problem members of the error body: code: ref_guard_failed, guard: expected_notes_ref_sha (also when the request sent the deprecated expected_ref_sha), and current_sha, the notes ref's tip or 40 zeros when it does not exist. new_ref_sha repeats current_sha. Its content type is application/problem+json, as for every body with the problem members. Before #568, the body had no problem members.

Upstream sync

Method & path Scope Notes
POST /repos/pull-upstream git:write Optional body {ref?, after?} → 202 Accepted (async). Sync-linked repos (upstream or base_repo sync) only. Deprecated upstream (2026-10-05) for POST /api/repos/{repo_name}/upstream/pull; still served. Every response on both path styles, errors included, carries a Deprecation header. Both body fields are accepted and ignored: every pull syncs all branches and tags of the upstream. A ref that holds a NUL byte is still a 400 on every backend, because PostgreSQL's job queue stores it as jsonb, which cannot hold a NUL. Upstream deprecated the body on 2026-10-08
POST /api/repos/{repo_name}/upstream/pull git:write Path style only (spec 2026-10-05). Same handler, scope, ref-policy check and responses as POST /repos/pull-upstream. The optional, deprecated body {ref?, after?} is decoded strictly: an unknown field or a null → 400. Its fields are ignored
POST /repos/push-upstream git:write + git:read {force?} → 202 Accepted (async). Sync-linked repos only. open.storage extension

A pull or push run whose upstream URL (https://{host}/{owner}/{name}.git, or the host as given when it has a scheme, without trailing /s) is over 131,070 bytes fails as repository configuration error before git starts. git gets the URL as one argument, and its HTTP transport hands it on with a / added, which must fit 128 KiB with its terminating NUL. POST /repos refuses such a link with 400 (Repository lifecycle), so only a link stored without that check (before it, or by an older server during an upgrade) reaches this one. A stored credential that git cannot take fails the same way (Git credentials). Values that each fit can still pass the total limit together: one git start can carry the URL twice and both credential entries, about 512 KiB at the limits, so a server with a stack limit of 2 MiB or less can fail such a run as a failed fetch or push.

Deprecation header

Every response of the four deprecated routes carries Deprecation: @1791331200: POST /api/v1/repos/pull-upstream, POST /api/repos/{repo_name}/pull-upstream, DELETE /api/v1/repos/base and DELETE /api/repos/{repo_name}/base. Error responses carry it too: 400, 401, 403, 404, 429 and 500. The replacements (POST .../upstream/pull, DELETE .../upstream) and push-upstream send no such header.

The value is an RFC 9745 date: deprecated since 2026-10-07T00:00:00Z, the date of upstream's changelog entry that announced the header. Upstream documents no value and no Link or Sunset header, so open.storage sends no Link or Sunset (deviation).

Both triggers:

  • A 202 is never dropped. A request that arrives during an in-flight sync run coalesces into one follow-up run, so some run observes upstream as of the request or later.
  • Egress is policy-guarded at dial time; see Egress policy below.

push-upstream (upstream forwards implicitly; see wire compatibility):

  • Publishes local refs/heads/* and refs/tags/* to the upstream with the stored credential. Ref deletions are not propagated.
  • Requires both scopes: the run exports every local head and tag, so a write-only token must not publish content it cannot clone.
  • Non-force by default. A ref the upstream refuses (non-fast-forward) fails the run, with per-ref reasons in the repo.push_upstream.failed event's rejected_refs. force: true opts into +refs, and survives coalescing (a forced request is never downgraded).
  • The push is atomic: one refused ref fails the whole batch and leaves the upstream untouched.
  • An unreachable upstream retries with exponential backoff (1–16 min, 5 attempts). Auth, config, and rejection failures do not retry.
  • A successful run schedules one follow-up inbound sync, so a pull that raced the forward cannot strand a stale local snapshot.
  • Private/special destinations are denied (permanent repository configuration error failure) unless OPENSTORAGE_SYNC_PUSH_ALLOW_PRIVATE opts internal forges in.

Events and cancellation: outbound runs emit repo.push_upstream.* events (webhooks); inbound runs emit repo.sync.*. An outbound run emits repo.push_upstream.started once its loopback fetch of this server has the snapshot it forwards, before it pushes to the upstream. A run that fails before or at that fetch emits repo.push_upstream.started right before its repo.push_upstream.failed. DELETE /repos/base silently cancels in-flight runs in both directions. A run that server shutdown cancels also ends without a terminal event: its request stays pending, and a later run (the next server process, or on PostgreSQL another replica) runs it with a new repo.sync.started (outbound: repo.push_upstream.started). An outbound run emits no event when a write in progress (a git push, or on SQLite and S3WAL a ref write through this API) holds a ref that the run would otherwise forward at an older value: the request stays pending, and a new run starts a few seconds later.

Ref policies fail closed: any policy op denies pull-upstream, push-upstream, and a sync create at POST /repos (403). The same gate covers the sync that a ref write schedules. A REST write or git push from a token that carries any ref-policy op does not trigger the inbound sync, since the sync force-updates every head and tag from the upstream, not just the refs that token may touch. For forward_pushes repos, such a write, or one from a token that lacks git:read, does not trigger the forward, since the forward publishes every head and tag. The write stays local. Nothing polls the upstream, so the repository converges only on the next authorized trigger: a write, pull-upstream, or push-upstream that passes these gates.

Ref writes that forward: on SQLite and S3WAL, a ref write through this API that triggers the forward (a forward_pushes repo and a token that passes the gates above) holds the ref and records the forward request before it changes the ref. It waits up to 10 seconds for a git push or another such write that holds the same ref or a directory/file relative of it (refs/heads/a and refs/heads/a/b), then fails with 503 and Retry-After: 1. When the read of the repository's upstream link fails, a ref write from a token that passes the gates above fails with a plain 500 on any repository, forwarding or not: the write reads the link before it knows whether the repository forwards. A write to the ephemeral namespace is the exception: it takes no hold and reads no link. Any other failure to take the hold, or a failed write of the forward request, also fails the write with a plain 500. In each case the ref stays unchanged. A write that loses its compare-and-swap (409) has recorded its request already, so the repository gets one forward run with nothing new to push.

Egress policy

Per ADR-45, upstream_host is caller-linked data. Every http(s) sync transfer in either direction dials through a vetting proxy that applies the webhook delivery destination policy. That covers pull-upstream fetches (including the first sync at POST /repos and freshness pokes) and push-upstream forwards.

  • Governed by OPENSTORAGE_SYNC_ALLOW_PRIVATE. Transitional default: pulls allow private upstreams, pushes deny.
  • A denied pull destination fails the run as repository configuration error; a denied push destination fails the same way.
  • POST /repos with upstream or a base_repo sync also rejects, with 400, an upstream.host or upstream_host the pull policy denies. This registration check is a courtesy; dial time is authoritative.

Caution

Mixed-fleet prerequisite: finish the rolling upgrade of every replica to a build with this feature before creating repositories with forward_pushes: true. The forward reroute and local-wins pull rule are replica-local code. A pre-feature replica that accepts a push on such a repository still schedules the legacy inbound force-mirror ("upstream wins"), which can rewind the just-accepted write, and schedules no forward. Repositories without the flag are unaffected: old and new replicas agree on pull-only behavior. This ordering is documentation-enforced, like the other upgrade orderings.

Resource limits on git reads

The git:read endpoints answer from git subprocesses over a cache repository. Anyone who can push shapes that repository, so every git subprocess that reads repository data for these endpoints runs under the limits below (#313). Each limit takes effect before the work it bounds.

Limit Value When it is exceeded
Concurrency At most 8 requests per server process run git at once, and file and archive downloads have a separate pool of 8. One repository can hold at most 2 slots of each pool, whether its tokens name it by URL or by ID. Cache maintenance (commit-graph refreshes) can hold up to 2 of the 8 JSON slots at a time, counted in the refreshed repository's share, so JSON reads always keep at least 6. A request takes its slot at its first git subprocess, including single-object reads, and keeps it until the server has finished writing its response to the network connection. A request waits up to 1 second for a slot. 503 with Retry-After: 1. git is not started.
Time Every git subprocess of a request must finish within 30 seconds of the request's first one. This is wall-clock time, so the server's own work between subprocesses counts too. archive gets 10 minutes, because it streams at the client's pace between subprocesses. 503 without Retry-After. The running git subprocess is stopped.
Memory (Linux) 256 MiB of git heap per subprocess (RLIMIT_DATA, set before git starts); 32 MiB for single-object reads. Read-only pack mappings are shared page cache and are not counted. 422. A git crash by SIGSEGV, SIGBUS or SIGABRT while running under the cap is also reported as this limit.
Output 64 MiB of buffered git output per request, shared by all its subprocesses. File contents that file, archive and diff stream instead of buffering are not counted. A recursive files call with limit or cursor counts only the entries of its page. 422. git is stopped as soon as the limit is passed.
File size 100 MiB per file, checked from the tree before the file is read. 422 for file (GET and HEAD) and archive, before any response byte. The body of a file GET and of an archive answer names the file (quoted, cut at 256 bytes), and exclude_globs leaves it out of an archive.
Symlink target 4,095 bytes, the most that symlink(2) accepts on Linux. XFS and macOS accept at most 1,023. archive reads each target in memory to write its tar header, checks its size from the tree first, and stops reading at the limit if git prints more. 422 for archive, before any response byte. The body names the symlink (quoted, cut at 256 bytes), and exclude_globs leaves the link out of the archive. file streams a symlink's target like any file, so the 100 MiB file limit applies to it.
Delivery Each 64 KiB of a response must reach the client within 30 seconds, and the whole response within 2 minutes of its first byte (file and archive: 10 minutes). The connection is closed. The request's slot, memory and temporary files are released.

On a 300,000-commit linear history, git log -1 -- <file added in the root commit> needs 184 MB of git heap. The files/metadata history walk for files that date from the root commit served a 400,000-commit linear history in about 5 seconds with at most 192 MiB of git heap, and got 422 at 500,000 commits (#576, #588, measured 2026-10-28). Histories past roughly 400,000 commits can get 422 for per-file history walks and blame of old files. Deep commits pages need less memory: they still fit at 1,000,000 commits (at most 232 MiB) and are estimated to reach the cap at roughly 1.1 million. Every files/metadata call, whatever its limit, walks history once for all files under path: it lists the whole history to a temporary file (about 80 bytes per commit, at most 256 MiB, or 422), then reads diffs down to the oldest of the files' last commits. It diffs only the commits that a file still waits on, and diffs a merge against a later parent only while a file is left that differs from every earlier parent. It sends up to 16 diffs ahead along chains of single-parent commits, so a linear history does not wait on git once per commit. On kubernetes (142,643 commits, 58,571 merges, 31,590 files) a root call took about 11 seconds alone, about 15 seconds with four such calls on four repositories at once, and about 17 seconds with eight. On git.git (82,605 commits) a root call took about 3 seconds. A call whose walks need more than 30 seconds in total gets 503; send a narrower path. A commit with more than about 25,000 parents (1 MiB of parent IDs) makes the walk fail with the output limit's 422. Commit-graphs, which full hydrates now write (ADR-47), make these walks cheaper when present, but the limits do not depend on them. The git log -1 and commits figures above are without a commit-graph; the files/metadata figures had one, except the 500,000-commit history, whose graph write timed out.

Endpoint git work Cost grows with
all below ref resolution (check-ref-format, rev-parse) nothing (single object)
commits git log --skip=<cursor offset> -n <limit+1> [-- path] cursor offset; history searched for path
commit git log -n 1, git cat-file commit the commit object (single object)
files git ls-tree [-r]; for a recursive call with a cursor, git cat-file --batch for the folders on the cursor's path and the ones after it, and git cat-file --batch-check for the sizes of the page's files, and git config --type=int --get core.maxTreeDepth once for a page the walk has filled, then git ls-tree -r again when the walk gives way tree size; for a recursive call with limit or cursor, the entries of the page and, with a cursor, the folders on its path and the ones after it, each read whole (not the folders before it). A walk that gives way has already paid for the folders it read when the stream starts
files/metadata git ls-tree -r; git rev-list --topo-order --parents and git diff-tree --stdin for the last commit of every file under path; git log --no-walk for the listed files' commits tree size; history length; history depth to the oldest last commit
file git ls-tree, git log -1 -- <path>, git cat-file blob history depth; file size
diff, branches/diff git merge-base, three git diff runs, git cat-file blob per changed file history to the merge base; number and size of changed files
blame git blame file length × history depth
grep git grep (one thread) tree size; number of matches
archive git ls-tree -r, git cat-file blob per file tree size
tags, tag git for-each-ref refs/tags number of tags
notes git notes show notes tree and note size
merge/preview git merge-base, git merge-tree, git ls-tree and git cat-file per conflict history to the merge base; tree size

Other limits and gaps:

  • Platforms. The memory limit needs RLIMIT_DATA, which only Linux enforces. On other server platforms, such as macOS, git runs without a memory cap, and the concurrency, time, output and file-size limits still apply. No endpoint refuses a request because the memory cap is unavailable. For deployments where untrusted users can push, run the server on Linux. See ADR-49.
  • archive streams its response. An error after the response has started (for example, the time limit, or a delta-compressed file whose base object does not fit in memory) closes the connection, so the client sees a truncated, invalid gzip stream instead of a status code.
  • Not covered by these limits: hydrating the cache repository before the git reads (serialized per repository), git clone and fetch over the git protocol (upload-pack, which has its own request-size limits), and the write endpoints.

Status-code contract (what clients key on)

Status Meaning to clients
200/201 success (201 accepted by SDKs on create endpoints)
202 pull-upstream / push-upstream accepted
206/304/412/416 file conditional/range results (passed through)
400 invalid input, a diff-commit patch over 262144000 bytes among them (streaming protocols)
401 no Authorization header, or a scheme other than Bearer (Authentication required)
403 a token that fails verification (Invalid or expired token); permission or ref-policy denied; authentication_unavailable when the key store fails (retry) (failure mapping)
404 repo/object/branch not found; unborn-branch file metadata; no API route matches the path (route_not_found); a path that is not clean, or /api, when its redirect Location would be longer than 16384 bytes (paths that are not clean)
405 the path has routes, but not for this method (Allow lists them)
409 repo exists, repo already deleted, credential exists, merge conflict, failed ref guard (expected_target_sha, expected_source_sha, expected_notes_ref_sha), CAS conflict, a diff-commit patch that does not apply to the base (streaming protocols)
412 a failed restore-commit base_ref precondition; a merge that is not a fast-forward under ff_only, or a merge or merge preview of unrelated histories without allow_unrelated_histories (a preview with ff_only answers rejected instead); a commit-pack or diff-commit that changes nothing (no changes to commit) or whose stream ends before an eof chunk (streaming protocols); a branches/create move guarded by expected_target_sha without force that is not a fast-forward (details)
413 a commit-pack whose decoded file contents pass 262144000 bytes (streaming protocols)
422 a git read exceeded a memory, output, file-size or symlink-target limit (resource limits on git reads); retrying the same request fails the same way
429 rate limit, busy or backpressure (plain problem body)
5xx internal/unavailable; 503 documented for a sync create whose first sync could not be scheduled (POST /repos, with Retry-After), for cold-storage warmup on grep/archive, for git reads when the server's git concurrency is exhausted (with Retry-After) or a request exceeds its git time budget (without Retry-After) (resource limits on git reads), and, on SQLite and S3WAL, for a ref write that forwards and waited 10 seconds for a concurrent git push or ref write that holds the same ref or a directory/file relative of it (with Retry-After; ref writes that forward)