Federation API
9 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.
Endpoints
GET /api/v1/repositories/{name}/federation
Get a repository's federation status
Federation health of one repository: whether it is enabled, the log position, and every peer (with its state, lag and backlog) and inbound token. Requires the repository-scoped manage permission (global administrators have it) or the maintainer or owner role in the repository's project. supported is false for proxy and group repositories and for formats without federation.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Federation status | application/json: FederationStatus |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Manage permission on the repository required | - |
404 | Repository not found | - |
PUT /api/v1/repositories/{name}/federation
Enable or disable federation
Enabling backfills the change log from the repository's existing content. Disabling removes the log and all peers. Idempotent. Same permission as the status read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
Request body (required)
application/json: UpdateFederationRequest
Responses
| Status | Description | Body |
|---|---|---|
200 | The new federation status | application/json: FederationStatus |
400 | Invalid request, or the repository is not hosted or its format has no federation (error code validation_failed) | application/json: Error |
403 | Manage permission on the repository required | - |
404 | Repository not found | - |
409 | Conflict with the current state | application/json: Error |
POST /api/v1/repositories/{name}/federation/peers
Add a federation peer
Registers a remote instance to pull this repository's changes from. The base URL is validated against the outbound (SSRF) policy. Requires federation to be enabled (409 otherwise) and the repository-scoped manage permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
Request body (required)
application/json: CreateFederationPeerRequest
Responses
| Status | Description | Body |
|---|---|---|
201 | Peer added | application/json: FederationPeer |
400 | Invalid request (error code validation_failed) | application/json: Error |
403 | Manage permission on the repository required | - |
404 | Repository not found | - |
409 | Federation is not enabled, or a peer with this name already exists | application/json: Error |
PATCH /api/v1/repositories/{name}/federation/peers/{id}
Update a federation peer
Changes a peer's name, URL, credentials or enabled flag; absent fields stay unchanged. Same permission as the status read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
id | path | string (uuid) | yes | Peer id. |
Request body (required)
application/json: UpdateFederationPeerRequest
Responses
| Status | Description | Body |
|---|---|---|
200 | The updated peer | application/json: FederationPeer |
400 | Invalid request (error code validation_failed) | application/json: Error |
403 | Manage permission on the repository required | - |
404 | Repository or peer not found | - |
409 | A peer with this name already exists | application/json: Error |
DELETE /api/v1/repositories/{name}/federation/peers/{id}
Delete a federation peer
Stops pulling from the peer and forgets its cursor and deferred units. Content already applied stays. Same permission as the status read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
id | path | string (uuid) | yes | Peer id. |
Responses
| Status | Description | Body |
|---|---|---|
204 | Peer deleted | - |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Manage permission on the repository required | - |
404 | Repository or peer not found | - |
409 | Conflict with the current state | application/json: Error |
GET /api/v1/repositories/{name}/federation/peers/{id}/deferred
List a peer's deferred units
Units pulled from the peer that could not be applied yet (for example a dependency has not arrived) and are being retried. Same permission as the status read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
id | path | string (uuid) | yes | Peer id. |
Responses
| Status | Description | Body |
|---|---|---|
200 | The deferred units | application/json: FederationDeferredList |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Manage permission on the repository required | - |
404 | Repository or peer not found | - |
409 | Conflict with the current state | application/json: Error |
POST /api/v1/repositories/{name}/federation/peers/{id}/resync
Resync a federation peer
Resets the peer's cursor so the next pass re-reads its whole log and merges it idempotently. Returns at once; the peer reports resync_requested until the pass starts. Same permission as the status read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
id | path | string (uuid) | yes | Peer id. |
Responses
| Status | Description | Body |
|---|---|---|
202 | Resync queued | application/json: FederationPeer |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Manage permission on the repository required | - |
404 | Repository or peer not found | - |
409 | Conflict with the current state | application/json: Error |
POST /api/v1/repositories/{name}/federation/tokens
Create an inbound federation token
Mints a token a peer presents to pull this repository's log. The clear-text token is returned only in this response. Requires federation to be enabled (409 otherwise) and the repository-scoped manage permission.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
Request body (required)
application/json: CreateFederationTokenRequest
Responses
| Status | Description | Body |
|---|---|---|
201 | Token created | application/json: FederationTokenCreated |
400 | Invalid request (error code validation_failed) | application/json: Error |
403 | Manage permission on the repository required | - |
404 | Repository not found | - |
409 | Federation is not enabled | application/json: Error |
DELETE /api/v1/repositories/{name}/federation/tokens/{id}
Revoke an inbound federation token
The token stops working at once; it stays listed with revoked_at set. Same permission as the status read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | yes | - |
id | path | string (uuid) | yes | Token id. |
Responses
| Status | Description | Body |
|---|---|---|
204 | Token revoked | - |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Manage permission on the repository required | - |
404 | Repository or token not found | - |
409 | Conflict with the current state | application/json: Error |