{"openapi":"3.1.0","info":{"title":"VegaCap Platform API","version":"1.0.0","description":"Embed psychometric assessments into any platform. REST API + embeddable SDK for DiSC, AAPA, LPM, FRA, and TFD assessments.","contact":{"email":"support@vegacapltd.com","url":"https://developer.vegacapltd.com"}},"servers":[{"url":"https://vegacapltd.com/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/sessions":{"post":{"summary":"Create assessment session","operationId":"createSession","tags":["Sessions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionRequest"}}}},"responses":{"201":{"description":"Session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"No available licenses"},"403":{"description":"Assessment not enabled"}}},"get":{"summary":"List sessions","operationId":"listSessions","tags":["Sessions"],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["created","in_progress","completed","failed","expired"]}},{"name":"assessment_type","in":"query","schema":{"type":"string","enum":["aapa","disc","fra","lpm","lpm_u","tfd","tfd_plus"]}},{"name":"candidate_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Session list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionList"}}}}}}},"/sessions/{id}":{"get":{"summary":"Get session","operationId":"getSession","tags":["Sessions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session details with results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResult"}}}},"404":{"description":"Session not found"}}},"delete":{"summary":"Soft-delete session (GDPR)","operationId":"deleteSession","tags":["Sessions"],"description":"GDPR right-to-forget. Zeros out candidate email/name, metadata, config, responses, and result summary, then stamps deletedAt. The row is retained as a tombstone for audit and idempotency-key protection. Subsequent GET/LIST calls return 404.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Session soft-deleted"},"404":{"description":"Not found"}}}},"/sessions/{id}/submit":{"post":{"summary":"Submit assessment responses","operationId":"submitSession","tags":["Sessions"],"description":"Submit responses for the assessment. The request body varies by assessment type.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Submitted successfully"},"400":{"description":"Validation error"},"409":{"description":"Already completed"},"410":{"description":"Session expired"}}}},"/sessions/{id}/report.pdf":{"get":{"summary":"Download PDF report","operationId":"downloadReport","tags":["Sessions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"PDF file","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Session not completed"}}}},"/status":{"get":{"summary":"Platform health status","operationId":"getStatus","tags":["Platform"],"description":"Public, unauthenticated health endpoint. Returns database, webhook-queue, and cron probes. Cache-Control: no-store. CORS: *.","security":[],"responses":{"200":{"description":"Health summary (always 200 — check the `status` field)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}}}}},"/assessments/types":{"get":{"summary":"List assessment types","operationId":"listAssessmentTypes","tags":["Assessments"],"responses":{"200":{"description":"Available assessment types"}}}},"/assessments/questions/{type}":{"get":{"summary":"Get questions for assessment type","operationId":"getQuestions","tags":["Assessments"],"parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["aapa","disc","fra","lpm","lpm_u","tfd","tfd_plus"]}}],"responses":{"200":{"description":"Question bank"}}}},"/webhooks":{"post":{"summary":"Register webhook endpoint","operationId":"createWebhook","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}}},"responses":{"201":{"description":"Webhook created"}}},"get":{"summary":"List webhook endpoints","operationId":"listWebhooks","tags":["Webhooks"],"responses":{"200":{"description":"Webhook list"}}}},"/webhooks/{id}":{"patch":{"summary":"Update webhook","operationId":"updateWebhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated"}}},"delete":{"summary":"Delete webhook","operationId":"deleteWebhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Secret API key (vegacap_sk_live_...)"}},"schemas":{"CreateSessionRequest":{"type":"object","required":["assessmentType","candidate"],"properties":{"assessmentType":{"type":"string","enum":["aapa","disc","fra","lpm","lpm_u","tfd","tfd_plus"]},"candidate":{"type":"object","required":["externalId"],"properties":{"externalId":{"type":"string","description":"Your platform's user ID"},"email":{"type":"string","format":"email"},"name":{"type":"string"}}},"config":{"type":"object","description":"Assessment-specific configuration"},"metadata":{"type":"object","description":"Arbitrary key-value pairs returned in webhooks"},"redirectUrl":{"type":"string","format":"uri"},"expiresIn":{"type":"integer","minimum":300,"maximum":604800,"default":86400}}},"Session":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["created","in_progress","completed","failed","expired"]},"assessmentType":{"type":"string"},"sessionToken":{"type":"string","description":"Pass to embed SDK or redirect URL"},"assessmentUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"candidate":{"type":"object"},"metadata":{"type":"object"}}},"SessionResult":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"assessmentType":{"type":"string"},"results":{"type":"object","nullable":true,"description":"Scoring results (varies by assessment type)"},"reportUrl":{"type":"string","nullable":true},"metadata":{"type":"object"},"completedAt":{"type":"string","format":"date-time","nullable":true}}},"SessionList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"CreateWebhookRequest":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["session.completed","session.failed","session.started","session.expired","session.created","report.generated"]}},"description":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"doc_url":{"type":"string","format":"uri"},"details":{"type":"object"}}}}},"StatusResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","down"]},"checks":{"type":"object","properties":{"database":{"type":"object","properties":{"ok":{"type":"boolean"},"latencyMs":{"type":"integer"}}},"webhookQueue":{"type":"object","properties":{"ok":{"type":"boolean"},"pendingCount":{"type":"integer"},"dlqCount":{"type":"integer"}}},"cron":{"type":"object","properties":{"ok":{"type":"boolean"},"lastRunAt":{"type":"string","format":"date-time","nullable":true}}}}},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}