API Reference: Overview

The Groundtruth Platform API provides programmatic access to engagements, deliverables, quality scores, and more. All endpoints are served from the same origin as the web application.

Base URL

https://app.groundtruth.ai

For local development:

http://localhost:3000

All API routes are prefixed with /api/.

Authentication

The API supports three authentication methods. Every request must use one of them.

1. Cookie-based (browser sessions)

Automatic for browser sessions. When a user logs in via Supabase Auth, session cookies are set and sent with every request. This is the default method used by the dashboard UI.

Cookie auth is required for administrative operations:

• API key management (/api/api-keys)
• Webhook management (/api/webhooks)

These endpoints will return 403 if accessed with an API key.

2. API Key (Bearer token)

For programmatic access from scripts, CI/CD, Slack bots, or third-party integrations.

Authorization: Bearer gt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are generated in the dashboard under Settings > API Keys. The full key is displayed only once at creation time; store it securely.

Key properties:

Key format: gt_live_ followed by 64 hex characters. Keys are stored as SHA-256 hashes in the database; the platform never stores the raw key.

API keys inherit the creating user's tenant. All data returned is scoped to that tenant.

3. Portal token (client portal)

Used for client portal endpoints only. The token is embedded in the URL path:

/api/engagements/:id/portal/:tokenId

No Authorization header is needed. Portal tokens provide read-only access to a specific engagement's deliverables and allow posting comments and reviews.

API Key Management

API keys are managed exclusively through the dashboard (cookie auth required). You cannot use an API key to create or revoke other API keys.

Rate Limiting

Rate limiting is enforced per-tenant (or per-API-key when using Bearer auth). The system uses Redis-backed sliding window rate limiting via Upstash, with automatic fallback to in-memory token bucket rate limiting if Redis is unavailable.

Rate Limit Tiers

Rate Limit Response

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating the number of seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": "Too many requests"
}

Error Format

All errors are returned as JSON with an error field and an appropriate HTTP status code:

{
  "error": "Human-readable error message"
}

Common Status Codes

Write Access

All mutating operations (POST, PUT, PATCH, DELETE) require an API key with read_write scope. Attempting a write operation with a read_only key returns:

{
  "error": "Read-only API key"
}

This applies to: creating engagements, starting/stopping/pausing/resuming runs, deleting engagements, submitting reviews, and triggering reruns.

Tenant Isolation

All data is automatically scoped to your tenant. You will never see data from another tenant, and another tenant will never see yours. This is enforced at multiple levels:

1. Application layer: Every query includes a tenantId filter derived from your session or API key.
2. Database layer: PostgreSQL Row-Level Security (RLS) policies enforce tenant boundaries even if application code has a bug.
3. API key scope: Keys inherit the creating user's tenant and cannot be used to access other tenants.
4. Engagement scoping: API keys scoped to a specific engagement will return 404 for all other engagements.

Interactive Documentation

Swagger UI is available at:

https://app.groundtruth.ai/api/docs

The interactive documentation is generated from the OpenAPI 3.0 specification and allows you to explore and test endpoints directly from the browser.

Webhook Signature Verification

When you register a webhook endpoint, the platform signs every payload with HMAC-SHA256 so you can verify authenticity. See webhooks.md for the full verification guide, supported events, and payload schemas.

The signature is sent in the X-Groundtruth-Signature header:

X-Groundtruth-Signature: t=1700000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Further Reading

• engagements.md -- Engagement and run control endpoints
• deliverables.md -- Deliverable listing, versioning, review, rerun, and PDF export
• webhooks.md -- Webhook registration, events, payload schemas, and signature verification
• api-keys.md -- API key creation, rotation, scoping, and revocation