{ "openapi": "3.1.0", "info": { "title": "Turrilum Partner API", "version": "1.0.0", "description": "The Turrilum v1 Partner API provides programmatic access to candidates, applications, jobs, offers, and interviews.\n\n**Base URL:** `https://app.turrilum.com/api/v1`\n\n**Authentication:** Pass your API key as a Bearer token in the `Authorization` header:\n```\nAuthorization: Bearer sk_live_...\n```\n\n**Environments:** Keys prefixed `sk_live_` operate on production data. Keys prefixed `sk_test_` are sandbox keys — they exercise the identical API surface and currently share the same data plane, so use clearly-labelled test records.", "contact": { "name": "Turrilum API Support", "url": "https://turrilum.com/docs/api" } }, "servers": [ { "url": "https://app.turrilum.com/api/v1", "description": "Production" } ], "tags": [ { "name": "Candidates", "description": "Candidate profiles." }, { "name": "Applications", "description": "Job applications linking candidates to jobs." }, { "name": "Jobs", "description": "Job requisitions." }, { "name": "Offers", "description": "Offer letters." }, { "name": "Interviews", "description": "Scheduled interviews." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Pass your API key (`sk_live_*` or `sk_test_*`) as a Bearer token." } }, "schemas": { "ProblemDetails": { "type": "object", "description": "RFC 9457 Problem Details error envelope.", "required": [ "type", "title", "status", "detail", "instance", "code", "request_id" ], "properties": { "type": { "type": "string", "format": "uri", "example": "https://turrilum.com/docs/errors/unauthorized" }, "title": { "type": "string", "example": "Unauthorized" }, "status": { "type": "integer", "example": 401 }, "detail": { "type": "string", "example": "No Authorization header supplied." }, "instance": { "type": "string", "example": "/api/v1/candidates" }, "code": { "type": "string", "example": "unauthorized" }, "request_id": { "type": "string", "format": "uuid", "example": "01920f3b-c1a9-7000-89d2-5f5b8f9b1234" } } }, "ListMeta": { "type": "object", "required": [ "data", "has_more" ], "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque keyset cursor — pass as starting_after." } } }, "Candidate": { "type": "object", "required": [ "id", "name", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "primary_email": { "type": [ "string", "null" ], "format": "email" }, "primary_phone": { "type": [ "string", "null" ] }, "source_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Application": { "type": "object", "required": [ "id", "candidate_id", "job_id", "milestone", "status", "applied_at", "updated_at" ], "properties": { "id": { "type": "string" }, "candidate_id": { "type": "string" }, "job_id": { "type": "string" }, "stage_id": { "type": [ "string", "null" ] }, "milestone": { "type": "string", "enum": [ "active", "offer", "hired", "rejected", "withdrawn" ] }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "external_id": { "type": [ "string", "null" ] }, "applied_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Job": { "type": "object", "required": [ "id", "title", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "department": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "employment_type": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "draft", "closed" ] }, "requisition_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Offer": { "type": "object", "required": [ "id", "candidate_id", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "candidate_id": { "type": "string" }, "job_id": { "type": [ "string", "null" ] }, "job_posting_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "signed", "declined" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Interview": { "type": "object", "required": [ "id", "candidate_id", "title", "starts_at", "duration_mins", "modality", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "application_id": { "type": [ "string", "null" ] }, "candidate_id": { "type": "string" }, "title": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "duration_mins": { "type": "integer", "minimum": 1 }, "modality": { "type": "string" }, "status": { "type": "string", "enum": [ "scheduled", "completed", "cancelled" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "paths": { "/candidates": { "get": { "tags": [ "Candidates" ], "summary": "List candidates", "operationId": "list_candidates", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return. 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "starting_after", "in": "query", "description": "Opaque keyset cursor returned in the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "modified_after", "in": "query", "description": "ISO-8601 datetime. Only return records updated after this point.", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_deleted", "in": "query", "description": "When true, include soft-deleted records (deleted_at is set).", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A paginated list of candidate objects.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } } } } ] } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-required-scope": "read:candidates" }, "post": { "tags": [ "Candidates" ], "summary": "Create a candidate", "operationId": "create_candidate", "security": [ { "BearerAuth": [] } ], "x-required-scope": "write:candidates", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (UUID recommended). If provided, retrying the identical request within 24 h returns the original response instead of re-executing.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Full name." }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "source_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created successfully.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Candidate" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — idempotency key in-flight (concurrent duplicate).", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable — idempotency_key_reused with different body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/candidates/{id}": { "get": { "tags": [ "Candidates" ], "summary": "Get a candidate", "operationId": "get_candidate", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The candidate id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Candidate" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "patch": { "tags": [ "Candidates" ], "summary": "Update a candidate", "operationId": "update_candidate", "security": [ { "BearerAuth": [] } ], "x-required-scope": "write:candidates", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The candidate id.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (UUID recommended). If provided, retrying the identical request within 24 h returns the original response instead of re-executing.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Candidate" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — idempotency key in-flight (concurrent duplicate).", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable — idempotency_key_reused with different body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/applications": { "get": { "tags": [ "Applications" ], "summary": "List applications", "operationId": "list_applications", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return. 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "starting_after", "in": "query", "description": "Opaque keyset cursor returned in the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "modified_after", "in": "query", "description": "ISO-8601 datetime. Only return records updated after this point.", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_deleted", "in": "query", "description": "When true, include soft-deleted records (deleted_at is set).", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A paginated list of application objects.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } } } ] } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-required-scope": "read:applications" }, "post": { "tags": [ "Applications" ], "summary": "Create a application", "operationId": "create_application", "security": [ { "BearerAuth": [] } ], "x-required-scope": "write:applications", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (UUID recommended). If provided, retrying the identical request within 24 h returns the original response instead of re-executing.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "candidate_id", "job_id" ], "properties": { "candidate_id": { "type": "string" }, "job_id": { "type": "string" }, "stage_id": { "type": "string", "description": "Initial pipeline stage id." } } } } } }, "responses": { "201": { "description": "Created successfully.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — idempotency key in-flight (concurrent duplicate).", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable — idempotency_key_reused with different body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/applications/{id}": { "get": { "tags": [ "Applications" ], "summary": "Get a application", "operationId": "get_application", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The application id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "patch": { "tags": [ "Applications" ], "summary": "Update a application", "operationId": "update_application", "security": [ { "BearerAuth": [] } ], "x-required-scope": "write:applications", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The application id.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (UUID recommended). If provided, retrying the identical request within 24 h returns the original response instead of re-executing.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage_id": { "type": "string", "description": "Move to this pipeline stage." }, "archive": { "type": "boolean", "description": "Set true to archive (withdraw/reject) the application." } } } } } }, "responses": { "200": { "description": "OK.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — idempotency key in-flight (concurrent duplicate).", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable — idempotency_key_reused with different body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/jobs": { "get": { "tags": [ "Jobs" ], "summary": "List jobs", "operationId": "list_jobs", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return. 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "starting_after", "in": "query", "description": "Opaque keyset cursor returned in the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "modified_after", "in": "query", "description": "ISO-8601 datetime. Only return records updated after this point.", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_deleted", "in": "query", "description": "When true, include soft-deleted records (deleted_at is set).", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A paginated list of job objects.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } } } } ] } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-required-scope": "read:jobs" }, "post": { "tags": [ "Jobs" ], "summary": "Create a job", "operationId": "create_job", "security": [ { "BearerAuth": [] } ], "x-required-scope": "write:jobs", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (UUID recommended). If provided, retrying the identical request within 24 h returns the original response instead of re-executing.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "department": { "type": "string" }, "location_name": { "type": "string" }, "employment_type": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "internal", "private" ] } } } } } }, "responses": { "201": { "description": "Created successfully.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — idempotency key in-flight (concurrent duplicate).", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable — idempotency_key_reused with different body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/jobs/{id}": { "get": { "tags": [ "Jobs" ], "summary": "Get a job", "operationId": "get_job", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The job id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "patch": { "tags": [ "Jobs" ], "summary": "Update a job", "operationId": "update_job", "security": [ { "BearerAuth": [] } ], "x-required-scope": "write:jobs", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The job id.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (UUID recommended). If provided, retrying the identical request within 24 h returns the original response instead of re-executing.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "department": { "type": "string" }, "location_name": { "type": "string" }, "employment_type": { "type": "string" }, "visibility": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "draft", "closed" ] }, "close_reason_id": { "type": "string", "description": "Required when setting status to closed." } } } } } }, "responses": { "200": { "description": "OK.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — idempotency key in-flight (concurrent duplicate).", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable — idempotency_key_reused with different body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/offers": { "get": { "tags": [ "Offers" ], "summary": "List offers", "operationId": "list_offers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return. 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "starting_after", "in": "query", "description": "Opaque keyset cursor returned in the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "modified_after", "in": "query", "description": "ISO-8601 datetime. Only return records updated after this point.", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_deleted", "in": "query", "description": "When true, include soft-deleted records (deleted_at is set).", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A paginated list of offer objects.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } } } } ] } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-required-scope": "read:offers" }, "post": { "tags": [ "Offers" ], "summary": "Create a offer", "operationId": "create_offer", "security": [ { "BearerAuth": [] } ], "x-required-scope": "write:offers", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (UUID recommended). If provided, retrying the identical request within 24 h returns the original response instead of re-executing.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "candidate_id" ], "properties": { "candidate_id": { "type": "string" }, "title": { "type": "string" }, "job_posting_id": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created successfully.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — idempotency key in-flight (concurrent duplicate).", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable — idempotency_key_reused with different body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/offers/{id}": { "get": { "tags": [ "Offers" ], "summary": "Get a offer", "operationId": "get_offer", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The offer id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "patch": { "tags": [ "Offers" ], "summary": "Update a offer", "operationId": "update_offer", "security": [ { "BearerAuth": [] } ], "x-required-scope": "write:offers", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The offer id.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (UUID recommended). If provided, retrying the identical request within 24 h returns the original response instead of re-executing.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "job_posting_id": { "type": "string" }, "action": { "type": "string", "enum": [ "send" ], "description": "Pass \"send\" to transition the offer to sent status and emit the offer.sent webhook. Note: email delivery is not performed via the API — use the Turrilum UI for outbound emails." } } } } } }, "responses": { "200": { "description": "OK.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Offer" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — idempotency key in-flight (concurrent duplicate).", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable — idempotency_key_reused with different body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/interviews": { "get": { "tags": [ "Interviews" ], "summary": "List interviews", "operationId": "list_interviews", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return. 1–200, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "starting_after", "in": "query", "description": "Opaque keyset cursor returned in the previous page's next_cursor.", "schema": { "type": "string" } }, { "name": "modified_after", "in": "query", "description": "ISO-8601 datetime. Only return records updated after this point.", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_deleted", "in": "query", "description": "When true, include soft-deleted records (deleted_at is set).", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A paginated list of interview objects.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ListMeta" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Interview" } } } } ] } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-required-scope": "read:interviews" }, "post": { "tags": [ "Interviews" ], "summary": "Create a interview", "operationId": "create_interview", "security": [ { "BearerAuth": [] } ], "x-required-scope": "write:interviews", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (UUID recommended). If provided, retrying the identical request within 24 h returns the original response instead of re-executing.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "candidate_id", "title", "starts_at" ], "properties": { "candidate_id": { "type": "string" }, "application_id": { "type": "string" }, "title": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "duration_mins": { "type": "integer", "minimum": 1, "default": 30 }, "attendees": { "type": "array", "items": { "type": "string", "format": "email" } }, "location_label": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created successfully.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interview" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — idempotency key in-flight (concurrent duplicate).", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable — idempotency_key_reused with different body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/interviews/{id}": { "get": { "tags": [ "Interviews" ], "summary": "Get a interview", "operationId": "get_interview", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The interview id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interview" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "patch": { "tags": [ "Interviews" ], "summary": "Update a interview", "operationId": "update_interview", "security": [ { "BearerAuth": [] } ], "x-required-scope": "write:interviews", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The interview id.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (UUID recommended). If provided, retrying the identical request within 24 h returns the original response instead of re-executing.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "starts_at": { "type": "string", "format": "date-time", "description": "New start time (reschedule)." }, "duration_mins": { "type": "integer", "minimum": 1 }, "action": { "type": "string", "enum": [ "cancel" ], "description": "Pass \"cancel\" to cancel the interview and emit the interview.cancelled webhook." } } } } } }, "responses": { "200": { "description": "OK.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interview" } } } }, "400": { "description": "Bad request — validation_error or invalid_parameter.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — missing or invalid API key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — key lacks required scope.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not found.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — idempotency key in-flight (concurrent duplicate).", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable — idempotency_key_reused with different body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limited.", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit for the current window." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Epoch seconds when the window resets." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Remaining." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Legacy alias for RateLimit-Reset." }, "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Unexpected server error.", "headers": { "X-Request-Id": { "schema": { "type": "string", "format": "uuid" }, "description": "Correlation id." }, "X-Turrilum-Environment": { "schema": { "type": "string", "enum": [ "live", "test" ] }, "description": "Environment of the authenticating key." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } } }