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

Examples

These `curl` examples are generated from the current backend route map and docs metadata. Replace placeholder ids, cookies, and tokens with real values from your environment.

GET /health

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

Intended for uptime probes and smoke tests.

Returns service-degraded output when the database probe fails.

curl -X GET "https://api.cognit.online/health"

GET /check-username

Check whether a participant username is available before registration.

curl -X GET "https://api.cognit.online/check-username?username=<candidate_username>"

GET /check-email

Check whether an email address is already in use.

curl -X GET "https://api.cognit.online/check-email?email=<candidate@example.com>"

POST /client-errors

Receive structured frontend error telemetry for observability and debugging.

curl -X POST "https://api.cognit.online/client-errors" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Unhandled UI exception",
  "route": "/survey",
  "tag": "ui_exception",
  "context": {
    "component": "SurveyPage"
  },
  "meta": {
    "browser": "Safari"
  },
  "stack": "Error: ..."
}'

POST /participants

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

Sets secure participant cookies on success.

Turnstile is enforced when backend production verification is enabled.

curl -X POST "https://api.cognit.online/participants" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: <uuid>" \
  -d '{
  "username": "gaurav_01",
  "email": "gaurav@example.com",
  "gender_code": "male",
  "age": 24,
  "location": "Ahmedabad, Gujarat",
  "language_code": "en",
  "prior_experience": "none",
  "turnstile_token": "<turnstile-token>"
}'

POST /consent

Mark consent as recorded for an existing participant.

This is a simple update operation and no longer uses the idempotency layer.

curl -X POST "https://api.cognit.online/consent" \
  -H "Content-Type: application/json" \
  -d '{
  "public_id": "<participant_public_id>"
}'

GET /participants/session

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

curl -X GET "https://api.cognit.online/participants/session"

GET /participant-options

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

curl -X GET "https://api.cognit.online/participant-options"

POST /email-otp/request

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

Use `email_update=true` when the participant is changing their email address.

Delivery is rate-limited and OTP state is managed server-side rather than with idempotency replay.

curl -X POST "https://api.cognit.online/email-otp/request" \
  -H "Content-Type: application/json" \
  -d '{
  "public_id": "<participant_public_id>",
  "email": "gaurav@example.com",
  "email_update": false
}'

POST /email-otp/verify

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

Consumes the OTP on success and increments attempt counters on invalid codes.

curl -X POST "https://api.cognit.online/email-otp/verify" \
  -H "Content-Type: application/json" \
  -d '{
  "public_id": "<participant_public_id>",
  "email": "gaurav@example.com",
  "otp": "123456"
}'

GET /images/random

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

Pass previously shown image ids via `exclude` to avoid immediate repeats in the client.

Providing `public_id` enables participant-aware sequencing for the 2-step submission flow.

Current backend flow expects exactly 2 submissions per participant session.

curl -X GET "https://api.cognit.online/images/random?public_id=<participant_public_id>&exclude=image_001,image_002"

POST /submit

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

Requires a valid participant public_id and a participant that is already consented.

Stores both survey output and engagement telemetry.

Backend determines whether a submission is survey vs attention from image assignment; client flags are not required.

`survey_index` is backend-owned simple submission order for the participant across both attention-check and survey images.

Protected with idempotency because duplicate submission writes are materially harmful.

curl -X POST "https://api.cognit.online/submit" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: <uuid>" \
  -d '{
  "public_id": "<participant_public_id>",
  "session_id": "<participant_session_id_optional>",
  "image_id": "1.svg",
  "description": "A detailed 60+ word description of the image content goes here.",
  "feedback": "The task instructions were clear.",
  "time_spent_seconds": 94,
  "survey_index": 1,
  "tab_switch_count": 0,
  "page_close_attempts": 0,
  "network_disconnects": 0,
  "survey_time_spent_seconds": 91,
  "survey_page_views": 1,
  "survey_tab_switches": 0,
  "survey_page_close_attempts": 0,
  "survey_network_disconnects": 0,
  "survey_max_scroll_depth_pct": 100,
  "survey_clicks": 4,
  "survey_keypresses": 102,
  "confidence_rating": 4,
  "difficulty_self_report": 3,
  "time_before_typing_seconds": 1.2,
  "edit_count": 5,
  "backspace_count": 10,
  "first_view_duration_seconds": 1.2,
  "writing_duration_seconds": 82,
  "avg_keystroke_interval_seconds": null,
  "keystroke_variance": null,
  "pause_count": 0,
  "avg_pause_duration_seconds": null,
  "turnstile_token": "<turnstile-token>"
}'
C.O.G.N.I.T