API reference
The ticketyboo API is a REST API served from AWS API Gateway in the eu-north-1 (Stockholm) region. All requests and responses use JSON. This page covers the base URL, authentication methods, and common response patterns.
Base URL
https://api.ticketyboo.devAll endpoints are prefixed with this base URL. There is no versioning prefix on the main API path (/api/...). The archetypes endpoint used by the extension uses a /v1/ prefix.
Authentication
Most public endpoints (scan submission, newsletter) require no authentication. Account and billing endpoints require authentication. Two authentication methods are supported:
Cognito JWT (Bearer token)
Obtained after signing in to ticketyboo.dev. Sent as an Authorization header:
Authorization: Bearer <jwt-token>JWTs are RS256 signed by the Cognito user pool eu-north-1_DKAA4NX9p. The API verifies the signature using the pool's JWKS endpoint before processing authenticated requests.
API key
Generated from your account page. Keys begin with tbo-. Sent as an x-api-key header:
x-api-key: tbo-your-key-hereAPI keys are used by the VS Code extension to call the archetypes endpoints. They can also be used in CI pipelines to submit scans programmatically.
Common response structure
All responses include CORS headers. Successful responses use 2xx status codes. Error responses use the following structure:
{
"error": "error_type",
"message": "Human-readable description"
}Common error codes
| Status | Error type | Meaning |
|---|---|---|
| 400 | invalid_request | Missing or invalid request body fields |
| 401 | unauthorized | Missing or invalid authentication |
| 403 | forbidden | Authenticated but insufficient permissions or credits |
| 404 | not_found | Resource does not exist |
| 429 | rate_limited | Rate limit exceeded |
| 500 | internal_error | Unexpected server error |
Rate limits
| Endpoint | Limit | Window |
|---|---|---|
| POST /api/scan (shallow) | 1 per IP | 24 hours |
| POST /api/scan (deep) | 3 per IP | 7-day rolling window |
Rate limits are tracked by IP address in DynamoDB. Use GET /api/scan/deep-quota to check remaining deep scan quota for the current IP.
Endpoint index
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/scan | None / API key | Submit a scan |
| GET | /api/scan/{id} | None | Get scan status and findings |
| GET | /api/scan/{id}/report | None | Get full scan report from S3 |
| GET | /api/scan/deep-quota | None | Get remaining deep scan quota for calling IP |
| POST | /api/scan/{id}/feedback | JWT / API key | Submit finding feedback |
| GET | /api/scan/{id}/feedback | JWT / API key | Get feedback for a scan |
| GET | /v1/archetypes | API key | List available contract archetypes |
| POST | /v1/archetypes/{name}/instantiate | API key | Generate a devcontract.json from an archetype |
| GET | /api/account/me | JWT | Get account profile and credit balance |
| POST | /api/account/apikey | JWT | Generate a new API key |
| POST | /api/checkout | JWT | Create Stripe checkout for subscription plan |
| POST | /api/topup | JWT | Create Stripe checkout for credit pack top-up |
| POST | /api/stripe-webhook | HMAC-SHA256 | Stripe webhook receiver |
| POST | /api/subscribe | None | Newsletter subscribe |
| POST | /api/unsubscribe | None | Newsletter unsubscribe (GDPR hard delete) |
| POST | /api/support | None | Create Stripe checkout for one-time donation |
| GET | /api/team/supporters | None | Get supporter count and total donation stats |
Section contents
Scan
Submit scans, poll for status, retrieve reports, manage feedback, and check quota.
Contracts
List archetypes and instantiate a devcontract.json via the /v1/archetypes endpoints.
Subscription
Account profile, API key generation, Stripe checkout for plans and credit packs.
Newsletter
Subscribe and unsubscribe from methodology update emails.
Health and support
Supporter stats and one-time donation checkout.