API reference

Everything under /api/v1 is tenant-scoped and authenticated with the Thundera SSO session (cookie) or a bearer access token from auth.thundera.eu.

Machine-readable

The GitHub contract is also served as OpenAPI at /api/v1/openapi.json.

Conventions

  • Errors: {"error": {"code", "message", "trace_id"}}. Quote trace_id when asking for support.
  • The tenant is always derived from your session, never from a request body.
  • Unauthenticated calls to protected routes return 401. Network errors are not a revoked session: clients must not discard tokens on them.
  • POST /api/v1/reviews accepts an Idempotency-Key header (max 200 chars); repeated calls return the same review.

Reviews

EndpointAuthRequestResponse
POST /api/v1/reviewsSSO{repository, revision, files:[{path, content}]} + optional Idempotency-Key header201 Review
Errors: 400 invalid review, 413 too large, 422 policy
GET /api/v1/reviewsSSO-200 {reviews: Review[]}
Errors: 401
GET /api/v1/reviews/:idSSO-200 Review (findings, state)
Errors: 401, 404
POST /api/v1/reviews/:id/cancelSSO-200 Review
Errors: 404, 409 wrong state
POST /api/v1/reviews/:id/retrySSO-200 Review
Errors: 404, 409 wrong state
POST /api/v1/reviews/from-githubSSO{connection_id, pull_number}201 Review (bound to the PR head SHA, idempotent)
Errors: 400, 404, 409, 502
POST /api/v1/reviews/from-bitbucketSSO{connectionId, pullNumber}201 Review
Errors: 400, 404, 502

GitHub

EndpointAuthRequestResponse
GET /api/v1/connections/githubSSO-200 {connections[]}
Errors: 401
POST /api/v1/connections/githubSSO{repository: 'owner/repo' or https://github.com/owner/repo URL}201 connection
Errors: 400, 404, 502
POST /api/v1/connections/github/privateSSO{repository}201 connection
Errors: 409 GITHUB_INSTALLATION_REQUIRED, 503 GITHUB_APP_NOT_CONFIGURED
GET /api/v1/connections/github/installationSSO-200 {installed, account_login, account_type}
Errors: 401
GET /api/v1/connections/github/installation/repositoriesSSO-200 repositories visible to the installation
Errors: 404 GITHUB_APP_NOT_INSTALLED, 503, 502
DELETE /api/v1/connections/github/installationSSO-removes the recorded installation
Errors: 401
POST /api/v1/connections/github/install-urlSSO-201 {install_url, authorize_url, state, app_install_url} (single-use, tenant-bound state)
Errors: 503
GET /api/v1/connections/github/callbackstate?code&state (browser redirect from GitHub)302 /settings/connections?github=connected|not_installed|error
GET /api/v1/connections/github/:idSSO-200 connection
Errors: 404
DELETE /api/v1/connections/github/:idSSO-204
Errors: 404
GET /api/v1/connections/github/:id/pulls?page=NSSO-200 {pulls[], page, has_more}
Errors: 404, 502

Bitbucket Cloud

EndpointAuthRequestResponse
GET /api/v1/connections/bitbucketSSO-200 {connections[]}
Errors: 401
POST /api/v1/connections/bitbucketSSO{workspace, repository, authMethod:'basic'|'bearer', email (basic only), apiToken}201 connection
Errors: 400 INVALID_BITBUCKET_INPUT, 401-mapped BITBUCKET_APP_PASSWORD_DEPRECATED / BITBUCKET_EMAIL_REQUIRED / BITBUCKET_CREDENTIALS_INVALID
GET /api/v1/connections/bitbucket/:idSSO-200 connection
Errors: 404
DELETE /api/v1/connections/bitbucket/:idSSO-204
Errors: 404
GET /api/v1/connections/bitbucket/:id/pullsSSO-200 pull requests
Errors: 404, 502

Learnings and usage

EndpointAuthRequestResponse
GET /api/v1/learnings?connection_id=SSO-200 {learnings[]} (max 200)
Errors: 400
POST /api/v1/learningsSSO{content (1-500 chars), connection_id?}201 learning
Errors: 400 INVALID_LEARNING, 404
DELETE /api/v1/learnings/:idSSO-204
Errors: 404
GET /api/v1/usageSSO-200 {window_hours, tokens_used, token_budget, model_enabled, budget_exceeded}
Errors: 401

Public and operational

EndpointAuthRequestResponse
GET /api/plansnone-200 plan catalogue (proxy of the central billing catalogue, 60 s cache)
GET /api/v1/openapi.jsonnone-200 OpenAPI document
GET /healthnone-200 {status:'ok'} (liveness)
GET /readynone-200 when the database is reachable
Errors: 503
POST /api/v1/webhooks/github/appsignatureGitHub App webhook (X-Hub-Signature-256)2xx
Errors: 401 bad signature
POST /api/v1/webhooks/github/:installationsignatureInstallation webhook2xx
Errors: 401
POST /api/v1/webhooks/bitbucket/:connectionIdsignatureBitbucket webhook2xx
Errors: 401

Example

curl -X POST https://thundercode.thundera.eu/api/v1/reviews \
  -H "Authorization: Bearer $THUNDERA_ACCESS_TOKEN" \
  -H "Idempotency-Key: demo-1" -H "Content-Type: application/json" \
  -d '{"repository":"acme/web","revision":"HEAD","files":[{"path":"a.ts","content":"const password = \"x\";"}]}'