Endpoint reference

• POSThttps://metering.codereef.app/v1/engine

  Authenticate a job and serve it the engine artifact.

  The launcher presents a GitHub Actions OIDC token as a bearer credential and asks for a version. The token is verified before the requested version is resolved, so an unauthenticated caller cannot learn which engine versions exist. A public repository needs no licence; a private or internal one needs a valid, unexpired, unrevoked licence bound to that organisation. On success the response is the gzipped tarball, streamed, with x-credda-engine-version set. The launcher does not trust that header or these bytes: it verifies them against a digest committed in its own repository, so a compromise of this service cannot hand a runner code it will execute. The download is not recorded.

  Auth. Authorization: Bearer <GitHub Actions OIDC token>. Requires permissions: id-token: write.

  • 200 application/octet-stream — the engine tarball, streamed.
  • 400 bad-version, or a body that is not a JSON object, or over 2048 bytes.
  • 401 The OIDC token is missing, malformed, expired, stale, or not GitHub’s. Ten named reasons.
  • 402 Private repository, and the licence is missing, malformed, unsigned, expired, revoked, or for another organisation. Carries checkoutUrl.
  • 404 unknown-version: the version is well-formed and no artifact exists for it.
  • 405 Any method other than POST.
  • 503 Ours or GitHub’s, never yours: jwks-unavailable, missing-claims, verifier-unavailable, storage-unavailable.

  credda-backend/src/routes/metering.ts (handleEngine)

• POSThttps://metering.codereef.app/v1/runs

  Post the receipt for a run that has already happened.

  Advisory, and deliberately powerless: the run finished before this was called, and the client is built so that an outage here is invisible from inside a job. The body carries salted hashes — of the organisation, the repository and the actor — never names, plus the outcome token, the duration, the action version and whether the repository is private. The day is taken from this server’s clock and never from the body. A public repository is always recorded and no licence is read. A private one without a valid licence is refused and NOT recorded, because an unentitled run is not a fact this ledger is for. A failed write answers 200 with recorded:false rather than 500.

  Auth. None. Entitlement on a private repository comes from the licenceKey in the body.

  • 200 { ok, recorded, entitlement } — recorded:false means the row was lost, not that the run was refused.
  • 400 invalid_body with one of eleven named reasons, including body-too-large over 2048 bytes.
  • 402 license_required on a private repository, with the reason, a sentence for a human, and checkoutUrl. It means “do not post a decline reply”, not “stop”.
  • 405 Any method other than POST.
  • 500 verifier_unavailable: the licence could not be checked. Never reported as revoked.

  credda-backend/src/routes/metering.ts (handleRuns)

• POSThttps://metering.codereef.app/v1/waitlist

  Record an email address on the waitlist.

  Accepts JSON or a form post, and answers identically whether the address was new or already present, so it cannot be used to test whether a given address signed up. CORS is an echoed allow-list of the marketing origins rather than a wildcard, because a wildcard would let any page anywhere post addresses from a visitor’s browser. A failure to record is reported rather than swallowed: telling somebody they are on a list they are not on is the mistake this product exists to avoid.

  Auth. None. Browser-callable from the allow-listed marketing origins only.

  • 200 { ok: true, joined: true }.
  • 204 The CORS preflight.
  • 303 A form post with redirect, sent back with a status parameter.
  • 400 invalid_email or malformed_body.
  • 405 Any method other than POST or OPTIONS.
  • 413 Over 4096 bytes.
  • 503 not_recorded: the store refused the write.

  credda-backend/src/routes/metering.ts (handleWaitlist)

• GET/livez

  Liveness only, and answered with nothing. Outside the auth gate.

  Auth. None. Declared above authMiddleware, and there is nothing here to protect.

  • 204 No body at all: no schema version, no check names, no configuration.

  core/apps/api/src/app.ts

