{"openapi":"3.0.0","paths":{"/v1/api/agent":{"post":{"description":"Runs the tenant-scoped Veref agent with tools allowed by the API key scopes. Requires references:read.","operationId":"PublicApiController_askAgent","parameters":[{"name":"x-api-key","in":"header","description":"Alternative to Authorization: Bearer <key>.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"What needs attention in this reference workflow?"}},"required":["message"]}}}},"responses":{"200":{"description":"Agent response with optional tool results."}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"summary":"Ask the Veref workspace agent","tags":["Public API"]}},"/v1/api/ops/feed":{"get":{"description":"Returns coordination messages for the API-key tenant. Requires references:read.","operationId":"PublicApiController_getOpsFeed","parameters":[{"name":"x-api-key","in":"header","description":"Alternative to Authorization: Bearer <key>.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tenant ops feed snapshot."}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"summary":"Read the tenant ops feed","tags":["Public API"]}},"/v1/api/ops/messages":{"post":{"description":"Creates a tenant-scoped coordination message. Use workflow endpoints for state changes. Requires references:write.","operationId":"PublicApiController_createOpsMessage","parameters":[{"name":"x-api-key","in":"header","description":"Alternative to Authorization: Bearer <key>.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","example":"Reference check ready for review"},"body":{"type":"string","example":"All required referee responses are complete."},"from":{"type":"string","example":"agent:codex"},"to":{"type":"string","example":"recruiter:owner"},"priority":{"type":"string","enum":["low","normal","high"],"example":"high"}},"required":["title","body"]}}}},"responses":{"200":{"description":"Created ops message."}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"summary":"Create an ops coordination message","tags":["Public API"]}},"/v1/api/reference-requests/{requestId}":{"get":{"description":"Returns one reference request for the API-key tenant. Requires references:read.","operationId":"PublicApiController_getReferenceRequest","parameters":[{"name":"x-api-key","in":"header","description":"Alternative to Authorization: Bearer <key>.","required":false,"schema":{"type":"string"}},{"name":"requestId","required":true,"in":"path","description":"Reference request id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Reference request detail."}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"summary":"Read a reference request","tags":["Public API"]}},"/v1/api/reference-requests":{"post":{"description":"Creates a reference request. Use candidate_intake for candidate-led referee collection or manual_references when contacts are already known. Requires references:write.","operationId":"PublicApiController_createReferenceRequest","parameters":[{"name":"x-api-key","in":"header","description":"Alternative to Authorization: Bearer <key>.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"launchMode":{"type":"string","enum":["candidate_intake","manual_references"],"example":"candidate_intake"},"roleTitle":{"type":"string","example":"Founding Engineer"},"candidate":{"type":"object","properties":{"firstName":{"type":"string","example":"Ada"},"lastName":{"type":"string","example":"Lovelace"},"email":{"type":"string","example":"ada@example.com"},"stage":{"type":"string","example":"sourced"}},"required":["firstName","lastName","email"]},"contacts":{"type":"array","items":{"type":"object","properties":{"firstName":{"type":"string","example":"Grace"},"lastName":{"type":"string","example":"Hopper"},"email":{"type":"string","example":"grace@example.com"},"phone":{"type":"string","example":"+15555550100"},"relationship":{"type":"string","example":"Former manager"}}}},"notes":{"type":"string","example":"Started by external recruiting agent"}},"required":["launchMode","candidate"]}}}},"responses":{"200":{"description":"Created reference request and queued workflow metadata."}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"summary":"Start a reference-check workflow","tags":["Public API"]}},"/v1/api/reference-requests/{requestId}/lifecycle":{"post":{"description":"Moves a reference request through an explicit lifecycle action. Most workflows do not need this call. Requires references:write.","operationId":"PublicApiController_advanceReferenceRequest","parameters":[{"name":"x-api-key","in":"header","description":"Alternative to Authorization: Bearer <key>.","required":false,"schema":{"type":"string"}},{"name":"requestId","required":true,"in":"path","description":"Reference request id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["request_candidate_consent","grant_candidate_consent","queue_outreach","request_recruiter_review"],"example":"request_recruiter_review"},"reason":{"type":"string","example":"All required reference evidence has been collected."}},"required":["action"]}}}},"responses":{"200":{"description":"Updated reference-request lifecycle state."}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"summary":"Advance reference-request lifecycle","tags":["Public API"]}},"/v1/api/reference-requests/{requestId}/valuation/draft":{"post":{"description":"Creates the recruiter-reviewable valuation/report draft for a reference request. Requires valuations:write.","operationId":"PublicApiController_generateValuationDraft","parameters":[{"name":"x-api-key","in":"header","description":"Alternative to Authorization: Bearer <key>.","required":false,"schema":{"type":"string"}},{"name":"requestId","required":true,"in":"path","description":"Reference request id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Valuation draft preview."}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"summary":"Generate or preview a valuation draft","tags":["Public API"]}},"/v1/api/reference-requests/{requestId}/valuation/approve":{"post":{"description":"Approves the generated report package on behalf of the API key actor. Requires valuations:write.","operationId":"PublicApiController_approveValuation","parameters":[{"name":"x-api-key","in":"header","description":"Alternative to Authorization: Bearer <key>.","required":false,"schema":{"type":"string"}},{"name":"requestId","required":true,"in":"path","description":"Reference request id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Approved report state."}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"summary":"Approve a valuation/report package","tags":["Public API"]}},"/v1/api/reference-requests/{requestId}/share":{"post":{"description":"Creates a shareable customer report link for an approved reference request. Requires reports:write.","operationId":"PublicApiController_createShare","parameters":[{"name":"x-api-key","in":"header","description":"Alternative to Authorization: Bearer <key>.","required":false,"schema":{"type":"string"}},{"name":"requestId","required":true,"in":"path","description":"Reference request id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Created share link metadata."}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"summary":"Create a customer share link","tags":["Public API"]}}},"info":{"title":"Veref API","description":"External API-key routes for customer, partner, and agent integrations.","version":"1.0","contact":{}},"tags":[],"servers":[{"url":"https://api.veref.work","description":"Production"},{"url":"http://localhost:8787","description":"Local development"}],"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","bearerFormat":"Veref API key","type":"http","description":"Use a tenant API key in the Authorization header."},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Alternative tenant API key header."}},"schemas":{}}}