C.O.G.N.I.T. API Docs

A C.O.G.N.I.T. API which powers C.O.G.N.I.T. website

Endpoints

This index reflects the current backend route map, auth expectations, and example request shapes.

GET/health

Check whether the API process is up and whether the database can be reached right now.

Auth: none Idempotency: n/a Rate limit: 20 per minute
Note: Intended for uptime probes and smoke tests.
Note: Returns service-degraded output when the database probe fails.
GET/check-username

Check whether a participant username is available before registration.

Auth: none Idempotency: n/a Rate limit: 60 per minute
Query: username=<candidate_username>
GET/check-email

Check whether an email address is already in use.

Auth: none Idempotency: n/a Rate limit: 60 per minute
Query: email=<candidate@example.com>
POST/client-errors

Receive structured frontend error telemetry for observability and debugging.

Auth: none Idempotency: n/a Rate limit: 60 per minute
Headers: Content-Type: application/json
Body: JSON payload required
POST/participants

Create a participant record, set participant cookies, and start the registration session.

Auth: none Idempotency: required Rate limit: 80 per minute
Headers: Content-Type: application/json, X-Idempotency-Key: <uuid>
Body: JSON payload required
Note: Sets secure participant cookies on success.
Note: Turnstile is enforced when backend production verification is enabled.
POST/consent

Mark consent as recorded for an existing participant.

Auth: none Idempotency: n/a Rate limit: 80 per minute
Headers: Content-Type: application/json
Body: JSON payload required
Note: This is a simple update operation and no longer uses the idempotency layer.
GET/participants/session

Read the current participant identifiers from secure cookies, if they exist.

Auth: participant cookies (optional) Idempotency: n/a Rate limit: 60 per minute
GET/participant-options

Load registration form options such as genders, languages, and prior-experience groups.

Auth: none Idempotency: n/a Rate limit: 60 per minute
POST/email-otp/request

Create and send an email verification OTP for the participant email address.

Auth: none Idempotency: n/a Rate limit: 40 per hour
Headers: Content-Type: application/json
Body: JSON payload required
Note: Use `email_update=true` when the participant is changing their email address.
Note: Delivery is rate-limited and OTP state is managed server-side rather than with idempotency replay.
POST/email-otp/verify

Verify an email OTP and mark the participant email as verified.

Auth: none Idempotency: n/a Rate limit: 40 per minute
Headers: Content-Type: application/json
Body: JSON payload required
Note: Consumes the OTP on success and increments attempt counters on invalid codes.
GET/images/random

Select the next image for the active participant flow (survey or attention step).

Auth: none Idempotency: n/a Rate limit: 240 per minute
Query: public_id=<participant_public_id> (optional), exclude=image_001,image_002 (optional)
Note: Pass previously shown image ids via `exclude` to avoid immediate repeats in the client.
Note: Providing `public_id` enables participant-aware sequencing for the 2-step submission flow.
Note: Current backend flow expects exactly 2 submissions per participant session.
POST/submit

Submit an image description, feedback, and engagement telemetry for the active survey image.

Auth: participant public_id + consented participant state Idempotency: required Rate limit: 120 per minute
Headers: Content-Type: application/json, X-Idempotency-Key: <uuid>
Body: JSON payload required
Note: Requires a valid participant public_id and a participant that is already consented.
Note: Stores both survey output and engagement telemetry.
Note: Backend determines whether a submission is survey vs attention from image assignment; client flags are not required.
Note: `survey_index` is backend-owned simple submission order for the participant across both attention-check and survey images.
Note: Protected with idempotency because duplicate submission writes are materially harmful.
C.O.G.N.I.T