{ "openapi": "3.0.0", "info": { "title": "Stori API", "version": "1.0.0", "description": "# Stori API Documentation\n\nStori is a candidate intelligence platform that helps job seekers stand out and recruiters find the right talent.\n\n## Authentication\n\nMost endpoints require authentication via one of:\n- **Bearer Token**: Pass your Supabase JWT in the `Authorization: Bearer ` header\n- **Session Cookie**: Automatic for web app users\n\n## Rate Limits\n\nAll endpoints are rate-limited to prevent abuse:\n\n| Endpoint Type | Limit |\n|---------------|-------|\n| PDL Search | 75 req/min |\n| AI Generation | 7 req/min |\n| Auth | 5 req/min |\n| Email Send | 10 req/min |\n| Video Upload | 4 req/min |\n| Standard API | 100 req/min |\n| Read-only | 200 req/min |\n\nRate limit headers are included in all responses:\n- `X-RateLimit-Limit`: Maximum requests allowed\n- `X-RateLimit-Remaining`: Requests remaining\n- `X-RateLimit-Reset`: Unix timestamp when limit resets\n\n## Credits\n\nSome operations consume credits:\n- PDL searches cost credits based on results\n- Unlocking contact info costs 1 credit per contact\n- Credits can be purchased via Stripe checkout\n\n## Error Handling\n\nAll errors follow this format:\n```json\n{\n \"error\": \"Error message\",\n \"details\": { \"field\": [\"validation error\"] }\n}\n```\n\nCommon status codes:\n- `400` - Validation error\n- `401` - Unauthorized (invalid/missing token)\n- `402` - Payment required (insufficient credits)\n- `403` - Forbidden (subscription required)\n- `429` - Rate limit exceeded\n- `500` - Internal server error", "contact": { "name": "Stori Support", "url": "https://onestori.com" } }, "servers": [ { "url": "https://onestori.com", "description": "Production" }, { "url": "http://localhost:3000", "description": "Development" } ], "tags": [ { "name": "Profile", "description": "Profile management endpoints" }, { "name": "Jobs", "description": "Job tracking and preferences" }, { "name": "Billing", "description": "Subscription and payment endpoints" }, { "name": "Recruiter", "description": "PDL sourcing and contact management" }, { "name": "Email", "description": "Gmail/Outlook email integration" }, { "name": "AI", "description": "AI content generation" }, { "name": "Video", "description": "Video upload and management" }, { "name": "Traits", "description": "Behavioral trait assessment" }, { "name": "Webhooks", "description": "External webhook handlers" }, { "name": "Partner API v1", "description": "API-key authenticated, company-scoped partner endpoints. Stori gathers, organizes, and cross-validates candidate information to help employers make more informed decisions." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Supabase JWT token from authentication" }, "CookieAuth": { "type": "apiKey", "in": "cookie", "name": "sb-access-token", "description": "Supabase session cookie" }, "ApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "Stori API key (sk_live_... or sk_test_...). All v1 endpoints are scoped to the key's company. Scopes: read:jobs, read:candidates, read:credits, read:health." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "nullable": true, "description": "Additional error details" } }, "required": [ "error" ] }, "Success": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number" }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Items per page" } } } }, "parameters": {} }, "paths": { "/api/update-profile-header": { "post": { "tags": [ "Profile" ], "summary": "Update profile header information", "description": "Updates basic profile information like name, phone, location, and summary", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid", "description": "Profile UUID" }, "firstName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 30 }, "email": { "type": "string", "format": "email" }, "city": { "type": "string", "maxLength": 100 }, "country": { "type": "string", "maxLength": 100 }, "summary": { "type": "string", "maxLength": 5000 } }, "required": [ "profileId" ] } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "nullable": true, "description": "Additional error details" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/update-work-experience": { "post": { "tags": [ "Profile" ], "summary": "Update work experience", "description": "Replaces all work experience entries for a profile", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "workExperience": { "type": "array", "items": { "type": "object", "properties": { "company": { "type": "string", "minLength": 1, "maxLength": 200 }, "role": { "type": "string", "minLength": 1, "maxLength": 200 }, "from": { "type": "string" }, "to": { "type": "string" }, "city": { "type": "string", "maxLength": 100 }, "country": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 5000 }, "highlights": { "type": "array", "items": { "type": "string", "maxLength": 500 }, "maxItems": 10 } }, "required": [ "company", "role" ] }, "maxItems": 30 } }, "required": [ "profileId", "workExperience" ] } } } }, "responses": { "200": { "description": "Work experience updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "nullable": true, "description": "Additional error details" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/update-education": { "post": { "tags": [ "Profile" ], "summary": "Update education", "description": "Replaces all education entries for a profile", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "education": { "type": "array", "items": { "type": "object", "properties": { "institution": { "type": "string", "minLength": 1, "maxLength": 200 }, "degree": { "type": "string", "maxLength": 200 }, "major": { "type": "string", "maxLength": 200 }, "from": { "type": "string" }, "to": { "type": "string" }, "gpa": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "institution" ] }, "maxItems": 20 } }, "required": [ "profileId", "education" ] } } } }, "responses": { "200": { "description": "Education updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "details": { "nullable": true, "description": "Additional error details" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/update-skills": { "post": { "tags": [ "Profile" ], "summary": "Update skills", "description": "Replaces all skills for a profile", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "skills": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 100 } }, "required": [ "profileId", "skills" ] } } } }, "responses": { "200": { "description": "Skills updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/update-links": { "post": { "tags": [ "Profile" ], "summary": "Update profile links", "description": "Replaces all links (LinkedIn, GitHub, portfolio, etc.) for a profile", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string", "format": "uuid" }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "maxLength": 500, "format": "uri" } }, "required": [ "label", "url" ] }, "maxItems": 10 } }, "required": [ "profileId", "links" ] } } } }, "responses": { "200": { "description": "Links updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/job-preferences": { "post": { "tags": [ "Jobs" ], "summary": "Update job preferences", "description": "Updates the answers a job application asks for: personal info, work authorization and salary expectations", "security": [ { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 30 }, "countryOfResidence": { "type": "string", "maxLength": 100 }, "resumeUrl": { "type": "string", "format": "uri" }, "linkedinUrl": { "type": "string", "format": "uri" }, "portfolioUrl": { "type": "string", "format": "uri" }, "authorizedToWorkUS": { "type": "boolean" }, "requiresSponsorship": { "type": "boolean" }, "minBaseSalary": { "type": "string", "maxLength": 20 }, "yearsOfExperience": { "type": "string", "maxLength": 20 }, "highestEducation": { "type": "string", "maxLength": 100 } } } } } }, "responses": { "200": { "description": "Preferences saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "401": { "description": "Unauthorized" } } }, "get": { "tags": [ "Jobs" ], "summary": "Get job preferences", "description": "Retrieves the stored answers a job application asks for", "security": [ { "CookieAuth": [] } ], "responses": { "200": { "description": "Job preferences retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "preferences": { "type": "object", "additionalProperties": { "nullable": true }, "description": "All stored preferences" } }, "required": [ "preferences" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/jobs": { "get": { "tags": [ "Jobs" ], "summary": "List jobs", "description": "Returns all jobs for the authenticated user", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "responses": { "200": { "description": "Jobs list", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "job_title": { "type": "string" }, "company_name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "job_title", "company_name", "status", "created_at" ] } } }, "required": [ "jobs" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/stripe/create-checkout": { "post": { "tags": [ "Billing" ], "summary": "Create Stripe checkout session", "description": "Creates a Stripe checkout session for subscriptions or credit purchases", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "subscription", "payment" ], "description": "Checkout mode" }, "priceId": { "type": "string", "enum": [ "OUTREACH" ], "description": "Subscription mode: Outreach is the only subscription sold here" }, "items": { "type": "array", "items": { "type": "object", "properties": { "priceId": { "type": "string", "enum": [ "CANDIDATE_OUTREACH_50", "CANDIDATE_OUTREACH_100", "CANDIDATE_OUTREACH_200", "INTERVIEWS_10", "INTERVIEWS_100", "INTERVIEWS_500", "INTERVIEWS_1000" ] }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "priceId", "quantity" ] }, "maxItems": 10 }, "creditType": { "type": "string", "enum": [ "candidate_outreach", "client_interview" ] }, "companyId": { "type": "string", "format": "uuid", "description": "Required for client_interview" }, "returnUrl": { "type": "string", "maxLength": 500, "description": "Relative path to return to after checkout" } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "Checkout session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Stripe checkout URL" } }, "required": [ "url" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/billing/status": { "get": { "tags": [ "Billing" ], "summary": "Get billing status", "description": "Returns current subscription status and plan details", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "responses": { "200": { "description": "Billing status", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasSubscription": { "type": "boolean" }, "plan": { "type": "string" }, "status": { "type": "string" }, "currentPeriodEnd": { "type": "string" } }, "required": [ "hasSubscription" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/stripe/portal": { "post": { "tags": [ "Billing" ], "summary": "Create billing portal session", "description": "Creates a Stripe billing portal session for managing subscriptions", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "responses": { "200": { "description": "Portal URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Stripe billing portal URL" } }, "required": [ "url" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/recruiter/search": { "post": { "tags": [ "Recruiter" ], "summary": "Search for contacts (PDL)", "description": "Searches People Data Labs for hiring managers matching criteria. Costs credits per search.", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "job_title": { "type": "string", "maxLength": 200, "description": "Job title to search" }, "job_titles": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Multiple job titles" }, "company": { "type": "string", "maxLength": 200, "description": "Company name" }, "location": { "type": "string", "maxLength": 200, "description": "Location (city, state, country)" }, "industry": { "type": "string", "maxLength": 200, "description": "Industry" }, "company_size": { "type": "string", "maxLength": 50, "description": "Company size range" }, "seniority": { "type": "string", "maxLength": 50, "description": "Seniority level" } } }, "page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "full_name": { "type": "string" }, "job_title": { "type": "string" }, "job_company_name": { "type": "string" }, "location_name": { "type": "string" }, "linkedin_url": { "type": "string" } }, "required": [ "id", "full_name" ] } }, "total": { "type": "number" }, "page": { "type": "number" }, "pageSize": { "type": "number" } }, "required": [ "results", "total", "page", "pageSize" ] } } } }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient credits" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/recruiter/unlock": { "post": { "tags": [ "Recruiter" ], "summary": "Unlock contact details", "description": "Unlocks email/phone for contacts. Costs 1 credit per contact.", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contactIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50, "description": "Contact IDs to unlock" }, "unlockType": { "type": "string", "enum": [ "email", "phone", "both" ], "default": "email" } }, "required": [ "contactIds" ] } } } }, "responses": { "200": { "description": "Contacts unlocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "unlocked": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } }, "required": [ "id" ] } }, "creditsUsed": { "type": "number" }, "creditsRemaining": { "type": "number" } }, "required": [ "unlocked", "creditsUsed", "creditsRemaining" ] } } } }, "401": { "description": "Unauthorized" }, "402": { "description": "Insufficient credits" } } } }, "/api/recruiter/credits": { "get": { "tags": [ "Recruiter" ], "summary": "Get credit balance", "description": "Returns current credit balance for the user", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "responses": { "200": { "description": "Credit balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "credits": { "type": "number", "description": "Available credits" }, "used": { "type": "number", "description": "Credits used" }, "total": { "type": "number", "description": "Total credits purchased" } }, "required": [ "credits", "used", "total" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/recruiter/gmail/send": { "post": { "tags": [ "Email" ], "summary": "Send email via Gmail", "description": "Sends an email through the connected Gmail account", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "format": "email", "description": "Recipient email" }, "toName": { "type": "string", "maxLength": 200, "description": "Recipient name" }, "subject": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Email subject" }, "bodyText": { "type": "string", "maxLength": 100000, "description": "Plain text body" }, "bodyHtml": { "type": "string", "maxLength": 200000, "description": "HTML body" }, "draftId": { "type": "string", "format": "uuid", "description": "Draft ID to mark as sent" }, "videoIntro": { "type": "object", "properties": { "gifUrl": { "type": "string", "nullable": true, "format": "uri" }, "thumbnailUrl": { "type": "string", "nullable": true, "format": "uri" }, "landingPageUrl": { "type": "string", "format": "uri" } }, "required": [ "gifUrl", "thumbnailUrl", "landingPageUrl" ], "description": "Video intro to embed" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 100 }, "content": { "type": "string", "description": "Base64 encoded content" } }, "required": [ "filename", "mimeType", "content" ] }, "maxItems": 10 } }, "required": [ "to", "subject", "bodyText" ] } } } }, "responses": { "200": { "description": "Email sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "messageId": { "type": "string" } }, "required": [ "success", "messageId" ] } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Gmail not connected" } } } }, "/api/recruiter/gmail/status": { "get": { "tags": [ "Email" ], "summary": "Get Gmail connection status", "description": "Checks if Gmail is connected and returns connection details", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "responses": { "200": { "description": "Connection status", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "email": { "type": "string", "format": "email" }, "expiresAt": { "type": "string" } }, "required": [ "connected" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/ai/generate-content": { "post": { "tags": [ "AI" ], "summary": "Generate AI content", "description": "Generates profile content using AI (summary, work descriptions, highlights)", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sectionType": { "type": "string", "enum": [ "summary", "work_description", "work_highlights", "individual_highlight" ] }, "sectionId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Section identifier" }, "context": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional context" }, "force": { "type": "boolean", "default": false, "description": "Force regeneration" }, "highlightIndex": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "sectionType", "sectionId" ] } } } }, "responses": { "200": { "description": "Content generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Generated content" }, "cached": { "type": "boolean", "description": "Whether content was from cache" } }, "required": [ "content" ] } } } }, "401": { "description": "Unauthorized" }, "429": { "description": "Rate limit exceeded (7 req/min)" } } } }, "/api/upload-to-mux": { "post": { "tags": [ "Video" ], "summary": "Upload video to Mux", "description": "Uploads and transcodes a video through Mux", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "interviewId": { "type": "string", "format": "uuid" }, "videoIntroId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Upload initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadUrl": { "type": "string", "format": "uri", "description": "Direct upload URL" }, "assetId": { "type": "string" } }, "required": [ "uploadUrl", "assetId" ] } } } }, "401": { "description": "Unauthorized" }, "429": { "description": "Rate limit exceeded (4 req/min)" } } } }, "/api/video-intro/{slug}": { "get": { "tags": [ "Video" ], "summary": "Get video intro by slug", "description": "Returns public video intro data for embedding", "parameters": [ { "schema": { "type": "string", "description": "Video intro slug" }, "required": true, "description": "Video intro slug", "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Video intro data", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "playbackId": { "type": "string" }, "thumbnailUrl": { "type": "string", "format": "uri" }, "duration": { "type": "number" }, "viewCount": { "type": "number" } }, "required": [ "id", "playbackId", "viewCount" ] } } } }, "404": { "description": "Video not found" } } } }, "/api/traits/start-assessment": { "post": { "tags": [ "Traits" ], "summary": "Start trait assessment", "description": "Initiates a new trait assessment session", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "responses": { "200": { "description": "Assessment started", "content": { "application/json": { "schema": { "type": "object", "properties": { "assessmentId": { "type": "string", "format": "uuid" }, "totalBlocks": { "type": "number", "description": "Number of question blocks" } }, "required": [ "assessmentId", "totalBlocks" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/traits/save-response": { "post": { "tags": [ "Traits" ], "summary": "Save trait response", "description": "Saves a response for a trait assessment block", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "assessmentId": { "type": "string", "format": "uuid" }, "blockNumber": { "type": "integer", "minimum": 1, "maximum": 30 }, "mostLike": { "type": "string", "minLength": 1, "maxLength": 100 }, "moreLike": { "type": "string", "minLength": 1, "maxLength": 100 }, "leastLike": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "assessmentId", "blockNumber", "mostLike", "moreLike", "leastLike" ] } } } }, "responses": { "200": { "description": "Response saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/traits/calculate-report": { "post": { "tags": [ "Traits" ], "summary": "Calculate trait report", "description": "Calculates final trait scores from all responses", "security": [ { "BearerAuth": [] }, { "CookieAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "assessmentId": { "type": "string", "format": "uuid" } }, "required": [ "assessmentId" ] } } } }, "responses": { "200": { "description": "Report calculated", "content": { "application/json": { "schema": { "type": "object", "properties": { "traits": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "description": { "type": "string" } }, "required": [ "name", "score" ] } } }, "required": [ "traits" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/stripe/webhook": { "post": { "tags": [ "Webhooks" ], "summary": "Stripe webhook handler", "description": "Handles Stripe webhook events (signature verification required)", "parameters": [ { "schema": { "type": "string", "description": "Stripe signature header" }, "required": true, "description": "Stripe signature header", "name": "stripe-signature", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Event ID" }, "type": { "type": "string", "description": "Event type" }, "data": { "type": "object", "properties": { "object": { "nullable": true } } } }, "required": [ "id", "type", "data" ] } } } }, "responses": { "200": { "description": "Webhook processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean", "enum": [ true ] } }, "required": [ "received" ] } } } }, "400": { "description": "Invalid signature or duplicate event" } } } }, "/api/v1/jobs": { "get": { "tags": [ "Partner API v1" ], "summary": "List jobs", "description": "The company's jobs with candidate-pool counts. Scope: read:jobs.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "string", "description": "Filter by job status" }, "required": false, "description": "Filter by job status", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "candidate_count": { "type": "integer" }, "interviewed_count": { "type": "integer" } }, "required": [ "id", "title", "status", "location", "department", "created_at", "candidate_count", "interviewed_count" ] } }, "has_more": { "type": "boolean" } }, "required": [ "data", "has_more" ] } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Insufficient scope" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/v1/jobs/{id}": { "get": { "tags": [ "Partner API v1" ], "summary": "Get job detail", "description": "Job spec fields plus pool counts. Scope: read:jobs.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Job detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "candidate_count": { "type": "integer" }, "interviewed_count": { "type": "integer" }, "skills": { "type": "array", "nullable": true, "items": { "type": "string" } }, "requirements": { "nullable": true }, "responsibilities": { "nullable": true } }, "required": [ "id", "title", "status", "location", "department", "created_at", "candidate_count", "interviewed_count", "skills" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Job not found" } } } }, "/api/v1/jobs/{id}/candidates": { "get": { "tags": [ "Partner API v1" ], "summary": "List candidates in a job", "description": "Candidate summary rows for a job pool. Scope: read:candidates.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Candidates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "candidate_id": { "type": "string", "format": "uuid" }, "full_name": { "type": "string" }, "job_title": { "type": "string", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "interview_completed_at": { "type": "string", "nullable": true }, "resume_match_score": { "type": "number", "nullable": true }, "interview_intelligence_score": { "type": "number", "nullable": true }, "stori_composite_score": { "type": "number", "nullable": true }, "pool_rank": { "type": "number", "nullable": true } }, "required": [ "candidate_id", "full_name", "job_title", "company_name", "interview_completed_at", "resume_match_score", "interview_intelligence_score", "stori_composite_score", "pool_rank" ] } }, "has_more": { "type": "boolean" } }, "required": [ "data", "has_more" ] } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Job not found" } } } }, "/api/v1/jobs/{id}/rankings": { "get": { "tags": [ "Partner API v1" ], "summary": "Rank a job pool by evidence strength", "description": "Deterministic ordering of scored candidates by strength of role-relevant, checkable evidence (résumé match + interview-demonstrated signal). Decision support — identifies who should be considered, not who is \"best\". Scope: read:candidates.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Rankings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" } }, "required": [ "id", "title" ] }, "ranked": { "type": "array", "items": { "type": "object", "properties": { "candidate_id": { "type": "string", "format": "uuid" }, "full_name": { "type": "string", "nullable": true }, "stori_composite_score": { "type": "number" }, "pool_rank": { "type": "integer" }, "pool_size": { "type": "integer" }, "pool_percentile": { "type": "number" }, "pool_standout_factor": { "type": "string" } }, "required": [ "candidate_id", "full_name", "stori_composite_score", "pool_rank", "pool_size", "pool_percentile", "pool_standout_factor" ] } }, "unscored": { "type": "array", "items": { "type": "object", "properties": { "candidate_id": { "type": "string", "format": "uuid" }, "full_name": { "type": "string" }, "interview_completed": { "type": "boolean" } }, "required": [ "candidate_id", "full_name", "interview_completed" ] } }, "note": { "type": "string" } }, "required": [ "job", "ranked", "unscored", "note" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Job not found" } } } }, "/api/v1/jobs/{id}/search": { "post": { "tags": [ "Partner API v1" ], "summary": "Ask a question across interview transcripts", "description": "Natural-language RAG search across a job's completed interview transcripts. Answers cite exact quotes with video timestamps. Scope: read:candidates. Requires a Sourcing subscription (test-environment keys exempt).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "minLength": 3, "maxLength": 2000 } }, "required": [ "question" ] } } } }, "responses": { "200": { "description": "Search result with cited evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "answer": { "type": "string" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "candidate_id": { "type": "string" }, "full_name": { "type": "string" }, "relevance_score": { "type": "number" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "quote": { "type": "string" }, "timestamp": { "type": "number", "description": "Seconds into the interview video" }, "context": { "type": "string" } }, "required": [ "quote", "timestamp", "context" ] } }, "summary": { "type": "string" } }, "required": [ "candidate_id", "full_name", "relevance_score", "evidence", "summary" ] } }, "follow_up_questions": { "type": "array", "items": { "type": "string" } }, "pool_size": { "type": "integer" } }, "required": [ "answer", "candidates", "follow_up_questions", "pool_size" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Missing/short question" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Sourcing subscription required (code: UPGRADE_REQUIRED)" }, "404": { "description": "Job not found" } } } }, "/api/v1/candidates/{id}": { "get": { "tags": [ "Partner API v1" ], "summary": "Get candidate intelligence report", "description": "Full structured report: identity, evidence-based scores, pool position, transcript analysis with cited evidence. Scores reflect strength of checkable, role-relevant information — decision support, not prediction. Scope: read:candidates.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Candidate report", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "nullable": true } } } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Candidate not found" } } } }, "/api/v1/credits": { "get": { "tags": [ "Partner API v1" ], "summary": "Get credit balances", "description": "Assessment and outreach credit balances (subscription + purchased buckets). Scope: read:credits.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Balances", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assessment_credits": { "type": "object", "properties": { "available": { "type": "number" }, "subscription": { "type": "number" }, "purchased": { "type": "number" } }, "required": [ "available" ] }, "outreach_credits": { "type": "object", "properties": { "available": { "type": "number" }, "subscription": { "type": "number" }, "purchased": { "type": "number" } }, "required": [ "available" ] } }, "required": [ "assessment_credits", "outreach_credits" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing or invalid API key" } } } }, "/api/v1/health": { "get": { "tags": [ "Partner API v1" ], "summary": "Authenticated health check", "description": "Confirms the API key works and reports environment context. Scope: read:health.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "db": { "type": "string" }, "latency_ms": { "type": "number" }, "environment": { "type": "string", "enum": [ "live", "test" ] } }, "required": [ "status", "db", "latency_ms", "environment" ] } } } }, "401": { "description": "Missing or invalid API key" }, "503": { "description": "Unhealthy" } } } } } }