{
    "openapi": "3.0.3",
    "info": {
        "title": "adam-calling Public API",
        "version": "1.0.0",
        "description": "Programmatic access to adam-calling: place outbound voice calls (freeform prompt or a stored pathway), poll their status and results, download recordings, and list your pathways.\n\nAuthenticate with an organization-scoped API key in the `Authorization` header — either `Authorization: Bearer <key>` or the raw `<prefix>.<secret>` key on its own. The organization is derived from the key, never from the URL.\n\nErrors share one envelope: `{\"status\": \"error\", \"message\": <summary>, \"errors\": [<detail>, …]}`. List endpoints wrap results in `{\"status\": \"success\", \"count\", \"total_count\", \"calls\"}`."
    },
    "paths": {
        "/v1/calls": {
            "get": {
                "operationId": "listCalls",
                "description": "Your organization's calls, newest first, in the `{status, count, total_count, calls}` envelope. Page with `limit`/`offset`; narrow with the filters below.",
                "summary": "List calls",
                "parameters": [
                    {
                        "in": "query",
                        "name": "created_from",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Calls created on or after this date (YYYY-MM-DD)."
                    },
                    {
                        "in": "query",
                        "name": "created_to",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Calls created on or before this date (YYYY-MM-DD)."
                    },
                    {
                        "in": "query",
                        "name": "limit",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Page size (default 50, max 1000)."
                    },
                    {
                        "in": "query",
                        "name": "offset",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Number of calls to skip."
                    },
                    {
                        "in": "query",
                        "name": "outcome",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Filter by call outcome."
                    },
                    {
                        "in": "query",
                        "name": "pathway_id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "Only calls placed against this pathway."
                    },
                    {
                        "in": "query",
                        "name": "phone_number",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Exact E.164 phone number."
                    },
                    {
                        "in": "query",
                        "name": "status",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Filter by call status (e.g. `completed`, `failed`)."
                    }
                ],
                "tags": [
                    "Calls"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PaginatedCallsResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `calls:read` scope."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            },
            "post": {
                "operationId": "sendCall",
                "description": "Place one outbound call. Provide exactly one of `task` (a freeform prompt) or `pathway_id` (a stored flow from `GET /pathways`). The call is queued and dialed immediately; poll `GET /calls/{id}` for its status and results.",
                "summary": "Send a call",
                "tags": [
                    "Calls"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SendCall"
                            },
                            "examples": {
                                "TaskMode(freeformPrompt)": {
                                    "value": {
                                        "phone_number": "+48512345678",
                                        "task": "You are calling Jan to confirm his test-drive appointment for the used BMW on Saturday at 11:00. Confirm he can still make it; if not, offer to reschedule.",
                                        "language": "pl",
                                        "name": "Jan Kowalski",
                                        "max_duration": 10,
                                        "metadata": {
                                            "crm_id": "abc-123"
                                        }
                                    },
                                    "summary": "Task mode (freeform prompt)"
                                },
                                "PathwayMode(storedFlow)": {
                                    "value": {
                                        "phone_number": "+48512345678",
                                        "pathway_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                                        "language": "pl",
                                        "record": true
                                    },
                                    "summary": "Pathway mode (stored flow)"
                                }
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/SendCall"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/SendCall"
                            }
                        }
                    },
                    "required": true
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SendCallResponse"
                                },
                                "examples": {
                                    "Accepted": {
                                        "value": {
                                            "status": "success",
                                            "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
                                        }
                                    }
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Invalid request (e.g. neither/both of `task`/`pathway_id`, or the pathway has no active version)."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `calls:write` scope, or the number has opted out."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Unknown `pathway_id` or `from_number_id` for this organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    },
                    "502": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The voice provider failed to place the call."
                    }
                }
            }
        },
        "/v1/calls/{id}": {
            "get": {
                "operationId": "getCall",
                "description": "The full call object: status, timing, transcript and turns, summary, extracted data, recording URL, your `metadata`, and cost. Result fields are `null` while the call is still in flight.",
                "summary": "Get a call",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The call id (the `call_id` returned by send-call).",
                        "required": true
                    }
                ],
                "tags": [
                    "Calls"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CallDetailResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `calls:read` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No call with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/calls/{id}/events": {
            "get": {
                "operationId": "listCallEvents",
                "description": "The call's append-only event trace — a chronological log of what happened during the call (status callbacks, the websocket connecting, per-node progress, a stop request, errors), oldest first, in a `{status, count, total_count, events}` envelope. Poll it to monitor a live call or diagnose one after the fact; page with `limit`/`offset`.",
                "summary": "List a call's events",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The call id (the `call_id` returned by send-call).",
                        "required": true
                    },
                    {
                        "in": "query",
                        "name": "limit",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Page size (default 50, max 1000)."
                    },
                    {
                        "in": "query",
                        "name": "offset",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Number of events to skip."
                    }
                ],
                "tags": [
                    "Calls"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PaginatedEventsResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `calls:read` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No call with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/calls/{id}/recording": {
            "get": {
                "operationId": "getCallRecording",
                "description": "Proxy-streams the call's audio (same-origin, so it plays directly in a browser `<audio>` element). Returns 404 when the call has no recording.",
                "summary": "Download a call recording",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The call id (the `call_id` returned by send-call).",
                        "required": true
                    }
                ],
                "tags": [
                    "Calls"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "audio/mpeg": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `calls:read` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No call with this id, or the call has no recording."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/calls/{id}/stop": {
            "post": {
                "operationId": "stopCall",
                "description": "End one active call. The stop is best-effort and converges through our normal call pipeline, so the response reflects the *request* — poll `GET /calls/{id}` for the final status. Stopping an already-ended call succeeds (idempotent).",
                "summary": "Stop a call",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The call id (the `call_id` returned by send-call).",
                        "required": true
                    }
                ],
                "tags": [
                    "Calls"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/StopCallResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The call is not active (already ended, or not yet dialed)."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `calls:write` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No call with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    },
                    "502": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The voice provider failed to stop the call."
                    }
                }
            }
        },
        "/v1/calls/active": {
            "get": {
                "operationId": "listActiveCalls",
                "description": "Your organization's active calls — queued or in progress, not yet finalized — newest first, in the same `{status, count, total_count, calls}` envelope as `GET /calls`. Page with `limit`/`offset`.",
                "summary": "List active calls",
                "parameters": [
                    {
                        "in": "query",
                        "name": "limit",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Page size (default 50, max 1000)."
                    },
                    {
                        "in": "query",
                        "name": "offset",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Number of calls to skip."
                    }
                ],
                "tags": [
                    "Calls"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PaginatedCallsResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `calls:read` scope."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/calls/active/stop": {
            "post": {
                "operationId": "stopActiveCalls",
                "description": "End every active (queued or in-progress) call on your organization. Returns the number of calls a hangup was issued for; each converges through the normal call pipeline.",
                "summary": "Stop all active calls",
                "tags": [
                    "Calls"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/StopActiveCallsResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `calls:write` scope."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/contacts": {
            "get": {
                "operationId": "listContacts",
                "description": "Your organization's contacts, newest first, in the `{status, count, total_count, contacts}` envelope. Page with `limit`/`offset`; narrow with the filters below. Test fixtures are never listed.",
                "summary": "List contacts",
                "parameters": [
                    {
                        "in": "query",
                        "name": "disposition",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Exact pathway-declared disposition key."
                    },
                    {
                        "in": "query",
                        "name": "external_id",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Exact external-system id."
                    },
                    {
                        "in": "query",
                        "name": "limit",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Page size (default 50, max 1000)."
                    },
                    {
                        "in": "query",
                        "name": "offset",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Number of contacts to skip."
                    },
                    {
                        "in": "query",
                        "name": "phone",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Exact E.164 phone number."
                    },
                    {
                        "in": "query",
                        "name": "updated_since",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        },
                        "description": "Only contacts modified at or after this ISO-8601 timestamp (for incremental sync)."
                    }
                ],
                "tags": [
                    "Contacts"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PaginatedContactsResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `contacts:read` scope."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            },
            "post": {
                "operationId": "upsertContact",
                "description": "Upsert a contact by phone number. `phone` is the merge key: the first call for a number creates the contact (`201`), a later call for the same number updates it in place (`200`). Custom fields ride in the nested `data` object — keys that match a declared contact field are coerced to its type, and any other key passes through unchanged. Set `do_not_call` to add or clear the number on your do-not-call registry (an opted-out number is never dialed).",
                "summary": "Create or update a contact",
                "tags": [
                    "Contacts"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ContactUpsert"
                            },
                            "examples": {
                                "UpsertWithCustomFields": {
                                    "value": {
                                        "phone": "+48512345678",
                                        "name": "Jan Kowalski",
                                        "language": "pl",
                                        "external_id": "crm-4821",
                                        "consent": true,
                                        "context": "Interested in the Saturday test drive.",
                                        "data": {
                                            "vehicle": "BMW 3 Series",
                                            "budget_pln": 90000
                                        }
                                    },
                                    "summary": "Upsert with custom fields"
                                }
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/ContactUpsert"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/ContactUpsert"
                            }
                        }
                    },
                    "required": true
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ContactResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "201": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ContactResponse"
                                },
                                "examples": {
                                    "Created": {
                                        "value": {
                                            "status": "success",
                                            "contact": {
                                                "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                                                "phone": "+48512345678",
                                                "external_id": "crm-4821",
                                                "name": "Jan Kowalski",
                                                "language": "pl",
                                                "timezone": "Europe/Warsaw",
                                                "consent": true,
                                                "do_not_call": false,
                                                "context": "Interested in the Saturday test drive.",
                                                "data": {
                                                    "vehicle": "BMW 3 Series",
                                                    "budget_pln": 90000
                                                },
                                                "status": "new",
                                                "disposition": "",
                                                "disposition_at": null,
                                                "last_outcome": "",
                                                "follow_up_at": null,
                                                "created": "2026-07-06T09:00:00Z",
                                                "modified": "2026-07-06T09:00:00Z"
                                            }
                                        }
                                    }
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Invalid request (e.g. malformed `phone`, or an `external_id` already in use)."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `contacts:write` scope."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/contacts/{id}": {
            "get": {
                "operationId": "getContact",
                "description": "The full contact object, including its computed `do_not_call` state and custom `data`.",
                "summary": "Get a contact",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The contact id.",
                        "required": true
                    }
                ],
                "tags": [
                    "Contacts"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ContactResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `contacts:read` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No contact with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            },
            "patch": {
                "operationId": "updateContact",
                "description": "Partially update a contact. Only the fields you send change; `phone` is the immutable merge key and cannot be patched (re-key by deleting and re-upserting). Keys in `data` are merged into the contact's existing custom data, not replaced wholesale.",
                "summary": "Update a contact",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The contact id.",
                        "required": true
                    }
                ],
                "tags": [
                    "Contacts"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PatchedContactUpdate"
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/PatchedContactUpdate"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/PatchedContactUpdate"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ContactResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Invalid request (e.g. an `external_id` already in use by another contact)."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `contacts:write` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No contact with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            },
            "delete": {
                "operationId": "deleteContact",
                "description": "Permanently delete a contact. This cascades: every call placed to the contact — and its transcript, recording metadata, extraction, and event trace — is deleted with it. The phone's do-not-call registry entry is deliberately kept, so a deleted-then-re-created contact can never resurrect a number that opted out.",
                "summary": "Delete a contact",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The contact id.",
                        "required": true
                    }
                ],
                "tags": [
                    "Contacts"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "204": {
                        "description": "The contact was deleted."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `contacts:write` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No contact with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/me": {
            "get": {
                "operationId": "getMe",
                "description": "Introspect the calling key: its prefix, name, scopes, and last-used time; the organization it belongs to; its owner (null for a machine key); and whether it may author pathways. No scope is required — a key may always introspect itself.",
                "summary": "Who am I",
                "tags": [
                    "Identity"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MeResponse"
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/metrics": {
            "get": {
                "operationId": "getMetrics",
                "description": "Your organization's funnel, per-language split, and outcome breakdown. The `cost` block is included only for an owner-bound key whose owner is an engineer — a machine or customer-role key never receives spend figures. Analytics payload — passed through from the internal service as-is; it evolves with the product and is not a frozen contract.",
                "summary": "Get organization metrics",
                "tags": [
                    "Analytics"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `metrics:read` scope."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/pathways": {
            "get": {
                "operationId": "listPathways",
                "description": "Your organization's pathways. By default only *live* pathways (those with an active version you can send a call against) are returned; pass `include_drafts=true` to also include draft-only pathways (`active_version_number` is then `null`).",
                "summary": "List pathways",
                "parameters": [
                    {
                        "in": "query",
                        "name": "include_drafts",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Include draft-only pathways (default false = live pathways only)."
                    }
                ],
                "tags": [
                    "Pathways"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/PublicPathway"
                                    }
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:read` scope."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            },
            "post": {
                "operationId": "createPathway",
                "description": "Create a pathway from a name and language. Version 1 is seeded from the default flow so the pathway opens runnable and can be iterated with `POST /pathways/{id}/import`. Requires an owner-bound key whose owner is an engineer.",
                "summary": "Create a pathway",
                "tags": [
                    "Pathways"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicPathwayCreate"
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicPathwayCreate"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicPathwayCreate"
                            }
                        }
                    },
                    "required": true
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicPathwayDetail"
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Invalid `name`/`language`."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:write` scope, is not owner-bound, or its owner is not an engineer."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/pathways/{id}": {
            "get": {
                "operationId": "getPathway",
                "description": "One pathway's metadata: name, language, active/draft version numbers, version count, and timestamps. The flow document itself is on `GET /pathways/{id}/versions`.",
                "summary": "Get a pathway",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The pathway id.",
                        "required": true
                    }
                ],
                "tags": [
                    "Pathways"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicPathwayDetail"
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:read` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No pathway with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/pathways/{id}/import": {
            "post": {
                "operationId": "importPathway",
                "description": "Import a complete `flow_json` (typically AI-authored) as a new draft version, optionally activating it with `?activate=true`. Hard-gated by validation — an import must be activatable as-is; on failure nothing is written and the errors come back (400). Requires an owner-bound key whose owner is an engineer.",
                "summary": "Import a flow as a new draft",
                "parameters": [
                    {
                        "in": "query",
                        "name": "activate",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Also activate the imported version."
                    },
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The pathway id.",
                        "required": true
                    }
                ],
                "tags": [
                    "Pathways"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicFlowImport"
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicFlowImport"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicFlowImport"
                            }
                        }
                    },
                    "required": true
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "201": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The flow failed validation (returned as `errors`)."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:write` scope, is not owner-bound, or its owner is not an engineer."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No pathway with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/pathways/{id}/post-call-config": {
            "get": {
                "operationId": "getPathwayPostCallConfig",
                "description": "The pathway's editable post-call config — summary instructions, extraction schema, and outcomes — read from the open draft when one exists, else the active version. Authoring payload — passed through from the internal service as-is; it evolves with the product and is not a frozen contract.",
                "summary": "Get post-call config",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The pathway id.",
                        "required": true
                    }
                ],
                "tags": [
                    "Pathways"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:read` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No pathway with this id, or the pathway has no versions."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            },
            "patch": {
                "operationId": "updatePathwayPostCallConfig",
                "description": "Save one or more post-call config fields onto the pathway's draft (forks a draft like a flow edit; absent fields are left untouched). Advisory validation rides back in `post_call_validation_errors` — activation is the hard gate. Authoring payload — passed through from the internal service as-is; it evolves with the product and is not a frozen contract.",
                "summary": "Update post-call config",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The pathway id.",
                        "required": true
                    }
                ],
                "tags": [
                    "Pathways"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PatchedPublicPostCallConfigSave"
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/PatchedPublicPostCallConfigSave"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/PatchedPublicPostCallConfigSave"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Invalid config field (e.g. `extraction_schema` not a list)."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:write` scope, is not owner-bound, or its owner is not an engineer."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No pathway with this id, or the pathway has no versions."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/pathways/{id}/versions": {
            "get": {
                "operationId": "listPathwayVersions",
                "description": "Every version of a pathway, newest first, each with its `flow_json`, stored validation state, and versioned post-call config. Authoring payload — passed through from the internal service as-is; it evolves with the product and is not a frozen contract.",
                "summary": "List pathway versions",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The pathway id.",
                        "required": true
                    }
                ],
                "tags": [
                    "Pathways"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:read` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No pathway with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/pathways/{id}/versions/{version_number}/activate": {
            "post": {
                "operationId": "activatePathwayVersion",
                "description": "Make a version live (rollback = activating an older one). Hard-gated by validation: if the version has blocking errors none is activated and they come back as findings (400). Requires an owner-bound key whose owner is an engineer.",
                "summary": "Activate a pathway version",
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The pathway id.",
                        "required": true
                    },
                    {
                        "in": "path",
                        "name": "version_number",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Version number.",
                        "required": true
                    }
                ],
                "tags": [
                    "Pathways"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicPathwayDetail"
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The version has blocking validation errors (returned as `errors`)."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:write` scope, is not owner-bound, or its owner is not an engineer."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No pathway/version with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/pathways/{id}/versions/{version_number}/analytics": {
            "get": {
                "operationId": "getPathwayVersionAnalytics",
                "description": "A per-node funnel + webhook health for one version, rolled up from its calls' trace events over `?days=` (default 7, clamped 1–90). Only placed/test calls populate it. Authoring payload — passed through from the internal service as-is; it evolves with the product and is not a frozen contract.",
                "summary": "Get pathway version analytics",
                "parameters": [
                    {
                        "in": "query",
                        "name": "days",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Look-back window in days (default 7, 1–90)."
                    },
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The pathway id.",
                        "required": true
                    },
                    {
                        "in": "path",
                        "name": "version_number",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Version number.",
                        "required": true
                    }
                ],
                "tags": [
                    "Analytics"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `metrics:read` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No pathway/version with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/pathways/{id}/versions/compare": {
            "get": {
                "operationId": "comparePathwayVersions",
                "description": "A keyed structural diff between two versions (`?base=<n>&target=<n>`, version numbers) — added/removed/modified nodes and functions, not a raw JSON text diff. Authoring payload — passed through from the internal service as-is; it evolves with the product and is not a frozen contract.",
                "summary": "Compare two pathway versions",
                "parameters": [
                    {
                        "in": "query",
                        "name": "base",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Base version number.",
                        "required": true
                    },
                    {
                        "in": "path",
                        "name": "id",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "description": "The pathway id.",
                        "required": true
                    },
                    {
                        "in": "query",
                        "name": "target",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Target version number.",
                        "required": true
                    }
                ],
                "tags": [
                    "Pathways"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing/invalid `base` or `target`, or they are the same version."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:read` scope."
                    },
                    "404": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "No pathway/version with this id for your organization."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/pathways/simulate": {
            "post": {
                "operationId": "simulatePathway",
                "description": "Run one text-simulator turn against exactly one of `flow_json` (the literal document), `pathway_ref` (`{pathway_id, version_number?}`), or `agent_ref` (`{agent_id, version_number?, contact_id?, caller_card?}`, which synthesizes the agent's hub flow — the same triage/routing an inbound call runs). The first call (no `sim_state`) opens the session; later calls echo `messages` + `sim_state` with a `user_message`. Requires an owner-bound key whose owner is an engineer. Authoring payload — passed through from the internal service as-is; it evolves with the product and is not a frozen contract.",
                "summary": "Simulate a conversation turn",
                "tags": [
                    "Pathways"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "additionalProperties": {}
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "type": "object",
                                "additionalProperties": {}
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "additionalProperties": {}
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Malformed body (e.g. neither/both of `flow_json`/`pathway_ref`)."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:write` scope, is not owner-bound, or its owner is not an engineer."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    },
                    "502": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The simulator turn failed."
                    }
                }
            }
        },
        "/v1/pathways/validate": {
            "post": {
                "operationId": "validatePathway",
                "description": "Run the exact deterministic gate `import`/`activate` enforce over a `flow_json` (plus optional post-call config) with no pathway checkout. Findings are DATA: a flow full of errors still returns 200 with them in the lists; only a body missing `flow_json` is a 400. Requires an owner-bound key whose owner is an engineer. Authoring payload — passed through from the internal service as-is; it evolves with the product and is not a frozen contract.",
                "summary": "Validate a flow",
                "tags": [
                    "Pathways"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicValidate"
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicValidate"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicValidate"
                            }
                        }
                    },
                    "required": true
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Body is missing `flow_json`."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:write` scope, is not owner-bound, or its owner is not an engineer."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/pathways/webhook-test": {
            "post": {
                "operationId": "testPathwayWebhook",
                "description": "Run a webhook node config once, live, against `sample_variables`. Secrets resolve server-side and never appear in the response; extracted variable values DO come back — that is the point. Requires an owner-bound key whose owner is an engineer. Authoring payload — passed through from the internal service as-is; it evolves with the product and is not a frozen contract.",
                "summary": "Test a webhook node",
                "tags": [
                    "Pathways"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "additionalProperties": {}
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "type": "object",
                                "additionalProperties": {}
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "additionalProperties": {}
                            }
                        }
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "400": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Body is missing a `webhook` config object, or it is invalid."
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `pathways:write` scope, is not owner-bound, or its owner is not an engineer."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        },
        "/v1/tools/analytics": {
            "get": {
                "operationId": "getToolAnalytics",
                "description": "Per-tool execution stats (total/success/failure/success-rate/avg-latency) across all of your calls over `?days=` (default 30, clamped 1–365), busiest tool first. Only placed/test calls populate it. Analytics payload — passed through from the internal service as-is; it evolves with the product and is not a frozen contract.",
                "summary": "Get tool analytics",
                "parameters": [
                    {
                        "in": "query",
                        "name": "days",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Look-back window in days (default 30, 1–365)."
                    }
                ],
                "tags": [
                    "Analytics"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {}
                                }
                            }
                        },
                        "description": ""
                    },
                    "401": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Missing, invalid, revoked, or expired API key."
                    },
                    "403": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "The key lacks the `metrics:read` scope."
                    },
                    "429": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        },
                        "description": "Rate limit exceeded."
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "CallDetailResponse": {
                "type": "object",
                "description": "``200`` body of ``GET /calls/{id}`` — the full call object under the success envelope.\n\nSubclasses the detail serializer only to add the ``status`` wrapper key the view prepends.",
                "properties": {
                    "call_id": {
                        "type": "string",
                        "format": "uuid",
                        "readOnly": true
                    },
                    "phone_number": {
                        "type": "string",
                        "readOnly": true
                    },
                    "call_status": {
                        "type": "string",
                        "readOnly": true
                    },
                    "outcome": {
                        "type": "string",
                        "nullable": true,
                        "readOnly": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "started_at": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "completed_at": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "duration_seconds": {
                        "type": "integer",
                        "nullable": true,
                        "readOnly": true
                    },
                    "pathway_id": {
                        "type": "string",
                        "nullable": true,
                        "readOnly": true
                    },
                    "pathway_version": {
                        "type": "integer",
                        "nullable": true,
                        "readOnly": true
                    },
                    "summary": {
                        "type": "string",
                        "nullable": true,
                        "readOnly": true
                    },
                    "transcript": {
                        "type": "string",
                        "nullable": true,
                        "readOnly": true
                    },
                    "transcripts": {
                        "type": "array",
                        "items": {},
                        "readOnly": true
                    },
                    "extracted": {
                        "type": "object",
                        "additionalProperties": {},
                        "nullable": true,
                        "readOnly": true
                    },
                    "extraction_status": {
                        "type": "string",
                        "nullable": true,
                        "readOnly": true
                    },
                    "recording_url": {
                        "type": "string",
                        "nullable": true,
                        "readOnly": true
                    },
                    "metadata": {
                        "type": "object",
                        "additionalProperties": {},
                        "nullable": true,
                        "readOnly": true
                    },
                    "cost": {
                        "type": "object",
                        "additionalProperties": {},
                        "nullable": true,
                        "readOnly": true
                    },
                    "error_message": {
                        "type": "string",
                        "nullable": true,
                        "readOnly": true
                    },
                    "status": {
                        "type": "string",
                        "description": "Always `success`."
                    }
                },
                "required": [
                    "call_id",
                    "call_status",
                    "completed_at",
                    "cost",
                    "created_at",
                    "duration_seconds",
                    "error_message",
                    "extracted",
                    "extraction_status",
                    "metadata",
                    "outcome",
                    "pathway_id",
                    "pathway_version",
                    "phone_number",
                    "recording_url",
                    "started_at",
                    "status",
                    "summary",
                    "transcript",
                    "transcripts"
                ]
            },
            "ContactResponse": {
                "type": "object",
                "description": "``200``/``201`` body of the single-contact endpoints — the contact under the success envelope.",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Always `success`."
                    },
                    "contact": {
                        "$ref": "#/components/schemas/PublicContact"
                    }
                },
                "required": [
                    "contact",
                    "status"
                ]
            },
            "ContactUpsert": {
                "type": "object",
                "description": "``POST /contacts`` body — ``phone`` (the merge key) is required; everything else optional.",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "language": {
                        "$ref": "#/components/schemas/LanguageEnum"
                    },
                    "timezone": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "consent": {
                        "type": "boolean"
                    },
                    "context": {
                        "type": "string"
                    },
                    "external_id": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "do_not_call": {
                        "type": "boolean"
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": {}
                    },
                    "phone": {
                        "type": "string",
                        "pattern": "^\\+[1-9]\\d{1,14}$",
                        "maxLength": 16
                    }
                },
                "required": [
                    "phone"
                ]
            },
            "Error": {
                "type": "object",
                "description": "The Bland-style error envelope shared by every failure response (``api_public.exceptions``).",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Always `error`."
                    },
                    "message": {
                        "type": "string",
                        "description": "A short human-readable summary (the first detail)."
                    },
                    "errors": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Every error detail as a flat list of strings (field errors are `field: message`)."
                    }
                },
                "required": [
                    "errors",
                    "message",
                    "status"
                ]
            },
            "LanguageEnum": {
                "enum": [
                    "pl",
                    "hr",
                    "en",
                    "uk",
                    "de",
                    "es",
                    "fr"
                ],
                "type": "string",
                "description": "* `pl` - Polish\n* `hr` - Croatian\n* `en` - English\n* `uk` - Ukrainian\n* `de` - German\n* `es` - Spanish\n* `fr` - French"
            },
            "MeKey": {
                "type": "object",
                "properties": {
                    "prefix": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "scopes": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "created": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "last_used_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "required": [
                    "created",
                    "last_used_at",
                    "name",
                    "prefix",
                    "scopes"
                ]
            },
            "MeOrganization": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "slug": {
                        "type": "string"
                    }
                },
                "required": [
                    "id",
                    "name",
                    "slug"
                ]
            },
            "MeOwner": {
                "type": "object",
                "properties": {
                    "username": {
                        "type": "string"
                    },
                    "display_name": {
                        "type": "string"
                    },
                    "role": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "required": [
                    "display_name",
                    "role",
                    "username"
                ]
            },
            "MeResponse": {
                "type": "object",
                "description": "``GET /me`` — who this key is. ``owner`` is null for a machine key; ``authoring`` reports\nwhether the key would clear the ENGINEER gate on the authoring endpoints.",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Always `success`."
                    },
                    "key": {
                        "$ref": "#/components/schemas/MeKey"
                    },
                    "organization": {
                        "$ref": "#/components/schemas/MeOrganization"
                    },
                    "owner": {
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/MeOwner"
                            }
                        ],
                        "nullable": true
                    },
                    "authoring": {
                        "type": "boolean",
                        "description": "True if the key may author pathways (owner-bound engineer)."
                    }
                },
                "required": [
                    "authoring",
                    "key",
                    "organization",
                    "owner",
                    "status"
                ]
            },
            "PaginatedCallsResponse": {
                "type": "object",
                "description": "``200`` body of ``GET /calls`` — the Bland-style limit/offset list envelope.",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Always `success`."
                    },
                    "count": {
                        "type": "integer",
                        "description": "Number of calls on this page."
                    },
                    "total_count": {
                        "type": "integer",
                        "description": "Total calls matching the filters."
                    },
                    "calls": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/PublicCallList"
                        }
                    }
                },
                "required": [
                    "calls",
                    "count",
                    "status",
                    "total_count"
                ]
            },
            "PaginatedContactsResponse": {
                "type": "object",
                "description": "``200`` body of ``GET /contacts`` — the Bland-style limit/offset list envelope.",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Always `success`."
                    },
                    "count": {
                        "type": "integer",
                        "description": "Number of contacts on this page."
                    },
                    "total_count": {
                        "type": "integer",
                        "description": "Total contacts matching the filters."
                    },
                    "contacts": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/PublicContact"
                        }
                    }
                },
                "required": [
                    "contacts",
                    "count",
                    "status",
                    "total_count"
                ]
            },
            "PaginatedEventsResponse": {
                "type": "object",
                "description": "``200`` body of ``GET /calls/{id}/events`` — the event-trace list envelope.",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Always `success`."
                    },
                    "count": {
                        "type": "integer",
                        "description": "Number of events on this page."
                    },
                    "total_count": {
                        "type": "integer",
                        "description": "Total events for this call."
                    },
                    "events": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/PublicCallEvent"
                        }
                    }
                },
                "required": [
                    "count",
                    "events",
                    "status",
                    "total_count"
                ]
            },
            "PatchedContactUpdate": {
                "type": "object",
                "description": "``PATCH /contacts/{id}`` body — every field optional (partial), ``phone`` is immutable.\n\n``phone`` is the per-org merge key that identifies the row, so it is deliberately not writable\nhere: re-keying a contact is a delete plus a fresh upsert, not a patch.",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "language": {
                        "$ref": "#/components/schemas/LanguageEnum"
                    },
                    "timezone": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "consent": {
                        "type": "boolean"
                    },
                    "context": {
                        "type": "string"
                    },
                    "external_id": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "do_not_call": {
                        "type": "boolean"
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": {}
                    }
                }
            },
            "PatchedPublicPostCallConfigSave": {
                "type": "object",
                "description": "Partial save of the three post-call config fields onto a pathway's draft (forks a draft like\na flow edit). All optional so a single-field save is allowed; absent keys are left untouched.",
                "properties": {
                    "summary_instructions": {
                        "type": "string"
                    },
                    "extraction_schema": {},
                    "outcomes": {}
                }
            },
            "PublicCallEvent": {
                "type": "object",
                "description": "One entry in a call's append-only event trace (``GET /calls/{id}/events``).\n\n``type`` is our own event vocabulary (deliberately not remapped onto Bland's coarser\nlevel/category taxonomy); ``payload`` is an arbitrary per-event object; ``sequence`` breaks ties\nbetween events recorded in the same instant; ``occurred_at`` is the event timestamp.",
                "properties": {
                    "type": {
                        "type": "string",
                        "readOnly": true
                    },
                    "payload": {
                        "readOnly": true
                    },
                    "sequence": {
                        "type": "integer",
                        "readOnly": true
                    },
                    "occurred_at": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    }
                },
                "required": [
                    "occurred_at",
                    "payload",
                    "sequence",
                    "type"
                ]
            },
            "PublicCallList": {
                "type": "object",
                "description": "One flat row in ``GET /calls`` — the poll-friendly summary, no transcript/extraction body.",
                "properties": {
                    "call_id": {
                        "type": "string",
                        "format": "uuid",
                        "readOnly": true
                    },
                    "phone_number": {
                        "type": "string",
                        "readOnly": true
                    },
                    "call_status": {
                        "type": "string",
                        "readOnly": true
                    },
                    "outcome": {
                        "type": "string",
                        "nullable": true,
                        "readOnly": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "duration_seconds": {
                        "type": "integer",
                        "nullable": true,
                        "readOnly": true
                    },
                    "has_recording": {
                        "type": "boolean",
                        "readOnly": true
                    },
                    "pathway_id": {
                        "type": "string",
                        "nullable": true,
                        "readOnly": true
                    },
                    "summary": {
                        "type": "string",
                        "nullable": true,
                        "readOnly": true
                    }
                },
                "required": [
                    "call_id",
                    "call_status",
                    "created_at",
                    "duration_seconds",
                    "has_recording",
                    "outcome",
                    "pathway_id",
                    "phone_number",
                    "summary"
                ]
            },
            "PublicContact": {
                "type": "object",
                "description": "The full public Contact object, shared by every contacts read/write response.\n\nA plain ``Serializer`` (not a ``ModelSerializer``) so the public field set is pinned by hand and\nnever silently grows when a column is added to the model. ``do_not_call`` is computed, never a\nstored field; every other field maps straight through from the ``Contact`` row.",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid",
                        "readOnly": true
                    },
                    "phone": {
                        "type": "string",
                        "readOnly": true
                    },
                    "external_id": {
                        "type": "string",
                        "readOnly": true
                    },
                    "name": {
                        "type": "string",
                        "readOnly": true
                    },
                    "language": {
                        "type": "string",
                        "readOnly": true
                    },
                    "timezone": {
                        "type": "string",
                        "readOnly": true
                    },
                    "consent": {
                        "type": "boolean",
                        "readOnly": true
                    },
                    "do_not_call": {
                        "type": "boolean",
                        "readOnly": true
                    },
                    "context": {
                        "type": "string",
                        "readOnly": true
                    },
                    "data": {
                        "readOnly": true
                    },
                    "status": {
                        "type": "string",
                        "readOnly": true
                    },
                    "disposition": {
                        "type": "string",
                        "readOnly": true
                    },
                    "disposition_at": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "last_outcome": {
                        "type": "string",
                        "readOnly": true
                    },
                    "follow_up_at": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "created": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "modified": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    }
                },
                "required": [
                    "consent",
                    "context",
                    "created",
                    "data",
                    "disposition",
                    "disposition_at",
                    "do_not_call",
                    "external_id",
                    "follow_up_at",
                    "id",
                    "language",
                    "last_outcome",
                    "modified",
                    "name",
                    "phone",
                    "status",
                    "timezone"
                ]
            },
            "PublicFlowImport": {
                "type": "object",
                "description": "A complete flow_json (typically AI-authored) imported as a new draft, plus optional post-call\nconfig. Mirrors the internal import inputs; ``flow_json`` shape is a validation FINDING, not a\nrequest-level 400 — only a body missing ``flow_json`` is malformed here.",
                "properties": {
                    "flow_json": {},
                    "summary_instructions": {
                        "type": "string"
                    },
                    "extraction_schema": {},
                    "outcomes": {}
                },
                "required": [
                    "flow_json"
                ]
            },
            "PublicPathway": {
                "type": "object",
                "description": "A pathway in the list: id, name, language, and the live + draft version numbers.\n\n``active_version_number`` is nullable now that ``?include_drafts=true`` can surface draft-only\npathways (no active version); ``draft_version_number`` is null when there is no open draft.",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid",
                        "readOnly": true
                    },
                    "name": {
                        "type": "string",
                        "readOnly": true
                    },
                    "language": {
                        "type": "string",
                        "readOnly": true
                    },
                    "active_version_number": {
                        "type": "integer",
                        "readOnly": true,
                        "nullable": true
                    },
                    "draft_version_number": {
                        "type": "integer",
                        "readOnly": true,
                        "nullable": true
                    }
                },
                "required": [
                    "active_version_number",
                    "draft_version_number",
                    "id",
                    "language",
                    "name"
                ]
            },
            "PublicPathwayCreate": {
                "type": "object",
                "description": "Create a pathway from ``{name, language}`` — the two fields a fresh flow needs; the service\nseeds version 1 from the default flow so the new pathway opens runnable.",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "language": {
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/LanguageEnum"
                            }
                        ],
                        "default": "pl"
                    }
                },
                "required": [
                    "name"
                ]
            },
            "PublicPathwayDetail": {
                "type": "object",
                "description": "The single-pathway metadata view: the list fields plus version count and timestamps. No\n``flow_json`` — the flow lives on the versions endpoint (the authoring passthrough tier).",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid",
                        "readOnly": true
                    },
                    "name": {
                        "type": "string",
                        "readOnly": true
                    },
                    "language": {
                        "type": "string",
                        "readOnly": true
                    },
                    "active_version_number": {
                        "type": "integer",
                        "readOnly": true,
                        "nullable": true
                    },
                    "draft_version_number": {
                        "type": "integer",
                        "readOnly": true,
                        "nullable": true
                    },
                    "version_count": {
                        "type": "integer",
                        "readOnly": true
                    },
                    "created": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "modified": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    }
                },
                "required": [
                    "active_version_number",
                    "created",
                    "draft_version_number",
                    "id",
                    "language",
                    "modified",
                    "name",
                    "version_count"
                ]
            },
            "PublicValidate": {
                "type": "object",
                "description": "The validate endpoint's body: ``flow_json`` plus the optional post-call config triple.\n\nUnlike import, does NOT reject a malformed ``flow_json`` — a bad shape is a finding returned in\nthe 200 body. Defaults let the view read every field unconditionally.",
                "properties": {
                    "flow_json": {},
                    "summary_instructions": {
                        "type": "string",
                        "default": ""
                    },
                    "extraction_schema": {},
                    "outcomes": {}
                },
                "required": [
                    "flow_json"
                ]
            },
            "SendCall": {
                "type": "object",
                "properties": {
                    "phone_number": {
                        "type": "string",
                        "pattern": "^\\+[1-9]\\d{1,14}$",
                        "maxLength": 16
                    },
                    "task": {
                        "type": "string"
                    },
                    "pathway_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "language": {
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/LanguageEnum"
                            }
                        ],
                        "default": "pl"
                    },
                    "name": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "context": {
                        "type": "string"
                    },
                    "voice": {
                        "type": "string",
                        "maxLength": 255
                    },
                    "from_number_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "record": {
                        "type": "boolean",
                        "nullable": true
                    },
                    "max_duration": {
                        "type": "integer",
                        "maximum": 60,
                        "minimum": 1,
                        "nullable": true
                    },
                    "metadata": {
                        "type": "object",
                        "additionalProperties": {}
                    }
                },
                "required": [
                    "phone_number"
                ]
            },
            "SendCallResponse": {
                "type": "object",
                "description": "``201`` body of ``POST /calls`` — the accepted call's id.",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Always `success`."
                    },
                    "call_id": {
                        "type": "string",
                        "format": "uuid",
                        "description": "The new call's id — poll it at `GET /calls/{id}`."
                    }
                },
                "required": [
                    "call_id",
                    "status"
                ]
            },
            "StopActiveCallsResponse": {
                "type": "object",
                "description": "``200`` body of ``POST /calls/active/stop`` — the account-wide stop sweep was accepted.",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Always `success`."
                    },
                    "message": {
                        "type": "string",
                        "description": "A human-readable note that the stop is in progress."
                    },
                    "num_calls": {
                        "type": "integer",
                        "description": "How many active calls a hangup was issued for."
                    }
                },
                "required": [
                    "message",
                    "num_calls",
                    "status"
                ]
            },
            "StopCallResponse": {
                "type": "object",
                "description": "``200`` body of ``POST /calls/{id}/stop`` — the stop request was accepted.",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Always `success`."
                    },
                    "message": {
                        "type": "string",
                        "description": "`Call ended successfully.`"
                    }
                },
                "required": [
                    "message",
                    "status"
                ]
            }
        },
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Organization-scoped API key. Send it in the `Authorization` header as `Bearer <key>`, `Api-Key <key>`, or the raw `<prefix>.<secret>` key on its own."
            }
        }
    },
    "servers": [
        {
            "url": "https://api.adamcalling.com",
            "description": "Production"
        }
    ]
}