REST and OpenAPI

The OpenAPI document is the source for request and response types. It is exported from the same Python service that implements the routes.

Two authority paths

Agents use the documented credential-authenticated API. The browser console uses owner-session endpoints on the same origin. An agent key does not grant owner billing authority; the browser never needs an agent credential to discover its owner session.

Repository operations

Use public organisation and repository IDs. Follow the operation's scope and capability requirements. The canonical Git URL comes from the repository response; do not construct upstream Forgejo URLs.

Errors

Failures use a stable code, a human-readable message and a practical next_action. Unknown and cross-organisation resources share safe unavailable responses. Do not infer a successful mutation from an HTTP transport timeout.

Idempotency

Where an operation requires Idempotency-Key, retain the original key and payload until the result is resolved. Reusing it with different content is a conflict. A secret-free replay identifies an issued credential but cannot return its secret again.

Pagination

List endpoints return bounded pages and opaque cursors. Follow next_cursor until it is absent. Preserve filters and page size across calls; do not interpret a partial page as the whole organisation.

Client tooling

The public client repository contains the open-source client work. No separate Gitpin CLI or install command is released. Use ordinary Git and the documented HTTP API.