Account API Reference

Account endpoints support GDPR-compliant data management, including full data export and account deletion. These endpoints are designed to satisfy the requirements of the EU General Data Protection Regulation (GDPR), specifically the right to data portability (Article 20) and the right to erasure (Article 17).

Base URL: /api/account

Authentication: All endpoints require authentication with admin access level.

Export All Tenant Data

GET /api/account/export

Exports all data associated with the authenticated tenant as a JSON file download. This implements the GDPR right to data portability.

Authentication

Requires admin access (cookie session or Bearer API key with read_only or read_write scope).

Response

Content-Type: application/json Content-Disposition: attachment; filename="groundtruth-export-<tenant-slug>-<date>.json"

The response is a JSON file download containing all tenant data.

Export Format

{
  "formatVersion": "groundtruth-data-export-v1",
  "exportedAt": "2025-06-01T14:00:00.000Z",
  "tenant": {
    "id": "clxyz100ten",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "professional",
    "createdAt": "2025-01-15T10:00:00.000Z"
  },
  "users": [
    {
      "id": "clxyz200usr",
      "email": "admin@acme.com",
      "name": "Jane Smith",
      "role": "owner",
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  ],
  "engagements": [
    {
      "id": "clxyz500eng",
      "name": "Brand Strategy",
      "slug": "brand-strategy",
      "client": "Example Client",
      "brief": "...",
      "budget": 5.0,
      "status": "completed",
      "tasks": [...],
      "createdAt": "2025-02-01T09:00:00.000Z"
    }
  ],
  "deliverables": [
    {
      "id": "clxyz700dlv",
      "engagementId": "clxyz500eng",
      "taskId": "brand_audit",
      "filename": "brand-audit-report.md",
      "content": "...",
      "version": 1,
      "wordCount": 2450,
      "createdAt": "2025-02-01T12:00:00.000Z"
    }
  ],
  "runs": [
    {
      "id": "clxyz600run",
      "engagementId": "clxyz500eng",
      "status": "completed",
      "startedAt": "2025-02-01T10:00:00.000Z",
      "finishedAt": "2025-02-01T11:45:00.000Z",
      "estimatedCost": 1.23,
      "inputTokens": 45000,
      "outputTokens": 12000
    }
  ],
  "apiKeys": [
    {
      "id": "clxyz300key",
      "name": "Production CI/CD",
      "prefix": "gt_live_a1b2",
      "scope": "read_write",
      "createdAt": "2025-05-15T08:00:00.000Z",
      "note": "Key hash redacted for security"
    }
  ],
  "webhooks": [
    {
      "id": "clxyz400whk",
      "url": "https://example.com/webhooks/groundtruth",
      "events": ["engagement.completed"],
      "enabled": true,
      "createdAt": "2025-05-20T10:00:00.000Z"
    }
  ],
  "templates": [
    {
      "id": "clxyz456def",
      "name": "Custom Research Template",
      "slug": "custom_research_template",
      "description": "A tailored research engagement template",
      "brief": "...",
      "isSystem": false,
      "createdAt": "2025-06-01T14:00:00.000Z"
    }
  ],
  "taskScores": [
    {
      "id": "clxyz800scr",
      "runId": "clxyz600run",
      "taskId": "brand_audit",
      "score": 8.5,
      "feedback": "Comprehensive analysis with strong competitive insights",
      "createdAt": "2025-02-01T12:00:00.000Z"
    }
  ],
  "libraryEntries": [
    {
      "id": "clxyz900lib",
      "engagementId": "clxyz500eng",
      "title": "Brand Strategy Patterns",
      "jsonData": {...},
      "createdAt": "2025-02-01T12:30:00.000Z"
    }
  ],
  "attachments": [
    {
      "id": "clxyz100att",
      "engagementId": "clxyz500eng",
      "filename": "brand-guidelines.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 2451890,
      "category": "brand_assets",
      "summary": "Official brand guidelines",
      "createdAt": "2025-06-01T09:15:00.000Z",
      "note": "File content stored in Supabase Storage, not included in export"
    }
  ]
}

Side Effects

Sends a confirmation email to the tenant admin notifying them of the data export

Example

# Download as a file
curl -X GET https://app.groundtruth.ai/api/account/export \
  -H "Cookie: sb-access-token=..." \
  -o groundtruth-export.json

# Or using an API key
curl -X GET https://app.groundtruth.ai/api/account/export \
  -H "Authorization: Bearer gt_live_abc123..." \
  -o groundtruth-export.json

Notes

API key hashes are redacted for security. Only the key name and prefix are included.
Attachment file content is stored in Supabase Storage and is not included in the JSON export. Only metadata is exported.
The export includes all versions of deliverables.

Delete Account and All Data

DELETE /api/account/delete

Permanently deletes the tenant account and all associated data. This implements the GDPR right to erasure ("right to be forgotten"). This action is irreversible.

Authentication

Requires admin access (cookie session or Bearer API key with read_write scope).

Request Body

Field	Type	Required	Description
`confirmText`	string	Yes	Must be exactly `"DELETE MY ACCOUNT"`

The confirmation text is required as a safeguard against accidental deletion.

Actions Performed

The following actions are executed in order:

Cancel Stripe subscription -- If the tenant has an active Stripe subscription, it is cancelled immediately
Delete files from Supabase Storage -- All uploaded attachments and generated files are removed
Delete tenant and cascade records -- The tenant record is deleted along with all associated data:
- Users
- Engagements (and their deliverables, runs, attachments, task scores)
- API keys
- Webhooks (and delivery history)
- Templates (tenant-specific only; system templates are unaffected)
- Library entries
- Platform insights
- Improvement proposals
- Data deletion requests
Anonymize audit logs -- Sets userId and tenantId to null on all audit log entries for this tenant. The audit log entries themselves are retained for compliance purposes, but they can no longer be linked to the deleted tenant.
Send confirmation email -- A deletion confirmation is sent to the tenant admin's email address

Response

{
  "status": "completed",
  "deletionRequestId": "clxyz050del",
  "summary": {
    "engagementsDeleted": 12,
    "deliverablesDeleted": 47,
    "runsDeleted": 15,
    "auditLogsAnonymized": 342,
    "stripeSubscriptionCancelled": true
  }
}

Example

curl -X DELETE https://app.groundtruth.ai/api/account/delete \
  -H "Cookie: sb-access-token=..." \
  -H "Content-Type: application/json" \
  -d '{
    "confirmText": "DELETE MY ACCOUNT"
  }'

Errors

Status	Description
400	Missing or incorrect `confirmText` (must be exactly `"DELETE MY ACCOUNT"`)
403	Insufficient permissions (admin access required)

WARNING

This action is permanent and irreversible. Once executed:

All engagement data, deliverables, runs, and files are permanently deleted
All API keys are invalidated
All webhook endpoints are removed
The Stripe subscription is cancelled
Audit logs are anonymized (retained for compliance but unlinked from the tenant)
User accounts associated with this tenant are deleted

It is strongly recommended to perform a data export (GET /api/account/export) before initiating account deletion.

Account API Reference

On this page