files

Repo files — presigned multipart upload/download against object storage, tree listing

5 operations · 17 schemas

GET `/v1/repos/{owner}/{repo}/tree`

List repo files

getRepoTree · scope none

Flat file listing with sizes, etags and sha256 digests (paths are /-separated keys; there are no directory objects). Filter with prefix; paginate for large repos.

Parameters

getRepoTree parameters
Name	In	Type	Description
`owner`required	path	`Handle`	Repo owner handle (username or org slug).
`repo`required	path	`Slug`	Repo slug.
`prefix`	query	`string` length ≤ `1024`	Only paths starting with this prefix.
`limit`	query	`integer` default `500` · ≥ `1` · ≤ `1000`	Page size (tree listings allow larger pages).
`cursor`	query	`string` length ≤ `512`	Opaque cursor from the previous page's `next_cursor`.

Responses

getRepoTree responses
Status	Description	Body
`200`	Page of file entries.	`TreePage`
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json

POST `/v1/repos/{owner}/{repo}/files/presign-upload`

Presign a batch multipart upload

presignUpload · scope key:write

Requests presigned multipart upload URLs for up to 100 files. Client supplies each file's path, size and sha256 (content addressing — also the seam for the M5 dedupe precheck). Server returns, per file, an upload_id and part URLs (part_size bytes each, last part may be short). Upload the parts with HTTP PUT, collect the returned ETags, then call complete. Limits (v0): single file ≤ 50 GiB, part size 100 MiB.

Parameters

presignUpload parameters
Name	In	Type	Description
`owner`required	path	`Handle`	Repo owner handle (username or org slug).
`repo`required	path	`Slug`	Repo slug.

Request body

application/json · required · PresignUploadRequest

presignUpload request body
Field	Type	Description
`files`required	`array of PresignUploadFile` items `1–100`

Responses

presignUpload responses
Status	Description	Body
`200`	Presigned upload targets, one per requested file.	`PresignUploadResponse`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`413`	A file exceeds the size limit or the account is over quota.	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

POST `/v1/repos/{owner}/{repo}/files/complete`

Complete a batch multipart upload

completeUpload · scope key:write

Finalizes multipart uploads previously presigned. Server completes the uploads in object storage, verifies etags, and upserts the RepoFile rows (existing paths are overwritten — repos have no revisions in v0).

Parameters

completeUpload parameters
Name	In	Type	Description
`owner`required	path	`Handle`	Repo owner handle (username or org slug).
`repo`required	path	`Slug`	Repo slug.

Request body

application/json · required · CompleteUploadRequest

completeUpload request body
Field	Type	Description
`uploads`required	`array of CompletedUpload` items `1–100`

Responses

completeUpload responses
Status	Description	Body
`200`	Files recorded.	`CompleteUploadResponse`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`409`	State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

POST `/v1/repos/{owner}/{repo}/files/presign-download`

Presign downloads

presignDownload · scope none

Returns short-lived (1 h) presigned GET URLs for up to 100 repo file paths. All-or-nothing: any unknown path fails the whole request with 404 (missing paths listed in the problem detail). Anonymous works for public repos.

Parameters

presignDownload parameters
Name	In	Type	Description
`owner`required	path	`Handle`	Repo owner handle (username or org slug).
`repo`required	path	`Slug`	Repo slug.

Request body

application/json · required · PresignDownloadRequest

presignDownload request body
Field	Type	Description
`paths`required	`array of FilePath` items `1–100`

Responses

presignDownload responses
Status	Description	Body
`200`	Presigned download URLs.	`PresignDownloadResponse`
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

POST `/v1/repos/{owner}/{repo}/files/delete`

Delete files (batch unlink)

deleteFiles · scope key:write

Unlinks up to 100 file rows from the repo. Content-addressed blobs are garbage-collected asynchronously once unreferenced. Unknown paths are ignored and reported back.

Parameters

deleteFiles parameters
Name	In	Type	Description
`owner`required	path	`Handle`	Repo owner handle (username or org slug).
`repo`required	path	`Slug`	Repo slug.

Request body

application/json · required · FileDeleteRequest

deleteFiles request body
Field	Type	Description
`paths`required	`array of FilePath` items `1–100`

Responses

deleteFiles responses
Status	Description	Body
`200`	Deletion summary.	`FileDeleteResponse`
`401`	Missing or invalid credentials.	`Problem`application/problem+json
`403`	Authenticated but not allowed (visibility, membership or scope).	`Problem`application/problem+json
`404`	Resource not found (or hidden from the caller).	`Problem`application/problem+json
`422`	Request failed validation.	`Problem`application/problem+json

Schemas (17)

The schemas these operations reach before any other tag’s do. A type that links elsewhere is rendered on that tag’s page.

TreePage

object

TreePage fields
Field	Type	Description
`items`required	`array of RepoFileEntry`
`next_cursor`required	`string \| null`

PresignUploadRequest

object

PresignUploadRequest fields
Field	Type	Description
`files`required	`array of PresignUploadFile` items `1–100`

PresignUploadResponse

object

PresignUploadResponse fields
Field	Type	Description
`uploads`required	`array of UploadTarget`
`expires_at`required	`string (date-time)`	When the presigned part URLs expire.

CompleteUploadRequest

object

CompleteUploadRequest fields
Field	Type	Description
`uploads`required	`array of CompletedUpload` items `1–100`

CompleteUploadResponse

object

CompleteUploadResponse fields
Field	Type	Description
`files`required	`array of RepoFileEntry`

PresignDownloadRequest

object

PresignDownloadRequest fields
Field	Type	Description
`paths`required	`array of FilePath` items `1–100`

PresignDownloadResponse

object

PresignDownloadResponse fields
Field	Type	Description
`files`required	`array of DownloadTarget`

FileDeleteRequest

object

FileDeleteRequest fields
Field	Type	Description
`paths`required	`array of FilePath` items `1–100`

FileDeleteResponse

object

FileDeleteResponse fields
Field	Type	Description
`deleted`required	`array of FilePath`
`missing`required	`array of FilePath`	Requested paths that did not exist (ignored).

RepoFileEntry

object

RepoFileEntry fields
Field	Type	Description
`path`required	`FilePath`
`size`required	`integer` ≥ `0`	Bytes.
`etag`	`string \| null`	Object-store ETag (multipart ETags are not content hashes).
`sha256`	`Sha256 \| null`
`mime`	`string \| null` length ≤ `255`	Detected media type.
`updated_at`required	`string (date-time)`

PresignUploadFile

object

PresignUploadFile fields
Field	Type	Description
`path`required	`FilePath`
`size`required	`integer` ≥ `0` · ≤ `53687091200`	Bytes; v0 single-file limit 50 GiB.
`sha256`required	`Sha256`
`content_type`	`string \| null` length ≤ `255`

UploadTarget

object

UploadTarget fields
Field	Type	Description
`path`required	`FilePath`
`upload_id`required	`string`	Multipart upload id; echo it back on `complete`.
`part_size`required	`integer`	Bytes per part (v0 fixed 100 MiB; last part may be short).
`parts`required	`array of UploadPart`

CompletedUpload

object

CompletedUpload fields
Field	Type	Description
`path`required	`FilePath`
`upload_id`required	`string`
`parts`required	`array of CompletedPart` items ≥ `1`

DownloadTarget

object

DownloadTarget fields
Field	Type	Description
`path`required	`FilePath`
`url`required	`string (uri)`
`expires_at`required	`string (date-time)`

Sha256

string

pattern ^[a-f0-9]{64}$

Lowercase hex SHA-256.

UploadPart

object

UploadPart fields
Field	Type	Description
`part_number`required	`integer` ≥ `1`
`url`required	`string (uri)`

CompletedPart

object

CompletedPart fields
Field	Type	Description
`part_number`required	`integer` ≥ `1`
`etag`required	`string`

files

GET /v1/repos/{owner}/{repo}/tree

Parameters

Responses

POST /v1/repos/{owner}/{repo}/files/presign-upload

Parameters

Request body

Responses

POST /v1/repos/{owner}/{repo}/files/complete

Parameters

Request body

Responses

POST /v1/repos/{owner}/{repo}/files/presign-download

Parameters

Request body

Responses

POST /v1/repos/{owner}/{repo}/files/delete

Parameters

Request body

Responses

Schemas (17)

TreePage

PresignUploadRequest

PresignUploadResponse

CompleteUploadRequest

CompleteUploadResponse

PresignDownloadRequest

PresignDownloadResponse

FileDeleteRequest

FileDeleteResponse

RepoFileEntry

PresignUploadFile

UploadTarget

CompletedUpload

DownloadTarget

Sha256

UploadPart

CompletedPart

GET `/v1/repos/{owner}/{repo}/tree`

POST `/v1/repos/{owner}/{repo}/files/presign-upload`

POST `/v1/repos/{owner}/{repo}/files/complete`

POST `/v1/repos/{owner}/{repo}/files/presign-download`

POST `/v1/repos/{owner}/{repo}/files/delete`