{ "openapi": "3.1.0", "info": { "title": "ProBB AI Customer API", "version": "1.4.0", "description": "Connect your recruiting system to ProBB AI: discover jobs, analyse resumes, invite candidates, retrieve evidence, and receive signed updates. Start with the developer guide, then use this reference for exact inputs and responses. Access is scoped to one enabled workspace and the permissions on your server-side API key." }, "servers": [ { "url": "https://app.probbai.com", "description": "Production: use your configured ProBB AI application origin. Interactive examples use a separately configured sandbox." } ], "security": [ { "ApiKey": [] } ], "paths": { "/api/v1/uploads": { "post": { "operationId": "prepareUpload", "summary": "Prepare a resume upload", "description": "Create a report and a temporary upload destination before analysing a resume. Use this to connect one candidate application to a job description. This step does not start analysis.\n\n## Before you call\n\nHave one PDF or DOCX (up to 10 MiB), its exact byte length, and job text or an active saved job ID. Choose a stable Idempotency-Key for this preparation.\n\n**Required scope:** `analyses:write`.\n\n## What happens next\n\nSave reportId, then PUT the file bytes to upload.url using upload.mimeType. Do not send your API key to storage. The URL lasts ten minutes; the preparation lasts 24 hours. After uploading, request an analysis quote.\n\n## Recovery\n\nRepeat the identical body/key after a timeout. EXTERNAL_REFERENCE_CONFLICT means the application reference is already used. JD_REVISION_CHANGED requires reviewing the updated job. PENDING_UPLOAD_LIMIT requires cancelling unused preparations or waiting for expiry.\n\n[Follow the complete workflow](/integration-api/) · [Errors and retries](/api-errors/)", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Stable key for one logical write. Retry the identical body with the same key after a timeout; a changed body conflicts. 1–128 letters, digits, dots, underscores, colons, or hyphens." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadInput" }, "example": { "fileName": "resume.pdf", "fileSize": 1024, "mimeType": "application/pdf", "externalReference": { "source": "my-ats", "id": "application-42" }, "jobDescription": { "kind": "text", "text": "Build reliable backend services. Required: API development, PostgreSQL, and production incident response." } } } } }, "responses": { "201": { "description": "Save reportId, then PUT the file bytes to upload.url using upload.mimeType. Do not send your API key to storage. The URL lasts ten minutes; the preparation lasts 24 hours. After uploading, request an analysis quote.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Upload" } } }, "example": { "data": { "reportId": "report_example", "upload": { "url": "https://storage.example.test/upload/synthetic-resume", "method": "PUT", "mimeType": "application/pdf", "sizeBytes": 1024, "expiresInSeconds": 600 } } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "Repeat the identical body/key after a timeout. EXTERNAL_REFERENCE_CONFLICT means the application reference is already used. JD_REVISION_CHANGED requires reviewing the updated job. PENDING_UPLOAD_LIMIT requires cancelling unused preparations or waiting for expiry.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "422": { "description": "Input cannot be processed or workspace allowance/capacity is insufficient. Inspect error.reason before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNPROCESSABLE_CONTENT", "message": "Analysis admission rejected. Check the upload, available quota or credits, and active work limits.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Uploads"], "x-required-scope": "analyses:write", "x-purpose": "Create a report and a temporary upload destination before analysing a resume. Use this to connect one candidate application to a job description. This step does not start analysis.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\n# Set REQUEST_KEY once for this logical write; reuse it with the same body on retries.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/uploads\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H \"Idempotency-Key: $REQUEST_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"fileName\": \"resume.pdf\",\n \"fileSize\": 1024,\n \"mimeType\": \"application/pdf\",\n \"externalReference\": {\n \"source\": \"my-ats\",\n \"id\": \"application-42\"\n },\n \"jobDescription\": {\n \"kind\": \"text\",\n \"text\": \"Build reliable backend services. Required: API development, PostgreSQL, and production incident response.\"\n }\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/uploads\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Idempotency-Key\": process.env.REQUEST_KEY, // retain for retries\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"fileName\": \"resume.pdf\",\n \"fileSize\": 1024,\n \"mimeType\": \"application/pdf\",\n \"externalReference\": {\n \"source\": \"my-ats\",\n \"id\": \"application-42\"\n },\n \"jobDescription\": {\n \"kind\": \"text\",\n \"text\": \"Build reliable backend services. Required: API development, PostgreSQL, and production incident response.\"\n }\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/uploads\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Idempotency-Key\"] = os.environ[\"REQUEST_KEY\"] # retain for retries\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"fileName\": \"resume.pdf\",\n \"fileSize\": 1024,\n \"mimeType\": \"application/pdf\",\n \"externalReference\": {\n \"source\": \"my-ats\",\n \"id\": \"application-42\"\n },\n \"jobDescription\": {\n \"kind\": \"text\",\n \"text\": \"Build reliable backend services. Required: API development, PostgreSQL, and production incident response.\"\n }\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/uploads/{id}/url": { "post": { "operationId": "refreshUploadUrl", "summary": "Refresh an upload URL", "description": "Get a fresh storage URL when the ten-minute upload URL has expired. Keep the same prepared report instead of creating a duplicate.\n\n## Before you call\n\nUse the reportId returned by preparation. The preparation must still exist and analysis must not have been admitted. This operation has no JSON body.\n\n**Required scope:** `analyses:write`.\n\n## What happens next\n\nPUT the original file to the new URL, then quote and submit the analysis. Refreshing does not extend the preparation beyond its 24-hour lifetime.\n\n## Recovery\n\nA missing or expired preparation requires a new preparation. A 409 means the resource is already admitted; read report status instead of uploading again.\n\n[Follow the complete workflow](/integration-api/) · [Errors and retries](/api-errors/)", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." } ], "responses": { "200": { "description": "PUT the original file to the new URL, then quote and submit the analysis. Refreshing does not extend the preparation beyond its 24-hour lifetime.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Upload" } } }, "example": { "data": { "reportId": "report_example", "upload": { "url": "https://storage.example.test/upload/synthetic-resume", "method": "PUT", "mimeType": "application/pdf", "sizeBytes": 1024, "expiresInSeconds": 600 } } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "A missing or expired preparation requires a new preparation. A 409 means the resource is already admitted; read report status instead of uploading again.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Uploads"], "x-required-scope": "analyses:write", "x-purpose": "Get a fresh storage URL when the ten-minute upload URL has expired. Keep the same prepared report instead of creating a duplicate.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/uploads/RESOURCE_ID/url\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/uploads/RESOURCE_ID/url\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/uploads/RESOURCE_ID/url\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/analysis-quotes": { "post": { "operationId": "quoteAnalysis", "summary": "Quote an analysis", "description": "Check the assigned report version and applicable price before starting analysis. The fingerprint binds the subsequent submission to the configuration you reviewed.\n\n## Before you call\n\nPrepare a report first. Use its reportId; upload the actual file before submitting the analysis.\n\n**Required scope:** `analyses:write`.\n\n## What happens next\n\nSave fingerprint and send it as quoteFingerprint to Start an analysis. Quoting does not reserve capacity or start processing. Prices shown in examples are illustrative; use your response.\n\n## Recovery\n\nIf the report is absent or expired, prepare it again. If configuration changes before submission, obtain a new quote and use a new submission key.\n\n[Follow the complete workflow](/integration-api/) · [Errors and retries](/api-errors/)", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteInput" }, "example": { "reportId": "report_example" } } } }, "responses": { "200": { "description": "Save fingerprint and send it as quoteFingerprint to Start an analysis. Quoting does not reserve capacity or start processing. Prices shown in examples are illustrative; use your response.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Quote" } } }, "example": { "data": { "reportId": "report_example", "reportSystemVersion": "assigned-report-version", "creditUnits": 100, "creditScale": 100, "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "If the report is absent or expired, prepare it again. If configuration changes before submission, obtain a new quote and use a new submission key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Analyses"], "x-required-scope": "analyses:write", "x-purpose": "Check the assigned report version and applicable price before starting analysis. The fingerprint binds the subsequent submission to the configuration you reviewed.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/analysis-quotes\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"reportId\": \"report_example\"\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/analysis-quotes\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"reportId\": \"report_example\"\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/analysis-quotes\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"reportId\": \"report_example\"\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/analyses": { "post": { "operationId": "startAnalysis", "summary": "Start an analysis", "description": "Submit the uploaded resume for asynchronous analysis against its job description. Use this after a successful storage upload and a current quote.\n\n## Before you call\n\nSend the prepared reportId, quoteFingerprint, and a stable Idempotency-Key. Capacity and the workspace allowance are checked at admission.\n\n**Required scope:** `analyses:write`.\n\n## What happens next\n\nA 202 means the analysis was accepted, not completed. Save attemptId and follow statusUrl or report events. The accepted file is frozen for this attempt.\n\n## Recovery\n\nRetry identical requests after timeouts. QUOTE_STALE needs a new quote/key. INVALID_UPLOAD needs a corrected upload. ACTIVE_ANALYSIS_LIMIT means wait for capacity. After terminal failure, a deliberate new attempt needs a new key/current quote; completed analyses cannot be restarted here.\n\n[Follow the complete workflow](/integration-api/) · [Errors and retries](/api-errors/)", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Stable key for one logical write. Retry the identical body with the same key after a timeout; a changed body conflicts. 1–128 letters, digits, dots, underscores, colons, or hyphens." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisInput" }, "example": { "reportId": "report_example", "quoteFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "responses": { "202": { "description": "A 202 means the analysis was accepted, not completed. Save attemptId and follow statusUrl or report events. The accepted file is frozen for this attempt.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Admission" } } }, "example": { "data": { "reportId": "report_example", "attemptId": "attempt_example", "statusUrl": "/api/v1/reports/report_example/status" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "Retry identical requests after timeouts. QUOTE_STALE needs a new quote/key. INVALID_UPLOAD needs a corrected upload. ACTIVE_ANALYSIS_LIMIT means wait for capacity. After terminal failure, a deliberate new attempt needs a new key/current quote; completed analyses cannot be restarted here.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "422": { "description": "Input cannot be processed or workspace allowance/capacity is insufficient. Inspect error.reason before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNPROCESSABLE_CONTENT", "message": "Analysis admission rejected. Check the upload, available quota or credits, and active work limits.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Analyses"], "x-required-scope": "analyses:write", "x-purpose": "Submit the uploaded resume for asynchronous analysis against its job description. Use this after a successful storage upload and a current quote.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\n# Set REQUEST_KEY once for this logical write; reuse it with the same body on retries.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/analyses\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H \"Idempotency-Key: $REQUEST_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"reportId\": \"report_example\",\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/analyses\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Idempotency-Key\": process.env.REQUEST_KEY, // retain for retries\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"reportId\": \"report_example\",\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/analyses\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Idempotency-Key\"] = os.environ[\"REQUEST_KEY\"] # retain for retries\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"reportId\": \"report_example\",\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/reports/{id}": { "get": { "operationId": "getReport", "summary": "Get a report summary", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." }, { "in": "query", "name": "include", "required": false, "schema": { "type": "string", "enum": ["reference"] }, "description": "Set to reference to include externalReference in report summaries; omitted by default for compatibility." } ], "responses": { "200": { "description": "Inspect status before reading result. A null result is not a zero score. Use Get report status for polling or Get report result for the full public evaluation.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Report" } } }, "example": { "data": { "id": "report_example", "createdAt": "2026-09-29T12:00:00.000Z", "reportSystemVersion": "assigned-report-version", "status": "completed", "attemptId": "attempt_example", "code": null, "jobDescription": { "id": "job_example", "title": "Backend Engineer", "company": "Example Company" }, "candidate": { "name": "Alex Example", "currentRole": "Software Engineer" }, "result": { "score": 8, "summary": "Relevant backend delivery experience; validate incident response depth.", "scoreReasoning": "Strong API and database evidence, with limited detail on production incidents." } } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Reports"], "x-required-scope": "reports:read", "description": "Read candidate and job context with a compact resume-analysis result. Use this for an application overview; use the detailed result endpoint for rubric evidence.\n\n## Before you call\n\nUse a reportId from preparation, admission, list results, or a report event. Add include=reference to include your external application reference.\n\n**Required scope:** `reports:read`.\n\n## What happens next\n\nInspect status before reading result. A null result is not a zero score. Use Get report status for polling or Get report result for the full public evaluation.\n\n## Recovery\n\nA 404 means the report is unavailable to this workspace or was removed. requires_action needs a human review in the app. Do not repeatedly resubmit to bypass that review.\n\n[Follow the complete workflow](/integration-results/) · [Errors and retries](/api-errors/)", "x-purpose": "Read candidate and job context with a compact resume-analysis result. Use this for an application overview; use the detailed result endpoint for rubric evidence.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/reports/RESOURCE_ID\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/reports/RESOURCE_ID\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/reports/RESOURCE_ID\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/reports/{id}/status": { "get": { "operationId": "getReportStatus", "summary": "Get report status", "description": "Poll the small status response while analysis is running, or reconcile a delayed webhook with the current attempt.\n\n## Before you call\n\nUse the reportId returned by preparation or admission. Keep polling infrequent enough to respect your read limit.\n\n**Required scope:** `reports:read`.\n\n## What happens next\n\nqueued and processing mean wait. completed means retrieve the result; requires_action means review in the app; failed means inspect code. attemptId is null before admission and can be null for legacy reports.\n\n## Recovery\n\nCompare the event attemptId with the current one before updating your records. Worker retries keep the attempt ID; a newly admitted run changes it. Do not infer failure from elapsed time alone.\n\n[Follow the complete workflow](/integration-results/) · [Errors and retries](/api-errors/)", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." } ], "responses": { "200": { "description": "queued and processing mean wait. completed means retrieve the result; requires_action means review in the app; failed means inspect code. attemptId is null before admission and can be null for legacy reports.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReportStatus" } } }, "example": { "data": { "id": "report_example", "status": "completed", "attemptId": "attempt_example", "code": null, "reportSystemVersion": "assigned-report-version" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Reports"], "x-required-scope": "reports:read", "x-purpose": "Poll the small status response while analysis is running, or reconcile a delayed webhook with the current attempt.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/reports/RESOURCE_ID/status\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/reports/RESOURCE_ID/status\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/reports/RESOURCE_ID/status\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/reports": { "get": { "operationId": "listReports", "summary": "List reports", "description": "Find reports in your workspace, reconcile stored application IDs, or backfill your local report index.\n\n## Before you call\n\nUse createdAfter/createdBefore for exclusive time bounds. External-reference filtering requires both source and ID. include=reference adds the reference to each returned report.\n\n**Required scope:** `reports:read`.\n\n## What happens next\n\nRead items and pass nextCursor unchanged to the next request with the same filters. null means the current list is exhausted. Reports are newest first.\n\n## Recovery\n\nStart from the first page if filters change or a cursor is invalid. Newer reports inserted during pagination appear on a fresh first page. Old unsigned cursors are no longer accepted.\n\n[Follow the complete workflow](/integration-discovery/) · [Errors and retries](/api-errors/)", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size, 1–100; defaults to 25." }, { "in": "query", "name": "externalReferenceSource", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": "External source slug. Must be supplied with externalReferenceId." }, { "in": "query", "name": "externalReferenceId", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Case-sensitive application ID. Must be supplied with externalReferenceSource." }, { "in": "query", "name": "include", "required": false, "schema": { "type": "string", "const": "reference" }, "description": "Set to reference to include externalReference in report summaries; omitted by default for compatibility." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Opaque cursor from the previous page. Repeat all filters unchanged. Never decode or construct a cursor yourself." }, { "in": "query", "name": "createdAfter", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "Exclusive lower creation-time bound, ISO 8601 with timezone." }, { "in": "query", "name": "createdBefore", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "Exclusive upper creation-time bound, ISO 8601 with timezone; must be later than createdAfter." } ], "responses": { "200": { "description": "Read items and pass nextCursor unchanged to the next request with the same filters. null means the current list is exhausted. Reports are newest first.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ReportPage" } } }, "example": { "data": { "items": [ { "id": "report_example", "createdAt": "2026-09-29T12:00:00.000Z", "reportSystemVersion": "assigned-report-version", "status": "completed", "attemptId": "attempt_example", "code": null, "jobDescription": { "id": "job_example", "title": "Backend Engineer", "company": "Example Company" }, "candidate": { "name": "Alex Example", "currentRole": "Software Engineer" }, "result": { "score": 8, "summary": "Relevant backend delivery experience; validate incident response depth.", "scoreReasoning": "Strong API and database evidence, with limited detail on production incidents." } } ], "nextCursor": null } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Reports"], "x-required-scope": "reports:read", "x-purpose": "Find reports in your workspace, reconcile stored application IDs, or backfill your local report index.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/reports\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/reports\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/reports\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/uploads/{id}": { "delete": { "operationId": "cancelUpload", "summary": "Cancel a pending upload", "description": "Release an unused preparation when an application is withdrawn or you no longer intend to upload its resume.\n\n## Before you call\n\nUse the reportId from preparation. Only unadmitted preparations can be cancelled. No JSON body or Idempotency-Key is needed.\n\n**Required scope:** `analyses:write`.\n\n## What happens next\n\nA 204 has no response body. The pending preparation no longer consumes preparation capacity; this does not cancel an accepted analysis.\n\n## Recovery\n\nCancellation is safe to repeat for an absent preparation. A conflict means analysis has already been admitted; inspect report status.\n\n[Follow the complete workflow](/integration-api/) · [Errors and retries](/api-errors/)", "x-required-scope": "analyses:write", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." } ], "responses": { "204": { "description": "A 204 has no response body. The pending preparation no longer consumes preparation capacity; this does not cancel an accepted analysis.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "Cancellation is safe to repeat for an absent preparation. A conflict means analysis has already been admitted; inspect report status.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Uploads"], "x-purpose": "Release an unused preparation when an application is withdrawn or you no longer intend to upload its resume.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X DELETE \"$PROBB_URL/api/v1/uploads/RESOURCE_ID\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/uploads/RESOURCE_ID\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"DELETE\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/uploads/RESOURCE_ID\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"DELETE\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/job-descriptions": { "get": { "operationId": "listJobDescriptions", "summary": "List job descriptions", "description": "Discover saved jobs so your integration can attach resumes to an existing role instead of copying job text into every request.\n\n## Before you call\n\nUse job-descriptions:read. By default only ACTIVE jobs are listed; search matches titles/companies. Archived jobs can be listed explicitly.\n\n**Required scope:** `job-descriptions:read`.\n\n## What happens next\n\nSave the selected job ID and fetch its full description. Follow nextCursor with unchanged search/status filters; null means the end.\n\n## Recovery\n\nArchived jobs cannot admit new work. If a role disappears, refresh the list and ask a workspace user to confirm the intended job. This API does not create or edit jobs.\n\n[Follow the complete workflow](/integration-discovery/) · [Errors and retries](/api-errors/)", "x-required-scope": "job-descriptions:read", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size, 1–100; defaults to 25." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Opaque cursor from the previous page. Repeat all filters unchanged. Never decode or construct a cursor yourself." }, { "in": "query", "name": "status", "required": false, "schema": { "default": "ACTIVE", "type": "string", "enum": ["ACTIVE", "ARCHIVED"] }, "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, { "in": "query", "name": "search", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Search saved job titles/companies, 1–120 characters after trimming." } ], "responses": { "200": { "description": "Save the selected job ID and fetch its full description. Follow nextCursor with unchanged search/status filters; null means the end.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/JobDescriptionPage" } } }, "example": { "data": { "items": [ { "id": "job_example", "title": "Backend Engineer", "company": "Example Company", "team": "Platform", "location": "Remote", "level": "Senior", "employmentType": "FULL_TIME", "status": "ACTIVE", "revision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "createdAt": "2026-09-29T12:00:00.000Z", "updatedAt": "2026-09-29T12:00:00.000Z" } ], "nextCursor": null } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Job descriptions"], "x-purpose": "Discover saved jobs so your integration can attach resumes to an existing role instead of copying job text into every request.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/job-descriptions\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/job-descriptions\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/job-descriptions\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/job-descriptions/{id}": { "get": { "operationId": "getJobDescription", "summary": "Get a job description", "description": "Read the full saved job and its content revision before attaching a candidate application.\n\n## Before you call\n\nUse an ID from List job descriptions. Check status is ACTIVE before preparing a new report.\n\n**Required scope:** `job-descriptions:read`.\n\n## What happens next\n\nPass the ID with kind=existing in the upload input. Send revision as expectedRevision when you want submission to fail if the job changes.\n\n## Recovery\n\nA 404 means the job is not available in this workspace. On JD_REVISION_CHANGED during preparation, read the job again and review the revised requirements before retrying.\n\n[Follow the complete workflow](/integration-discovery/) · [Errors and retries](/api-errors/)", "x-required-scope": "job-descriptions:read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." } ], "responses": { "200": { "description": "Pass the ID with kind=existing in the upload input. Send revision as expectedRevision when you want submission to fail if the job changes.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/JobDescription" } } }, "example": { "data": { "id": "job_example", "title": "Backend Engineer", "company": "Example Company", "team": "Platform", "location": "Remote", "level": "Senior", "employmentType": "FULL_TIME", "status": "ACTIVE", "description": "Build reliable backend services. Required: API development, PostgreSQL, and production incident response.", "revision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "createdAt": "2026-09-29T12:00:00.000Z", "updatedAt": "2026-09-29T12:00:00.000Z" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Job descriptions"], "x-purpose": "Read the full saved job and its content revision before attaching a candidate application.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/job-descriptions/RESOURCE_ID\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/job-descriptions/RESOURCE_ID\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/job-descriptions/RESOURCE_ID\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/reports/{id}/result": { "get": { "operationId": "getReportResult", "summary": "Get report evidence", "description": "Retrieve the versioned resume evaluation for an evidence-based review in your application. This includes rubric findings, supporting evidence, gaps, and follow-up questions.\n\n## Before you call\n\nUse reports:read and schemaVersion=1 (the default). Wait for a completed report or a report.result_ready event.\n\n**Required scope:** `reports:read`.\n\n## What happens next\n\nSave resultRevision with the resource and attempt IDs. Read scoreScale, limitations, and evidence before displaying a score. A pending or failed report has result=null. Text and lists are bounded.\n\n## Recovery\n\nRESULT_VERSION_UNSUPPORTED means request a supported schema version. Missing measurements are unknown, not zero. A 404 after a deletion event is expected; stop polling that resource.\n\n[Follow the complete workflow](/integration-results/) · [Errors and retries](/api-errors/)", "x-required-scope": "reports:read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." }, { "in": "query", "name": "schemaVersion", "required": false, "schema": { "default": "1", "type": "string", "const": "1" }, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." } ], "responses": { "200": { "description": "Save resultRevision with the resource and attempt IDs. Read scoreScale, limitations, and evidence before displaying a score. A pending or failed report has result=null. Text and lists are bounded.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RichResult" } } }, "example": { "data": { "schemaVersion": 1, "reportId": "report_example", "attemptId": "attempt_example", "reportSystemVersion": "assigned-report-version", "resultRevision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "publishedAt": "2026-09-29T12:00:00.000Z", "status": "completed", "code": null, "externalReference": { "source": "my-ats", "id": "application-42" }, "result": { "scoreScale": { "minimum": 0, "maximum": 10 }, "score": 8, "summary": "Relevant backend delivery experience; validate incident response depth.", "scoreReasoning": "Strong API and database evidence, with limited detail on production incidents.", "humanReviewRecommendation": "Validate operational experience in an interview.", "rubric": [ { "key": "backend", "label": "Backend delivery", "status": "positive", "score": 8, "analysis": "Relevant API delivery experience.", "evidence": [ "Built and maintained a PostgreSQL-backed API." ], "gaps": [ "Incident response ownership is not described." ] } ], "highlights": [ { "category": "technicalCore", "label": "API development", "status": "positive", "summary": "Relevant delivery evidence." } ], "followUpQuestions": { "technical": [ "Describe a database performance investigation." ], "clarification": [ "What was your role in production support?" ], "riskReview": [] }, "integrity": { "riskLevel": "low", "summary": "No conflicting identity evidence in this synthetic example.", "signals": [] }, "policyWarnings": [], "ignoredCriteria": [] } } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Reports"], "x-purpose": "Retrieve the versioned resume evaluation for an evidence-based review in your application. This includes rubric findings, supporting evidence, gaps, and follow-up questions.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/reports/RESOURCE_ID/result\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/reports/RESOURCE_ID/result\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/reports/RESOURCE_ID/result\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/events": { "get": { "operationId": "listEvents", "summary": "Read retained events", "description": "Recover notifications missed by your receiver or poll changes without hosting a webhook endpoint. The feed follows durable publication order within your workspace.\n\n## Before you call\n\nUse events:read. Start without a cursor, then retain the returned position. Optional type/reportId/interviewId filters must remain unchanged while following a cursor.\n\n**Required scope:** `events:read`.\n\n## What happens next\n\nProcess items durably before saving nextCursor, even on an empty page. Use hasMore to drain retained pages. Deleted bodies appear as minimal tombstones; a cursor is an opaque credential-like value, not an offset.\n\n## Recovery\n\nEVENT_CURSOR_EXPIRED returns 410 after retained history is lost. Reconcile current reports/interviews and establish a fresh position. Polling does not resend webhooks; use catch-up or replay for receiver redelivery.\n\n[Follow the complete workflow](/integration-webhooks/) · [Errors and retries](/api-errors/)", "x-required-scope": "events:read", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size, 1–100; defaults to 25." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Opaque cursor from the previous page. Repeat all filters unchanged. Never decode or construct a cursor yourself." }, { "in": "query", "name": "type", "required": false, "schema": { "type": "string", "enum": [ "batch.completed", "report.completed", "report.result_ready", "report.deleted", "report.failed", "report.requires_action", "webhook.test", "interview.invited", "interview.started", "interview.completed", "interview.expired", "interview.preparation_failed", "interview.result_ready", "interview.result_failed", "interview.invitation_failed" ] }, "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, { "in": "query", "name": "reportId", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, { "in": "query", "name": "interviewId", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Logical interview attempt ID returned by invitation. A reinterview receives a new ID." } ], "responses": { "200": { "description": "Process items durably before saving nextCursor, even on an empty page. Use hasMore to drain retained pages. Deleted bodies appear as minimal tombstones; a cursor is an opaque credential-like value, not an offset.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/EventPage" } } }, "example": { "data": { "items": [ { "id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d", "type": "report.completed", "schemaVersion": 1, "occurredAt": "2026-09-29T12:00:00.000Z", "data": { "reportId": "report_example", "attemptId": "attempt_example", "status": "completed", "code": null } } ], "nextCursor": "opaque-server-issued-cursor", "hasMore": false } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "410": { "description": "Event recovery cursor is outside retained history", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "reason": "EVENT_CURSOR_EXPIRED", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Events"], "x-purpose": "Recover notifications missed by your receiver or poll changes without hosting a webhook endpoint. The feed follows durable publication order within your workspace.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/events\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/events\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/events\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/interview-quotes": { "post": { "operationId": "quoteInterview", "summary": "Quote an interview", "description": "Check the assigned configuration and applicable price before inviting a candidate. The returned fingerprint binds the invitation details to the quote you reviewed.\n\n## Before you call\n\nUse a report with a usable completed analysis, candidateEmail, and sendEmail. Resolve mismatch review in the app first.\n\n**Required scope:** `interviews:write`.\n\n## What happens next\n\nPass fingerprint as quoteFingerprint with the same report, email, and delivery choice to Invite a candidate. A quote sends no email and reserves no capacity.\n\n## Recovery\n\nAn unfinished or unusable analysis cannot be quoted for interview. Requote if the invitation details or assigned configuration change. Example prices are illustrative.\n\n[Follow the complete workflow](/integration-interviews/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewQuoteInput" }, "example": { "reportId": "report_example", "candidateEmail": "candidate@example.test", "sendEmail": true } } } }, "responses": { "200": { "description": "Pass fingerprint as quoteFingerprint with the same report, email, and delivery choice to Invite a candidate. A quote sends no email and reserves no capacity.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InterviewQuote" } } }, "example": { "data": { "reportId": "report_example", "creditUnits": 100, "creditScale": 100, "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "interviewSystemVersion": "assigned-interview-version" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "An unfinished or unusable analysis cannot be quoted for interview. Requote if the invitation details or assigned configuration change. Example prices are illustrative.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Interviews"], "x-purpose": "Check the assigned configuration and applicable price before inviting a candidate. The returned fingerprint binds the invitation details to the quote you reviewed.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/interview-quotes\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interview-quotes\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interview-quotes\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/interviews": { "post": { "operationId": "inviteInterview", "summary": "Invite a candidate", "description": "Create an interview attempt and prepare its questions. ProBB AI can send the invitation email, or your own system can deliver the candidate link.\n\n## Before you call\n\nObtain a current interview quote and send the same details plus quoteFingerprint with a stable Idempotency-Key. The workspace must have interview allowance.\n\n**Required scope:** `interviews:write`.\n\n## What happens next\n\nA 202 returns interviewId and statusUrl. With sendEmail=true, invitationToken is null. With false, securely deliver /interview/{invitationToken} on the application origin yourself. Preparation and email delivery proceed independently.\n\n## Recovery\n\nRepeat the same body/key after a timeout. A returned token is a bearer credential; never log it. Replays only recover an eligible current pending invitation. Use resend for another email and reinterview for a new attempt.\n\n[Follow the complete workflow](/integration-interviews/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:write", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Stable key for one logical write. Retry the identical body with the same key after a timeout; a changed body conflicts. 1–128 letters, digits, dots, underscores, colons, or hyphens." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewInput" }, "example": { "reportId": "report_example", "candidateEmail": "candidate@example.test", "sendEmail": true, "quoteFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "responses": { "202": { "description": "A 202 returns interviewId and statusUrl. With sendEmail=true, invitationToken is null. With false, securely deliver /interview/{invitationToken} on the application origin yourself. Preparation and email delivery proceed independently.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InterviewAdmission" } } }, "example": { "data": { "interviewId": "interview_example", "reportId": "report_example", "invitationToken": null, "statusUrl": "/api/v1/interviews/interview_example/status", "emailDelivery": "queued" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "Repeat the same body/key after a timeout. A returned token is a bearer credential; never log it. Replays only recover an eligible current pending invitation. Use resend for another email and reinterview for a new attempt.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "422": { "description": "Input cannot be processed or workspace allowance/capacity is insufficient. Inspect error.reason before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNPROCESSABLE_CONTENT", "message": "Analysis admission rejected. Check the upload, available quota or credits, and active work limits.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Interviews"], "x-purpose": "Create an interview attempt and prepare its questions. ProBB AI can send the invitation email, or your own system can deliver the candidate link.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\n# Set REQUEST_KEY once for this logical write; reuse it with the same body on retries.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/interviews\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H \"Idempotency-Key: $REQUEST_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true,\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interviews\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Idempotency-Key\": process.env.REQUEST_KEY, // retain for retries\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true,\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interviews\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Idempotency-Key\"] = os.environ[\"REQUEST_KEY\"] # retain for retries\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true,\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] }, "get": { "operationId": "listInterviews", "summary": "List interviews", "description": "Find interview attempts for a report or external application, including prior attempts that remain available.\n\n## Before you call\n\nUse interviews:read. Optional filters include reportId, lifecycle, or both external-reference fields.\n\n**Required scope:** `interviews:read`.\n\n## What happens next\n\nRead each attempt independently and follow nextCursor with identical filters. Keep interview IDs separate from report IDs. Fetch a result for an attempt whose evaluation is ready.\n\n## Recovery\n\nA completed lifecycle is not proof the evaluation is ready. Filter on lifecycle only to select candidate progress; inspect evaluation separately.\n\n[Follow the complete workflow](/integration-interviews/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:read", "parameters": [ { "in": "query", "name": "reportId", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, { "in": "query", "name": "lifecycle", "required": false, "schema": { "type": "string", "enum": [ "invited", "in_progress", "completed", "expired", "superseded" ] }, "description": "Candidate progress: invited, in_progress, completed, expired, or superseded. Independent of preparation and evaluation." }, { "in": "query", "name": "externalReferenceSource", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": "External source slug. Must be supplied with externalReferenceId." }, { "in": "query", "name": "externalReferenceId", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Case-sensitive application ID. Must be supplied with externalReferenceSource." }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Page size, 1–100; defaults to 25." }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Opaque cursor from the previous page. Repeat all filters unchanged. Never decode or construct a cursor yourself." } ], "responses": { "200": { "description": "Read each attempt independently and follow nextCursor with identical filters. Keep interview IDs separate from report IDs. Fetch a result for an attempt whose evaluation is ready.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InterviewPage" } } }, "example": { "data": { "items": [ { "id": "interview_example", "reportId": "report_example", "interviewSystemVersion": "assigned-interview-version", "createdAt": "2026-09-29T12:00:00.000Z", "expiresAt": "2026-10-06T12:00:00.000Z", "startedAt": null, "completedAt": null, "lifecycle": "invited", "preparation": "queued", "evaluation": "not_started", "emailDelivery": "queued", "resultRevision": null } ], "nextCursor": null } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Interviews"], "x-purpose": "Find interview attempts for a report or external application, including prior attempts that remain available.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/interviews\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interviews\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interviews\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/interviews/{id}": { "get": { "operationId": "getInterview", "summary": "Get an interview", "description": "Read the independent candidate, preparation, evaluation, and email states of an interview attempt. Use this as the current attempt overview.\n\n## Before you call\n\nUse the interviewId returned by invitation or List interviews, not the reportId.\n\n**Required scope:** `interviews:read`.\n\n## What happens next\n\nlifecycle tracks the candidate. preparation=ready means questions are prepared. evaluation=ready means the evaluation is available. emailDelivery=sent means provider acceptance, not inbox delivery.\n\n## Recovery\n\nFetch the result only when evaluation is ready. A preparation or delivery failure can occur while lifecycle remains invited. An expired or superseded invitation cannot start a new session.\n\n[Follow the complete workflow](/integration-interviews/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." } ], "responses": { "200": { "description": "lifecycle tracks the candidate. preparation=ready means questions are prepared. evaluation=ready means the evaluation is available. emailDelivery=sent means provider acceptance, not inbox delivery.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Interview" } } }, "example": { "data": { "id": "interview_example", "reportId": "report_example", "interviewSystemVersion": "assigned-interview-version", "createdAt": "2026-09-29T12:00:00.000Z", "expiresAt": "2026-10-06T12:00:00.000Z", "startedAt": null, "completedAt": null, "lifecycle": "invited", "preparation": "queued", "evaluation": "not_started", "emailDelivery": "queued", "resultRevision": null } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Interviews"], "x-purpose": "Read the independent candidate, preparation, evaluation, and email states of an interview attempt. Use this as the current attempt overview.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/interviews/RESOURCE_ID\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interviews/RESOURCE_ID\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interviews/RESOURCE_ID\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/interviews/{id}/status": { "get": { "operationId": "getInterviewStatus", "summary": "Get interview status", "description": "Read the independent candidate, preparation, evaluation, and email states of an interview attempt. Use this endpoint to poll after an invitation or reconcile webhook events.\n\n## Before you call\n\nUse the interviewId returned by invitation or List interviews, not the reportId.\n\n**Required scope:** `interviews:read`.\n\n## What happens next\n\nlifecycle tracks the candidate. preparation=ready means questions are prepared. evaluation=ready means the evaluation is available. emailDelivery=sent means provider acceptance, not inbox delivery.\n\n## Recovery\n\nFetch the result only when evaluation is ready. A preparation or delivery failure can occur while lifecycle remains invited. An expired or superseded invitation cannot start a new session.\n\n[Follow the complete workflow](/integration-interviews/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." } ], "responses": { "200": { "description": "lifecycle tracks the candidate. preparation=ready means questions are prepared. evaluation=ready means the evaluation is available. emailDelivery=sent means provider acceptance, not inbox delivery.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Interview" } } }, "example": { "data": { "id": "interview_example", "reportId": "report_example", "interviewSystemVersion": "assigned-interview-version", "createdAt": "2026-09-29T12:00:00.000Z", "expiresAt": "2026-10-06T12:00:00.000Z", "startedAt": null, "completedAt": null, "lifecycle": "invited", "preparation": "queued", "evaluation": "not_started", "emailDelivery": "queued", "resultRevision": null } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Interviews"], "x-purpose": "Read the independent candidate, preparation, evaluation, and email states of an interview attempt. Use this endpoint to poll after an invitation or reconcile webhook events.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/interviews/RESOURCE_ID/status\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interviews/RESOURCE_ID/status\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interviews/RESOURCE_ID/status\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/interviews/{id}/result": { "get": { "operationId": "getInterviewResult", "summary": "Get interview evidence", "description": "Read the published evaluation for a specific interview attempt, including strengths, concerns, requirement coverage, and review limitations.\n\n## Before you call\n\nUse interviews:read and schemaVersion=1. Wait for evaluation=ready or interview.result_ready.\n\n**Required scope:** `interviews:read`.\n\n## What happens next\n\nSave resultRevision. Skill scores are 0–10; readiness and requirement confidence/coverage are 0–100. Null means unmeasured. Raw transcripts and audio are not returned.\n\n## Recovery\n\nIf result is null, inspect preparation and evaluation states. Do not replace a failed or pending evaluation with a zero score. A new interview has a new ID; retain prior attempt identity when storing results.\n\n[Follow the complete workflow](/integration-interviews/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:read", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." }, { "in": "query", "name": "schemaVersion", "required": false, "schema": { "default": "1", "type": "string", "const": "1" }, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." } ], "responses": { "200": { "description": "Save resultRevision. Skill scores are 0–10; readiness and requirement confidence/coverage are 0–100. Null means unmeasured. Raw transcripts and audio are not returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InterviewResult" } } }, "example": { "data": { "id": "interview_example", "reportId": "report_example", "interviewSystemVersion": "assigned-interview-version", "createdAt": "2026-09-29T12:00:00.000Z", "expiresAt": "2026-10-06T12:00:00.000Z", "startedAt": "2026-09-29T12:00:00.000Z", "completedAt": "2026-09-29T12:18:00.000Z", "lifecycle": "completed", "preparation": "ready", "evaluation": "ready", "emailDelivery": "sent", "resultRevision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "schemaVersion": 1, "result": { "decision": "Proceed", "limitations": "Synthetic illustration. Human review of evidence remains necessary.", "coverage": { "score": 8, "transcriptQuality": "adequate" }, "integrity": { "status": "clear", "confidence": "medium" }, "requirements": [ { "requirement": "Production incident response", "status": "supported", "score": 8, "confidence": 75, "coverage": 80, "evidence": [ "Explained an incident investigation and follow-up." ], "gaps": ["Scale of the incident was not quantified."], "finding": "Validate operational scope." } ], "recommendation": "Proceed", "summary": "Relevant backend reasoning with a remaining scope question.", "scores": { "coreSkill": 8, "problemSolving": 8, "communication": 7, "roleFit": 8, "readiness": 80 }, "strengths": [ "Clear explanation of investigation steps." ], "concerns": ["Operational scale needs confirmation."], "evidence": [ { "dimension": "problemSolving", "reasoning": "Structured investigation.", "supportingEvidence": [ "Compared queries before and after an index change." ] } ] } } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Interviews"], "x-purpose": "Read the published evaluation for a specific interview attempt, including strengths, concerns, requirement coverage, and review limitations.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/interviews/RESOURCE_ID/result\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interviews/RESOURCE_ID/result\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interviews/RESOURCE_ID/result\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/interviews/{id}/resend": { "post": { "operationId": "resendInterview", "summary": "Resend an invitation", "description": "Queue another email for the same pending interview when the candidate needs the invitation again. This does not create a new interview or charge for one.\n\n## Before you call\n\nUse a current, eligible pending interview ID and a new Idempotency-Key for each intentional resend. No JSON body is needed.\n\n**Required scope:** `interviews:write`.\n\n## What happens next\n\nSave deliveryId and inspect emailDelivery on the interview. The candidate credential is unchanged. A 202 means the email was queued, not delivered to an inbox.\n\n## Recovery\n\nRetry a timed-out resend with the same key. A conflict means the invitation is no longer eligible. Providers may duplicate an email if an acknowledgment is lost; avoid repeated fresh resend keys.\n\n[Follow the complete workflow](/integration-interviews/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:write", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Stable key for one logical write. Retry the identical body with the same key after a timeout; a changed body conflicts. 1–128 letters, digits, dots, underscores, colons, or hyphens." } ], "responses": { "202": { "description": "Save deliveryId and inspect emailDelivery on the interview. The candidate credential is unchanged. A 202 means the email was queued, not delivered to an inbox.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InterviewResend" } } }, "example": { "data": { "interviewId": "interview_example", "deliveryId": "delivery_example" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "Retry a timed-out resend with the same key. A conflict means the invitation is no longer eligible. Providers may duplicate an email if an acknowledgment is lost; avoid repeated fresh resend keys.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Interviews"], "x-purpose": "Queue another email for the same pending interview when the candidate needs the invitation again. This does not create a new interview or charge for one.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\n# Set REQUEST_KEY once for this logical write; reuse it with the same body on retries.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/interviews/RESOURCE_ID/resend\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H \"Idempotency-Key: $REQUEST_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interviews/RESOURCE_ID/resend\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Idempotency-Key\": process.env.REQUEST_KEY, // retain for retries\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interviews/RESOURCE_ID/resend\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Idempotency-Key\"] = os.environ[\"REQUEST_KEY\"] # retain for retries\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/interviews/{id}/reinterview": { "post": { "operationId": "reinviteInterview", "summary": "Create a reinterview", "description": "Create a new interview attempt for a candidate who needs another session. Unlike resend, this prepares a new interview and uses the current assigned version and allowance.\n\n## Before you call\n\nUse the previous interview ID, a fresh quote for the same report, invitation details, and a new Idempotency-Key. An in-progress session cannot be replaced.\n\n**Required scope:** `interviews:write`.\n\n## What happens next\n\nSave the newly returned interviewId. Previous public results remain tied to the old attempt. Old invitation links cannot enter the replacement session.\n\n## Recovery\n\nCheck the old lifecycle before replacing it. Retry identical requests after timeouts; requote with a new key if configuration has changed. Do not use reinterview merely to resend an email.\n\n[Follow the complete workflow](/integration-interviews/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:write", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Stable key for one logical write. Retry the identical body with the same key after a timeout; a changed body conflicts. 1–128 letters, digits, dots, underscores, colons, or hyphens." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewInput" }, "example": { "reportId": "report_example", "candidateEmail": "candidate@example.test", "sendEmail": true, "quoteFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "responses": { "202": { "description": "Save the newly returned interviewId. Previous public results remain tied to the old attempt. Old invitation links cannot enter the replacement session.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InterviewAdmission" } } }, "example": { "data": { "interviewId": "interview_new", "reportId": "report_example", "invitationToken": null, "statusUrl": "/api/v1/interviews/interview_new/status", "emailDelivery": "queued" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "Check the old lifecycle before replacing it. Retry identical requests after timeouts; requote with a new key if configuration has changed. Do not use reinterview merely to resend an email.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "422": { "description": "Input cannot be processed or workspace allowance/capacity is insufficient. Inspect error.reason before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNPROCESSABLE_CONTENT", "message": "Analysis admission rejected. Check the upload, available quota or credits, and active work limits.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Interviews"], "x-purpose": "Create a new interview attempt for a candidate who needs another session. Unlike resend, this prepares a new interview and uses the current assigned version and allowance.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\n# Set REQUEST_KEY once for this logical write; reuse it with the same body on retries.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/interviews/RESOURCE_ID/reinterview\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H \"Idempotency-Key: $REQUEST_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true,\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interviews/RESOURCE_ID/reinterview\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Idempotency-Key\": process.env.REQUEST_KEY, // retain for retries\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true,\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interviews/RESOURCE_ID/reinterview\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Idempotency-Key\"] = os.environ[\"REQUEST_KEY\"] # retain for retries\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true,\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/upload-batches": { "post": { "operationId": "createUploadBatch", "summary": "Create an upload batch", "description": "Queue several uploads in one durable request and track outcomes by your own itemKey. Use this to process an application import without coordinating every admission yourself.\n\n## Before you call\n\nSupply 1–20 items, at most 256 KiB JSON, unique itemKey values, and an Idempotency-Key. Only one batch of each kind can be active per workspace.\n\n**Required scope:** `analyses:write`.\n\n## What happens next\n\nA 202 returns batchId and statusUrl. Items can succeed or fail independently. Each successful item creates a preparation, not an analysis. PUT each file to its item upload URL before quoting analyses.\n\n## Recovery\n\nKeep successful resource IDs. Capacity-limited items can wait up to the admission deadline; inspect per-item errorCode. Retry failed items deliberately in a new batch; analysis/interview items need fresh quotes. Foreign or unknown resource IDs reject the envelope.\n\n[Follow the complete workflow](/integration-bulk/) · [Errors and retries](/api-errors/)", "x-required-scope": "analyses:write", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Stable key for one logical write. Retry the identical body with the same key after a timeout; a changed body conflicts. 1–128 letters, digits, dots, underscores, colons, or hyphens." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadBatchInput" }, "example": { "items": [ { "itemKey": "application-42", "input": { "fileName": "resume.pdf", "fileSize": 1024, "mimeType": "application/pdf", "externalReference": { "source": "my-ats", "id": "application-42" }, "jobDescription": { "kind": "text", "text": "Build reliable backend services. Required: API development, PostgreSQL, and production incident response." } } } ] } } } }, "responses": { "202": { "description": "A 202 returns batchId and statusUrl. Items can succeed or fail independently. Each successful item creates a preparation, not an analysis. PUT each file to its item upload URL before quoting analyses.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BatchAdmission" } } }, "example": { "data": { "batchId": "batch_uploads", "statusUrl": "/api/v1/upload-batches/batch_uploads" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "Keep successful resource IDs. Capacity-limited items can wait up to the admission deadline; inspect per-item errorCode. Retry failed items deliberately in a new batch; analysis/interview items need fresh quotes. Foreign or unknown resource IDs reject the envelope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Batches"], "x-purpose": "Queue several uploads in one durable request and track outcomes by your own itemKey. Use this to process an application import without coordinating every admission yourself.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\n# Set REQUEST_KEY once for this logical write; reuse it with the same body on retries.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/upload-batches\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H \"Idempotency-Key: $REQUEST_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"fileName\": \"resume.pdf\",\n \"fileSize\": 1024,\n \"mimeType\": \"application/pdf\",\n \"externalReference\": {\n \"source\": \"my-ats\",\n \"id\": \"application-42\"\n },\n \"jobDescription\": {\n \"kind\": \"text\",\n \"text\": \"Build reliable backend services. Required: API development, PostgreSQL, and production incident response.\"\n }\n }\n }\n ]\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/upload-batches\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Idempotency-Key\": process.env.REQUEST_KEY, // retain for retries\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"fileName\": \"resume.pdf\",\n \"fileSize\": 1024,\n \"mimeType\": \"application/pdf\",\n \"externalReference\": {\n \"source\": \"my-ats\",\n \"id\": \"application-42\"\n },\n \"jobDescription\": {\n \"kind\": \"text\",\n \"text\": \"Build reliable backend services. Required: API development, PostgreSQL, and production incident response.\"\n }\n }\n }\n ]\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/upload-batches\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Idempotency-Key\"] = os.environ[\"REQUEST_KEY\"] # retain for retries\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"fileName\": \"resume.pdf\",\n \"fileSize\": 1024,\n \"mimeType\": \"application/pdf\",\n \"externalReference\": {\n \"source\": \"my-ats\",\n \"id\": \"application-42\"\n },\n \"jobDescription\": {\n \"kind\": \"text\",\n \"text\": \"Build reliable backend services. Required: API development, PostgreSQL, and production incident response.\"\n }\n }\n }\n ]\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/upload-batches/{id}": { "get": { "operationId": "getUploadBatch", "summary": "Get upload batch status", "description": "Read individual outcomes from an accepted upload batch. Use itemKey to match each outcome to the original application row.\n\n## Before you call\n\nUse the batchId from creation and the same scope required to create that kind of batch.\n\n**Required scope:** `analyses:write`.\n\n## What happens next\n\nRead item state, resourceId, attemptId, and errorCode. Each successful item creates a preparation, not an analysis. PUT each file to its item upload URL before quoting analyses.\n\n## Recovery\n\ncompleted means all item processing is terminal, not that every item succeeded. Do not resubmit successful items. A revoked key can stop unadmitted items while accepted work continues.\n\n[Follow the complete workflow](/integration-bulk/) · [Errors and retries](/api-errors/)", "x-required-scope": "analyses:write", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." } ], "responses": { "200": { "description": "Read item state, resourceId, attemptId, and errorCode. Each successful item creates a preparation, not an analysis. PUT each file to its item upload URL before quoting analyses.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Batch" } } }, "example": { "data": { "id": "batch_uploads", "kind": "uploads", "status": "completed", "createdAt": "2026-09-29T12:00:00.000Z", "expiresAt": "2026-09-29T13:00:00.000Z", "items": [ { "itemKey": "application-42", "state": "succeeded", "resourceId": "report_example", "attemptId": null, "errorCode": null, "upload": { "url": "https://storage.example.test/upload/synthetic-resume", "method": "PUT", "mimeType": "application/pdf", "sizeBytes": 1024, "expiresInSeconds": 600 } } ] } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Batches"], "x-purpose": "Read individual outcomes from an accepted upload batch. Use itemKey to match each outcome to the original application row.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/upload-batches/RESOURCE_ID\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/upload-batches/RESOURCE_ID\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/upload-batches/RESOURCE_ID\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/analysis-batches": { "post": { "operationId": "createAnalysisBatch", "summary": "Create an analysis batch", "description": "Queue several analyses in one durable request and track outcomes by your own itemKey. Use this to process an application import without coordinating every admission yourself.\n\n## Before you call\n\nSupply 1–20 items, at most 256 KiB JSON, unique itemKey values, and an Idempotency-Key. Only one batch of each kind can be active per workspace.\n\n**Required scope:** `analyses:write`.\n\n## What happens next\n\nA 202 returns batchId and statusUrl. Items can succeed or fail independently. Items finish only after their admitted analysis reaches a terminal outcome. Fetch each report to distinguish completed, failed, and requires_action.\n\n## Recovery\n\nKeep successful resource IDs. Capacity-limited items can wait up to the admission deadline; inspect per-item errorCode. Retry failed items deliberately in a new batch; analysis/interview items need fresh quotes. Foreign or unknown resource IDs reject the envelope.\n\n[Follow the complete workflow](/integration-bulk/) · [Errors and retries](/api-errors/)", "x-required-scope": "analyses:write", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Stable key for one logical write. Retry the identical body with the same key after a timeout; a changed body conflicts. 1–128 letters, digits, dots, underscores, colons, or hyphens." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisBatchInput" }, "example": { "items": [ { "itemKey": "application-42", "input": { "reportId": "report_example", "quoteFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } ] } } } }, "responses": { "202": { "description": "A 202 returns batchId and statusUrl. Items can succeed or fail independently. Items finish only after their admitted analysis reaches a terminal outcome. Fetch each report to distinguish completed, failed, and requires_action.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BatchAdmission" } } }, "example": { "data": { "batchId": "batch_analyses", "statusUrl": "/api/v1/analysis-batches/batch_analyses" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "Keep successful resource IDs. Capacity-limited items can wait up to the admission deadline; inspect per-item errorCode. Retry failed items deliberately in a new batch; analysis/interview items need fresh quotes. Foreign or unknown resource IDs reject the envelope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Batches"], "x-purpose": "Queue several analyses in one durable request and track outcomes by your own itemKey. Use this to process an application import without coordinating every admission yourself.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\n# Set REQUEST_KEY once for this logical write; reuse it with the same body on retries.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/analysis-batches\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H \"Idempotency-Key: $REQUEST_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\",\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n }\n }\n ]\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/analysis-batches\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Idempotency-Key\": process.env.REQUEST_KEY, // retain for retries\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\",\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n }\n }\n ]\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/analysis-batches\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Idempotency-Key\"] = os.environ[\"REQUEST_KEY\"] # retain for retries\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\",\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n }\n }\n ]\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/analysis-batches/{id}": { "get": { "operationId": "getAnalysisBatch", "summary": "Get analysis batch status", "description": "Read individual outcomes from an accepted analysis batch. Use itemKey to match each outcome to the original application row.\n\n## Before you call\n\nUse the batchId from creation and the same scope required to create that kind of batch.\n\n**Required scope:** `analyses:write`.\n\n## What happens next\n\nRead item state, resourceId, attemptId, and errorCode. Items finish only after their admitted analysis reaches a terminal outcome. Fetch each report to distinguish completed, failed, and requires_action.\n\n## Recovery\n\ncompleted means all item processing is terminal, not that every item succeeded. Do not resubmit successful items. A revoked key can stop unadmitted items while accepted work continues.\n\n[Follow the complete workflow](/integration-bulk/) · [Errors and retries](/api-errors/)", "x-required-scope": "analyses:write", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." } ], "responses": { "200": { "description": "Read item state, resourceId, attemptId, and errorCode. Items finish only after their admitted analysis reaches a terminal outcome. Fetch each report to distinguish completed, failed, and requires_action.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Batch" } } }, "example": { "data": { "id": "batch_analyses", "kind": "analyses", "status": "completed", "createdAt": "2026-09-29T12:00:00.000Z", "expiresAt": "2026-09-29T13:00:00.000Z", "items": [ { "itemKey": "application-42", "state": "succeeded", "resourceId": "report_example", "attemptId": "attempt_example", "errorCode": null } ] } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Batches"], "x-purpose": "Read individual outcomes from an accepted analysis batch. Use itemKey to match each outcome to the original application row.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/analysis-batches/RESOURCE_ID\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/analysis-batches/RESOURCE_ID\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/analysis-batches/RESOURCE_ID\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/interview-batches": { "post": { "operationId": "createInterviewBatch", "summary": "Create an interview batch", "description": "Queue several interviews in one durable request and track outcomes by your own itemKey. Use this to process an application import without coordinating every admission yourself.\n\n## Before you call\n\nSupply 1–20 items, at most 256 KiB JSON, unique itemKey values, and an Idempotency-Key. Only one batch of each kind can be active per workspace.\n\n**Required scope:** `interviews:write`.\n\n## What happens next\n\nA 202 returns batchId and statusUrl. Items can succeed or fail independently. Items finish when invitation admission succeeds or fails, not when candidates finish interviewing. Only sendEmail=true is supported in invitation batches.\n\n## Recovery\n\nKeep successful resource IDs. Capacity-limited items can wait up to the admission deadline; inspect per-item errorCode. Retry failed items deliberately in a new batch; analysis/interview items need fresh quotes. Foreign or unknown resource IDs reject the envelope.\n\n[Follow the complete workflow](/integration-bulk/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:write", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Stable key for one logical write. Retry the identical body with the same key after a timeout; a changed body conflicts. 1–128 letters, digits, dots, underscores, colons, or hyphens." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewBatchInput" }, "example": { "items": [ { "itemKey": "application-42", "input": { "reportId": "report_example", "candidateEmail": "candidate@example.test", "sendEmail": true, "quoteFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } ] } } } }, "responses": { "202": { "description": "A 202 returns batchId and statusUrl. Items can succeed or fail independently. Items finish when invitation admission succeeds or fails, not when candidates finish interviewing. Only sendEmail=true is supported in invitation batches.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BatchAdmission" } } }, "example": { "data": { "batchId": "batch_interviews", "statusUrl": "/api/v1/interview-batches/batch_interviews" } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "409": { "description": "Keep successful resource IDs. Capacity-limited items can wait up to the admission deadline; inspect per-item errorCode. Retry failed items deliberately in a new batch; analysis/interview items need fresh quotes. Foreign or unknown resource IDs reject the envelope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "CONFLICT", "message": "Request conflicts with the current resource state.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Batches"], "x-purpose": "Queue several interviews in one durable request and track outcomes by your own itemKey. Use this to process an application import without coordinating every admission yourself.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\n# Set REQUEST_KEY once for this logical write; reuse it with the same body on retries.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/interview-batches\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H \"Idempotency-Key: $REQUEST_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true,\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n }\n }\n ]\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interview-batches\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Idempotency-Key\": process.env.REQUEST_KEY, // retain for retries\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true,\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n }\n }\n ]\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interview-batches\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Idempotency-Key\"] = os.environ[\"REQUEST_KEY\"] # retain for retries\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true,\n \"quoteFingerprint\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n }\n }\n ]\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/interview-batches/{id}": { "get": { "operationId": "getInterviewBatch", "summary": "Get interview batch status", "description": "Read individual outcomes from an accepted interview batch. Use itemKey to match each outcome to the original application row.\n\n## Before you call\n\nUse the batchId from creation and the same scope required to create that kind of batch.\n\n**Required scope:** `interviews:write`.\n\n## What happens next\n\nRead item state, resourceId, attemptId, and errorCode. Items finish when invitation admission succeeds or fails, not when candidates finish interviewing. Only sendEmail=true is supported in invitation batches.\n\n## Recovery\n\ncompleted means all item processing is terminal, not that every item succeeded. Do not resubmit successful items. A revoked key can stop unadmitted items while accepted work continues.\n\n[Follow the complete workflow](/integration-bulk/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:write", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Resource ID returned by this resource's creation or list endpoint. See prerequisites for whether this is a report, interview, job, or batch ID." } ], "responses": { "200": { "description": "Read item state, resourceId, attemptId, and errorCode. Items finish when invitation admission succeeds or fails, not when candidates finish interviewing. Only sendEmail=true is supported in invitation batches.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Batch" } } }, "example": { "data": { "id": "batch_interviews", "kind": "interviews", "status": "completed", "createdAt": "2026-09-29T12:00:00.000Z", "expiresAt": "2026-09-29T13:00:00.000Z", "items": [ { "itemKey": "application-42", "state": "succeeded", "resourceId": "interview_example", "attemptId": null, "errorCode": null } ] } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "404": { "description": "The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Report not found.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Batches"], "x-purpose": "Read individual outcomes from an accepted interview batch. Use itemKey to match each outcome to the original application row.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X GET \"$PROBB_URL/api/v1/interview-batches/RESOURCE_ID\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\"" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interview-batches/RESOURCE_ID\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"GET\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n },\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interview-batches/RESOURCE_ID\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nbody = None\nrequest = Request(url, data=body, headers=headers, method=\"GET\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/analysis-batch-quotes": { "post": { "operationId": "quoteAnalysisBatch", "summary": "Quote an analysis batch", "description": "Review per-item prices and fingerprints before creating an analysis batch. Use this to separate items ready for submission from items that need attention.\n\n## Before you call\n\nSend 1–20 quote inputs with unique itemKey values. Each item follows the same prerequisites as a single quote.\n\n**Required scope:** `analyses:write`.\n\n## What happens next\n\nOnly items with a non-null quote are ready to include in a submission. total is informational; admissionGuaranteed is always false. Quoting reserves neither capacity nor allowance.\n\n## Recovery\n\nInspect each errorCode and correct that item before quoting again. Include the returned fingerprint in each admitted item; do not use the aggregate total as authorization for a batch.\n\n[Follow the complete workflow](/integration-bulk/) · [Errors and retries](/api-errors/)", "x-required-scope": "analyses:write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisBatchQuoteInput" }, "example": { "items": [ { "itemKey": "application-42", "input": { "reportId": "report_example" } } ] } } } }, "responses": { "200": { "description": "Only items with a non-null quote are ready to include in a submission. total is informational; admissionGuaranteed is always false. Quoting reserves neither capacity nor allowance.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AnalysisBatchQuote" } } }, "example": { "data": { "total": { "creditUnits": 100, "creditScale": 100, "quotedItems": 1, "failedItems": 0, "admissionGuaranteed": false }, "items": [ { "itemKey": "application-42", "quote": { "reportId": "report_example", "reportSystemVersion": "assigned-report-version", "creditUnits": 100, "creditScale": 100, "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "errorCode": null } ] } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Batches"], "x-purpose": "Review per-item prices and fingerprints before creating an analysis batch. Use this to separate items ready for submission from items that need attention.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/analysis-batch-quotes\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\"\n }\n }\n ]\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/analysis-batch-quotes\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\"\n }\n }\n ]\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/analysis-batch-quotes\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\"\n }\n }\n ]\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } }, "/api/v1/interview-batch-quotes": { "post": { "operationId": "quoteInterviewBatch", "summary": "Quote an interview batch", "description": "Review per-item prices and fingerprints before creating an interview batch. Use this to separate items ready for submission from items that need attention.\n\n## Before you call\n\nSend 1–20 quote inputs with unique itemKey values. Each item follows the same prerequisites as a single quote.\n\n**Required scope:** `interviews:write`.\n\n## What happens next\n\nOnly items with a non-null quote are ready to include in a submission. total is informational; admissionGuaranteed is always false. Quoting reserves neither capacity nor allowance.\n\n## Recovery\n\nInspect each errorCode and correct that item before quoting again. Include the returned fingerprint in each admitted item; do not use the aggregate total as authorization for a batch.\n\n[Follow the complete workflow](/integration-bulk/) · [Errors and retries](/api-errors/)", "x-required-scope": "interviews:write", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewBatchQuoteInput" }, "example": { "items": [ { "itemKey": "application-42", "input": { "reportId": "report_example", "candidateEmail": "candidate@example.test", "sendEmail": true } } ] } } } }, "responses": { "200": { "description": "Only items with a non-null quote are ready to include in a submission. total is informational; admissionGuaranteed is always false. Quoting reserves neither capacity nor allowance.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/InterviewBatchQuote" } } }, "example": { "data": { "total": { "creditUnits": 100, "creditScale": 100, "quotedItems": 1, "failedItems": 0, "admissionGuaranteed": false }, "items": [ { "itemKey": "application-42", "quote": { "reportId": "report_example", "creditUnits": 100, "creditScale": 100, "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "interviewSystemVersion": "assigned-interview-version" }, "errorCode": null } ] } } } } }, "400": { "description": "Invalid input or cursor", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "401": { "description": "Invalid, expired, or revoked API key", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "403": { "description": "Disabled organisation or missing scope", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "FORBIDDEN", "message": "API access is disabled or this key lacks the required permission.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "405": { "description": "Method not allowed; consult Allow for supported methods", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "429": { "description": "Request limit exceeded", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many requests.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "500": { "description": "Unexpected failure", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unable to process the request.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } }, "503": { "description": "Service unavailable", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable.", "requestId": "25cbb923-8b3c-4d05-b74f-623efc6d5f8d" } } } } } }, "tags": ["Batches"], "x-purpose": "Review per-item prices and fingerprints before creating an interview batch. Use this to separate items ready for submission from items that need attention.", "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.\ncurl --fail-with-body -X POST \"$PROBB_URL/api/v1/interview-batch-quotes\" \\\n -H \"Authorization: Bearer $PROBB_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n --data-binary '{\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true\n }\n }\n ]\n}'" }, { "id": "js", "lang": "javascript", "label": "JavaScript", "source": "// Run on your backend. Replace RESOURCE_ID with the ID returned by ProBB AI.\nconst url = new URL(\"/api/v1/interview-batch-quotes\", process.env.PROBB_URL);\nconst response = await fetch(url, {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.PROBB_API_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true\n }\n }\n ]\n}),\n});\nconst payload = response.status === 204 ? null : await response.json();\nif (!response.ok) throw new Error(`ProBB AI request failed: ${response.status}; request ID: ${response.headers.get(\"X-Request-Id\")}`);\n// Store returned resource IDs securely. Do not log private URLs or tokens." }, { "id": "python", "lang": "python", "label": "Python", "source": "# Run on your backend. Replace RESOURCE_ID with the returned resource ID.\nimport json\nimport os\nfrom urllib.request import Request, urlopen\nfrom urllib.error import HTTPError\n\nurl = os.environ[\"PROBB_URL\"].rstrip(\"/\") + \"/api/v1/interview-batch-quotes\"\nheaders = {\"Authorization\": \"Bearer \" + os.environ[\"PROBB_API_KEY\"]}\nheaders[\"Content-Type\"] = \"application/json\"\nbody = r'''{\n \"items\": [\n {\n \"itemKey\": \"application-42\",\n \"input\": {\n \"reportId\": \"report_example\",\n \"candidateEmail\": \"candidate@example.test\",\n \"sendEmail\": true\n }\n }\n ]\n}'''.encode(\"utf-8\")\nrequest = Request(url, data=body, headers=headers, method=\"POST\")\ntry:\n with urlopen(request, timeout=30) as response:\n payload = None if response.status == 204 else json.load(response)\nexcept HTTPError as error:\n # Follow the documented recovery; do not blindly resubmit under a new key.\n raise RuntimeError(f\"ProBB AI returned {error.code}; request ID: {error.headers.get('X-Request-Id')}\") from None" }, { "id": "go", "lang": "go", "source": false }, { "id": "java", "lang": "java", "source": false }, { "id": "csharp", "lang": "csharp", "source": false }, { "id": "rust", "lang": "rust", "source": false } ] } } }, "webhooks": { "reportEvent": { "post": { "operationId": "receiveWebhook", "security": [], "summary": "Receive a webhook", "description": "Implement this POST handler on your own HTTPS server to receive signed change notifications from ProBB AI. This is your receiver, not a ProBB AI API URL.\n\n## Before you call\n\nConfigure an endpoint in Settings → Developer and store its signing secret. Read raw bytes and verify webhook-id, webhook-timestamp, and webhook-signature before parsing JSON.\n\n## What happens next\n\nDurably record the event ID and processing intent, then respond promptly with any 2xx. Fetch the current resource with your API key when your background handler processes the event.\n\n## Recovery\n\nEvents may arrive more than once or out of order. Deduplicate by verified event ID; verify a five-minute timestamp tolerance. Retryable delivery failures receive up to seven HTTP attempts. See the recovery guide for replay and catch-up.\n\n[Follow the complete workflow](/integration-webhooks/) · [Errors and retries](/api-errors/)", "parameters": [ { "in": "header", "name": "webhook-id", "required": true, "schema": { "type": "string" }, "description": "Signed event UUID. Must match the envelope id after signature verification." }, { "in": "header", "name": "webhook-timestamp", "required": true, "schema": { "type": "string" }, "description": "Unix timestamp in seconds, refreshed for each delivery; enforce a five-minute tolerance." }, { "in": "header", "name": "webhook-signature", "required": true, "schema": { "type": "string" }, "description": "One or more v1 HMAC signatures. Verify against the raw request body with your receiver's signing secret." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "a1cbb923-8b3c-4d05-b74f-623efc6d5f8d", "type": "report.completed", "schemaVersion": 1, "occurredAt": "2026-09-29T12:00:00.000Z", "data": { "reportId": "report_example", "attemptId": "attempt_example", "status": "completed", "code": null } } } } }, "responses": { "200": { "description": "Return any 2xx after durably recording the event; no response body is required." } }, "tags": ["Webhooks"], "x-purpose": "Implement this POST handler on your own HTTPS server to receive signed change notifications from ProBB AI. This is your receiver, not a ProBB AI API URL." } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "probb__" } }, "schemas": { "WebhookEvent": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "batch.completed", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "batchId": { "type": "string", "description": "Identifier returned when the batch was accepted; use it to retrieve item outcomes." }, "succeeded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of successful batch items; for interviews this means invitation admission, not candidate completion." }, "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of batch items that finished with a failure." } }, "required": ["batchId", "succeeded", "failed"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": ["id", "schemaVersion", "occurredAt", "type", "data"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "report.result_ready", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "attemptId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "resultRevision": { "type": "string", "description": "Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication." } }, "required": ["reportId", "attemptId", "resultRevision"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": ["id", "schemaVersion", "occurredAt", "type", "data"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "report.deleted", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." } }, "required": ["reportId"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": ["id", "schemaVersion", "occurredAt", "type", "data"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "enum": [ "interview.invited", "interview.started", "interview.completed", "interview.expired", "interview.preparation_failed", "interview.result_ready", "interview.result_failed", "interview.invitation_failed" ], "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "interviewId": { "type": "string", "description": "Logical interview attempt ID returned by invitation. A reinterview receives a new ID." }, "resultRevision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication." } }, "required": ["reportId", "interviewId", "resultRevision"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": ["id", "schemaVersion", "occurredAt", "type", "data"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "report.completed", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "attemptId": { "type": "string", "minLength": 1, "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "status": { "type": "string", "const": "completed", "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "code": { "type": "null", "description": "Stable machine-readable outcome or error code; null when no code applies." } }, "required": ["reportId", "attemptId", "status", "code"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": ["id", "schemaVersion", "occurredAt", "type", "data"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "report.failed", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "attemptId": { "type": "string", "minLength": 1, "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "status": { "type": "string", "const": "failed", "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "code": { "type": "string", "const": "ANALYSIS_FAILED", "description": "Stable machine-readable outcome or error code; null when no code applies." } }, "required": ["reportId", "attemptId", "status", "code"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": ["id", "schemaVersion", "occurredAt", "type", "data"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "report.requires_action", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "attemptId": { "type": "string", "minLength": 1, "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "status": { "type": "string", "const": "requires_action", "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "code": { "type": "string", "const": "CANDIDATE_JOB_MISMATCH", "description": "Stable machine-readable outcome or error code; null when no code applies." } }, "required": ["reportId", "attemptId", "status", "code"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": ["id", "schemaVersion", "occurredAt", "type", "data"], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "webhook.test", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "message": { "type": "string", "const": "ProBB webhook test", "description": "Human-readable summary. Use code/reason, not message text, for programmatic error handling." } }, "required": ["message"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": ["id", "schemaVersion", "occurredAt", "type", "data"], "additionalProperties": false } ] }, "UploadInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "externalReference": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Lowercase external-system slug, such as my-ats. Combined with id to identify one application in the workspace." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." } }, "required": ["source", "id"], "additionalProperties": false, "description": "Your application identity: source plus id, unique within the workspace. Prefer an application ID rather than personal information." }, "fileName": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\\\\\x00-\\x1f]+\\.(pdf|docx)$", "description": "Original PDF or DOCX filename, including extension. Paths and control characters are rejected." }, "fileSize": { "type": "integer", "minimum": 1, "maximum": 10485760, "description": "Exact file byte length, from 1 to 10,485,760. This is not the number of characters or a megabyte count." }, "mimeType": { "type": "string", "enum": [ "application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ], "description": "File content type. The file extension, declared type, and uploaded content must agree." }, "jobDescription": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "text", "description": "Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews." }, "text": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "Inline job-description text, up to 50,000 characters; describe responsibilities and required evidence." } }, "required": ["kind", "text"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "existing", "description": "Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews." }, "id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "expectedRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Optional SHA-256 job revision from discovery. Reject preparation if the saved role changed since you reviewed it." } }, "required": ["kind", "id"], "additionalProperties": false } ], "description": "Role context: inline text or a saved job ID on input; selected role fields on a report response." } }, "required": ["fileName", "fileSize", "mimeType", "jobDescription"], "additionalProperties": false }, "Upload": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "upload": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Short-lived signed storage URL. Treat it as a credential; never send your ProBB AI API key to it." }, "method": { "type": "string", "const": "PUT", "description": "HTTP method required for the signed file upload: PUT." }, "mimeType": { "type": "string", "description": "File content type. The file extension, declared type, and uploaded content must agree." }, "sizeBytes": { "type": "number", "description": "Expected upload size in bytes; send the matching file bytes to the signed URL." }, "expiresInSeconds": { "type": "number", "const": 600, "description": "Upload URL lifetime in seconds from issuance; refresh before reuse after expiry." } }, "required": [ "url", "method", "mimeType", "sizeBytes", "expiresInSeconds" ], "additionalProperties": false }, { "type": "null" } ], "description": "Temporary upload instructions; null after admission or when no eligible upload destination can be returned." } }, "required": ["reportId", "upload"], "additionalProperties": false }, "QuoteInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." } }, "required": ["reportId"], "additionalProperties": false }, "Quote": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "reportSystemVersion": { "type": "string", "description": "Assigned report version used by the quote or analysis. Can be null for a legacy report." }, "creditUnits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Applicable price in integer units for the assigned configuration. This is a quote, not a reservation; example prices are illustrative." }, "creditScale": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of integer units per displayed credit. Divide creditUnits by this value; use the scale returned by the API." }, "fingerprint": { "type": "string", "description": "Opaque quote fingerprint. Copy it unchanged into quoteFingerprint on the corresponding submission." } }, "required": [ "reportId", "reportSystemVersion", "creditUnits", "creditScale", "fingerprint" ], "additionalProperties": false }, "AnalysisInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "quoteFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Fingerprint copied unchanged from the corresponding current quote. Changing quote inputs requires a new quote." } }, "required": ["reportId", "quoteFingerprint"], "additionalProperties": false }, "Admission": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "attemptId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "statusUrl": { "type": "string", "description": "Relative API path to poll with the same workspace API key. Resolve against your application origin." } }, "required": ["reportId", "attemptId", "statusUrl"], "additionalProperties": false }, "Report": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "externalReference": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Lowercase external-system slug, such as my-ats. Combined with id to identify one application in the workspace." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." } }, "required": ["source", "id"], "additionalProperties": false }, { "type": "null" } ], "description": "Your application identity: source plus id, unique within the workspace. Prefer an application ID rather than personal information." }, "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC creation timestamp in ISO 8601 format." }, "reportSystemVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Assigned report version used by the quote or analysis. Can be null for a legacy report." }, "status": { "type": "string", "enum": [ "awaiting_upload", "queued", "processing", "requires_action", "completed", "failed" ], "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "attemptId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "code": { "anyOf": [ { "type": "string", "enum": [ "ANALYSIS_FAILED", "RESULT_UNAVAILABLE", "CANDIDATE_JOB_MISMATCH", "UNSUPPORTED_REPORT_VERSION" ] }, { "type": "null" } ], "description": "Stable machine-readable outcome or error code; null when no code applies." }, "jobDescription": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saved job title, or null if not supplied." }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company name recorded on the job description; null when not supplied." } }, "required": ["id", "title", "company"], "additionalProperties": false, "description": "Role context: inline text or a saved job ID on input; selected role fields on a report response." }, "candidate": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Candidate display name extracted from the supplied material, or null if unavailable." }, "currentRole": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Candidate's current role from the resume, or null if unavailable." } }, "required": ["name", "currentRole"], "additionalProperties": false, "description": "Public candidate context for this report; unavailable values are null." }, "result": { "anyOf": [ { "type": "object", "properties": { "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "Evidence score from 0 to 10, or null when unavailable. It is not a probability of hiring success." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Concise explanation of the result or finding; null when unavailable." }, "scoreReasoning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explanation of the evidence supporting the score, or null if unavailable." } }, "required": ["score", "summary", "scoreReasoning"], "additionalProperties": false }, { "type": "null" } ], "description": "Public evaluation. Null when unavailable, pending, or failed; inspect status rather than interpreting null as a zero score." } }, "required": [ "id", "createdAt", "reportSystemVersion", "status", "attemptId", "code", "jobDescription", "candidate", "result" ], "additionalProperties": false }, "ReportStatus": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "status": { "type": "string", "enum": [ "awaiting_upload", "queued", "processing", "requires_action", "completed", "failed" ], "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "attemptId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "code": { "anyOf": [ { "type": "string", "enum": [ "ANALYSIS_FAILED", "RESULT_UNAVAILABLE", "CANDIDATE_JOB_MISMATCH", "UNSUPPORTED_REPORT_VERSION" ] }, { "type": "null" } ], "description": "Stable machine-readable outcome or error code; null when no code applies." }, "reportSystemVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Assigned report version used by the quote or analysis. Can be null for a legacy report." } }, "required": [ "id", "status", "attemptId", "code", "reportSystemVersion" ], "additionalProperties": false }, "ReportPage": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "externalReference": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Lowercase external-system slug, such as my-ats. Combined with id to identify one application in the workspace." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." } }, "required": ["source", "id"], "additionalProperties": false }, { "type": "null" } ], "description": "Your application identity: source plus id, unique within the workspace. Prefer an application ID rather than personal information." }, "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC creation timestamp in ISO 8601 format." }, "reportSystemVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Assigned report version used by the quote or analysis. Can be null for a legacy report." }, "status": { "type": "string", "enum": [ "awaiting_upload", "queued", "processing", "requires_action", "completed", "failed" ], "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "attemptId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "code": { "anyOf": [ { "type": "string", "enum": [ "ANALYSIS_FAILED", "RESULT_UNAVAILABLE", "CANDIDATE_JOB_MISMATCH", "UNSUPPORTED_REPORT_VERSION" ] }, { "type": "null" } ], "description": "Stable machine-readable outcome or error code; null when no code applies." }, "jobDescription": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saved job title, or null if not supplied." }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company name recorded on the job description; null when not supplied." } }, "required": ["id", "title", "company"], "additionalProperties": false, "description": "Role context: inline text or a saved job ID on input; selected role fields on a report response." }, "candidate": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Candidate display name extracted from the supplied material, or null if unavailable." }, "currentRole": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Candidate's current role from the resume, or null if unavailable." } }, "required": ["name", "currentRole"], "additionalProperties": false, "description": "Public candidate context for this report; unavailable values are null." }, "result": { "anyOf": [ { "type": "object", "properties": { "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "Evidence score from 0 to 10, or null when unavailable. It is not a probability of hiring success." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Concise explanation of the result or finding; null when unavailable." }, "scoreReasoning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explanation of the evidence supporting the score, or null if unavailable." } }, "required": ["score", "summary", "scoreReasoning"], "additionalProperties": false }, { "type": "null" } ], "description": "Public evaluation. Null when unavailable, pending, or failed; inspect status rather than interpreting null as a zero score." } }, "required": [ "id", "createdAt", "reportSystemVersion", "status", "attemptId", "code", "jobDescription", "candidate", "result" ], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque continuation token. Reuse unchanged with the same filters. List endpoints return null at the end; the event feed always returns a position." } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "ApiError": { "type": "object", "required": ["error"], "additionalProperties": false, "properties": { "error": { "type": "object", "required": ["code", "message", "requestId"], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Stable machine-readable outcome or error code; null when no code applies." }, "message": { "type": "string", "description": "Human-readable summary. Use code/reason, not message text, for programmatic error handling." }, "requestId": { "type": "string", "format": "uuid", "description": "Request correlation UUID for support. Also returned in the X-Request-Id header." }, "reason": { "type": "string", "description": "Optional stable domain reason explaining the error. Use it to select the documented recovery action." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Location of an invalid request field, without its submitted value." }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code; null when no code applies." } }, "required": ["path", "code"], "additionalProperties": false }, "description": "Safe validation locations and codes, when available. Submitted values are not echoed." } }, "description": "Safe error details. Use code/reason for handling and requestId for support." } } }, "JobDescription": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saved job title, or null if not supplied." }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company name recorded on the job description; null when not supplied." }, "team": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Team recorded on the job description, or null if unspecified." }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Location recorded on the job description, or null if unspecified." }, "level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Seniority recorded on the job description, or null if unspecified." }, "employmentType": { "anyOf": [ { "type": "string", "enum": [ "FULL_TIME", "PART_TIME", "CONTRACT", "TEMPORARY", "INTERNSHIP" ] }, { "type": "null" } ], "description": "How the role is offered: FULL_TIME, PART_TIME, CONTRACT, TEMPORARY, or INTERNSHIP, or null if unspecified. Changes the job revision once set." }, "status": { "type": "string", "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "description": { "type": "string", "description": "Full job-description text used to understand the role requirements." }, "revision": { "type": "string", "description": "Content hash of the saved job. Send as expectedRevision when preparing against that exact reviewed content." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC creation timestamp in ISO 8601 format." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the saved job was last updated." } }, "required": [ "id", "title", "company", "team", "location", "level", "employmentType", "status", "description", "revision", "createdAt", "updatedAt" ], "additionalProperties": false }, "customerJobSummarySchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saved job title, or null if not supplied." }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company name recorded on the job description; null when not supplied." }, "team": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Team recorded on the job description, or null if unspecified." }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Location recorded on the job description, or null if unspecified." }, "level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Seniority recorded on the job description, or null if unspecified." }, "employmentType": { "anyOf": [ { "type": "string", "enum": [ "FULL_TIME", "PART_TIME", "CONTRACT", "TEMPORARY", "INTERNSHIP" ] }, { "type": "null" } ], "description": "How the role is offered: FULL_TIME, PART_TIME, CONTRACT, TEMPORARY, or INTERNSHIP, or null if unspecified. Changes the job revision once set." }, "status": { "type": "string", "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "revision": { "type": "string", "description": "Content hash of the saved job. Send as expectedRevision when preparing against that exact reviewed content." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC creation timestamp in ISO 8601 format." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the saved job was last updated." } }, "required": [ "id", "title", "company", "team", "location", "level", "employmentType", "status", "revision", "createdAt", "updatedAt" ], "additionalProperties": false }, "JobDescriptionPage": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saved job title, or null if not supplied." }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company name recorded on the job description; null when not supplied." }, "team": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Team recorded on the job description, or null if unspecified." }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Location recorded on the job description, or null if unspecified." }, "level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Seniority recorded on the job description, or null if unspecified." }, "employmentType": { "anyOf": [ { "type": "string", "enum": [ "FULL_TIME", "PART_TIME", "CONTRACT", "TEMPORARY", "INTERNSHIP" ] }, { "type": "null" } ], "description": "How the role is offered: FULL_TIME, PART_TIME, CONTRACT, TEMPORARY, or INTERNSHIP, or null if unspecified. Changes the job revision once set." }, "status": { "type": "string", "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "revision": { "type": "string", "description": "Content hash of the saved job. Send as expectedRevision when preparing against that exact reviewed content." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC creation timestamp in ISO 8601 format." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the saved job was last updated." } }, "required": [ "id", "title", "company", "team", "location", "level", "employmentType", "status", "revision", "createdAt", "updatedAt" ], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque continuation token. Reuse unchanged with the same filters. List endpoints return null at the end; the event feed always returns a position." } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "RichResult": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "attemptId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "reportSystemVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Assigned report version used by the quote or analysis. Can be null for a legacy report." }, "resultRevision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication." }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "UTC result publication time when available; null for unpublished or legacy data without a publication timestamp." }, "status": { "type": "string", "enum": [ "awaiting_upload", "queued", "processing", "requires_action", "completed", "failed" ], "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "code": { "anyOf": [ { "type": "string", "enum": [ "ANALYSIS_FAILED", "RESULT_UNAVAILABLE", "CANDIDATE_JOB_MISMATCH", "UNSUPPORTED_REPORT_VERSION" ] }, { "type": "null" } ], "description": "Stable machine-readable outcome or error code; null when no code applies." }, "externalReference": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Lowercase external-system slug, such as my-ats. Combined with id to identify one application in the workspace." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." } }, "required": ["source", "id"], "additionalProperties": false }, { "type": "null" } ], "description": "Your application identity: source plus id, unique within the workspace. Prefer an application ID rather than personal information." }, "result": { "anyOf": [ { "type": "object", "properties": { "scoreScale": { "type": "object", "properties": { "minimum": { "type": "number", "const": 0, "description": "Lower bound of the displayed score scale (0)." }, "maximum": { "type": "number", "const": 10, "description": "Upper bound of the displayed score scale (10)." } }, "required": ["minimum", "maximum"], "additionalProperties": false, "description": "Minimum and maximum values used for the report score." }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "Evidence score from 0 to 10, or null when unavailable. It is not a probability of hiring success." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Concise explanation of the result or finding; null when unavailable." }, "scoreReasoning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explanation of the evidence supporting the score, or null if unavailable." }, "humanReviewRecommendation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Suggested next review step based on the evidence and its limitations." }, "rubric": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable rubric criterion identifier within the returned evaluation." }, "label": { "type": "string", "description": "Human-readable name of this criterion or finding." }, "status": { "type": "string", "enum": [ "positive", "neutral", "concern", "negative" ], "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "Evidence score from 0 to 10, or null when unavailable. It is not a probability of hiring success." }, "analysis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explanation of the evidence for this rubric criterion." }, "evidence": { "type": "array", "items": { "type": "string" }, "description": "Selected supporting observations. The API excludes raw transcripts, recordings, and original documents." }, "gaps": { "type": "array", "items": { "type": "string" }, "description": "Requirements or supporting evidence not established by the available material." } }, "required": [ "key", "label", "status", "score", "analysis", "evidence", "gaps" ], "additionalProperties": false }, "description": "Criterion-by-criterion resume assessment, including scores, evidence, and missing information." }, "highlights": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": ["technicalCore", "strategicFit"], "description": "Grouping of a highlight: technicalCore or strategicFit." }, "label": { "type": "string", "description": "Human-readable name of this criterion or finding." }, "status": { "type": "string", "enum": [ "positive", "neutral", "concern", "negative" ], "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Concise explanation of the result or finding; null when unavailable." } }, "required": ["category", "label", "status", "summary"], "additionalProperties": false }, "description": "Selected technical and role-fit findings; review their status and supporting context." }, "followUpQuestions": { "type": "object", "properties": { "technical": { "type": "array", "items": { "type": "string" }, "description": "Follow-up questions about role-related technical capabilities." }, "clarification": { "type": "array", "items": { "type": "string" }, "description": "Questions to clarify incomplete or ambiguous resume evidence." }, "riskReview": { "type": "array", "items": { "type": "string" }, "description": "Questions to investigate job-related concerns before acting on the report." } }, "required": ["technical", "clarification", "riskReview"], "additionalProperties": false, "description": "Suggested questions grouped by technical evidence, clarification, and risk review." }, "integrity": { "type": "object", "properties": { "riskLevel": { "anyOf": [ { "type": "string", "enum": ["low", "medium", "high"] }, { "type": "null" } ], "description": "Severity of integrity concerns, or null when the assessment is unavailable." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Concise explanation of the result or finding; null when unavailable." }, "signals": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews." }, "severity": { "type": "string", "enum": ["low", "medium", "high"], "description": "Priority of this integrity signal: low, medium, or high." }, "evidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Selected supporting observations. The API excludes raw transcripts, recordings, and original documents." }, "recommendation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Suggested human follow-up or advisory outcome, as appropriate to the surrounding finding." } }, "required": [ "kind", "severity", "evidence", "recommendation" ], "additionalProperties": false }, "description": "Individual integrity findings with evidence and suggested follow-up." } }, "required": ["riskLevel", "summary", "signals"], "additionalProperties": false, "description": "Evidence-quality and identity-review signals, not a determination of candidate dishonesty." }, "policyWarnings": { "type": "array", "items": { "type": "string" }, "description": "Assessment policy limitations to consider during human review." }, "ignoredCriteria": { "type": "array", "items": { "type": "string" }, "description": "Job criteria excluded from assessment. Do not treat these as evidence against a candidate." } }, "required": [ "scoreScale", "score", "summary", "scoreReasoning", "humanReviewRecommendation", "rubric", "highlights", "followUpQuestions", "integrity", "policyWarnings", "ignoredCriteria" ], "additionalProperties": false }, { "type": "null" } ], "description": "Public evaluation. Null when unavailable, pending, or failed; inspect status rather than interpreting null as a zero score." } }, "required": [ "schemaVersion", "reportId", "attemptId", "reportSystemVersion", "resultRevision", "publishedAt", "status", "code", "externalReference", "result" ], "additionalProperties": false }, "EventPage": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "batch.completed", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "batchId": { "type": "string", "description": "Identifier returned when the batch was accepted; use it to retrieve item outcomes." }, "succeeded": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of successful batch items; for interviews this means invitation admission, not candidate completion." }, "failed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of batch items that finished with a failure." } }, "required": ["batchId", "succeeded", "failed"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": [ "id", "schemaVersion", "occurredAt", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "report.result_ready", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "attemptId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "resultRevision": { "type": "string", "description": "Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication." } }, "required": [ "reportId", "attemptId", "resultRevision" ], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": [ "id", "schemaVersion", "occurredAt", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "report.deleted", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." } }, "required": ["reportId"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": [ "id", "schemaVersion", "occurredAt", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "enum": [ "interview.invited", "interview.started", "interview.completed", "interview.expired", "interview.preparation_failed", "interview.result_ready", "interview.result_failed", "interview.invitation_failed" ], "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "interviewId": { "type": "string", "description": "Logical interview attempt ID returned by invitation. A reinterview receives a new ID." }, "resultRevision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication." } }, "required": [ "reportId", "interviewId", "resultRevision" ], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": [ "id", "schemaVersion", "occurredAt", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "report.completed", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "attemptId": { "type": "string", "minLength": 1, "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "status": { "type": "string", "const": "completed", "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "code": { "type": "null", "description": "Stable machine-readable outcome or error code; null when no code applies." } }, "required": [ "reportId", "attemptId", "status", "code" ], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": [ "id", "schemaVersion", "occurredAt", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "report.failed", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "attemptId": { "type": "string", "minLength": 1, "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "status": { "type": "string", "const": "failed", "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "code": { "type": "string", "const": "ANALYSIS_FAILED", "description": "Stable machine-readable outcome or error code; null when no code applies." } }, "required": [ "reportId", "attemptId", "status", "code" ], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": [ "id", "schemaVersion", "occurredAt", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "report.requires_action", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "attemptId": { "type": "string", "minLength": 1, "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "status": { "type": "string", "const": "requires_action", "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "code": { "type": "string", "const": "CANDIDATE_JOB_MISMATCH", "description": "Stable machine-readable outcome or error code; null when no code applies." } }, "required": [ "reportId", "attemptId", "status", "code" ], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": [ "id", "schemaVersion", "occurredAt", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "type": { "type": "string", "const": "webhook.test", "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "data": { "type": "object", "properties": { "message": { "type": "string", "const": "ProBB webhook test", "description": "Human-readable summary. Use code/reason, not message text, for programmatic error handling." } }, "required": ["message"], "additionalProperties": false, "description": "Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data." } }, "required": [ "id", "schemaVersion", "occurredAt", "type", "data" ], "additionalProperties": false } ] }, { "type": "object", "properties": { "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "type": { "type": "string", "enum": [ "batch.completed", "report.completed", "report.result_ready", "report.deleted", "report.failed", "report.requires_action", "webhook.test", "interview.invited", "interview.started", "interview.completed", "interview.expired", "interview.preparation_failed", "interview.result_ready", "interview.result_failed", "interview.invitation_failed" ], "description": "Event type. Subscribe to the events needed for your workflow and process unknown future types safely." }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC time the event occurred. Delivery may be delayed or out of order." }, "deleted": { "type": "boolean", "const": true, "description": "True when the original retained event body has been erased. Only its minimal identity remains." } }, "required": ["id", "type", "occurredAt", "deleted"], "additionalProperties": false } ] }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." }, "nextCursor": { "type": "string", "description": "Opaque continuation token. Reuse unchanged with the same filters. List endpoints return null at the end; the event feed always returns a position." }, "hasMore": { "type": "boolean", "description": "Whether more retained events are immediately available after this page. Keep nextCursor even when false." } }, "required": ["items", "nextCursor", "hasMore"], "additionalProperties": false }, "Interview": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "interviewSystemVersion": { "type": "string", "description": "Assigned interview version captured for this quote or attempt. Existing attempts retain their version." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC creation timestamp in ISO 8601 format." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC expiration timestamp. For a batch this is the admission deadline, not a cancellation time for already accepted work." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "UTC time the candidate started the interview; null before start." }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "UTC time the candidate completed the conversation; null before completion. Evaluation may still be pending." }, "lifecycle": { "type": "string", "enum": [ "invited", "in_progress", "completed", "expired", "superseded" ], "description": "Candidate progress: invited, in_progress, completed, expired, or superseded. Independent of preparation and evaluation." }, "preparation": { "type": "string", "enum": ["queued", "processing", "ready", "failed"], "description": "Interview question-preparation state. ready means the interview content is prepared; it does not mean evaluation is complete." }, "evaluation": { "type": "string", "enum": ["not_started", "processing", "ready", "failed"], "description": "Evaluation progress, separate from candidate completion. Read the evaluation when ready." }, "emailDelivery": { "type": "string", "enum": ["queued", "sent", "failed", "not_requested"], "description": "Email processing state. sent means provider acceptance, not confirmed inbox delivery; not_requested means your system delivers the link." }, "resultRevision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication." } }, "required": [ "id", "reportId", "interviewSystemVersion", "createdAt", "expiresAt", "startedAt", "completedAt", "lifecycle", "preparation", "evaluation", "emailDelivery", "resultRevision" ], "additionalProperties": false }, "InterviewResult": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "interviewSystemVersion": { "type": "string", "description": "Assigned interview version captured for this quote or attempt. Existing attempts retain their version." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC creation timestamp in ISO 8601 format." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC expiration timestamp. For a batch this is the admission deadline, not a cancellation time for already accepted work." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "UTC time the candidate started the interview; null before start." }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "UTC time the candidate completed the conversation; null before completion. Evaluation may still be pending." }, "lifecycle": { "type": "string", "enum": [ "invited", "in_progress", "completed", "expired", "superseded" ], "description": "Candidate progress: invited, in_progress, completed, expired, or superseded. Independent of preparation and evaluation." }, "preparation": { "type": "string", "enum": ["queued", "processing", "ready", "failed"], "description": "Interview question-preparation state. ready means the interview content is prepared; it does not mean evaluation is complete." }, "evaluation": { "type": "string", "enum": ["not_started", "processing", "ready", "failed"], "description": "Evaluation progress, separate from candidate completion. Read the evaluation when ready." }, "emailDelivery": { "type": "string", "enum": ["queued", "sent", "failed", "not_requested"], "description": "Email processing state. sent means provider acceptance, not confirmed inbox delivery; not_requested means your system delivers the link." }, "resultRevision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication." }, "schemaVersion": { "type": "number", "const": 1, "description": "Public payload format version. Result requests currently support 1; this is independent of the assigned product version." }, "result": { "anyOf": [ { "type": "object", "properties": { "decision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Advisory evaluation outcome, where available; requires human review and is not an automated hiring decision." }, "limitations": { "type": "string", "description": "Constraints on interpretation of the available interview evidence; display alongside the evaluation." }, "coverage": { "type": "object", "properties": { "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "Evidence score from 0 to 10, or null when unavailable. It is not a probability of hiring success." }, "transcriptQuality": { "anyOf": [ { "type": "string", "enum": [ "strong", "adequate", "thin", "insufficient" ] }, { "type": "null" } ], "description": "Quality of available interview evidence: strong, adequate, thin, or insufficient; null when unavailable." } }, "required": ["score", "transcriptQuality"], "additionalProperties": false, "description": "How much relevant evidence was assessed. Requirement coverage uses 0–100; the overall coverage object contains a 0–10 score and transcript quality." }, "integrity": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "enum": [ "clear", "review_recommended", "verification_limited" ] }, { "type": "null" } ], "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "confidence": { "anyOf": [ { "type": "string", "enum": ["low", "medium", "high"] }, { "type": "null" } ], "description": "Confidence in the finding. Requirement confidence uses 0–100; integrity confidence uses low, medium, or high. Null means unavailable." } }, "required": ["status", "confidence"], "additionalProperties": false, "description": "Evidence-quality and identity-review signals, not a determination of candidate dishonesty." }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "requirement": { "type": "string", "description": "Role requirement being evaluated." }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "Evidence score from 0 to 10, or null when unavailable. It is not a probability of hiring success." }, "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "Confidence in the finding. Requirement confidence uses 0–100; integrity confidence uses low, medium, or high. Null means unavailable." }, "coverage": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "How much relevant evidence was assessed. Requirement coverage uses 0–100; the overall coverage object contains a 0–10 score and transcript quality." }, "evidence": { "type": "array", "items": { "type": "string" }, "description": "Selected supporting observations. The API excludes raw transcripts, recordings, and original documents." }, "gaps": { "type": "array", "items": { "type": "string" }, "description": "Requirements or supporting evidence not established by the available material." }, "finding": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable finding for this requirement, or null if unavailable." } }, "required": [ "requirement", "status", "score", "confidence", "coverage", "evidence", "gaps", "finding" ], "additionalProperties": false }, "description": "Requirement-level findings, confidence, coverage, supporting evidence, and gaps." }, "recommendation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Suggested human follow-up or advisory outcome, as appropriate to the surrounding finding." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Concise explanation of the result or finding; null when unavailable." }, "scores": { "type": "object", "properties": { "coreSkill": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "Core skill evidence score from 0 to 10; null when not measured." }, "problemSolving": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "Problem-solving evidence score from 0 to 10; null when not measured." }, "communication": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "Communication evidence score from 0 to 10; null when not measured." }, "roleFit": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10 }, { "type": "null" } ], "description": "Role-fit evidence score from 0 to 10; null when not measured." }, "readiness": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "Advisory readiness score from 0 to 100; null when not measured." } }, "required": [ "coreSkill", "problemSolving", "communication", "roleFit", "readiness" ], "additionalProperties": false, "description": "Interview skill scores (0–10) and readiness (0–100); missing measurements are null." }, "strengths": { "type": "array", "items": { "type": "string" }, "description": "Job-related strengths supported by the available interview evidence." }, "concerns": { "type": "array", "items": { "type": "string" }, "description": "Job-related concerns that need human review; an empty list is not a guarantee of suitability." }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "description": "Capability assessed by this evidence item." }, "reasoning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Explanation supporting this evidence finding, or null if unavailable." }, "supportingEvidence": { "type": "array", "items": { "type": "string" }, "description": "Selected observations supporting this dimension's reasoning." } }, "required": [ "dimension", "reasoning", "supportingEvidence" ], "additionalProperties": false }, "description": "Selected supporting observations. The API excludes raw transcripts, recordings, and original documents." } }, "required": [ "decision", "limitations", "coverage", "integrity", "requirements", "recommendation", "summary", "scores", "strengths", "concerns", "evidence" ], "additionalProperties": false }, { "type": "null" } ], "description": "Public evaluation. Null when unavailable, pending, or failed; inspect status rather than interpreting null as a zero score." } }, "required": [ "id", "reportId", "interviewSystemVersion", "createdAt", "expiresAt", "startedAt", "completedAt", "lifecycle", "preparation", "evaluation", "emailDelivery", "resultRevision", "schemaVersion", "result" ], "additionalProperties": false }, "InterviewPage": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "interviewSystemVersion": { "type": "string", "description": "Assigned interview version captured for this quote or attempt. Existing attempts retain their version." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC creation timestamp in ISO 8601 format." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC expiration timestamp. For a batch this is the admission deadline, not a cancellation time for already accepted work." }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "UTC time the candidate started the interview; null before start." }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "UTC time the candidate completed the conversation; null before completion. Evaluation may still be pending." }, "lifecycle": { "type": "string", "enum": [ "invited", "in_progress", "completed", "expired", "superseded" ], "description": "Candidate progress: invited, in_progress, completed, expired, or superseded. Independent of preparation and evaluation." }, "preparation": { "type": "string", "enum": ["queued", "processing", "ready", "failed"], "description": "Interview question-preparation state. ready means the interview content is prepared; it does not mean evaluation is complete." }, "evaluation": { "type": "string", "enum": ["not_started", "processing", "ready", "failed"], "description": "Evaluation progress, separate from candidate completion. Read the evaluation when ready." }, "emailDelivery": { "type": "string", "enum": ["queued", "sent", "failed", "not_requested"], "description": "Email processing state. sent means provider acceptance, not confirmed inbox delivery; not_requested means your system delivers the link." }, "resultRevision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication." } }, "required": [ "id", "reportId", "interviewSystemVersion", "createdAt", "expiresAt", "startedAt", "completedAt", "lifecycle", "preparation", "evaluation", "emailDelivery", "resultRevision" ], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque continuation token. Reuse unchanged with the same filters. List endpoints return null at the end; the event feed always returns a position." } }, "required": ["items", "nextCursor"], "additionalProperties": false }, "InterviewInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "candidateEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address of the intended candidate. The quote and invitation must use the same address." }, "sendEmail": { "default": true, "type": "boolean", "description": "True (default) asks ProBB AI to email the invitation. False returns a private link credential for your system to deliver. Invitation batches require true." }, "quoteFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Fingerprint copied unchanged from the corresponding current quote. Changing quote inputs requires a new quote." } }, "required": ["reportId", "candidateEmail", "quoteFingerprint"], "additionalProperties": false }, "InterviewQuoteInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "candidateEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address of the intended candidate. The quote and invitation must use the same address." }, "sendEmail": { "default": true, "type": "boolean", "description": "True (default) asks ProBB AI to email the invitation. False returns a private link credential for your system to deliver. Invitation batches require true." } }, "required": ["reportId", "candidateEmail"], "additionalProperties": false }, "InterviewAdmission": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "interviewId": { "type": "string", "description": "Logical interview attempt ID returned by invitation. A reinterview receives a new ID." }, "reportId": { "type": "string", "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "invitationToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bearer credential returned only when sendEmail is false and the invitation is current and pending; otherwise null." }, "statusUrl": { "type": "string", "description": "Relative API path to poll with the same workspace API key. Resolve against your application origin." }, "emailDelivery": { "type": "string", "enum": ["queued", "sent", "failed", "not_requested"], "description": "Email processing state. sent means provider acceptance, not confirmed inbox delivery; not_requested means your system delivers the link." } }, "required": [ "interviewId", "reportId", "invitationToken", "statusUrl", "emailDelivery" ], "additionalProperties": false }, "InterviewQuote": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "creditUnits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Applicable price in integer units for the assigned configuration. This is a quote, not a reservation; example prices are illustrative." }, "creditScale": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of integer units per displayed credit. Divide creditUnits by this value; use the scale returned by the API." }, "fingerprint": { "type": "string", "description": "Opaque quote fingerprint. Copy it unchanged into quoteFingerprint on the corresponding submission." }, "interviewSystemVersion": { "type": "string", "description": "Assigned interview version captured for this quote or attempt. Existing attempts retain their version." } }, "required": [ "reportId", "creditUnits", "creditScale", "fingerprint", "interviewSystemVersion" ], "additionalProperties": false }, "InterviewResend": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "interviewId": { "type": "string", "description": "Logical interview attempt ID returned by invitation. A reinterview receives a new ID." }, "deliveryId": { "type": "string", "description": "Identifier of the queued invitation email delivery, not an interview attempt ID." } }, "required": ["interviewId", "deliveryId"], "additionalProperties": false }, "UploadBatchInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "jobDescription": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "text", "description": "Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews." }, "text": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "Inline job-description text, up to 50,000 characters; describe responsibilities and required evidence." } }, "required": ["kind", "text"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "existing", "description": "Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews." }, "id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "expectedRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Optional SHA-256 job revision from discovery. Reject preparation if the saved role changed since you reviewed it." } }, "required": ["kind", "id"], "additionalProperties": false } ], "description": "Role context: inline text or a saved job ID on input; selected role fields on a report response." }, "items": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Your unique identifier within this batch, used to match each outcome to its input. It is not the HTTP idempotency key." }, "input": { "type": "object", "properties": { "externalReference": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "description": "Lowercase external-system slug, such as my-ats. Combined with id to identify one application in the workspace." }, "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." } }, "required": ["source", "id"], "additionalProperties": false, "description": "Your application identity: source plus id, unique within the workspace. Prefer an application ID rather than personal information." }, "fileName": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^/\\\\\\x00-\\x1f]+\\.(pdf|docx)$", "description": "Original PDF or DOCX filename, including extension. Paths and control characters are rejected." }, "fileSize": { "type": "integer", "minimum": 1, "maximum": 10485760, "description": "Exact file byte length, from 1 to 10,485,760. This is not the number of characters or a megabyte count." }, "mimeType": { "type": "string", "enum": [ "application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ], "description": "File content type. The file extension, declared type, and uploaded content must agree." }, "jobDescription": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "text", "description": "Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews." }, "text": { "type": "string", "minLength": 1, "maxLength": 50000, "description": "Inline job-description text, up to 50,000 characters; describe responsibilities and required evidence." } }, "required": ["kind", "text"], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "existing", "description": "Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews." }, "id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "expectedRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Optional SHA-256 job revision from discovery. Reject preparation if the saved role changed since you reviewed it." } }, "required": ["kind", "id"], "additionalProperties": false } ], "description": "Role context: inline text or a saved job ID on input; selected role fields on a report response." } }, "required": ["fileName", "fileSize", "mimeType"], "additionalProperties": false, "description": "The request for this individual batch item, using the corresponding single-operation fields." } }, "required": ["itemKey", "input"], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." } }, "required": ["items"], "additionalProperties": false }, "AnalysisBatchInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Your unique identifier within this batch, used to match each outcome to its input. It is not the HTTP idempotency key." }, "input": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "quoteFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Fingerprint copied unchanged from the corresponding current quote. Changing quote inputs requires a new quote." } }, "required": ["reportId", "quoteFingerprint"], "additionalProperties": false, "description": "The request for this individual batch item, using the corresponding single-operation fields." } }, "required": ["itemKey", "input"], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." } }, "required": ["items"], "additionalProperties": false }, "InterviewBatchInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Your unique identifier within this batch, used to match each outcome to its input. It is not the HTTP idempotency key." }, "input": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "candidateEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address of the intended candidate. The quote and invitation must use the same address." }, "sendEmail": { "default": true, "type": "boolean", "const": true, "description": "True (default) asks ProBB AI to email the invitation. False returns a private link credential for your system to deliver. Invitation batches require true." }, "quoteFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Fingerprint copied unchanged from the corresponding current quote. Changing quote inputs requires a new quote." } }, "required": [ "reportId", "candidateEmail", "quoteFingerprint" ], "additionalProperties": false, "description": "The request for this individual batch item, using the corresponding single-operation fields." } }, "required": ["itemKey", "input"], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." } }, "required": ["items"], "additionalProperties": false }, "AnalysisBatchQuoteInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Your unique identifier within this batch, used to match each outcome to its input. It is not the HTTP idempotency key." }, "input": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." } }, "required": ["reportId"], "additionalProperties": false, "description": "The request for this individual batch item, using the corresponding single-operation fields." } }, "required": ["itemKey", "input"], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." } }, "required": ["items"], "additionalProperties": false }, "InterviewBatchQuoteInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$", "description": "Your unique identifier within this batch, used to match each outcome to its input. It is not the HTTP idempotency key." }, "input": { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "candidateEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Email address of the intended candidate. The quote and invitation must use the same address." }, "sendEmail": { "default": true, "type": "boolean", "description": "True (default) asks ProBB AI to email the invitation. False returns a private link credential for your system to deliver. Invitation batches require true." } }, "required": ["reportId", "candidateEmail"], "additionalProperties": false, "description": "The request for this individual batch item, using the corresponding single-operation fields." } }, "required": ["itemKey", "input"], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." } }, "required": ["items"], "additionalProperties": false }, "AnalysisBatchQuote": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "total": { "type": "object", "properties": { "creditUnits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Applicable price in integer units for the assigned configuration. This is a quote, not a reservation; example prices are illustrative." }, "creditScale": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Number of integer units per displayed credit. Divide creditUnits by this value; use the scale returned by the API." }, "quotedItems": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of items successfully quoted; excludes items with errors." }, "failedItems": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of items that could not be quoted; their quote is null and errorCode explains why." }, "admissionGuaranteed": { "type": "boolean", "const": false, "description": "Always false: a quote reserves neither capacity nor allowance." } }, "required": [ "creditUnits", "creditScale", "quotedItems", "failedItems", "admissionGuaranteed" ], "additionalProperties": false, "description": "Informational aggregate across successfully quoted items. Each submission is still checked independently." }, "items": { "type": "array", "items": { "type": "object", "properties": { "itemKey": { "type": "string", "description": "Your unique identifier within this batch, used to match each outcome to its input. It is not the HTTP idempotency key." }, "quote": { "anyOf": [ { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "reportSystemVersion": { "type": "string", "description": "Assigned report version used by the quote or analysis. Can be null for a legacy report." }, "creditUnits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Applicable price in integer units for the assigned configuration. This is a quote, not a reservation; example prices are illustrative." }, "creditScale": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of integer units per displayed credit. Divide creditUnits by this value; use the scale returned by the API." }, "fingerprint": { "type": "string", "description": "Opaque quote fingerprint. Copy it unchanged into quoteFingerprint on the corresponding submission." } }, "required": [ "reportId", "reportSystemVersion", "creditUnits", "creditScale", "fingerprint" ], "additionalProperties": false }, { "type": "null" } ], "description": "This item's quote, or null when quoting failed. Copy its fingerprint into the matching submission item." }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason this item failed. Null when no item error is present; inspect item state too." } }, "required": ["itemKey", "quote", "errorCode"], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." } }, "required": ["total", "items"], "additionalProperties": false }, "InterviewBatchQuote": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "total": { "type": "object", "properties": { "creditUnits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Applicable price in integer units for the assigned configuration. This is a quote, not a reservation; example prices are illustrative." }, "creditScale": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Number of integer units per displayed credit. Divide creditUnits by this value; use the scale returned by the API." }, "quotedItems": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of items successfully quoted; excludes items with errors." }, "failedItems": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of items that could not be quoted; their quote is null and errorCode explains why." }, "admissionGuaranteed": { "type": "boolean", "const": false, "description": "Always false: a quote reserves neither capacity nor allowance." } }, "required": [ "creditUnits", "creditScale", "quotedItems", "failedItems", "admissionGuaranteed" ], "additionalProperties": false, "description": "Informational aggregate across successfully quoted items. Each submission is still checked independently." }, "items": { "type": "array", "items": { "type": "object", "properties": { "itemKey": { "type": "string", "description": "Your unique identifier within this batch, used to match each outcome to its input. It is not the HTTP idempotency key." }, "quote": { "anyOf": [ { "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace." }, "creditUnits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Applicable price in integer units for the assigned configuration. This is a quote, not a reservation; example prices are illustrative." }, "creditScale": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of integer units per displayed credit. Divide creditUnits by this value; use the scale returned by the API." }, "fingerprint": { "type": "string", "description": "Opaque quote fingerprint. Copy it unchanged into quoteFingerprint on the corresponding submission." }, "interviewSystemVersion": { "type": "string", "description": "Assigned interview version captured for this quote or attempt. Existing attempts retain their version." } }, "required": [ "reportId", "creditUnits", "creditScale", "fingerprint", "interviewSystemVersion" ], "additionalProperties": false }, { "type": "null" } ], "description": "This item's quote, or null when quoting failed. Copy its fingerprint into the matching submission item." }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason this item failed. Null when no item error is present; inspect item state too." } }, "required": ["itemKey", "quote", "errorCode"], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." } }, "required": ["total", "items"], "additionalProperties": false }, "Batch": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI." }, "kind": { "type": "string", "enum": ["uploads", "analyses", "interviews"], "description": "Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews." }, "status": { "type": "string", "enum": ["queued", "processing", "completed"], "description": "Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC creation timestamp in ISO 8601 format." }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "UTC expiration timestamp. For a batch this is the admission deadline, not a cancellation time for already accepted work." }, "items": { "type": "array", "items": { "type": "object", "properties": { "itemKey": { "type": "string", "description": "Your unique identifier within this batch, used to match each outcome to its input. It is not the HTTP idempotency key." }, "state": { "type": "string", "enum": [ "queued", "waiting", "processing", "admitted", "succeeded", "failed" ], "description": "Individual batch progress. succeeded/failed are terminal; waiting means capacity has delayed admission." }, "resourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resource created by this batch item; null until available. Use the batch kind to select the report or interview endpoint." }, "attemptId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available." }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason this item failed. Null when no item error is present; inspect item state too." }, "upload": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Short-lived signed storage URL. Treat it as a credential; never send your ProBB AI API key to it." }, "method": { "type": "string", "const": "PUT", "description": "HTTP method required for the signed file upload: PUT." }, "mimeType": { "type": "string", "description": "File content type. The file extension, declared type, and uploaded content must agree." }, "sizeBytes": { "type": "number", "description": "Expected upload size in bytes; send the matching file bytes to the signed URL." }, "expiresInSeconds": { "type": "number", "const": 600, "description": "Upload URL lifetime in seconds from issuance; refresh before reuse after expiry." } }, "required": [ "url", "method", "mimeType", "sizeBytes", "expiresInSeconds" ], "additionalProperties": false }, { "type": "null" } ], "description": "Temporary upload instructions; null after admission or when no eligible upload destination can be returned." } }, "required": [ "itemKey", "state", "resourceId", "attemptId", "errorCode" ], "additionalProperties": false }, "description": "Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next." } }, "required": ["id", "kind", "status", "createdAt", "expiresAt", "items"], "additionalProperties": false }, "BatchAdmission": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "batchId": { "type": "string", "description": "Identifier returned when the batch was accepted; use it to retrieve item outcomes." }, "statusUrl": { "type": "string", "description": "Relative API path to poll with the same workspace API key. Resolve against your application origin." } }, "required": ["batchId", "statusUrl"], "additionalProperties": false } } } }