Skip to main content
Download a repository snapshot as a streaming tar.gz archive. 
POST /api/v1/repos/archive
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "ref": "main",
  "include_globs": ["README.md", "src/**"],
  "exclude_globs": ["vendor/**"],
  "max_blob_size": 1048576,
  "archive": {
    "prefix": "repo/"
  }
}

​
Request Body

​
ref
string
Branch name, tag, or commit SHA to archive. Defaults to the repository’s default branch.
​
include_globs
string
Glob patterns for files to include in the archive.
​
exclude_globs
string
Glob patterns for files to exclude from the archive.
​
max_blob_size
number
Maximum blob size in bytes. When provided, files larger than this limit are excluded from the archive.
​
archive.prefix
string
Prefix to add to each entry in the tar archive (e.g., repo/).

​
JWT Requirements

  • The JWT must include the repository in the repo claim
  • Requires git:read scope

​
Response

Returns a streaming tar.gz body. Typical headers:
  • Content-Type: application/gzip
  • Content-Disposition: attachment; filename="<repo>-<rev>.tar.gz"
  • Cache-Control: no-store

​
Notes

  • If ref is omitted or empty, the server uses the repository’s default branch (or HEAD if no default is set).
  • If max_blob_size is provided, files with blob size larger than this value are filtered out.
  • archive.prefix must be a relative path without backslashes, leading slashes, or ./.. path segments. A trailing / is added automatically if missing.
  • If include_globs are provided but none match, the response is an empty tar.gz with status 200.

​
Error Responses

​
400 Bad Request
string
Invalid JSON, invalid prefix, invalid max_blob_size, or failed to resolve ref
​
401 Unauthorized
string
Missing or invalid JWT
​
403 Forbidden
string
Missing git:read scope
​
404 Not Found
string
Ref does not exist
​
500 Internal Server Error
string
Archive generation failed
​
502 Bad Gateway
string
Failed to contact storage
​
503 Service Unavailable
string
Storage selection failed