{"openapi": "3.0.3", "info": {"title": "MyValidCV API pilot", "version": "1.0.0", "description": "Owner-approved, capped 14-day pilot. Advisory comparisons only; no automated hiring or email sending."}, "servers": [{"url": "/api/v1"}], "security": [{"BearerKey": []}], "components": {"securitySchemes": {"BearerKey": {"type": "http", "scheme": "bearer"}}, "schemas": {"Candidate": {"type": "object", "required": ["text"], "properties": {"reference": {"type": "string", "maxLength": 80}, "text": {"type": "string", "minLength": 450, "maxLength": 50000}}}, "Result": {"type": "object", "properties": {"reference": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 100}, "matched": {"type": "array", "items": {"type": "string"}}, "missing": {"type": "array", "items": {"type": "string"}}, "evidence": {"type": "array", "items": {"type": "object"}}, "confidence": {"type": "object"}, "model_version": {"type": "string"}, "advisory_only": {"type": "boolean"}}}, "Batch": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["queued", "processing", "completed", "failed", "held", "cancelled", "expired"]}, "comparisons": {"type": "integer"}, "credits_charged": {"type": "integer"}, "error_code": {"type": "string"}, "created_at": {"type": "string", "format": "date-time"}, "retention_expires_at": {"type": "string", "format": "date-time"}, "url": {"type": "string"}, "advisory_only": {"type": "boolean"}, "results": {"type": "array", "items": {"$ref": "#/components/schemas/Result"}}}}, "Usage": {"type": "object", "properties": {"company": {"type": "string"}, "status": {"type": "string"}, "allowance": {"type": "integer"}, "used": {"type": "integer"}, "reserved": {"type": "integer"}, "remaining": {"type": "integer"}, "requests_per_minute": {"type": "integer"}, "batch_limit": {"type": "integer"}, "pilot_expires_at": {"type": "string", "format": "date-time", "nullable": true}, "automatic_charges": {"type": "boolean"}}}, "Error": {"type": "object", "properties": {"error": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}}}}}, "paths": {"/batches/": {"post": {"summary": "Queue up to three CV comparisons", "parameters": [{"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "maxLength": 100}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["job_description", "candidates"], "properties": {"job_title": {"type": "string", "maxLength": 150}, "job_description": {"type": "string", "maxLength": 20000}, "candidates": {"type": "array", "minItems": 1, "maxItems": 3, "items": {"$ref": "#/components/schemas/Candidate"}}}}}, "multipart/form-data": {"schema": {"type": "object", "required": ["job_description", "cvs"], "properties": {"job_description": {"type": "string"}, "job_title": {"type": "string"}, "cvs": {"type": "array", "minItems": 1, "maxItems": 3, "items": {"type": "string", "format": "binary"}}}}}}}, "responses": {"200": {"description": "Existing idempotent batch", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Batch"}}}}, "202": {"description": "Queued", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Batch"}}}}, "400": {"description": "Invalid input", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Invalid key", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "No credits", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Pilot unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Idempotency conflict", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "413": {"description": "Too large", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "415": {"description": "Unsupported media type", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Limit reached", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/batches/{id}/": {"parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "get": {"summary": "Read your batch status and results", "responses": {"200": {"description": "Status and advisory results", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Batch"}}}}, "404": {"description": "Not found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}, "delete": {"summary": "Delete your retained input and results; completed credits are not refunded", "responses": {"200": {"description": "Deleted", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Batch"}}}}, "409": {"description": "Processing in progress", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/batches/{id}/csv/": {"parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "get": {"summary": "Export your completed results", "responses": {"200": {"description": "CSV results", "content": {"text/csv": {"schema": {"type": "string"}}}}, "409": {"description": "Not completed", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/usage/": {"get": {"summary": "Read your pilot usage", "responses": {"200": {"description": "Allowance, reservations, expiry and rate limits", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Usage"}}}}}}}}}