v1.0

Capsiynau v1 API reference

Every /api/v1/* endpoint with request bodies, responses, curl examples, and SDK equivalents. The official Node SDK wraps the core flow; this page is for direct REST work and for non-Node developers.

Authentication

Every endpoint uses a Bearer API key. Keys start with ck_live_.

Authorization: Bearer ck_live_YOUR_KEY
Get an API key
Official Node SDK

Wraps the core flow (submit, poll, export) with typed errors.

npm install @capsiynau/sdk-transcribe
View on npm

Core transcription

Submit a transcription job

Pro+
POST/api/v1/transcribe

Queues a transcription job for a project. Returns a jobId immediately; poll /api/v1/status to follow progress.

SDK equivalent: client.submit()
Request body
{ "projectId": "PROJECT_ID", "fileUrl": "https://example.com/audio.mp3", "sourceLanguage": "cy" }
Response
{ "jobId": "...", "projectId": "...", "engine": "assemblyai", "status": "queued" }
curl
curl -X POST "https://www.capsiynau.com/api/v1/transcribe" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","fileUrl":"https://...","sourceLanguage":"cy"}'

Poll job status

Pro+
GET/api/v1/status?jobId=JOB_ID

Returns the current status of a transcription job. Terminal statuses are 'done' (success), 'failed', and 'cancelled'.

SDK equivalent: client.getStatus() / client.waitFor()
Response
{ "job": { "id": "...", "status": "done", "project_id": "...", "error": null, "created_at": "...", "updated_at": "..." } }
curl
curl "https://www.capsiynau.com/api/v1/status?jobId=JOB_ID" -H "Authorization: Bearer YOUR_KEY"

Export the transcript

Pro+
GET/api/v1/export?projectId=PROJECT_ID&format=srt&track=original

Returns the project transcript in the requested format. Supported formats: json, srt, vtt, txt, ebutt, ttml. JSON returns parsed segments (each with start_ms, end_ms, text, language, and speaker_label when speaker diarisation has run); the others stream as file downloads with Content-Disposition: attachment.

SDK equivalent: client.getTranscript()
Response
JSON: { "project_id": "...", "source_language": "cy-GB", "segments": [{ "start_ms": 0, "end_ms": 2650, "text": "...", "language": "cy", "speaker_label": "Speaker 1" }, ...] }\nSRT/VTT/TXT/EBUTT/TTML: file download
curl
curl "https://www.capsiynau.com/api/v1/export?projectId=PROJECT_ID&format=json" \
  -H "Authorization: Bearer YOUR_KEY"

Intelligence

Generate SEO metadata

Studio+
POST/api/v1/metadata

Auto-generates summary, chapters, keywords, named entities, sentiment, and JSON-LD structured data from a completed transcript. Studio plan or above. Each call increments your monthly SEO Pack usage counter, returned inline in `seoPackUsage`.

Request body
{ "projectId": "PROJECT_ID" }
Response
{ "metadata": { "summary": "...", "chapters": [...], "keywords": [...], "entities": [...], "sentiment": "...", "jsonld": {...} }, "seoPackUsage": { "used": 1, "month": "2026-05" } }
curl
curl -X POST "https://www.capsiynau.com/api/v1/metadata" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID"}'

Generate Golden Moments

Studio+
POST/api/v1/moments

Returns up to 5 scored Golden Moments per project: timecodes, categories, bilingual reasons, and pre-cut SRT for each clip. Studio plan or above. Each call increments your monthly SEO Pack usage counter, returned inline in `seoPackUsage`.

Request body
{ "projectId": "PROJECT_ID" }
Response
{ "moments": [{ "start": 12.3, "end": 25.6, "category": "...", "reason_en": "...", "reason_cy": "...", "srt": "..." }], "seoPackUsage": { "used": 1, "month": "2026-05" } }
curl
curl -X POST "https://www.capsiynau.com/api/v1/moments" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID"}'

Translate short text (Welsh<->English)

Pro+
POST/api/v1/translate

Stateless text translation between Welsh and English. No project required. Use context: "tts" for short broadcast captions, "subtitle" for caption refinement.

Request body
{ "text": "Bore da", "targetLang": "en", "sourceLang": "cy", "context": "tts" }
Response
{ "text": "Good morning", "sourceLang": "cy", "targetLang": "en", "engine": "..." }
curl
curl -X POST "https://www.capsiynau.com/api/v1/translate" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Bore da","targetLang":"en","context":"tts"}'

Queue AI Intelligence job

Pro+
POST/api/v1/sessions/:id/intelligence

Generates summary + action points + todos for a live session. Worker calls Claude with Welsh-aware prompts. Results poll-able via GET on the same path.

Request body
{ "features": ["summary", "action_points", "todos"] }
Response
{ "requestId": "...", "sessionId": "...", "features": [...], "status": "queued" }
curl
curl -X POST "https://www.capsiynau.com/api/v1/sessions/SESSION_ID/intelligence" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"features":["summary","action_points","todos"]}'

Fetch Intelligence results

Pro+
GET/api/v1/sessions/:id/intelligence

Returns the latest summary, action_points, and todos for a session. Empty arrays if the job has not completed.

Response
{ "sessionId": "...", "session_type": "...", "summary": { "content": "...", "language": "cy", "generated_at": "...", "version": 1 }, "action_points": [...], "todos": [...] }
curl
curl "https://www.capsiynau.com/api/v1/sessions/SESSION_ID/intelligence" -H "Authorization: Bearer YOUR_KEY"

Resources

List projects

Pro+
GET/api/v1/projects

Returns projects scoped to the API key’s organisation. Supports limit + offset.

Response
{ "projects": [...], "total": 42, "limit": 20, "offset": 0 }
curl
curl "https://www.capsiynau.com/api/v1/projects" -H "Authorization: Bearer YOUR_KEY"

Create a project

Pro+
POST/api/v1/projects

Creates a new empty project. Returns the project record with a fresh id you pass to /transcribe.

Request body
{ "title": "My project", "source_language": "cy-GB", "welsh_dialect": "broadcast" }
Response
{ "project": { "id": "...", "title": "...", "status": "ready", "created_date": "..." } }
curl
curl -X POST "https://www.capsiynau.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"My project","source_language":"cy-GB"}'

Manage API keys

Pro+
GETPOSTDELETE/api/v1/keys

GET lists keys, POST creates a new key (returned once, never shown again), DELETE revokes by id. Issuance is also available in-app at /accountsettings.

Request body
POST: { "name": "My integration" }\nDELETE: { "id": "KEY_ID" }
Response
GET: { "keys": [...] }\nPOST: { "key": "ck_live_..." }  // raw key shown ONCE\nDELETE: { "ok": true }
curl
curl -X POST "https://www.capsiynau.com/api/v1/keys" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My integration"}'

Error codes

StatusCodeMeaning
200—Success
201—Created
400validation.*Bad request - missing or invalid parameter
401auth.*Invalid or revoked API key
402plan.requiredPlan upgrade required for this endpoint
404not_found.*Resource not found
405method.not_allowedMethod not allowed on this endpoint
409CONFLICT_RACEConflict - retry the request (race recovery)
422validation.*Unprocessable entity - validation failed
429quota.exceededRate limit or quota exceeded - check Retry-After
500server.*Server error - retry with backoff

Error bodies always include { error: '<string>' } and (from v1.1) a structured 'code' field. The SDK throws typed classes (AuthError, PlanGateError, QuotaError, ValidationError, NetworkError, ServerError).

DevelopersAPI overviewCode samplesError code catalogSDK source