• GET/openapi.json

  The engine API’s own specification, served by your deployment and not by this host.

  Auth. None. Deliberately readable before a key exists, so it is useful to somebody deciding whether to integrate.

  • 200 The document describing the routes below. Built per call, so it cannot describe a process it is older than.

  core/apps/api/src/app.ts

• POST/api/investigations/{id}/cancel

  Stop a run, and say which of the three things it achieved.

  Auth. authMiddleware covers /api/*; the mode is the engine’s own configuration.

  • 200 CANCELLED — the run had not started and now cannot; or ALREADY_CANCELLED, because repeating the request is not an error. Nothing is running.
  • 202 CANCELLATION_REQUESTED: a worker is inside the run and honours this on its next heartbeat. It has NOT stopped yet — /events and /stream are how a caller learns that it did.
  • 401 The auth middleware refused the request.
  • 404 notFoundHandler: no such route, or no such id.
  • 409 ALREADY_FINISHED, or NOT_CANCELLABLE for a run executing outside the job queue — a `credda run` on somebody’s laptop, which this process cannot reach and will not pretend to.
  • 413 The body exceeded the ceiling the handler reads against.

  core/apps/api/src/routes/investigations.ts

• GET/api/health

  Liveness and readiness for the engine process.

  core/apps/api/src/routes/health.ts

• GET/api/investigations

  List investigations.

  core/apps/api/src/routes/investigations.ts

• POST/api/investigations

  Open an investigation.

  core/apps/api/src/routes/investigations.ts

• GET/api/investigations/{id}

  One investigation.

  core/apps/api/src/routes/investigations.ts

• GET/api/investigations/{id}/events

  The event log for one investigation.

  core/apps/api/src/routes/investigations.ts

• GET/api/investigations/{id}/evidence

  The evidence an investigation captured.

  core/apps/api/src/routes/investigations.ts

• GET/api/investigations/{id}/stream

  Server-sent events as an investigation runs.

  core/apps/api/src/routes/investigations.ts

• GET/api/metrics

  The measured metrics, each with its status.

  core/apps/api/src/routes/metrics.ts

• GET/api/organization

  The organisation this key is scoped to.

  core/apps/api/src/routes/organization.ts

• GET/api/organization/members

  Members of that organisation.

  core/apps/api/src/routes/organization.ts

• GET/api/organization/keys

  API keys issued for that organisation.

  core/apps/api/src/routes/organization.ts

• GET/api/repositories

  Repositories the engine knows about.

  core/apps/api/src/routes/repositories.ts

• GET/api/repositories/{id}

  One repository, resolved from the repositoryId a detail body carries.

  core/apps/api/src/routes/repositories.ts

• GET/api/repositories/{id}/learnings

  What the engine recalled from prior runs on one repository.

  core/apps/api/src/routes/repositories.ts

• GET/api/resolutions

  List resolutions.

  core/apps/api/src/routes/resolutions.ts

• GET/api/resolutions/latest

  The most recent resolution.

  core/apps/api/src/routes/resolutions.ts

• GET/api/resolutions/{id}

  One resolution.

  core/apps/api/src/routes/resolutions.ts

• GET/api/validations

  List validations.

  core/apps/api/src/routes/validations.ts

• GET/api/validations/{id}

  One validation.

  core/apps/api/src/routes/validations.ts

• GET/api/validations/{id}/checks

  The checks a validation ran.

  core/apps/api/src/routes/validations.ts

• GET/api/validations/{id}/findings

  What a validation found.

  core/apps/api/src/routes/validations.ts

• GET/api/validations/{id}/evidence

  The evidence a validation captured.

  core/apps/api/src/routes/validations.ts

• GET/api/validations/{id}/events

  The event log for one validation.

  core/apps/api/src/routes/validations.ts

• GET/api/validations/{id}/stream

  Server-sent events as a validation runs.

  core/apps/api/src/routes/validations.ts

Outcome tokens returned by these endpoints are defined at What a run can end as. Installing the Action is on the docs page.