{ "openapi": "3.1.0", "info": { "title": "LEIN open Liberian English dataset API", "version": "1.0.0", "description": "One API for the contributor website, reviewers, admins and the LEIN AI agent. Files never pass through JSON: get a signed link, PUT the file, then register it." }, "servers": [ { "url": "/api/v1" } ], "components": { "securitySchemes": { "userToken": { "type": "http", "scheme": "bearer", "description": "Contributor session token (u_...)" }, "agentKey": { "type": "http", "scheme": "bearer", "description": "API key (lein_...) with scopes: datasets:read, samples:read, labels:write, feedback:write, annotations:write, webhooks:write" }, "adminCookie": { "type": "apiKey", "in": "cookie", "name": "lein_admin" } } }, "paths": { "/config": { "get": { "summary": "Site configuration, topics, counties, limits", "tags": [ "Public" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } } } }, "/auth/start": { "post": { "summary": "Create an anonymous contributor; returns a session token and a one-time recovery code", "tags": [ "Contributors" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } } } }, "/auth/recover": { "post": { "summary": "Sign in on another device with the recovery code", "tags": [ "Contributors" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } } } } } } }, "/auth/new-code": { "post": { "summary": "Replace the recovery code", "tags": [ "Contributors" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "userToken": [] } ] } }, "/me": { "get": { "summary": "Profile, consent state and contribution counts", "tags": [ "Contributors" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "userToken": [] } ] }, "put": { "summary": "Save profile and consent (consent, adult required; videoConsent optional)", "tags": [ "Contributors" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "userToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "ageRange": { "type": "string", "enum": [ "18-24", "25-34", "35-44", "45-54", "55-64", "65+" ] }, "gender": { "type": "string", "enum": [ "female", "male", "other" ] }, "county": { "type": "string", "description": "County of origin (one of the 15 counties or 'Outside Liberia'); optional" }, "currentLocation": { "type": "string", "description": "Current location (county or 'Outside Liberia'); optional" }, "languages": { "type": "string" }, "accentNotes": { "type": "string" }, "showOnBoard": { "type": "boolean" }, "adult": { "type": "boolean" }, "consent": { "type": "boolean" }, "videoConsent": { "type": "boolean" } }, "required": [ "ageRange", "gender" ] } } } } }, "delete": { "summary": "Stop contributing: delete unreleased items, exclude from future releases", "tags": [ "Contributors" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "userToken": [] } ] } }, "/prompts/next": { "get": { "summary": "Next tasks for this contributor", "tags": [ "Tasks" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "read | speak | write | photo" }, { "name": "n", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1-10" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" }, "description": "e.g. Liberian English (default)" }, { "name": "variety", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Liberian English reading prompts only: kolokwa | liberian_english" } ] } }, "/uploads/sign": { "post": { "summary": "Get a short-lived signed link to upload a file straight to storage", "tags": [ "Uploads" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "description": "Returns {key, upload:{url, method:'PUT', headers, expiresAt}}. PUT the raw file to upload.url, then register it with POST /samples.", "security": [ { "userToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audio", "video", "image" ] }, "contentType": { "type": "string" }, "size": { "type": "integer" } } } } } } } }, "/samples": { "post": { "summary": "Register an uploaded file (audio, video, image) or submit text (sentence or dialogue)", "tags": [ "Samples" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "userToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audio", "video", "image", "text" ] }, "key": { "type": "string" }, "promptId": { "type": "integer" }, "mode": { "type": "string" }, "durationMs": { "type": "integer" }, "peak": { "type": "number" }, "silenceRatio": { "type": "number" }, "transcript": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "everyoneAgreed": { "type": "boolean" }, "noMusic": { "type": "boolean" }, "caption": { "type": "string" }, "shareCounty": { "type": "boolean" }, "format": { "type": "string" }, "topic": { "type": "string" }, "situation": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "type": "string" }, "text": { "type": "string" }, "english": { "type": "string" } } } }, "language": { "type": "string", "description": "Liberian English (default), Kpelle, Bassa, Grebo, Gio (Dan) and other Liberian languages" }, "collection": { "type": "string", "enum": [ "general", "health", "agriculture", "energy", "education", "economy", "research", "legal" ] }, "variety": { "type": "string", "description": "kolokwa | liberian_english; reading follows the prompt's variety" }, "sampleRate": { "type": "integer", "description": "Audio: recording sample rate in Hz" }, "snrDb": { "type": "number", "description": "Audio: estimated signal-to-noise ratio in dB, measured in the browser" } } } } } }, "description": "Returns {id, ref, status}. ref is the contributor-facing reference number, e.g. LV-7K3Q-92." }, "get": { "summary": "Samples changed since a time (incremental sync for the agent)", "tags": [ "Agent" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "agentKey": [ "samples:read" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "approved | pending | disputed" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO time; use next_since from the previous call" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "max 500" } ] } }, "/review/queue": { "get": { "summary": "Next item to check", "tags": [ "Review" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "userToken": [] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "audio | video | image | text" } ], "description": "Reviewers and admins only." } }, "/reviews": { "post": { "summary": "Approve or reject an item, optionally with a corrected transcript", "tags": [ "Review" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "description": "Two approvals approve, two rejections reject, a split goes to 'disputed' for an admin. Reviewers and admins only.", "security": [ { "userToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sampleId": { "type": "string" }, "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "audioQuality": { "type": "integer" }, "transcriptCorrect": { "type": "boolean" }, "correctedText": { "type": "string" }, "notes": { "type": "string" } } } } } } } }, "/annotation/tasks": { "get": { "summary": "Next approved image to annotate, with agent pre-annotations", "tags": [ "Annotation" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "userToken": [] } ], "description": "Reviewers and admins only." } }, "/annotations": { "post": { "summary": "Save labels, boxes and captions; accept or reject agent boxes", "tags": [ "Annotation" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "userToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sampleId": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "class": { "type": "string" }, "geometry": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" } } }, "text": { "type": "string" } } } }, "acceptAgent": { "type": "array", "items": { "type": "integer" } }, "rejectAgent": { "type": "array", "items": { "type": "integer" } } } } } } } } }, "/stats": { "get": { "summary": "Public totals, coverage by county, gender, age and topic", "tags": [ "Public" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } } } }, "/datasets": { "get": { "summary": "Published releases", "tags": [ "Datasets" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } } } }, "/datasets/{version}/manifest": { "get": { "summary": "Every file in a release with sha256, transcript, agent output kept separate, and speaker metadata", "tags": [ "Datasets" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" }, "description": "e.g. 2026.11.0" } ] } }, "/datasets/{version}/download": { "get": { "summary": "Zip of a release: files, manifest.json, metadata.jsonl, README dataset card", "tags": [ "Datasets" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string" }, "description": "" } ] } }, "/agent/labels": { "post": { "summary": "Send refined transcripts (single object or array). Stored as source=agent with confidence; <0.6 flags the item for human review", "tags": [ "Agent" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "agentKey": [ "labels:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sample_id": { "type": "string" }, "transcript": { "type": "string" }, "confidence": { "type": "number" }, "model": { "type": "string" }, "flags": { "type": "object" } } } } } } } }, "/agent/feedback": { "post": { "summary": "Report data gaps; prompts on that topic move up the queue", "tags": [ "Agent" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "agentKey": [ "feedback:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "county": { "type": "string" }, "topic": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object" } } } } } } } }, "/agent/annotations": { "post": { "summary": "Propose boxes, polygons, masks or labels for an image (pre-annotation)", "tags": [ "Agent" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "agentKey": [ "annotations:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sample_id": { "type": "string" }, "model": { "type": "string" }, "annotations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "class": { "type": "string" }, "geometry": { "type": "object" }, "confidence": { "type": "number" } } } } } } } } } } }, "/webhooks": { "post": { "summary": "Register a webhook. Payloads are signed: X-LEIN-Signature: sha256=HMAC(secret, body)", "tags": [ "Agent" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "agentKey": [ "webhooks:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "dataset.version.published" ] } } } } } } } }, "/admin/login": { "post": { "summary": "Admin sign-in (sets an HttpOnly cookie)", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string" } } } } } } } }, "/admin/overview": { "get": { "summary": "Counts, agent feedback and flags", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ] } }, "/admin/samples": { "get": { "summary": "Items by status", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "disputed | pending | flagged | approved | rejected" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ] } }, "/admin/samples/{id}": { "post": { "summary": "Decide an item or correct its transcript", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "transcript": { "type": "string" }, "clearFlag": { "type": "boolean" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "" } ] }, "delete": { "summary": "Delete an item and its files", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "" } ] } }, "/admin/prompts/import": { "post": { "summary": "Bulk import prompts (TSV: text, english, topic)", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" }, "variety": { "type": "string", "description": "kolokwa | liberian_english (Liberian English reading prompts)" } } } } } } } }, "/admin/datasets": { "post": { "summary": "Publish the next numbered release and notify webhooks", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string" } } } } } } } }, "/admin/api-clients": { "get": { "summary": "List API keys", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ] }, "post": { "summary": "Create an API key (shown once)", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "/admin/audit": { "get": { "summary": "Audit log", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ] } }, "/me/contributions": { "get": { "summary": "Everything this contributor has sent: reference number, preview link, language, status and the releases that include it", "tags": [ "Contributors" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "description": "Items that were not accepted are listed with deleteAfter and removed 30 days after the decision.", "security": [ { "userToken": [] } ] } }, "/me/reviewer": { "post": { "summary": "Become a reviewer with a code from LEIN", "tags": [ "Contributors" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "userToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } } } } } } }, "/admin/reviewers": { "get": { "summary": "Reviewer invitations and their activity", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ] }, "post": { "summary": "Create a one-time reviewer code (shown once)", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" } } } } } } } }, "/admin/reviewers/{id}": { "delete": { "summary": "Remove a reviewer; they become a contributor again", "tags": [ "Admin" ], "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } }, "security": [ { "adminCookie": [] } ] } }, "/admin/export/tts": { "get": { "summary": "Voice-training (TTS) export: ZIP of approved speech with metadata.csv, speakers.csv and README; splits by speaker", "tags": [ "Admin" ], "security": [ { "adminCookie": [] } ], "parameters": [ { "name": "variety", "in": "query", "required": false, "schema": { "type": "string" }, "description": "kolokwa | liberian_english (omit for both)" }, { "name": "minQuality", "in": "query", "required": false, "schema": { "type": "string" }, "description": "0-1, minimum average reviewer quality (e.g. 0.8 = 4/5)" } ], "responses": { "200": { "description": "application/zip" }, "4XX": { "description": "Error: {\"error\": \"message\"}" } } } }, "/phrases.json": { "get": { "summary": "All sentences to read as phrase records {phrase, meaning, category} (text is CC0)", "tags": [ "Public" ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "e.g. Greeting" }, { "name": "variety", "in": "query", "required": false, "schema": { "type": "string" }, "description": "kolokwa | liberian_english" }, { "name": "full", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1 adds id and variety" } ], "responses": { "200": { "description": "Array of phrase records", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "https://lein-voice-commons.vercel.app/schemas/phrase.schema.json#/$defs/record" } } } } } } } }, "/phrases/categories": { "get": { "summary": "The official phrase categories", "tags": [ "Public" ], "responses": { "200": { "description": "{categories: string[]}" } } } }, "/admin/phrases/import": { "post": { "summary": "Check and import phrase records. Accepts one object, an array, or JSON Lines. dryRun checks only; any error stops the import unless allowPartial.", "tags": [ "Admin" ], "security": [ { "adminCookie": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "JSON text or an array of records" }, "dryRun": { "type": "boolean" }, "allowPartial": { "type": "boolean" }, "collection": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ok, saved, summary:{records, valid, errors, warnings, alreadyOnSite, toAdd}, issues:[{index, field, message, level}]}" }, "400": { "description": "Not JSON, or no records" } } } }, "/dictionary": { "get": { "summary": "Search the Liberian Kolokwa Dictionary", "tags": [ "Public" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "text to find in phrase, meaning, examples or spellings" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "greeting | expression | slang | word | question | proverb | exclamation | grammar" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "official category" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "draft | reviewed | verified | disputed" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "new | popular" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1-100" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "{total, entries, counts, categories, types}" } } } }, "/dictionary.json": { "get": { "summary": "Every public dictionary entry in the agreed format (CC0). ?status=verified for checked entries only", "tags": [ "Public" ], "responses": { "200": { "description": "Array of entries" } } } }, "/dictionary/today": { "get": { "summary": "Word of the day", "tags": [ "Public" ], "responses": { "200": { "description": "{entry}" } } } }, "/dictionary/{id}": { "get": { "summary": "One entry, e.g. LKD-00001", "tags": [ "Public" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{entry}" }, "404": { "description": "Not found" } } } }, "/dictionary/{id}/vote": { "post": { "summary": "Vote 1 (we say this) or -1 (not how we say it, optional fix). Two or more yes votes verify an entry; verified phrases become sentences to read.", "tags": [ "Contributors" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{status, votes}" } } } }, "/dictionary/suggest": { "post": { "summary": "Suggest a new entry (shown after an admin accepts it)", "tags": [ "Contributors" ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "{id}" }, "409": { "description": "Already in the dictionary" } } } }, "/admin/dictionary": { "get": { "summary": "Entries by status (suggested, disputed, ...) with voters' fixes", "tags": [ "Admin" ], "security": [ { "adminCookie": [] } ], "responses": { "200": { "description": "{entries, counts}" } } } }, "/admin/dictionary/{id}/decide": { "post": { "summary": "Set an entry's status; admin decisions are not changed by later votes", "tags": [ "Admin" ], "security": [ { "adminCookie": [] } ], "responses": { "200": { "description": "ok" } } } } } }