{ "openapi": "3.0.0", "info": { "title": "Erika API", "version": "1.0.0", "description": "Erika is an AI-first applicant tracking system. This is the REST API for external integrations — authenticate with an API key from Settings → API Keys." }, "servers": [ { "url": "https://app.erikawork.com/api", "description": "Erika production" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "API key from Settings → API Keys. Format: ek_live_<32 hex>. Permissions are bound to the key at creation time." } }, "schemas": { "Organization": { "type": "object", "properties": { "id": { "type": "string" }, "pid": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "timezone": { "type": "string" }, "language": { "type": "string" }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "pid", "name", "slug", "timezone", "language", "dateCreated" ] }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "success", "error" ], "description": "Error response. Quote the requestId when contacting support." }, "Job": { "type": "object", "properties": { "id": { "type": "string" }, "pid": { "type": "integer" }, "title": { "type": "string" }, "externalRef": { "type": "string", "nullable": true, "maxLength": 100, "description": "Your own reference for this position, typically the job ID from your ATS. Free text, up to 100 characters. Every application on this job returns it as `jobExternalRef`, so you can match applications without a lookup.", "example": "RS-2026-0412" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "open", "paused", "closed", "archived" ] }, "hiringManagerId": { "type": "string", "nullable": true }, "jobDetails": { "$ref": "#/components/schemas/JobDetails" }, "dateCreated": { "type": "string", "format": "date-time" }, "dateUpdated": { "type": "string", "format": "date-time" } }, "required": [ "id", "pid", "title", "externalRef", "description", "status", "hiringManagerId", "jobDetails", "dateCreated", "dateUpdated" ] }, "JobDetails": { "type": "object", "nullable": true, "properties": { "location": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "employmentType": { "type": "string", "nullable": true }, "remote": { "type": "boolean", "nullable": true }, "salaryMin": { "type": "number", "nullable": true }, "salaryMax": { "type": "number", "nullable": true }, "salaryCurrency": { "type": "string", "nullable": true } } }, "Candidate": { "type": "object", "properties": { "id": { "type": "string" }, "pid": { "type": "integer" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "nullable": true, "format": "email" }, "phonePrefix": { "type": "string", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "linkedinUrl": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "dateCreated": { "type": "string", "format": "date-time" }, "dateUpdated": { "type": "string", "format": "date-time" } }, "required": [ "id", "pid", "firstName", "lastName", "email", "phonePrefix", "phoneNumber", "linkedinUrl", "source", "tags", "dateCreated", "dateUpdated" ] }, "CandidateDetail": { "allOf": [ { "$ref": "#/components/schemas/Candidate" }, { "type": "object", "properties": { "applications": { "type": "array", "items": { "$ref": "#/components/schemas/CandidateApplication" } } }, "required": [ "applications" ] } ] }, "CandidateApplication": { "type": "object", "properties": { "id": { "type": "string" }, "jobId": { "type": "string" }, "jobTitle": { "type": "string" }, "jobStatus": { "type": "string" }, "currentStage": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" } }, "required": [ "id", "name", "category" ] }, "status": { "type": "string" }, "averageRating": { "type": "number", "nullable": true }, "ratingCount": { "type": "integer" }, "applicationAnswers": { "type": "array", "items": { "type": "object", "properties": { "questionKey": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" } }, "required": [ "question", "answer" ] }, "description": "Answers the candidate gave on the application form" }, "candidateProfile": { "$ref": "#/components/schemas/CandidateProfile" }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "jobId", "jobTitle", "jobStatus", "currentStage", "status", "averageRating", "ratingCount", "applicationAnswers", "candidateProfile", "dateCreated" ] }, "CandidateProfile": { "type": "object", "nullable": true, "properties": { "startAvailability": { "type": "object", "nullable": true, "properties": { "text": { "type": "string", "example": "Employed, 2-month notice" }, "tier": { "type": "string", "nullable": true, "enum": [ "immediate", "weeks", "months", null ], "description": "Coarse band derived from the text. Null when it names a bare date we do not parse — read `text` instead." } }, "required": [ "text", "tier" ], "description": "How soon they can start / notice period" }, "salaryExpectation": { "type": "object", "nullable": true, "properties": { "text": { "type": "string", "example": "45 000 CZK / month gross" } }, "required": [ "text" ], "description": "Verbatim, with currency and period as they said it" }, "jobSearchStatus": { "type": "object", "nullable": true, "properties": { "text": { "type": "string" }, "intent": { "type": "string", "nullable": true, "enum": [ "active", "open", "browsing", null ] }, "nuance": { "type": "string", "nullable": true, "description": "Whatever they said beyond the bucket" } }, "required": [ "text", "intent", "nuance" ] }, "bestTimeToCall": { "type": "object", "nullable": true, "properties": { "text": { "type": "string", "example": "weekdays after 3pm" }, "timezone": { "type": "string", "description": "IANA zone the windows are expressed in", "example": "Europe/Prague" }, "anytime": { "type": "boolean", "description": "Treat as 09:00–18:00 local" }, "noCalls": { "type": "boolean", "description": "Prefers text, not calls" }, "windows": { "type": "array", "items": { "$ref": "#/components/schemas/CallWindow" } }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/CallException" } }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "text", "timezone", "anytime", "noCalls", "windows", "exceptions", "updatedAt" ] }, "capturedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the facts were captured" }, "isStale": { "type": "boolean", "description": "Captured over 30 days ago — show the date, do not present as current" } }, "required": [ "startAvailability", "salaryExpectation", "jobSearchStatus", "bestTimeToCall", "capturedAt", "isStale" ], "description": "Candidate-stated situation facts, collected during screening. Null when the API key lacks VIEW_SCREENING or the candidate stated none of them." }, "CallWindow": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "description": "ISO weekdays, 1 = Monday … 7 = Sunday" }, "from": { "type": "string", "description": "\"HH:mm\", candidate-local" }, "to": { "type": "string", "description": "\"HH:mm\", exclusive end" } }, "required": [ "days", "from", "to" ] }, "CallException": { "type": "object", "properties": { "date": { "type": "string", "description": "\"YYYY-MM-DD\", candidate-local" }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "date", "from", "to" ] }, "ApplicationSummary": { "type": "object", "properties": { "id": { "type": "string" }, "candidateId": { "type": "string" }, "candidateName": { "type": "string" }, "candidateEmail": { "type": "string", "nullable": true }, "candidateTags": { "type": "array", "items": { "type": "string" } }, "jobId": { "type": "string" }, "jobTitle": { "type": "string" }, "jobExternalRef": { "type": "string", "nullable": true, "description": "The job's `externalRef`: your own ATS position ID, read live from the job (so it reflects the job's current value, also on older applications). Null when the job has none.", "example": "RS-2026-0412" }, "stageName": { "type": "string" }, "stageCategory": { "type": "string" }, "source": { "type": "string" } }, "required": [ "id", "candidateId", "candidateName", "candidateEmail", "candidateTags", "jobId", "jobTitle", "jobExternalRef", "stageName", "stageCategory", "source" ] }, "ApplicationListItem": { "type": "object", "properties": { "id": { "type": "string" }, "pid": { "type": "integer" }, "candidate": { "type": "object", "properties": { "id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "nullable": true } }, "required": [ "id", "firstName", "lastName", "email" ] }, "jobExternalRef": { "type": "string", "nullable": true, "description": "The job's `externalRef`: your own ATS position ID, read live from the job (so it reflects the job's current value, also on older applications). Null when the job has none.", "example": "RS-2026-0412" }, "currentStage": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" } }, "required": [ "id", "name", "category" ] }, "status": { "type": "string", "enum": [ "active", "rejected", "withdrawn", "hired" ] }, "source": { "type": "string" }, "isViewed": { "type": "boolean" }, "averageRating": { "type": "number", "nullable": true }, "ratingCount": { "type": "integer" }, "recentActivities": { "type": "array", "items": { "type": "object", "properties": { "activityType": { "type": "string" }, "actorType": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "activityType", "actorType", "summary", "dateCreated" ] } }, "candidateProfile": { "$ref": "#/components/schemas/CandidateProfile" }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "pid", "candidate", "jobExternalRef", "currentStage", "status", "source", "isViewed", "averageRating", "ratingCount", "recentActivities", "candidateProfile", "dateCreated" ] }, "Application": { "type": "object", "properties": { "id": { "type": "string" }, "pid": { "type": "integer" }, "candidate": { "type": "object", "properties": { "id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phonePrefix": { "type": "string", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true } }, "required": [ "id", "firstName", "lastName", "email", "phonePrefix", "phoneNumber" ] }, "candidateProfile": { "$ref": "#/components/schemas/CandidateProfile" }, "job": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ] }, "jobExternalRef": { "type": "string", "nullable": true, "description": "The job's `externalRef`: your own ATS position ID, read live from the job (so it reflects the job's current value, also on older applications). Null when the job has none.", "example": "RS-2026-0412" }, "currentStage": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" } }, "required": [ "id", "name", "category" ] }, "status": { "type": "string", "enum": [ "active", "rejected", "withdrawn", "hired" ] }, "source": { "type": "string" }, "firstViewedAt": { "type": "string", "nullable": true, "format": "date-time" }, "firstViewedBy": { "type": "string", "nullable": true }, "isViewed": { "type": "boolean" }, "rejectedAt": { "type": "string", "nullable": true, "format": "date-time" }, "rejectionReason": { "type": "string", "nullable": true }, "activities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "activityType": { "type": "string" }, "actorType": { "type": "string" }, "actorId": { "type": "string", "nullable": true }, "actorName": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "dateCreated": { "type": "string", "format": "date-time" }, "editedAt": { "type": "string", "nullable": true, "format": "date-time" }, "editedByName": { "type": "string", "nullable": true } }, "required": [ "id", "activityType", "actorType", "actorId", "actorName", "summary", "metadata", "dateCreated", "editedAt", "editedByName" ] } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "fileType": { "type": "string" }, "publicUrl": { "type": "string", "nullable": true }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "fileName", "fileType", "publicUrl", "dateCreated" ] } }, "ratings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "raterId": { "type": "string" }, "raterName": { "type": "string" }, "rating": { "type": "integer" }, "commentKeys": { "type": "array", "items": { "type": "string" } }, "comment": { "type": "string", "nullable": true }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "raterId", "raterName", "rating", "commentKeys", "comment", "dateCreated" ] } }, "averageRating": { "type": "number", "nullable": true }, "ratingCount": { "type": "integer" }, "applicationAnswers": { "type": "array", "items": { "type": "object", "properties": { "questionKey": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "source": { "type": "string" }, "answeredAt": { "type": "string" } }, "required": [ "questionKey", "question", "answer", "source" ] } }, "answerFit": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "Advisory per-answer requirement labels. Null when not evaluated." }, "qualifier": { "type": "object", "nullable": true, "properties": { "verdict": { "type": "string", "enum": [ "qualified", "not_qualified" ] }, "reason": { "type": "string" }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "must", "nice" ] }, "status": { "type": "string", "enum": [ "met", "failed", "unclear", "unverified" ], "description": "unclear = ambiguous answer; unverified = nothing collected could show it (never counts against the candidate)." } }, "required": [ "text", "kind", "status" ] } }, "basis": { "type": "string", "enum": [ "form", "prescreen" ], "description": "What the judgement ran on: the application form only, or the form plus the prescreen result." }, "moved": { "type": "boolean", "description": "Whether Erika moved the card to the next stage." }, "judgedAt": { "type": "string" }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "met": { "type": "array", "items": { "type": "string" } } }, "required": [ "jobId", "title", "met" ] }, "description": "Not qualified only: up to 2 of the company's other open positions this candidate fits, with what they clearly meet there. Never added automatically; positions that closed or that the candidate is already in are left out." } }, "required": [ "verdict", "reason", "requirements", "basis", "moved", "judgedAt" ], "description": "AI qualifier result for sourced candidates: the position's must-haves checked one by one. It never rejects. Null when not judged (qualifier off, not a sourced candidate, or not run yet)." }, "applicationConsents": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "text": { "type": "string" }, "accepted": { "type": "boolean" }, "isRequired": { "type": "boolean" }, "respondedAt": { "type": "string", "nullable": true } }, "required": [ "key", "text", "accepted", "respondedAt" ] } }, "dateCreated": { "type": "string", "format": "date-time" }, "dateUpdated": { "type": "string", "format": "date-time" } }, "required": [ "id", "pid", "candidate", "candidateProfile", "job", "jobExternalRef", "currentStage", "status", "source", "firstViewedAt", "firstViewedBy", "isViewed", "rejectedAt", "rejectionReason", "activities", "attachments", "ratings", "averageRating", "ratingCount", "applicationAnswers", "answerFit", "qualifier", "applicationConsents", "dateCreated", "dateUpdated" ] }, "ApplicationBulkDeleteResult": { "type": "object", "properties": { "total": { "type": "integer" }, "deletedCount": { "type": "integer" }, "skippedCount": { "type": "integer" }, "deletedIds": { "type": "array", "items": { "type": "string" } }, "jobTitle": { "type": "string", "nullable": true } }, "required": [ "total", "deletedCount", "skippedCount", "deletedIds", "jobTitle" ] }, "Rating": { "type": "object", "properties": { "workerId": { "type": "string" }, "workerName": { "type": "string", "nullable": true }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "commentKeys": { "type": "array", "items": { "type": "string" } }, "comment": { "type": "string", "nullable": true }, "dateCreated": { "type": "string", "format": "date-time" }, "dateUpdated": { "type": "string", "format": "date-time" } }, "required": [ "workerId", "workerName", "rating", "commentKeys", "comment", "dateCreated", "dateUpdated" ] }, "Attachment": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "fileType": { "type": "string", "nullable": true }, "contentType": { "type": "string" }, "size": { "type": "integer" }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "fileName", "fileType", "contentType", "size", "dateCreated" ] }, "PipelineTemplate": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "sourced", "applied", "screening", "interview", "evaluation", "offer", "hired", "rejected", "custom" ] }, "orderIndex": { "type": "integer" } }, "required": [ "id", "name", "category", "orderIndex" ] } }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "isDefault", "stages", "dateCreated" ] }, "RejectionReason": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string", "nullable": true }, "isArchived": { "type": "boolean" }, "orderIndex": { "type": "integer" } }, "required": [ "id", "label", "description", "isArchived", "orderIndex" ] }, "WebhookRegistration": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "endpointUrl": { "type": "string", "format": "uri" }, "description": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string", "enum": [ "candidate.created", "candidate.updated", "application.created", "application.stage_changed", "application.qualified", "application.unqualified", "application.status_changed", "screening.completed", "screening.failed" ], "description": "Subscribe to one of the documented event names. See the event catalog in the Developers page." } }, "isActive": { "type": "boolean" }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "endpointUrl", "description", "events", "isActive", "dateCreated" ] }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string", "enum": [ "candidate.created", "candidate.updated", "application.created", "application.stage_changed", "application.qualified", "application.unqualified", "application.status_changed", "screening.completed", "screening.failed" ], "description": "Subscribe to one of the documented event names. See the event catalog in the Developers page." }, "status": { "type": "string", "enum": [ "pending", "processing", "delivered", "failed" ] }, "attempts": { "type": "integer" }, "statusCode": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true }, "deliveredAt": { "type": "string", "nullable": true, "format": "date-time" }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "eventType", "status", "attempts", "statusCode", "error", "deliveredAt", "dateCreated" ] }, "SourcingCampaign": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "jobId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "ready", "launching", "active", "paused", "completed", "cancelled" ] }, "finishedOn": { "type": "string", "nullable": true, "description": "Day the campaign ran to its end date (YYYY-MM-DD); null while it can still deliver" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Set when a user archived (hid) the campaign in the app. Nothing is deleted." }, "creatives": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "semanticName": { "type": "string", "nullable": true }, "creativeType": { "type": "string" }, "fileCount": { "type": "integer" } }, "required": [ "id", "semanticName", "creativeType" ] } }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "jobId", "status", "dateCreated" ] }, "SourcingCreative": { "type": "object", "properties": { "id": { "type": "string" }, "semanticName": { "type": "string", "nullable": true }, "creativeType": { "type": "string", "enum": [ "ugc", "street_interview", "radio_interview", "pov_walkup", "studio_backstage" ] }, "languageCode": { "type": "string", "nullable": true }, "sourcingCampaignId": { "type": "string" }, "script": { "type": "string", "nullable": true }, "prompt": { "type": "string", "nullable": true }, "files": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "semanticName", "creativeType", "languageCode", "sourcingCampaignId", "script", "prompt", "dateCreated" ] }, "SourcingAdvert": { "type": "object", "properties": { "id": { "type": "string" }, "creativeId": { "type": "string" }, "metaAdId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "dateCreated": { "type": "string", "format": "date-time" } }, "required": [ "id", "creativeId", "metaAdId", "status", "dateCreated" ] }, "CampaignBuildAccepted": { "type": "object", "properties": { "buildId": { "type": "string" }, "status": { "type": "string" }, "statusUrl": { "type": "string" }, "webhookSecret": { "type": "string", "description": "Shown ONCE. Verify the x-webhook-signature (base64 HMAC-SHA256) on the callback with it." } }, "required": [ "buildId", "status", "statusUrl" ] }, "CreateCampaignBuild": { "type": "object", "properties": { "jobDescription": { "type": "string", "minLength": 50, "maxLength": 20000, "description": "Description Erika builds a NEW job from. Provide exactly one of jobDescription or jobId." }, "jobId": { "type": "string", "format": "uuid", "description": "Reuse an EXISTING Erika job (no new job is created); targeting is seeded from its details. Provide exactly one of jobDescription or jobId." }, "budget": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Total credit envelope. Production (videos + AI) is spent from it; the remainder funds Meta." }, "budgetCurrency": { "type": "string", "enum": [ "CREDITS", "USD", "EUR" ], "default": "CREDITS" }, "duration": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Campaign run length in days" }, "city": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Work-location city. Inferred from the job description when omitted." }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO-3166 alpha-2 (e.g. CZ). Inferred from the job description when omitted." }, "language": { "type": "string", "minLength": 2, "maxLength": 5, "description": "Ad + screening language (e.g. cs). Inferred from the job description when omitted." }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Scheduled launch day, ISO YYYY-MM-DD. Omitted launches today. A past date is clamped to now.", "example": "2026-07-01" }, "callbackUrl": { "type": "string", "format": "uri", "description": "HTTPS endpoint POSTed a signed result on completion/failure" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Caller-defined tracking, echoed back verbatim on the status endpoint and the completion webhook (your job id, client, brand, campaign ref). Opaque to Erika. Up to 20 keys; key <= 40 chars, value <= 500 chars.", "example": { "externalJobId": "REQ-4821", "client": "Acme Staffing", "brand": "Acme Logistics" } }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 255, "description": "Required. A retry with the same key returns the same build (no double spend)." } }, "required": [ "budget", "duration", "idempotencyKey" ] }, "CampaignBuildStatus": { "type": "object", "properties": { "buildId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "step": { "type": "string" }, "campaignId": { "type": "string", "nullable": true }, "jobId": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The tracking data you submitted on create, echoed back. Absent if none was sent." }, "links": { "type": "object", "properties": { "self": { "type": "string" } }, "required": [ "self" ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true } }, "required": [ "code", "message" ] }, "dateCreated": { "type": "string", "format": "date-time" }, "dateUpdated": { "type": "string", "format": "date-time" } }, "required": [ "buildId", "status", "step", "campaignId", "jobId", "links", "dateCreated", "dateUpdated" ] }, "CreditPurchaseHistory": { "type": "object", "properties": { "purchases": { "type": "array", "items": { "$ref": "#/components/schemas/CreditPurchase" } }, "hasMore": { "type": "boolean", "description": "True when more purchases exist past this page." }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `before` to fetch the next page. Null on the last page." } }, "required": [ "purchases", "hasMore", "nextCursor" ] }, "CreditPurchase": { "type": "object", "properties": { "date": { "type": "string", "format": "date-time", "description": "When the purchase was made." }, "kind": { "type": "string", "enum": [ "manual", "auto_recharge", "subscription", "granted" ], "description": "manual = one-off top-up you bought; auto_recharge = charged automatically when the balance ran low; subscription = monthly plan credit grant (renewal, initial subscribe, or plan change); granted = credits Erika added to your account at no charge (no amount, no invoice)." }, "credits": { "type": "integer", "description": "Credits granted by this purchase." }, "amount": { "type": "integer", "nullable": true, "description": "Money charged in MINOR units of `currency` (e.g. 425000 = 4,250.00 CZK). Null only for legacy top-ups recorded before the amount was stored." }, "currency": { "type": "string", "nullable": true, "description": "Lowercase ISO currency code (e.g. \"czk\"), or null if unknown." }, "invoiceId": { "type": "string", "nullable": true, "description": "Stripe invoice id, when one exists." }, "reference": { "type": "string", "nullable": true, "description": "Stripe checkout-session/invoice id or auto-recharge attempt id." } }, "required": [ "date", "kind", "credits", "amount", "currency", "invoiceId", "reference" ] }, "BillingBalance": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "free", "starter", "growth", "scale", "pro" ], "description": "Active subscription plan" }, "creditsRemaining": { "type": "integer", "minimum": 0 }, "creditsMonthly": { "type": "integer", "nullable": true, "minimum": 0 }, "trialEndsAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "plan", "creditsRemaining", "creditsMonthly", "trialEndsAt" ] } }, "parameters": {} }, "paths": { "/organizations/me": { "get": { "tags": [ "Organization" ], "summary": "Get current organization", "description": "Returns the organization associated with the API key. Note: PATCH /organizations/me is web-only.", "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Organization" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/jobs": { "get": { "tags": [ "Jobs" ], "summary": "List jobs", "parameters": [ { "schema": { "type": "string", "enum": [ "draft", "open", "paused", "closed", "archived" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Jobs page", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `cursor` to fetch the next page. Null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "success", "data", "nextCursor", "hasMore" ], "description": "Cursor-paginated success response" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Jobs" ], "summary": "Create job", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "externalRef": { "type": "string", "maxLength": 100, "description": "Your own reference for this position, typically the job ID from your ATS. Free text, up to 100 characters. Every application on this job returns it as `jobExternalRef`, so you can match applications without a lookup.", "example": "RS-2026-0412" }, "description": { "type": "string", "maxLength": 20000 }, "pipelineTemplateId": { "type": "string" }, "hiringManagerId": { "type": "string" }, "jobDetails": { "$ref": "#/components/schemas/JobDetails" }, "screeningConfig": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "title", "pipelineTemplateId" ] } } } }, "responses": { "201": { "description": "Created. Fetch GET /jobs/{id} for the full job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "stageCount": { "type": "integer" }, "deduplicated": { "type": "boolean", "description": "True when an identical job created moments ago was reused instead." } }, "required": [ "id", "title", "stageCount" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/jobs/{id}": { "get": { "tags": [ "Jobs" ], "summary": "Get job by ID", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Job", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Job" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Jobs" ], "summary": "Update job", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "externalRef": { "type": "string", "maxLength": 100, "description": "Send an empty string to clear it.", "example": "RS-2026-0412" }, "description": { "type": "string", "maxLength": 20000 }, "hiringManagerId": { "type": "string", "nullable": true }, "jobDetails": { "$ref": "#/components/schemas/JobDetails" }, "screeningConfig": { "type": "object", "additionalProperties": { "nullable": true } } } } } } }, "responses": { "200": { "description": "Updated. Fetch GET /jobs/{id} for the full job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Jobs" ], "summary": "Delete job (soft delete)", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/jobs/{id}/status": { "patch": { "tags": [ "Jobs" ], "summary": "Change job status", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "open", "paused", "closed", "archived" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Status changed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Job" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/jobs/{id}/stages": { "put": { "tags": [ "Jobs" ], "summary": "Replace job pipeline stages", "description": "Replaces all stages on the job. Existing applications are kept (mapped onto stages by ID when possible). Use with care.", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "stages": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "category": { "type": "string", "enum": [ "sourced", "applied", "screening", "interview", "evaluation", "offer", "hired", "rejected", "custom" ] }, "orderIndex": { "type": "integer", "minimum": 0 } }, "required": [ "name", "category", "orderIndex" ] }, "minItems": 1 } }, "required": [ "stages" ] } } } }, "responses": { "200": { "description": "Stages replaced", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/jobs/{jobId}/board": { "get": { "tags": [ "Jobs" ], "summary": "Get kanban board view", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "jobId", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "includeRejected", "in": "query" } ], "responses": { "200": { "description": "Board (stages + applications)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "stages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "orderIndex": { "type": "integer" }, "applications": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } } }, "required": [ "id", "name", "category", "orderIndex", "applications" ] } } }, "required": [ "stages" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/board/all": { "get": { "tags": [ "Jobs" ], "summary": "Get the unified kanban board across all jobs", "description": "Applications across every in-scope job, grouped into columns keyed by stage category. Defaults to open + paused jobs.", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "includeRejected", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "includeClosed", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "jobIds", "in": "query" } ], "responses": { "200": { "description": "Unified board (jobs + category columns)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "orderIndex": { "type": "integer" } }, "required": [ "id", "name", "category", "orderIndex" ] } } }, "required": [ "id", "title", "status", "stages" ] } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "applications": { "type": "array", "items": { "type": "object", "additionalProperties": { "nullable": true } } } }, "required": [ "category", "applications" ] } }, "totalApplications": { "type": "integer" } }, "required": [ "jobs", "columns", "totalApplications" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/jobs/{jobId}/qualifier": { "get": { "tags": [ "Jobs" ], "summary": "Get the AI qualifier setting of a position", "description": "The AI qualifier checks each sourced candidate against the position's must-haves and, in mode `move`, moves the qualified ones to `targetStage` (the next stage unless the position picked another one from `targetOptions`). It never rejects. `requirements` is the position's own list when one was set, else null (Erika derives the must-haves from the job and the application form).", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "jobId", "in": "path" } ], "responses": { "200": { "description": "Qualifier setting", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "move", "rank_only", "off" ], "description": "move = Erika moves qualified candidates to the target stage; rank_only = only marks them, without moving (the value keeps its name for compatibility); off." }, "modeSource": { "type": "string", "enum": [ "job", "campaign", "company" ] }, "companyDefault": { "type": "string", "nullable": true, "enum": [ "on", "off", null ] }, "sendsToConnector": { "type": "boolean" }, "targetStage": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "targetIsDefault": { "type": "boolean" }, "defaultTargetId": { "type": "string", "nullable": true }, "targetOptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "requirements": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 120 }, "kind": { "type": "string", "enum": [ "must", "nice" ] } }, "required": [ "text", "kind" ] } } }, "required": [ "available", "mode", "modeSource", "companyDefault", "sendsToConnector", "targetStage", "targetIsDefault", "defaultTargetId", "targetOptions", "requirements" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Jobs" ], "summary": "Change the AI qualifier of a position", "description": "Set the mode, where qualified candidates go (`targetStageId`, one of `targetOptions`; `null` = the next stage after the one candidates land in, the default) and/or the position's own must-haves (`requirements: null` goes back to Erika's own list). Switching a position off also makes off the company default for new campaigns.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "jobId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "move", "rank_only", "off" ], "description": "move = Erika moves qualified candidates to the target stage; rank_only = only marks them, without moving (the value keeps its name for compatibility); off." }, "targetStageId": { "type": "string", "nullable": true }, "requirements": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 120 }, "kind": { "type": "string", "enum": [ "must", "nice" ] } }, "required": [ "text", "kind" ] }, "maxItems": 8 } } } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "jobId": { "type": "string" } }, "required": [ "jobId" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/candidates": { "get": { "tags": [ "Candidates" ], "summary": "List candidates", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "source", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tag", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Candidates page", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `cursor` to fetch the next page. Null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "success", "data", "nextCursor", "hasMore" ], "description": "Cursor-paginated success response" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Candidates" ], "summary": "Create candidate", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "format": "email" }, "phonePrefix": { "type": "string", "maxLength": 10 }, "phoneNumber": { "type": "string", "maxLength": 40 }, "linkedinUrl": { "type": "string", "format": "uri" }, "source": { "type": "string", "maxLength": 60 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 60 } } }, "required": [ "firstName", "lastName" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "nullable": true } }, "required": [ "id", "email" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/candidates/bulk": { "post": { "tags": [ "Candidates" ], "summary": "Bulk create candidates", "description": "Up to 1000 rows per request. Duplicates by email are skipped and reported in the response.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "format": "email" }, "phonePrefix": { "type": "string", "maxLength": 10 }, "phoneNumber": { "type": "string", "maxLength": 40 }, "linkedinUrl": { "type": "string", "format": "uri" }, "source": { "type": "string", "maxLength": 60 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 60 } } }, "required": [ "firstName", "lastName" ] }, "minItems": 1, "maxItems": 1000 } }, "required": [ "rows" ] } } } }, "responses": { "200": { "description": "Bulk result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "created": { "type": "integer" }, "skipped": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "string" } }, "createdIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "created", "skipped", "errors", "createdIds" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/candidates/{id}": { "get": { "tags": [ "Candidates" ], "summary": "Get candidate by ID", "description": "Full candidate detail including every application, its form answers, and the candidate's stated situation facts (`candidateProfile`: start availability, salary expectation, job-search status, best time to call). `candidateProfile` requires the API key to hold VIEW_SCREENING.", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Candidate", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/CandidateDetail" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Candidates" ], "summary": "Update candidate", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "format": "email" }, "phonePrefix": { "type": "string", "maxLength": 10 }, "phoneNumber": { "type": "string", "maxLength": 40 }, "linkedinUrl": { "type": "string", "format": "uri" }, "source": { "type": "string", "maxLength": 60 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 60 } } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Candidates" ], "summary": "Delete candidate (soft delete)", "description": "Soft-deletes the candidate and cascades to their applications + notes (the platform talent profile is left intact). Returns the bulk-delete result (deletedCount is 1 for this single-id path; deletedApplications is the cascade count).", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "total": { "type": "integer" }, "deletedCount": { "type": "integer" }, "skippedCount": { "type": "integer" }, "deletedIds": { "type": "array", "items": { "type": "string" } }, "deletedApplications": { "type": "integer" } }, "required": [ "total", "deletedCount", "skippedCount", "deletedIds", "deletedApplications" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/candidates/{id}/notes": { "post": { "tags": [ "Candidates" ], "summary": "Add note to candidate", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "content" ] } } } }, "responses": { "201": { "description": "Note added", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/applications": { "get": { "tags": [ "Applications" ], "summary": "List all applications (flat)", "description": "Flat list across all jobs. For paginated per-job results use GET /jobs/{jobId}/applications.", "responses": { "200": { "description": "Applications", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationSummary" } } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/jobs/{jobId}/applications": { "get": { "tags": [ "Applications" ], "summary": "List applications for a job", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "jobId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Page of applications", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationListItem" } }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `cursor` to fetch the next page. Null on the last page." }, "hasMore": { "type": "boolean" } }, "required": [ "success", "data", "nextCursor", "hasMore" ], "description": "Cursor-paginated success response" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Applications" ], "summary": "Create application (assign candidate to job)", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "jobId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "candidateId": { "type": "string" }, "source": { "type": "string", "maxLength": 60 }, "stageId": { "type": "string" } }, "required": [ "candidateId" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "stageId": { "type": "string" }, "stageName": { "type": "string" } }, "required": [ "id", "stageId", "stageName" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/applications/{id}": { "get": { "tags": [ "Applications" ], "summary": "Get application", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Application", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Application" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Applications" ], "summary": "Delete application (soft delete)", "description": "Removes the application from boards, lists, exports and search. Destructive — distinct from rejecting (which keeps the record). Returns the bulk-delete result (deletedCount is 1 for this single-id path).", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/ApplicationBulkDeleteResult" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/applications/{id}/stage": { "patch": { "tags": [ "Applications" ], "summary": "Move application to a different stage", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "stageId": { "type": "string" } }, "required": [ "stageId" ] } } } }, "responses": { "200": { "description": "Moved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "fromStage": { "type": "string" }, "toStage": { "type": "string" } }, "required": [ "id", "fromStage", "toStage" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/applications/{id}/status": { "patch": { "tags": [ "Applications" ], "summary": "Change application status", "description": "Set to rejected, withdrawn, or hired. Reject requires either reason text or rejectionReasonId.", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "rejected", "withdrawn", "hired" ] }, "reason": { "type": "string" }, "rejectionReasonId": { "type": "string" }, "note": { "type": "string" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Status changed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/applications/{id}/unhire": { "patch": { "tags": [ "Applications" ], "summary": "Revert hired status back to active", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Reverted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "stageId": { "type": "string" }, "stageName": { "type": "string" } }, "required": [ "id", "stageId", "stageName" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/applications/{id}/note": { "post": { "tags": [ "Applications" ], "summary": "Add note to application timeline", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "content" ] } } } }, "responses": { "201": { "description": "Note added", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/applications/{id}/qualifier/add-to-position": { "post": { "tags": [ "Applications" ], "summary": "Add a candidate to a position the AI qualifier suggested", "description": "For a candidate the AI qualifier judged not qualified, add them to one of the other open positions it suggested (`qualifier.suggestions` on the application). Creates a new application with the same source; the original application stays. Both timelines note where the candidate came from. Requires MANAGE_CANDIDATES.", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" } }, "required": [ "jobId" ] } } } }, "responses": { "201": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "applicationId": { "type": "string" }, "jobTitle": { "type": "string" } }, "required": [ "applicationId", "jobTitle" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/applications/{id}/rating": { "put": { "tags": [ "Ratings" ], "summary": "Create or update current worker's rating", "description": "Idempotent — one rating per (worker, application). Subsequent PUTs replace the prior value.", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "commentKeys": { "type": "array", "items": { "type": "string" } }, "comment": { "type": "string", "maxLength": 2000 } }, "required": [ "rating" ] } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Rating" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Ratings" ], "summary": "Delete current worker's rating", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/applications/{id}/ratings": { "get": { "tags": [ "Ratings" ], "summary": "Get all ratings for an application", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Ratings (one per worker who has rated)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "ratings": { "type": "array", "items": { "$ref": "#/components/schemas/Rating" } }, "average": { "type": "number", "nullable": true } }, "required": [ "ratings", "average" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/applications/{id}/attachments": { "post": { "tags": [ "Attachments" ], "summary": "Upload attachment to an application", "description": "multipart/form-data with `file` field. Max ~50MB.", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "fileType": { "type": "string" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Uploaded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Attachment" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Attachments" ], "summary": "List attachments on an application", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Attachments", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/attachments/{id}/url": { "get": { "tags": [ "Attachments" ], "summary": "Get a signed download URL", "description": "Returns a short-lived signed URL pointing at GCS. Use for direct browser downloads.", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Signed URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "url", "expiresAt" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/attachments/{id}/download": { "get": { "tags": [ "Attachments" ], "summary": "Download attachment (proxied stream)", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "inline", "in": "query" } ], "responses": { "200": { "description": "Binary file stream", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/attachments/{id}": { "delete": { "tags": [ "Attachments" ], "summary": "Delete attachment", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/pipeline-templates": { "get": { "tags": [ "Pipeline Templates" ], "summary": "List pipeline templates", "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineTemplate" } } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Pipeline Templates" ], "summary": "Create pipeline template", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "stages": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "category": { "type": "string", "enum": [ "sourced", "applied", "screening", "interview", "evaluation", "offer", "hired", "rejected", "custom" ] }, "orderIndex": { "type": "integer", "minimum": 0 } }, "required": [ "name", "category", "orderIndex" ] }, "minItems": 1 } }, "required": [ "name", "stages" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/PipelineTemplate" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/pipeline-templates/{id}": { "patch": { "tags": [ "Pipeline Templates" ], "summary": "Update pipeline template", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "isDefault": { "type": "boolean" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "category": { "type": "string", "enum": [ "sourced", "applied", "screening", "interview", "evaluation", "offer", "hired", "rejected", "custom" ] }, "orderIndex": { "type": "integer", "minimum": 0 } }, "required": [ "name", "category", "orderIndex" ] }, "minItems": 1 } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/PipelineTemplate" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Pipeline Templates" ], "summary": "Delete pipeline template", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/rejection-reasons": { "get": { "tags": [ "Rejection Reasons" ], "summary": "List rejection reasons", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "includeArchived", "in": "query" } ], "responses": { "200": { "description": "Reasons", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RejectionReason" } } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Rejection Reasons" ], "summary": "Create rejection reason", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "label" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/RejectionReason" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/rejection-reasons/{id}": { "patch": { "tags": [ "Rejection Reasons" ], "summary": "Update rejection reason", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 }, "isArchived": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/RejectionReason" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Rejection Reasons" ], "summary": "Delete rejection reason (soft delete)", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/rejection-reasons/reorder": { "post": { "tags": [ "Rejection Reasons" ], "summary": "Reorder rejection reasons", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderedIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "orderedIds" ] } } } }, "responses": { "200": { "description": "Reordered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook-registrations": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook registrations", "responses": { "200": { "description": "Registrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookRegistration" } } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook registration", "description": "The response includes a one-time secret used to sign deliveries — save it now, it can't be retrieved later.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "endpointUrl": { "type": "string", "format": "uri" }, "description": { "type": "string", "maxLength": 500 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "candidate.created", "candidate.updated", "application.created", "application.stage_changed", "application.qualified", "application.unqualified", "application.status_changed", "screening.completed", "screening.failed" ], "description": "Subscribe to one of the documented event names. See the event catalog in the Developers page." }, "minItems": 1 } }, "required": [ "name", "endpointUrl", "events" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "secret" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook-registrations/{id}": { "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook registration", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "endpointUrl": { "type": "string", "format": "uri" }, "description": { "type": "string", "maxLength": 500 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "candidate.created", "candidate.updated", "application.created", "application.stage_changed", "application.qualified", "application.unqualified", "application.status_changed", "screening.completed", "screening.failed" ], "description": "Subscribe to one of the documented event names. See the event catalog in the Developers page." }, "minItems": 1 }, "isActive": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/WebhookRegistration" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook registration", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error or business-rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhook-registrations/{id}/events": { "get": { "tags": [ "Webhooks" ], "summary": "List recent deliveries for a webhook", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Recent deliveries", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sourcing/campaigns": { "get": { "tags": [ "Sourcing" ], "summary": "List sourcing campaigns", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "jobId", "in": "query" } ], "responses": { "200": { "description": "Campaigns", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/SourcingCampaign" } } }, "required": [ "campaigns" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sourcing/campaigns/{id}": { "get": { "tags": [ "Sourcing" ], "summary": "Get sourcing campaign", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/SourcingCampaign" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sourcing/creatives": { "get": { "tags": [ "Sourcing" ], "summary": "List creatives", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "campaignId", "in": "query" } ], "responses": { "200": { "description": "Creatives", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/SourcingCreative" } } }, "required": [ "creatives" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sourcing/creatives/{id}": { "get": { "tags": [ "Sourcing" ], "summary": "Get creative", "parameters": [ { "schema": { "type": "string", "description": "Resource ID (UUID)" }, "required": true, "description": "Resource ID (UUID)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Creative", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/SourcingCreative" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sourcing/adverts": { "get": { "tags": [ "Sourcing" ], "summary": "List adverts", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "campaignId", "in": "query" } ], "responses": { "200": { "description": "Adverts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "adverts": { "type": "array", "items": { "$ref": "#/components/schemas/SourcingAdvert" } } }, "required": [ "adverts" ] } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/campaign-builds": { "post": { "tags": [ "Campaign Builds" ], "summary": "Start an autonomous campaign build", "description": "Create a Job, generate creatives + videos, and launch a Meta campaign end to end from one call. Requires the MANAGE_CAMPAIGN_API scope. Returns 202 immediately; poll the status URL or receive a signed webhook on completion.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignBuild" } } } }, "responses": { "202": { "description": "Build accepted and queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignBuildAccepted" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Validation error, or INSUFFICIENT_JD_CONTEXT when the job description lacks enough detail to determine a location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Insufficient budget or credits (code INSUFFICIENT_BUDGET / INSUFFICIENT_CREDITS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "JOB_NOT_FOUND — the jobId does not match a job in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key reused with a different request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many builds in progress for this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Could not analyze the job description right now (transient). Retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/campaign-builds/{id}": { "get": { "tags": [ "Campaign Builds" ], "summary": "Get campaign build status", "parameters": [ { "schema": { "type": "string", "description": "Campaign build ID" }, "required": true, "description": "Campaign build ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Current build status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/CampaignBuildStatus" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Build not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/credit-purchases": { "get": { "tags": [ "Credits" ], "summary": "List credit purchases", "description": "Chronological history (newest first) of credit top-ups, auto-recharges and subscription plan grants with the amount + currency charged — for billing transparency. Readable with either the VIEW_CAMPAIGN_API or MANAGE_CAMPAIGN_API scope.", "parameters": [ { "schema": { "type": "string", "description": "Page size, 1–100 (default 20)." }, "required": false, "description": "Page size, 1–100 (default 20).", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "ISO timestamp cursor from a previous page's nextCursor — returns purchases strictly older than this." }, "required": false, "description": "ISO timestamp cursor from a previous page's nextCursor — returns purchases strictly older than this.", "name": "before", "in": "query" } ], "responses": { "200": { "description": "Credit purchase history", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/CreditPurchaseHistory" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "400": { "description": "Invalid 'before' cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/billing/balance": { "get": { "tags": [ "Billing" ], "summary": "Get plan and credit balance", "description": "Returns the org's active plan and remaining AI credits. Useful for external monitoring or budget alerts.", "responses": { "200": { "description": "Current balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/BillingBalance" } }, "required": [ "success", "data" ], "description": "Success response wrapper" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks the permission for this endpoint, or endpoint is web-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } } }