{ "openapi": "3.1.0", "info": { "title": "CertBoost API", "version": "1.0.0", "description": "Read learner progress, run graded practice quizzes, and manage webhooks. Authenticate with `Authorization: Bearer `. Personal keys act on their owner; system keys pass `userId`. Errors are `{\"error\":{\"code\",\"message\"}}`. Rate limit: 120 requests/minute per key." }, "servers": [ { "url": "/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Learners" }, { "name": "Catalog" }, { "name": "Attempts" }, { "name": "Practice" }, { "name": "Webhooks" } ], "paths": { "/me": { "get": { "summary": "Get the learner's profile", "tags": [ "Learners" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "System keys only: the learner to act on." } ] } }, "/certifications": { "get": { "summary": "List certifications", "tags": [ "Catalog" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Certification" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" } } ] } }, "/progress": { "get": { "summary": "Progress summary", "tags": [ "Learners" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Progress" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "System keys only: the learner to act on." }, { "name": "recent", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 200 } } ] } }, "/attempts": { "get": { "summary": "List exam attempts", "tags": [ "Attempts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attempt" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "System keys only: the learner to act on." }, { "name": "certificationId", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 200 } } ] } }, "/attempts/{attemptId}": { "get": { "summary": "Get one attempt with answers and explanations", "tags": [ "Attempts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attempt" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "attemptId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "System keys only: the learner to act on." }, { "name": "includeQuestions", "in": "query", "schema": { "type": "boolean", "default": true } } ] } }, "/review-queue": { "get": { "summary": "Questions due for spaced-repetition review", "tags": [ "Learners" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewQueue" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "System keys only: the learner to act on." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ] } }, "/practice-sessions": { "post": { "summary": "Start a graded practice quiz", "tags": [ "Practice" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PracticeSession" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "description": "Returns questions without answers and a single-use sessionToken. Requires an active plan for personal keys.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartPractice" } } } }, "x-permission": "ReadWrite" } }, "/practice-sessions/submit": { "post": { "summary": "Submit answers and score the quiz", "tags": [ "Practice" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attempt" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } }, "description": "Records the attempt, updates the review queue and fires attempt.completed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitPractice" } } } }, "x-permission": "ReadWrite" } }, "/webhook-events": { "get": { "summary": "List webhook event types", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/webhooks": { "get": { "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "400": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "x-permission": "ReadWrite" } }, "/webhooks/{id}": { "get": { "summary": "Get a webhook endpoint", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "summary": "Update a webhook endpoint", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" } } } }, "x-permission": "ReadWrite" }, "delete": { "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permission": "ReadWrite" } }, "/webhooks/{id}/rotate-secret": { "post": { "summary": "Rotate the signing secret", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreated" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permission": "ReadWrite" } }, "/webhooks/{id}/test": { "post": { "summary": "Send a webhook.ping", "tags": [ "Webhooks" ], "responses": { "202": { "description": "Queued" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permission": "ReadWrite" } }, "/webhooks/{id}/deliveries": { "get": { "summary": "Recent deliveries", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ] } }, "/webhook-deliveries/{deliveryId}/redeliver": { "post": { "summary": "Redeliver an event", "tags": [ "Webhooks" ], "responses": { "202": { "description": "Queued" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permission": "ReadWrite" } } }, "webhooks": { "attempt.completed": { "post": { "summary": "attempt.completed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds" } } } }, "assignment.created": { "post": { "summary": "assignment.created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds" } } } }, "subscription.activated": { "post": { "summary": "subscription.activated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds" } } } }, "webhook.ping": { "post": { "summary": "webhook.ping", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "CertBoost API key (cb_\u2026). Also accepted as X-CertBoost-Key." } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Profile": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "object", "properties": { "tier": { "type": "string" }, "active": { "type": "boolean" }, "renewsOrEndsAt": { "type": "string", "format": "date-time" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } }, "Certification": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string" } } }, "Progress": { "type": "object", "properties": { "userId": { "type": "string" }, "totalAttempts": { "type": "integer" }, "overallAveragePercent": { "type": "number" }, "passingAttempts": { "type": "integer" }, "categoriesAttempted": { "type": "integer" }, "recentAttempts": { "type": "array", "items": { "type": "object", "properties": { "attemptId": { "type": "string" }, "categoryId": { "type": "integer" }, "categoryName": { "type": "string" }, "correct": { "type": "integer" }, "total": { "type": "integer" }, "percent": { "type": "number" }, "taken": { "type": "string", "format": "date-time" } } } }, "perCategory": { "type": "array", "items": { "type": "object", "properties": { "categoryId": { "type": "integer" }, "categoryName": { "type": "string" }, "attempts": { "type": "integer" }, "averagePercent": { "type": "number" }, "bestPercent": { "type": "number" }, "lastAttempt": { "type": "string", "format": "date-time" } } } } } }, "Option": { "type": "object", "properties": { "letter": { "type": "string" }, "text": { "type": "string" } } }, "Question": { "type": "object", "properties": { "number": { "type": "integer" }, "question": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Option" } } } }, "QuestionResult": { "allOf": [ { "$ref": "#/components/schemas/Question" }, { "type": "object", "properties": { "yourAnswer": { "type": "string" }, "correctAnswer": { "type": "string" }, "correct": { "type": "boolean" }, "explanation": { "type": "string" } } } ] }, "Attempt": { "type": "object", "properties": { "attemptId": { "type": "string" }, "certificationId": { "type": "integer" }, "certificationName": { "type": "string" }, "correct": { "type": "integer" }, "total": { "type": "integer" }, "percent": { "type": "number" }, "passed": { "type": "boolean" }, "takenAt": { "type": "string", "format": "date-time" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionResult" } } } }, "ReviewQueue": { "type": "object", "properties": { "dueNow": { "type": "integer" }, "totalInQueue": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "certificationId": { "type": "integer" }, "certificationName": { "type": "string" }, "dueAt": { "type": "string", "format": "date-time" }, "repetitions": { "type": "integer" }, "question": { "$ref": "#/components/schemas/Question" } } } } } }, "StartPractice": { "type": "object", "required": [ "certificationId" ], "properties": { "certificationId": { "type": "integer" }, "count": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50 }, "mode": { "type": "string", "enum": [ "random", "adaptive" ], "default": "random" }, "userId": { "type": "string" } } }, "PracticeSession": { "type": "object", "properties": { "sessionToken": { "type": "string" }, "certificationId": { "type": "integer" }, "certificationName": { "type": "string" }, "mode": { "type": "string" }, "questionCount": { "type": "integer" }, "timeLimitMinutes": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" }, "passMarkPercent": { "type": "integer" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" } }, "instructions": { "type": "string" } } }, "SubmitPractice": { "type": "object", "required": [ "sessionToken", "answers" ], "properties": { "sessionToken": { "type": "string" }, "answers": { "type": "array", "items": { "type": "string" }, "description": "One option letter per question, in order." }, "userId": { "type": "string" } } }, "WebhookCreate": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "attempt.completed", "assignment.created", "subscription.activated", "*" ] } }, "description": { "type": "string" }, "secret": { "type": "string", "minLength": 16, "description": "Optional; generated when omitted." } } }, "WebhookUpdate": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "active": { "type": "boolean" } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "hasSecret": { "type": "boolean" }, "secretPreview": { "type": "string" }, "active": { "type": "boolean" }, "disabledReason": { "type": "string" }, "lastDeliveryAt": { "type": "string", "format": "date-time" }, "lastStatusCode": { "type": "integer" } } }, "WebhookCreated": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Shown only on creation and rotation." } } } ] }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "subscriptionId": { "type": "string" }, "event": { "type": "string" }, "eventId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "attempts": { "type": "integer" }, "lastStatusCode": { "type": "integer" }, "lastError": { "type": "string" }, "lastDurationMs": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "nextAttemptAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } } }, "WebhookEnvelope": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "apiVersion": { "type": "string" }, "deliveryId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } } } } }