# API and integration handover

## Browser application

All browser writes require a signed-in account cookie and an Origin matching APP_URL. Server actions are authorised independently of the UI. JSON bodies are limited to 512 KB. Multipart uploads are limited to 30 MB total, with lower per-file limits.

`GET /api/data` returns role-filtered questions, documents, sessions, session events, runs, search measurements, issues, comments, drafts, users (administrator only) and serverTime. It returns 401 if not signed in. Temporary-password accounts see only the password-change requirement.

`POST /api/data` accepts JSON, or multipart with a `data` field containing the same JSON plus repeated `file` fields. The `action` chooses:

| Action | Fields / rules |
|---|---|
| quickSession | oiName and channel only; server creates/reuses a session and supplies optional release metadata |
| session | operation=start, title, oiName, build, environment, channel, selectedQuestionIds; or pause/resume/finish with id |
| question | administrator; id/version for update; title, area, prompt, setup, expected, checklist, priority, references, documentIds |
| document | administrator; multipart; code, title, optional id/version for replacement; exactly one file |
| draft | own questionId, payload, revision; server returns next revision; optimistic conflict check |
| run | own active sessionId, operationId UUID, questionId, questionVersion, verdict, actual, setupConfirmed, outcomeVerified, optional evidence/reason, measurements, previousRunId, issueId/issueRevision, documentVersions map; screenshot files optional |
| search | own accessible runId, label, optional sources/startedAt/duration/costAmount/currency/basis/notes |
| issue | technical/admin; id, revision, status, owner, priority, fix, fixBuild |
| linkIssue | technical/admin; runId, issueId for same question; adds evidence without modifying original result |
| mergeIssue | technical/admin; id of duplicate, targetId of shared issue for same question; preserves history |
| comment | accessible runId, body |
| user | administrator; name, email, role, temporary password for create/reset; id and active for updates |

Run measurements: duration, sourceCount, inputTokens, outputTokens, sourcesChecked, costAmount, costCurrency, costBasis, costScope, costNotes. Missing numeric values are null, not zero. duration is seconds. Cost is a decimal amount in the named currency, not an amount converted to cents. It is a recorded measurement, not a billing ledger.

`GET /api/files?id=FILE_UUID&view=1` requires access. Documents are shared reference files. Tester screenshot access is limited to their own run evidence; technical/admin can inspect consolidated evidence. Without view=1, downloads use attachment disposition.

`POST /api/auth`: login with email/password; logout; password with current and password. Roles and account activation come from the database, never the browser payload.

## Automatic search measurements from OI Workforce

Disabled unless TELEMETRY_API_KEY is configured with at least 32 random characters. Keep the key only on trusted servers. Do not put it in browser JavaScript or share it with testers.

After an attempt is saved, its API response includes `id`, the run UUID. OI Workforce needs to correlate its search trace with this saved attempt. Either hold the external trace and attach it after saving, or implement a reviewed correlation workflow in OI Workforce. This release does not automatically instrument the OI or infer search cost from tokens.

```http
POST /api/telemetry
Authorization: Bearer YOUR_SERVER_ONLY_KEY
Content-Type: application/json
```

```json
{
  "runId": "UUID_RETURNED_BY_SAVED_TEST",
  "externalId": "unique-organisation-trace-search-id",
  "label": "Find the current leave policy",
  "sources": "Current employee handbook; leave policy",
  "startedAt": "2026-11-20T09:00:00Z",
  "duration": 1.42,
  "costAmount": 0.00012,
  "currency": "USD",
  "basis": "Displayed estimate",
  "notes": "Retrieval charge only; speech and model generation excluded"
}
```

`externalId` prevents duplicate trace delivery. Reusing it for a different run is rejected. Measurements are marked System integration; manual entries remain separately labelled. Do not resend conflicting measurements under the same externalId: idempotency retains the first saved entry. Use a new correction entry with explanatory notes if required. A telemetry key can attach measurements across this installation; treat it as a privileged integration credential and rotate it if exposed.

Responses: 200 saved/known id; 400 invalid fields; 401 invalid key; 404 run not found; 409 duplicate trace conflict; 503 integration not configured. Telemetry cannot set Pass, alter questions, create users or resolve issues.

## Moving from the current hosted Test Centre

This package includes the 116-question starter bank, not your live hosted database. Export records from the hosted dashboard and keep that JSON plus original evidence files before migration. The self-hosted schema uses independent UUIDs and password accounts, not ChatGPT identities. Existing hosted files need an authenticated download and deliberate mapping before import. No untested automatic results importer is included. Your team should map users, question versions, documents, sessions and evidence in staging, verify totals and sample attachments, then retain the original export. Do not fabricate historical session start times from an export that contains only attempt timestamps.
