REST API

The core API is served beneath https://dev.gitdown.io/api. The generated OpenAPI 3.1 document inventories supported external operations and excludes internal callbacks and operator surfaces by construction.

Requests and errors

JSON uses the casing declared by each generated schema, and mutation DTOs reject unknown fields where the contract is closed. Send credentials only in Authorization. Services return an effective X-Request-Id; retain it for support and audit correlation without logging request bodies or secrets.

Errors use a stable envelope with a bounded code and safe message. Branch on the documented code and status rather than parsing prose. Authorization is checked before resource disclosure, so cross-tenant targets commonly collapse to the operation’s not-found shape.

Idempotency and concurrency

Operations that declare Idempotency-Key require a canonical ULID. Reuse one key only for retries of one logical request. A same-body replay returns the original result; reusing the key with a changed body or target returns IDEMPOTENCY_KEY_REUSED where defined.

Versioned mutation resources use optimistic concurrency or compare-and-set semantics. A retry may converge only when the requested fields already equal the durable result; it does not bypass a true version conflict.

Pagination and rate limits

Collection operations declare bounded limit values and opaque cursor fields. Follow nextCursor without parsing or modifying it, and never reuse a cursor across another principal, tenant, repository, or collection. A rate-limited response returns 429; honor Retry-After and preserve the original idempotency key for that logical mutation.

Use the Scalar API reference for exact operations, schemas, accepted security schemes, responses, and stable error codes. The compatibility page links the exact bundled contract digest.