Skip to content

Site API

site-api runs the Go API on port 10000. It binds only the loopback address, and the proxy reaches it through that address. It does not authenticate requests itself. The liveness probe runs /api healthcheck in the container, because the kubelet cannot reach a loopback port.

It handles file and directory operations, token operations, signed and session URLs, checksums, and health. See Site API design.

The proxy gates <site-path>s/api/ with the same admin chain as the admin path (admin_auth.lua); token and public paths use their own rules (site proxy).

The version endpoints /api/v1/version/ and /api/v2/version/ return the IMAGE_TAG environment variable, or N/A when the variable is unset (api/api/version.go).

Use cases

  • Publishing pipelines: a CI job uploads or replaces content with an HTTP PUT and a Site token.
  • Large or unreliable transfers: resumable uploads with Content-Range.
  • Machine access without a browser: tokens, signed URLs, and session URLs instead of an OpenID Connect (OIDC) login.
  • Integrity and housekeeping: checksums, listings, directory creation, and bulk deletes.

Example usage

Health, a filtered listing, and a multipart upload:

curl -H "Authorization: Bearer ${SITE_TOKEN}" \
  "https://<domain>/<space>/<site>/s/api/v2/health/"

curl -H "Authorization: Bearer ${SITE_TOKEN}" \
  "https://<domain>/<space>/<site>/s/api/v2/files/?match=*.pdf"

curl -X PUT -H "Authorization: Bearer ${SITE_TOKEN}" \
  -F "file=@report.pdf" \
  "https://<domain>/<space>/<site>/s/api/v2/files/reports/report.pdf"

The end-user cookbook has the resumable-upload, pagination, delete, and token examples.

Request flow

flowchart LR
    C["Client with a Site token"] --> P["site-proxy: API auth chain"]
    P --> A["site-api 127.0.0.1:10000"]
    A --> V[("Site content and token database on the Site PVC")]