{
  "openapi": "3.1.0",
  "info": {
    "title": "Reach Agents Agent API",
    "version": "1.1.0",
    "description": "ReachAgents Public API contract for company/workspace setup, discovery agents, contacts, six campaign and inbox channels, automation, run diagnostics, and YouTube video data. Customer clients use https://api.reachagents.ai/v1; provider availability and server-side rollout gates still apply."
  },
  "servers": [
    {
      "url": "https://api.reachagents.ai",
      "description": "Production ReachAgents API"
    }
  ],
  "security": [
    {
      "BearerApiKey": []
    }
  ],
  "tags": [
    {
      "name": "Identity"
    },
    {
      "name": "Data",
      "description": "Public data lookups (e.g. YouTube video metrics)."
    },
    {
      "name": "Workspaces"
    },
    {
      "name": "Onboarding"
    },
    {
      "name": "Agents"
    },
    {
      "name": "Contacts"
    },
    {
      "name": "Contact groups"
    },
    {
      "name": "Campaigns"
    },
    {
      "name": "Runs"
    },
    {
      "name": "Inbox Automation"
    },
    {
      "name": "Legacy compatibility"
    },
    {
      "name": "Inbox"
    },
    {
      "name": "Setup"
    }
  ],
  "paths": {
    "/v1/youtube-videos/{video}": {
      "get": {
        "tags": [
          "Data"
        ],
        "summary": "Get YouTube video metrics",
        "description": "Scrapes public per-video metrics (title, url, published date, description, duration, views, likes, comments, paid-promotion flag) from the YouTube watch page, served through a global read-through cache. `video` may be an 11-character video id or any watch / share / shorts / embed URL.",
        "operationId": "getYouTubeVideo",
        "x-required-scopes": [
          "data:read"
        ],
        "parameters": [
          {
            "name": "video",
            "in": "path",
            "required": true,
            "description": "YouTube video id or URL.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "refresh",
            "in": "query",
            "required": false,
            "description": "Bypass the cache and force a live re-scrape.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "max_age_hours",
            "in": "query",
            "required": false,
            "description": "Maximum acceptable cache age in hours before a re-scrape (default 24, max 720).",
            "schema": {
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Video metrics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/YouTubeVideoLookupResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/youtube-videos": {
      "get": {
        "tags": [
          "Data"
        ],
        "summary": "Batch YouTube video metrics",
        "description": "Look up up to 10 videos in one call. `ids` (alias `urls`) is a comma-separated list of video ids or URLs. Per-video failures are reported inline as an `error` object on that item without failing the whole batch.",
        "operationId": "listYouTubeVideos",
        "x-required-scopes": [
          "data:read"
        ],
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "description": "Comma-separated video ids or URLs (max 10).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "refresh",
            "in": "query",
            "required": false,
            "description": "Bypass the cache and force a live re-scrape.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "max_age_hours",
            "in": "query",
            "required": false,
            "description": "Maximum acceptable cache age in hours before a re-scrape (default 24, max 720).",
            "schema": {
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Video metrics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/YouTubeVideoLookupResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/whoami": {
      "get": {
        "tags": [
          "Identity"
        ],
        "summary": "Inspect the authenticated API key",
        "description": "Returns company, key prefix, scopes, workspace allowlist, and default workspace. Does not return raw key material.",
        "operationId": "whoami",
        "x-required-scopes": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Authenticated key metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WhoamiResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "data": {
                        "company_id": "co_123",
                        "organization_id": "co_123",
                        "key_id": "key_123",
                        "key_prefix": "dsg_live_abc...",
                        "environment": "production",
                        "scopes": [
                          "workspaces:read",
                          "agents:run"
                        ],
                        "workspace_access": "selected_workspaces",
                        "workspace_ids": [
                          "ws_123"
                        ],
                        "workspace_count": 1,
                        "default_workspace_id": "ws_123"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/company": {
      "get": {
        "tags": [
          "Workspaces"
        ],
        "summary": "Get company details",
        "description": "Returns the company attached to the authenticated key plus the workspaces visible through its workspace access policy.",
        "operationId": "getCompany",
        "x-required-scopes": [
          "workspaces:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Company details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Workspaces"
        ],
        "summary": "Update company profile details",
        "description": "Updates the authenticated company name/description so operator channels can keep company-level setup in sync with workspace setup.",
        "operationId": "updateCompany",
        "x-required-scopes": [
          "workspaces:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompanyPatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated company details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/workspaces": {
      "get": {
        "tags": [
          "Workspaces"
        ],
        "summary": "List accessible workspaces",
        "operationId": "listWorkspaces",
        "x-required-scopes": [
          "workspaces:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Case-insensitive workspace name search."
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/workspaces/{workspace_id}": {
      "get": {
        "tags": [
          "Workspaces"
        ],
        "summary": "Get one workspace",
        "operationId": "getWorkspace",
        "x-required-scopes": [
          "workspaces:read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace ID inside the authenticated key company/workspace access boundary."
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Workspaces"
        ],
        "summary": "Update workspace details",
        "description": "Updates workspace name, description, AI goal, or communication style. The key must include workspaces:write and the workspace must be inside the key workspace access policy.",
        "operationId": "updateWorkspace",
        "x-required-scopes": [
          "workspaces:write"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Workspace ID inside the authenticated key company/workspace access boundary."
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspacePatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/agents": {
      "get": {
        "tags": [
          "Agents"
        ],
        "summary": "List agents",
        "operationId": "listAgents",
        "x-required-scopes": [
          "agents:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/AgentStatus"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Agents"
        ],
        "summary": "Create a lead agent and start discovery by default",
        "operationId": "createAgent",
        "x-required-scopes": [
          "agents:write",
          "agents:run"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent created; includes auto_run and run_id when the first run was queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        },
        "description": "Creates a lead agent with the same default behavior as the ReachAgents UI: the agent is marked running, next_run_at is set immediately, and the first discovery run is started unless auto_run=false or manual_only=true is provided. Auto-run creation requires both agents:write and agents:run scopes; manual-only creation requires agents:write."
      }
    },
    "/v1/agents/{agent_id}": {
      "get": {
        "tags": [
          "Agents"
        ],
        "summary": "Get one agent",
        "operationId": "getAgent",
        "x-required-scopes": [
          "agents:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentIdPath"
          },
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Agents"
        ],
        "summary": "Update a lead agent",
        "operationId": "updateAgent",
        "x-required-scopes": [
          "agents:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentIdPath"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      },
      "delete": {
        "tags": [
          "Agents"
        ],
        "summary": "Delete a non-running lead agent",
        "operationId": "deleteAgent",
        "x-required-scopes": [
          "agents:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentIdPath"
          },
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent deleted"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/agents/{agent_id}/run": {
      "post": {
        "tags": [
          "Agents",
          "Runs"
        ],
        "summary": "Queue an agent discovery run",
        "operationId": "runAgent",
        "x-required-scopes": [
          "agents:run"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentIdPath"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRunRequest"
              },
              "examples": {
                "dryRun": {
                  "value": {
                    "workspace_id": "ws_123",
                    "dry_run": true,
                    "limit": 25,
                    "inputs": {
                      "query": "Bittensor founders"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Run queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunAcceptedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "409": {
            "description": "Idempotency conflict, or monthly_limit_reached: the agent reached its monthly spending limit; details.next_run_at is when it resumes. Raise monthly_spend_limit_usd to run it sooner.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        },
        "description": "Queues and starts a discovery run for the agent when dry_run is false. dry_run=true only validates/records the dry run without invoking discovery."
      }
    },
    "/v1/contacts": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "summary": "List contacts",
        "operationId": "listContacts",
        "x-required-scopes": [
          "contacts:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "name": "group_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "agent_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "platform",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Contact page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactListResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Contacts"
        ],
        "summary": "Create or upsert a contact",
        "operationId": "createContact",
        "x-required-scopes": [
          "contacts:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactUpsertRequest"
              },
              "examples": {
                "xLead": {
                  "value": {
                    "workspace_id": "ws_123",
                    "platform": "x",
                    "handle": "desearch_ai",
                    "name": "Desearch AI",
                    "contact_group": "Bittensor",
                    "tags": [
                      "ai",
                      "bittensor"
                    ],
                    "upsert": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing contact updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          },
          "201": {
            "description": "Contact created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      },
      "patch": {
        "tags": [
          "Contacts"
        ],
        "summary": "Patch a contact by ID in the request body",
        "description": "Compatibility shorthand for clients that cannot template /v1/contacts/{contact_id}. Prefer PATCH /v1/contacts/{contact_id}.",
        "operationId": "patchContactByBodyId",
        "deprecated": true,
        "x-required-scopes": [
          "contacts:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactPatchByBodyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/contacts/{contact_id}": {
      "patch": {
        "tags": [
          "Contacts"
        ],
        "summary": "Patch a contact",
        "operationId": "patchContact",
        "x-required-scopes": [
          "contacts:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ContactIdPath"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactPatchRequest"
              },
              "examples": {
                "status": {
                  "value": {
                    "workspace_id": "ws_123",
                    "status": "qualified",
                    "metadata": {
                      "source": "cli"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/contacts/bulk": {
      "post": {
        "tags": [
          "Contacts"
        ],
        "summary": "Bulk import contacts",
        "operationId": "bulkImportContacts",
        "x-required-scopes": [
          "contacts:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactBulkRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Bulk import accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkImportResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/contact-groups": {
      "get": {
        "tags": [
          "Contact groups"
        ],
        "summary": "List contact groups",
        "operationId": "listContactGroups",
        "x-required-scopes": [
          "contact_groups:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Contact group page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactGroupListResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Contact groups"
        ],
        "summary": "Create a contact group",
        "operationId": "createContactGroup",
        "x-required-scopes": [
          "contact_groups:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactGroupCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Contact group created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactGroupResponse"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/contact-groups/{group_id}/contacts": {
      "post": {
        "tags": [
          "Contact groups"
        ],
        "summary": "Add contacts to a group",
        "operationId": "addContactsToGroup",
        "x-required-scopes": [
          "contact_groups:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/GroupIdPath"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GroupMembershipAddRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Memberships added",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupMembershipResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/contact-groups/{group_id}/contacts/{contact_id}": {
      "delete": {
        "tags": [
          "Contact groups"
        ],
        "summary": "Remove one contact from a group",
        "operationId": "removeContactFromGroup",
        "x-required-scopes": [
          "contact_groups:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/GroupIdPath"
          },
          {
            "$ref": "#/components/parameters/ContactIdPath"
          },
          {
            "name": "workspace_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Membership removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupMembershipResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/campaigns": {
      "get": {
        "tags": [
          "Campaigns"
        ],
        "summary": "List campaigns",
        "operationId": "listCampaigns",
        "x-required-scopes": [
          "campaigns:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/CampaignStatus"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "x",
                "email",
                "linkedin"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignListResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Create a campaign draft",
        "operationId": "createCampaign",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CampaignCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Campaign created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      },
      "patch": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Patch a campaign by ID in the request body",
        "description": "Compatibility shorthand for clients that cannot template /v1/campaigns/{campaign_id}. Prefer PATCH /v1/campaigns/{campaign_id}.",
        "operationId": "patchCampaignByBodyId",
        "deprecated": true,
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CampaignPatchByBodyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Campaign updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/campaigns/linkedin": {
      "post": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Create a LinkedIn campaign draft",
        "description": "Creates a LinkedIn campaign draft through the channel-specific public API endpoint, persists the audience contract, and materializes draft targets when audience.materialization.strategy is not none.",
        "operationId": "createLinkedInCampaign",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LinkedInCampaignCreateRequest"
              },
              "examples": {
                "followUp": {
                  "value": {
                    "workspace_id": "ws_123",
                    "name": "LinkedIn follow-up",
                    "linkedin_account_id": "li_123",
                    "audience": {
                      "mode": "all_contacts",
                      "suppression": {
                        "exclude_previous_campaign_targets": false,
                        "exclude_existing_conversations": false,
                        "exclude_replied_contacts": false
                      },
                      "materialization": {
                        "strategy": "snapshot",
                        "limit": 100
                      }
                    },
                    "steps": [
                      {
                        "order": 1,
                        "body": "Hi {{first_name}}, quick follow-up."
                      }
                    ]
                  }
                },
                "inviteOnlyNoNote": {
                  "summary": "LinkedIn connection request only, no note or message",
                  "value": {
                    "workspace_id": "ws_123",
                    "name": "LinkedIn invite-only",
                    "linkedin_account_id": "li_123",
                    "linkedin_action": "connection_request_only",
                    "audience": {
                      "mode": "all_contacts",
                      "filters": {
                        "platform": "linkedin"
                      },
                      "materialization": {
                        "strategy": "snapshot",
                        "limit": 100
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "LinkedIn campaign draft created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}": {
      "get": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Get one campaign",
        "operationId": "getCampaign",
        "x-required-scopes": [
          "campaigns:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CampaignIdPath"
          },
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Patch a campaign draft/configuration",
        "operationId": "patchCampaign",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CampaignIdPath"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CampaignPatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Campaign updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      },
      "delete": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Delete an inactive campaign draft",
        "operationId": "deleteDraftCampaign",
        "description": "Only drafts without campaign/email events and without active or delivered target states can be deleted. Returns 409 unsafe_delete_campaign when activity exists.",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CampaignIdPath"
          },
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Delete an inactive campaign draft",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}/preview": {
      "post": {
        "tags": [
          "Campaigns",
          "Runs"
        ],
        "summary": "Preview a campaign audience/messages without sending",
        "operationId": "previewCampaign",
        "x-required-scopes": [
          "campaigns:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CampaignIdPath"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CampaignPreviewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preview result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignPreviewResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}/run": {
      "post": {
        "tags": [
          "Campaigns",
          "Runs"
        ],
        "summary": "Queue a campaign run",
        "operationId": "runCampaign",
        "x-required-scopes": [
          "campaigns:run"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CampaignIdPath"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CampaignRunRequest"
              },
              "examples": {
                "dryRunFirst": {
                  "value": {
                    "workspace_id": "ws_123",
                    "dry_run": true,
                    "limit": 25
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Run queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunAcceptedResponse"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/runs/batch": {
      "post": {
        "tags": [
          "Runs"
        ],
        "summary": "Queue multiple agent/campaign runs",
        "operationId": "createBatchRun",
        "x-required-scopes": [
          "agents:run",
          "campaigns:run"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchRunRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Batch queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchRunAcceptedResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/runs/{run_id}": {
      "get": {
        "tags": [
          "Runs"
        ],
        "summary": "Get run status",
        "operationId": "getRun",
        "x-required-scopes": [
          "runs:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/RunIdPath"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Run",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/runs/{run_id}/logs": {
      "get": {
        "tags": [
          "Runs"
        ],
        "summary": "Get run logs",
        "operationId": "getRunLogs",
        "x-required-scopes": [
          "runs:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/RunIdPath"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/LogLevel"
            }
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Run log page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunLogListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/runs/{run_id}/cancel": {
      "post": {
        "tags": [
          "Runs"
        ],
        "summary": "Cancel a queued or running run",
        "operationId": "cancelRun",
        "x-required-scopes": [
          "runs:cancel"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/RunIdPath"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelRunRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Cancellation requested",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunResponse"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/conversations": {
      "get": {
        "tags": [
          "Inbox"
        ],
        "summary": "List inbox conversations",
        "description": "Returns inbox conversations with server-side filters matching the app inbox filters.",
        "operationId": "listConversations",
        "x-required-scopes": [
          "contacts:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "name": "platform",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "email",
                "linkedin",
                "x",
                "telegram",
                "whatsapp",
                "instagram"
              ]
            }
          },
          {
            "name": "read_status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "unread",
                "read",
                "no_reply"
              ]
            }
          },
          {
            "name": "contact_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "campaign_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "connected_account_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email_account_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "account_ids",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated connected account or email account IDs."
          },
          {
            "name": "is_request",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "needs_backfill",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "last_message_direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "inbound",
                "outbound"
              ]
            }
          },
          {
            "name": "response_filter",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "has_response",
                "needs_reply",
                "no_response"
              ]
            }
          },
          {
            "name": "last_message_after",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "last_message_before",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          },
          {
            "name": "include_system",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "system_category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Conversation page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationListResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/conversations/{conversation_id}/messages": {
      "get": {
        "tags": [
          "Inbox"
        ],
        "summary": "List conversation messages",
        "operationId": "listConversationMessages",
        "x-required-scopes": [
          "contacts:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ConversationIdPath"
          },
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "name": "direction",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "inbound",
                "outbound"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Message page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageListResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      },
      "post": {
        "tags": [
          "Inbox"
        ],
        "summary": "Send or draft a conversation message",
        "description": "Text-only endpoint for email, LinkedIn, Telegram, WhatsApp and Instagram. X live sends currently return 422 unsupported_platform. send=false creates a draft. Outgoing media fields return 422 unsupported_media. Instagram is limited to 1000 characters; other accepted messages to 8000. Provider gates, account state, group restrictions, and limits apply. An uncertain Telegram, WhatsApp or Instagram send returns 409 *_send_unconfirmed; inspect conversation state before retrying. A draft is not a sent message.",
        "operationId": "createConversationMessage",
        "x-required-scopes": [
          "contacts:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ConversationIdPath"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConversationMessageCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageResponse"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/agents": {
      "get": {
        "tags": [
          "Legacy compatibility"
        ],
        "summary": "Legacy alias for GET /v1/agents",
        "operationId": "legacyListAgents",
        "deprecated": true,
        "security": [
          {
            "LegacyApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Legacy { agents: [...] } response retained for current callers."
          }
        }
      }
    },
    "/leads": {
      "post": {
        "tags": [
          "Legacy compatibility"
        ],
        "summary": "Legacy alias for POST /v1/contacts",
        "operationId": "legacyCreateLead",
        "deprecated": true,
        "security": [
          {
            "LegacyApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Legacy { lead, profile_id } response retained for current callers. One contact per workspace and profile: posting a person who is already a contact links that contact to the agent (and the group, when given), keeps its status and adds existing: true."
          }
        }
      }
    },
    "/leads/bulk": {
      "post": {
        "tags": [
          "Legacy compatibility"
        ],
        "summary": "Legacy alias for POST /v1/contacts/bulk",
        "operationId": "legacyBulkLeads",
        "deprecated": true,
        "security": [
          {
            "LegacyApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Legacy { created, linked, errors? } response. created counts new contacts; linked counts people who were already contacts in the workspace and were linked to the agent instead of duplicated."
          }
        }
      }
    },
    "/v1/inbox-automation/policies": {
      "get": {
        "tags": [
          "Inbox Automation"
        ],
        "summary": "List inbox automation policies",
        "operationId": "listInboxAutomationPolicies",
        "x-required-scopes": [
          "inbox_automation:read"
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "required": false
          },
          {
            "name": "workspace_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "account_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InboxAutomationPolicyListResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Inbox Automation"
        ],
        "summary": "Create or update an inbox automation policy",
        "operationId": "upsertInboxAutomationPolicy",
        "x-required-scopes": [
          "inbox_automation:write"
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "required": false
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InboxAutomationPolicyUpsertRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InboxAutomationPolicyResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Inbox Automation"
        ],
        "summary": "Create or update an inbox automation policy",
        "operationId": "putInboxAutomationPolicy",
        "x-required-scopes": [
          "inbox_automation:write"
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "required": false
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InboxAutomationPolicyUpsertRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InboxAutomationPolicyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inbox-automation/candidates": {
      "get": {
        "tags": [
          "Inbox Automation"
        ],
        "summary": "List inbox automation candidates",
        "description": "Returns classified conversations with decisions, proposed replies, safety flags, and analysis context.",
        "operationId": "listInboxAutomationCandidates",
        "x-required-scopes": [
          "inbox_automation:read"
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "required": false
          },
          {
            "name": "workspace_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "classification",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "conversation_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InboxAutomationCandidateListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inbox-automation/candidates/{candidate_id}": {
      "patch": {
        "tags": [
          "Inbox Automation"
        ],
        "summary": "Patch an inbox automation candidate",
        "operationId": "patchInboxAutomationCandidate",
        "x-required-scopes": [
          "inbox_automation:write"
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "required": false
          },
          {
            "name": "candidate_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InboxAutomationCandidatePatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InboxAutomationCandidateResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inbox-automation/candidates/{candidate_id}/send": {
      "post": {
        "tags": [
          "Inbox Automation"
        ],
        "summary": "Send an inbox automation candidate reply",
        "operationId": "sendInboxAutomationCandidate",
        "x-required-scopes": [
          "inbox_automation:run"
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "required": false
          },
          {
            "name": "candidate_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InboxAutomationSendRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InboxAutomationCandidateResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inbox-automation/run": {
      "post": {
        "tags": [
          "Inbox Automation"
        ],
        "summary": "Run inbox automation manually",
        "description": "Scans recent conversations, analyzes full conversation history, loads workspace description and sender account goal/style, classifies replies, drafts safe responses, and optionally auto-sends when policy gates pass.",
        "operationId": "runInboxAutomation",
        "x-required-scopes": [
          "inbox_automation:run"
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "required": false
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InboxAutomationRunRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InboxAutomationRunEnvelopeResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/onboarding/readiness": {
      "get": {
        "tags": [
          "Onboarding"
        ],
        "summary": "Diagnose onboarding readiness for a workspace",
        "description": "Returns profile gaps, agents/campaign/contact counts, sender inventory, missing setup pieces, and approval-safe next actions for Telegram, WhatsApp, Discord, or in-app operator bots.",
        "operationId": "getOnboardingReadiness",
        "x-required-scopes": [
          "workspaces:read"
        ],
        "parameters": [
          {
            "name": "workspace_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Defaults to the API key default workspace."
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Onboarding readiness diagnosis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingReadinessResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/onboarding/analyze-website": {
      "post": {
        "tags": [
          "Onboarding"
        ],
        "summary": "Analyze a website into a ReachAgents business profile",
        "description": "Fetches a public website and returns structured company positioning, ICP hints, pain points, recommended lead agent draft, campaign draft, and follow-up questions. This endpoint is read-only and does not require idempotency.",
        "operationId": "analyzeOnboardingWebsite",
        "x-required-scopes": [
          "workspaces:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OnboardingWebsiteAnalysisRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Website analysis profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingWebsiteAnalysisResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "415": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "502": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/v1/onboarding/setup": {
      "post": {
        "tags": [
          "Onboarding"
        ],
        "summary": "Apply onboarding business profile to company and workspace",
        "description": "Applies analyzed business profile fields to company/workspace setup. It does not launch campaigns; bots should create drafts and require explicit user approval before live sends.",
        "operationId": "applyOnboardingSetup",
        "x-required-scopes": [
          "workspaces:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OnboardingSetupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Applied onboarding setup",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingSetupResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/campaigns/whatsapp": {
      "post": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Create a WhatsApp campaign draft",
        "description": "Creates a draft only. Recipients need a WhatsApp identity or an international phone number; registration is checked before the first send. Live sends remain gated by WHATSAPP_SEND_ENABLED and WHATSAPP_CAMPAIGNS_ENABLED.",
        "operationId": "createWhatsAppCampaign",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WhatsAppCampaignCreateRequest"
              },
              "examples": {
                "directMessages": {
                  "value": {
                    "workspace_id": "ws_123",
                    "name": "WhatsApp follow-up",
                    "whatsapp_account_id": "wa_123",
                    "audience": {
                      "mode": "contacts",
                      "include_contact_ids": [
                        "contact_123"
                      ]
                    },
                    "steps": [
                      {
                        "order": 1,
                        "body": "Hello {{first_name}}",
                        "delay_hours": 0
                      }
                    ],
                    "schedule": {
                      "dailyLimit": 20,
                      "maxNewConversationsPerDay": 5
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "LinkedIn campaign draft created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/campaigns/instagram": {
      "post": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Create a Instagram campaign draft",
        "description": "Creates an Instagram draft when INSTAGRAM_CAMPAIGNS_ENABLED is true. A healthy same-company Instagram sender and explicit Instagram contact identities are required. Live sending also requires INSTAGRAM_SEND_ENABLED. All rollout flags default off pending a real-account pilot. Preview/run use existing campaign routes.",
        "operationId": "createInstagramCampaign",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstagramCampaignCreateRequest"
              },
              "examples": {
                "directMessages": {
                  "value": {
                    "workspace_id": "ws_123",
                    "name": "Instagram follow-up",
                    "instagram_account_id": "ig_123",
                    "audience": {
                      "mode": "contacts",
                      "include_contact_ids": [
                        "contact_123"
                      ]
                    },
                    "steps": [
                      {
                        "order": 1,
                        "body": "Hello {{first_name}}",
                        "delay_hours": 0
                      }
                    ],
                    "schedule": {
                      "dailyLimit": 20,
                      "maxNewConversationsPerDay": 5
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Instagram campaign draft created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/campaigns/telegram": {
      "post": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Create a Telegram campaign draft",
        "description": "Creates a Telegram DM campaign draft and materializes draft targets when audience.materialization.strategy is not none. The sender must be an active, connected and unpaused Telegram account in the same company as workspace_id. Recipients need a native Telegram identity (platform=telegram with a provider id, username or non-synthetic handle); X can_dm is never applied. Preview/run use the existing campaign routes, and run-campaign applies the account's Telegram schedule and DM limits.",
        "operationId": "createTelegramCampaign",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TelegramCampaignCreateRequest"
              },
              "examples": {
                "directMessages": {
                  "value": {
                    "workspace_id": "ws_123",
                    "name": "Telegram outreach",
                    "telegram_account_id": "tg_123",
                    "audience": {
                      "mode": "all_contacts",
                      "materialization": {
                        "strategy": "snapshot",
                        "limit": 100
                      }
                    },
                    "steps": [
                      {
                        "order": 1,
                        "body": "Hi {{first_name}}, quick question.",
                        "delay_hours": 0
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Telegram campaign draft created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/sender-accounts": {
      "get": {
        "tags": [
          "Setup"
        ],
        "summary": "List sender accounts",
        "operationId": "listSenderAccounts",
        "x-required-scopes": [
          "campaigns:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "email",
                "x",
                "linkedin",
                "telegram",
                "whatsapp",
                "instagram"
              ],
              "default": "all"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "name": "is_active",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sender accounts in scope. Telegram, Instagram and WhatsApp can be shared by sibling workspaces in the same company; credentials are never returned."
          }
        }
      }
    },
    "/v1/campaigns/x-dm": {
      "post": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Create an X DM campaign draft",
        "operationId": "createXDMCampaign",
        "description": "Creates a draft and optionally materializes audience targets. Preview and run use the shared campaign endpoints. Requires an authorized sender account.",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "201": {
            "description": "Create an X DM campaign draft",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/XDMCampaignCreateRequest"
              }
            }
          }
        }
      }
    },
    "/v1/campaigns/email": {
      "post": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Create an email campaign draft",
        "operationId": "createEmailCampaign",
        "description": "Creates a draft and optionally materializes audience targets. Preview and run use the shared campaign endpoints. Requires an authorized sender account.",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "201": {
            "description": "Create an email campaign draft",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailCampaignCreateRequest"
              }
            }
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}/targets": {
      "get": {
        "tags": [
          "Campaigns"
        ],
        "summary": "List campaign targets",
        "operationId": "listCampaignTargets",
        "description": "The email filter applies within the fetched page. Use contact_id for a database-level contact filter.",
        "x-required-scopes": [
          "campaigns:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CampaignIdPath"
          },
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contact_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "List campaign targets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CampaignTarget"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PageMeta"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}/events": {
      "get": {
        "tags": [
          "Campaigns"
        ],
        "summary": "List campaign email events",
        "operationId": "listCampaignEvents",
        "description": "Reads email_events for the campaign; this is not an all-provider message event feed.",
        "x-required-scopes": [
          "campaigns:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CampaignIdPath"
          },
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "name": "event_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "target_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contact_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "message_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "List campaign email events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CampaignEmailEvent"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PageMeta"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}/summary": {
      "get": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Get campaign health and delivery summary",
        "operationId": "getCampaignSummary",
        "description": "Returns campaign, target_status_counts, email_event_counts, delivery_usage_counts, duplicate_sent_events, sender_accounts, provider_status, and evidence_limits. Usage counters cover X DMs, LinkedIn messages/invitations, and email; zero counters do not prove zero Telegram, WhatsApp or Instagram sends. Duplicate evidence scans at most 5000 email sent events. Read newer channel sender state separately from /v1/sender-accounts, especially for company-shared accounts.",
        "x-required-scopes": [
          "campaigns:read"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CampaignIdPath"
          },
          {
            "$ref": "#/components/parameters/WorkspaceId"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Get campaign health and delivery summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CampaignSummary"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/EnvelopeMeta"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}/targets/{target_id}": {
      "patch": {
        "tags": [
          "Campaigns"
        ],
        "summary": "Update a campaign target",
        "operationId": "patchCampaignTarget",
        "description": "",
        "x-required-scopes": [
          "campaigns:write"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CampaignIdPath"
          },
          {
            "name": "target_id",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Update a campaign target",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CampaignTarget"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/EnvelopeMeta"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace_id": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "last_event_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  }
                },
                "description": "Provide at least one of status, metadata, or last_event_at."
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "DES_GROWTH_API_KEY",
        "description": "Primary auth. Send Authorization: Bearer <raw API key>. Store and log only key hashes/prefixes."
      },
      "LegacyApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Compatibility auth for existing /leads, /leads/bulk, and /agents callers."
      }
    },
    "parameters": {
      "WorkspaceId": {
        "name": "workspace_id",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Workspace filter. Required for scoped reads when the key has access to multiple workspaces unless endpoint explicitly supports cross-workspace discovery."
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "minLength": 8,
          "maxLength": 200
        },
        "description": "Required for creates, imports, runs, and cancellation in production clients. Same key + same body returns the original result; same key + different body returns 409."
      },
      "RequestIdHeader": {
        "name": "X-Request-Id",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 128
        },
        "description": "Optional caller-supplied request correlation ID. Echoed in responses and audit logs."
      },
      "AgentIdPath": {
        "name": "agent_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "CampaignIdPath": {
        "name": "campaign_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "ContactIdPath": {
        "name": "contact_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "GroupIdPath": {
        "name": "group_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "RunIdPath": {
        "name": "run_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "ConversationIdPath": {
        "name": "conversation_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed JSON, missing header, or invalid query parameter.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, invalid, expired, or revoked API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Authenticated key lacks scope or workspace access.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found within allowed company/workspace scope.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Conflict": {
        "description": "Idempotency conflict, duplicate resource, or terminal run cannot be cancelled.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unprocessable": {
        "description": "Semantic validation failure with field-level details.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded. Retry after the Retry-After header.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "EnvelopeMeta": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string"
          },
          "rate_limit": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer"
              },
              "remaining": {
                "type": "integer"
              },
              "reset_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "PageMeta": {
        "allOf": [
          {
            "$ref": "#/components/schemas/EnvelopeMeta"
          },
          {
            "type": "object",
            "properties": {
              "next_cursor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "has_more": {
                "type": "boolean"
              }
            }
          }
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "examples": [
                  "forbidden_scope"
                ]
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "additionalProperties": true
              },
              "request_id": {
                "type": "string"
              }
            }
          }
        }
      },
      "WhoamiResponse": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "company_id",
              "key_id",
              "scopes",
              "workspace_access"
            ],
            "properties": {
              "company_id": {
                "type": "string"
              },
              "organization_id": {
                "type": "string"
              },
              "key_id": {
                "type": "string"
              },
              "key_prefix": {
                "type": "string"
              },
              "environment": {
                "type": "string",
                "enum": [
                  "production",
                  "development",
                  "test"
                ]
              },
              "scopes": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Scope"
                }
              },
              "workspace_access": {
                "type": "string",
                "enum": [
                  "all_current_and_future",
                  "selected_workspaces",
                  "default_workspace_only"
                ]
              },
              "workspace_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "workspace_count": {
                "type": "integer",
                "minimum": 0
              },
              "default_workspace_id": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "Scope": {
        "type": "string",
        "enum": [
          "workspaces:read",
          "workspaces:write",
          "agents:read",
          "agents:write",
          "agents:run",
          "contacts:read",
          "contacts:write",
          "contact_groups:read",
          "contact_groups:write",
          "campaigns:read",
          "campaigns:write",
          "campaigns:run",
          "inbox_automation:read",
          "inbox_automation:write",
          "inbox_automation:run",
          "runs:read",
          "runs:cancel",
          "data:read"
        ]
      },
      "YouTubeVideoError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "YouTubeVideo": {
        "type": "object",
        "description": "Public per-video YouTube metrics scraped from the watch page.",
        "properties": {
          "video_id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "duration_seconds": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Null for live streams and upcoming premieres."
          },
          "views": {
            "type": [
              "integer",
              "null"
            ]
          },
          "likes": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Null when the creator hides likes (see likes_hidden)."
          },
          "likes_hidden": {
            "type": "boolean"
          },
          "comments": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Approximate in v1 (derived from the abbreviated label); see comments_exact."
          },
          "comments_abbrev": {
            "type": [
              "string",
              "null"
            ],
            "description": "Human string as YouTube shows it, e.g. \"1.2K\"."
          },
          "comments_exact": {
            "type": "boolean",
            "description": "False in v1 — exact comment counts are a later phase."
          },
          "comments_disabled": {
            "type": "boolean"
          },
          "paid_promotion": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Tri-state: true/false when determinable on an OK page, null when unknown."
          },
          "playability_status": {
            "type": [
              "string",
              "null"
            ]
          },
          "playability_reason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why a non-OK page is limited, e.g. \"Sign in to confirm your age\"."
          },
          "is_live": {
            "type": "boolean"
          },
          "is_upcoming": {
            "type": "boolean"
          },
          "parse_ok": {
            "type": "boolean"
          },
          "fetched_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "cached": {
            "type": "boolean",
            "description": "True when served from cache, false when freshly scraped."
          },
          "input": {
            "type": "string",
            "description": "Present only on an error item whose input could not be resolved to a video id."
          },
          "error": {
            "$ref": "#/components/schemas/YouTubeVideoError"
          }
        }
      },
      "YouTubeVideoLookupResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "videos": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/YouTubeVideo"
                }
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "Workspace": {
        "type": "object",
        "required": [
          "id",
          "workspace_id",
          "company_id",
          "organization_id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "company_id": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "is_default": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_goal": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_communication_style": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "WorkspaceListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Workspace"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "AgentStatus": {
        "type": "string",
        "enum": [
          "idle",
          "running",
          "paused",
          "draft",
          "completed",
          "failed"
        ]
      },
      "Agent": {
        "type": "object",
        "required": [
          "id",
          "workspace_id",
          "name",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/AgentStatus"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "goal": {
            "type": [
              "string",
              "null"
            ]
          },
          "criteria": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "discovery_platforms": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "x",
                "youtube",
                "tiktok",
                "linkedin"
              ]
            }
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "generate_reply_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "rejection_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_run_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "next_run_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "run_interval_minutes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "auto_run": {
            "type": "boolean",
            "description": "Present on create responses; true when the initial discovery run was queued."
          },
          "run_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Public API run id for the initial discovery run when auto_run is true."
          },
          "leads_per_run": {
            "type": "integer",
            "minimum": 5,
            "maximum": 200
          },
          "discovery_backend": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "legacy",
              "desearch",
              "shadow",
              null
            ],
            "description": "Read-only. Discovery backend override for this agent; null uses the workspace or platform default."
          },
          "monthly_spend_limit_usd": {
            "type": [
              "number",
              "null"
            ],
            "description": "The agent's monthly spending limit in US dollars; null means none."
          },
          "spent_this_month_usd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Read-only, only on GET /v1/agents/{agent_id}: lead charges this calendar month (UTC) plus what open searches may still charge, in US dollars."
          },
          "blocked_reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "insufficient_credits",
              "missing_linkedin_connected_account",
              "missing_linkedin_search_capable_account",
              "monthly_limit_reached",
              "no_runnable_platforms",
              "payment_past_due",
              "subscription_inactive",
              "trial_expired",
              null
            ],
            "description": "Read-only. Why scheduled runs are paused until someone acts: insufficient_credits means the workspace balance is empty, monthly_limit_reached means the agent hit monthly_spend_limit_usd. null when not paused."
          }
        }
      },
      "AgentListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Agent"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "AgentResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Agent"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "AgentRunRequest": {
        "type": "object",
        "required": [
          "workspace_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "dry_run": {
            "type": "boolean",
            "default": false
          },
          "inputs": {
            "type": "object",
            "additionalProperties": true
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          },
          "contact_group_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "callback_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ContactIdentity": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string",
            "examples": [
              "x",
              "instagram"
            ]
          },
          "handle": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "profile_url": {
            "type": "string",
            "format": "uri"
          },
          "external_id": {
            "type": "string"
          },
          "instagram_username": {
            "type": "string",
            "maxLength": 31,
            "description": "Explicit Instagram username; optional leading @ is normalized. Can be attached to a contact whose primary platform is different."
          },
          "instagram_url": {
            "type": "string",
            "format": "uri",
            "description": "HTTPS Instagram profile URL with exactly one username path segment."
          },
          "platform_user_id": {
            "type": "string",
            "pattern": "^[0-9]+$",
            "description": "Numeric Instagram provider identity as a string. Accepted only for platform=instagram."
          }
        }
      },
      "Contact": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContactIdentity"
          },
          {
            "type": "object",
            "required": [
              "id",
              "workspace_id",
              "platform"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "workspace_id": {
                "type": "string"
              },
              "agent_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "contact_group_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status": {
                "type": "string"
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "metadata": {
                "type": "object",
                "additionalProperties": true
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "ContactUpsertRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContactIdentity"
          },
          {
            "type": "object",
            "required": [
              "workspace_id",
              "platform"
            ],
            "properties": {
              "workspace_id": {
                "type": "string"
              },
              "agent_id": {
                "type": "string"
              },
              "contact_group_id": {
                "type": "string"
              },
              "contact_group": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "bio": {
                "type": "string"
              },
              "website": {
                "type": "string",
                "format": "uri"
              },
              "location": {
                "type": "string"
              },
              "followers": {
                "type": "integer"
              },
              "following": {
                "type": "integer"
              },
              "avatar_url": {
                "type": "string",
                "format": "uri"
              },
              "linkedin_url": {
                "type": "string",
                "format": "uri"
              },
              "twitter_url": {
                "type": "string",
                "format": "uri"
              },
              "position": {
                "type": "string"
              },
              "skills": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "metadata": {
                "type": "object",
                "additionalProperties": true
              },
              "upsert": {
                "type": "boolean",
                "default": true
              }
            }
          }
        ]
      },
      "ContactPatchRequest": {
        "type": "object",
        "required": [
          "workspace_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "contact_group_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "contact_group": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ContactPatchByBodyRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContactPatchRequest"
          },
          {
            "type": "object",
            "required": [
              "contact_id"
            ],
            "properties": {
              "contact_id": {
                "type": "string"
              }
            }
          }
        ]
      },
      "ContactBulkRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "contacts"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "agent_id": {
            "type": "string"
          },
          "contact_group_id": {
            "type": "string"
          },
          "contact_group": {
            "type": "string"
          },
          "dedupe_strategy": {
            "type": "string",
            "enum": [
              "identity",
              "external_id",
              "none"
            ],
            "default": "identity"
          },
          "upsert": {
            "type": "boolean",
            "default": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "contacts": {
            "type": "array",
            "minItems": 1,
            "maxItems": 1000,
            "items": {
              "$ref": "#/components/schemas/ContactUpsertRequest"
            }
          }
        }
      },
      "ContactListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "ContactResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Contact"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "BulkImportResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "run_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/components/schemas/RunStatus"
              },
              "accepted": {
                "type": "integer"
              },
              "rejected": {
                "type": "integer"
              },
              "errors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "ContactGroup": {
        "type": "object",
        "required": [
          "id",
          "workspace_id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "contact_count": {
            "type": "integer"
          }
        }
      },
      "ContactGroupCreateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "external_id": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ContactGroupListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactGroup"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "ContactGroupResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ContactGroup"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "GroupMembershipAddRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "contact_ids"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "contact_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "maxItems": 1000
          }
        }
      },
      "GroupMembershipResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "group_id": {
                "type": "string"
              },
              "added": {
                "type": "integer"
              },
              "removed": {
                "type": "integer"
              },
              "skipped": {
                "type": "integer"
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "CampaignStatus": {
        "type": "string",
        "enum": [
          "draft",
          "scheduled",
          "running",
          "paused",
          "completed",
          "failed",
          "archived"
        ]
      },
      "Campaign": {
        "type": "object",
        "required": [
          "id",
          "workspace_id",
          "name",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "dm",
              "x",
              "email",
              "linkedin",
              "telegram",
              "whatsapp",
              "instagram"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/CampaignStatus"
          },
          "contact_group_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "steps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CampaignStep"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "audience": {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "groups",
                  "dynamic_groups",
                  "all_contacts",
                  "contacts",
                  "api_materialized"
                ]
              },
              "include_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "include_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "filters": {
                "type": "object",
                "additionalProperties": true
              },
              "suppression": {
                "type": "object",
                "properties": {
                  "exclude_previous_campaign_targets": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_existing_conversations": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_replied_contacts": {
                    "type": "boolean",
                    "default": true
                  }
                },
                "additionalProperties": true
              },
              "materialization": {
                "type": "object",
                "properties": {
                  "strategy": {
                    "type": "string",
                    "enum": [
                      "snapshot",
                      "none"
                    ],
                    "default": "snapshot"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          },
          "connected_account_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "email_account_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "CampaignStep": {
        "type": "object",
        "required": [
          "order",
          "channel",
          "body"
        ],
        "properties": {
          "order": {
            "type": "integer"
          },
          "channel": {
            "type": "string",
            "enum": [
              "x_dm",
              "email",
              "linkedin_dm"
            ]
          },
          "body": {
            "type": "string"
          },
          "delay_hours": {
            "type": "integer"
          }
        }
      },
      "CampaignCreateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "type"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "dm",
              "x",
              "email",
              "linkedin",
              "telegram",
              "whatsapp",
              "instagram"
            ]
          },
          "agent_id": {
            "type": "string"
          },
          "contact_group_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "steps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CampaignStep"
            }
          },
          "schedule": {
            "type": "object",
            "additionalProperties": true
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "connected_account_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "email_account_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "contact_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "include_already_contacted": {
            "type": "boolean",
            "default": false
          },
          "include_previous_campaign_targets": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "LinkedInCampaignCreateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "linkedin_account_id",
          "audience"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "linkedin_account_id": {
            "type": "string",
            "description": "Connected LinkedIn sender account. connected_account_id is accepted as a compatibility alias by the API."
          },
          "connected_account_id": {
            "type": "string",
            "description": "Compatibility alias for linkedin_account_id."
          },
          "audience": {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "groups",
                  "dynamic_groups",
                  "all_contacts",
                  "contacts",
                  "api_materialized"
                ]
              },
              "include_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "include_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "filters": {
                "type": "object",
                "additionalProperties": true
              },
              "suppression": {
                "type": "object",
                "properties": {
                  "exclude_previous_campaign_targets": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_existing_conversations": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_replied_contacts": {
                    "type": "boolean",
                    "default": true
                  }
                },
                "additionalProperties": true
              },
              "materialization": {
                "type": "object",
                "properties": {
                  "strategy": {
                    "type": "string",
                    "enum": [
                      "snapshot",
                      "none"
                    ],
                    "default": "snapshot"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "order": {
                  "type": "integer"
                },
                "body": {
                  "type": "string"
                },
                "delay_hours": {
                  "type": "integer"
                }
              },
              "additionalProperties": true
            },
            "description": "LinkedIn message/note steps. Optional when linkedin_action=connection_request_only because no message or note is sent."
          },
          "schedule": {
            "type": "object",
            "additionalProperties": true
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "linkedin_action": {
            "type": "string",
            "enum": [
              "message",
              "connection_request_only",
              "connection_request_with_note",
              "connection_request_then_followup"
            ],
            "default": "message",
            "description": "LinkedIn send mode. Use connection_request_only for invites with no note and no follow-up DM; steps can be omitted in that mode."
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "generation_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "goal": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_context": {
            "type": [
              "string",
              "null"
            ]
          },
          "include_already_contacted": {
            "type": "boolean",
            "default": false
          },
          "include_previous_campaign_targets": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "CampaignPatchRequest": {
        "type": "object",
        "required": [
          "workspace_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/CampaignStatus"
          },
          "contact_group_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "schedule": {
            "type": "object",
            "additionalProperties": true
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "include_already_contacted": {
            "type": "boolean",
            "default": false
          },
          "include_previous_campaign_targets": {
            "type": "boolean",
            "default": false
          }
        },
        "description": "Patch the listed campaign configuration fields. The current handler does not update steps or sender accounts; recreate an inactive draft to change those."
      },
      "CampaignPatchByBodyRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CampaignPatchRequest"
          },
          {
            "type": "object",
            "required": [
              "campaign_id"
            ],
            "properties": {
              "campaign_id": {
                "type": "string"
              }
            }
          }
        ]
      },
      "CampaignListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Campaign"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "CampaignResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Campaign"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "CampaignPreviewRequest": {
        "type": "object",
        "required": [
          "workspace_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          },
          "contact_group_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "contact_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sample_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "CampaignPreviewResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "campaign_id": {
                "type": "string"
              },
              "dry_run": {
                "type": "boolean",
                "const": true
              },
              "eligible_contacts": {
                "type": "integer"
              },
              "sample_messages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "contact_id": {
                      "type": "string"
                    },
                    "step_order": {
                      "type": "integer"
                    },
                    "body": {
                      "type": "string"
                    }
                  }
                }
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "CampaignRunRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "dry_run"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "dry_run": {
            "type": "boolean",
            "description": "Must be explicitly present. Use true for validation-only runs."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          },
          "contact_group_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "contact_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "callback_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "RunStatus": {
        "type": "string",
        "enum": [
          "queued",
          "running",
          "succeeded",
          "failed",
          "cancelled",
          "timed_out"
        ]
      },
      "Run": {
        "type": "object",
        "required": [
          "id",
          "workspace_id",
          "type",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "agent",
              "campaign",
              "batch",
              "contact_import"
            ]
          },
          "resource_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/RunStatus"
          },
          "dry_run": {
            "type": "boolean"
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "counts": {
            "type": "object",
            "properties": {
              "accepted": {
                "type": "integer"
              },
              "processed": {
                "type": "integer"
              },
              "created": {
                "type": "integer"
              },
              "updated": {
                "type": "integer"
              },
              "sent": {
                "type": "integer"
              },
              "failed": {
                "type": "integer"
              },
              "agent_run_id": {
                "type": "string"
              },
              "discovery_backend": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "legacy",
                  "desearch",
                  "mixed",
                  "shadow",
                  null
                ]
              },
              "leads_stored": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "New contacts this run added."
              },
              "contacts_inserted": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "contacts_linked": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "contacts_refreshed": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            }
          },
          "error": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "agent_run_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "For agent runs: the Lead Agent run this run follows. The run stays running until that agent run finishes."
          }
        }
      },
      "RunAcceptedResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Run"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "BatchRunItem": {
        "type": "object",
        "required": [
          "type",
          "id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "agent",
              "campaign"
            ]
          },
          "id": {
            "type": "string"
          },
          "inputs": {
            "type": "object",
            "additionalProperties": true
          },
          "limit": {
            "type": "integer"
          },
          "dry_run": {
            "type": "boolean"
          },
          "contact_group_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "BatchRunRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "items"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "dry_run": {
            "type": "boolean",
            "default": true
          },
          "concurrency": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 2
          },
          "stop_on_error": {
            "type": "boolean",
            "default": false
          },
          "callback_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/BatchRunItem"
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "BatchRunAcceptedResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "run_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/components/schemas/RunStatus"
              },
              "item_run_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "RunResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Run"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "LogLevel": {
        "type": "string",
        "enum": [
          "debug",
          "info",
          "warn",
          "error"
        ]
      },
      "RunLog": {
        "type": "object",
        "required": [
          "id",
          "run_id",
          "level",
          "message",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "run_id": {
            "type": "string"
          },
          "level": {
            "$ref": "#/components/schemas/LogLevel"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RunLogListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RunLog"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "CancelRunRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "reason"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "reason": {
            "type": "string",
            "minLength": 3
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "Conversation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "workspace_id": {
            "type": "string"
          },
          "contact_id": {
            "type": "string",
            "nullable": true
          },
          "platform": {
            "type": "string"
          },
          "read_status": {
            "type": "string",
            "nullable": true
          },
          "is_request": {
            "type": "boolean"
          },
          "needs_backfill": {
            "type": "boolean"
          },
          "last_message_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "last_message": {
            "$ref": "#/components/schemas/Message"
          },
          "lead": {
            "type": "object",
            "nullable": true
          }
        }
      },
      "ConversationListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Conversation"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "conversation_id": {
            "type": "string"
          },
          "direction": {
            "type": "string",
            "enum": [
              "inbound",
              "outbound"
            ]
          },
          "body": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "attachment_url": {
            "type": "string",
            "nullable": true
          },
          "x_event_id": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MessageListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "ConversationMessageCreateRequest": {
        "type": "object",
        "required": [
          "body"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "body": {
            "type": "string",
            "minLength": 1,
            "maxLength": 8000
          },
          "text": {
            "type": "string",
            "deprecated": true
          },
          "send": {
            "type": "boolean",
            "default": true
          },
          "subject": {
            "type": "string",
            "description": "Required for email sends."
          },
          "to_email": {
            "type": "string",
            "format": "email",
            "description": "Optional override for email recipient."
          },
          "body_html": {
            "type": "string"
          },
          "track_opens": {
            "type": "boolean",
            "default": false
          },
          "track_clicks": {
            "type": "boolean",
            "default": false
          },
          "skip_automation_review": {
            "type": "boolean",
            "default": false,
            "description": "Skip the automatic review trigger after this message."
          }
        },
        "description": "Text-only endpoint for email, LinkedIn, Telegram, WhatsApp and Instagram. X live sends currently return 422 unsupported_platform. send=false creates a draft. Outgoing media fields return 422 unsupported_media. Instagram is limited to 1000 characters; other accepted messages to 8000. Provider gates, account state, group restrictions, and limits apply."
      },
      "MessageResponse": {
        "type": "object",
        "properties": {
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Message"
              }
            ],
            "type": "object"
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "InboxAutomationPolicy": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string",
            "enum": [
              "all",
              "email",
              "x",
              "linkedin",
              "telegram",
              "whatsapp",
              "instagram"
            ]
          },
          "account_kind": {
            "type": "string",
            "enum": [
              "workspace",
              "email",
              "connected"
            ]
          },
          "account_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "mode": {
            "type": "string",
            "enum": [
              "off",
              "monitor",
              "suggest",
              "auto_reply"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "max_replies_per_hour": {
            "type": "integer"
          },
          "max_replies_per_day": {
            "type": "integer"
          },
          "business_timezone": {
            "type": "string"
          },
          "business_hour_start": {
            "type": "integer"
          },
          "business_hour_end": {
            "type": "integer"
          },
          "min_confidence": {
            "type": "number"
          },
          "require_review_below_confidence": {
            "type": "number"
          },
          "safety": {
            "type": "object"
          },
          "prompt_context": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "InboxAutomationPolicyUpsertRequest": {
        "type": "object",
        "required": [
          "workspace_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string",
            "enum": [
              "all",
              "email",
              "x",
              "linkedin",
              "telegram",
              "whatsapp",
              "instagram"
            ]
          },
          "account_kind": {
            "type": "string",
            "enum": [
              "workspace",
              "email",
              "connected"
            ]
          },
          "account_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "mode": {
            "type": "string",
            "enum": [
              "off",
              "monitor",
              "suggest",
              "auto_reply"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "max_replies_per_hour": {
            "type": "integer"
          },
          "max_replies_per_day": {
            "type": "integer"
          },
          "business_timezone": {
            "type": "string"
          },
          "business_hour_start": {
            "type": "integer"
          },
          "business_hour_end": {
            "type": "integer"
          },
          "min_confidence": {
            "type": "number"
          },
          "require_review_below_confidence": {
            "type": "number"
          },
          "safety": {
            "type": "object"
          },
          "prompt_context": {
            "type": "string"
          }
        }
      },
      "InboxAutomationCandidate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "policy_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "run_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "conversation_id": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "x",
              "linkedin",
              "telegram",
              "whatsapp",
              "instagram"
            ]
          },
          "account_kind": {
            "type": "string",
            "enum": [
              "workspace",
              "email",
              "connected"
            ]
          },
          "account_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "drafted",
              "approved",
              "sent",
              "skipped",
              "failed",
              "dismissed"
            ]
          },
          "classification": {
            "type": "string",
            "enum": [
              "meeting_request",
              "pricing_question",
              "resource_request",
              "positive_interest",
              "objection",
              "support_request",
              "negative_reply",
              "opt_out",
              "out_of_office",
              "bounce",
              "acknowledgement",
              "ambiguous",
              "unknown"
            ]
          },
          "decision": {
            "type": "string",
            "enum": [
              "reply_needed",
              "no_reply_needed",
              "review_required",
              "unsafe"
            ]
          },
          "confidence": {
            "type": "number"
          },
          "conversation_summary": {
            "type": "string",
            "nullable": true
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "proposed_reply": {
            "type": "string",
            "nullable": true
          },
          "safety_flags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "metadata": {
            "type": "object"
          }
        }
      },
      "InboxAutomationRunRequest": {
        "type": "object",
        "properties": {
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "dry_run": {
            "type": "boolean",
            "default": true
          },
          "channel": {
            "type": "string",
            "enum": [
              "all",
              "email",
              "x",
              "linkedin",
              "telegram",
              "whatsapp",
              "instagram"
            ]
          },
          "account_id": {
            "type": "string",
            "format": "uuid"
          },
          "max_conversations": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          }
        }
      },
      "InboxAutomationRunResponse": {
        "type": "object",
        "properties": {
          "run": {
            "type": "object"
          },
          "candidates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InboxAutomationCandidate"
            }
          }
        }
      },
      "InboxAutomationCandidatePatchRequest": {
        "type": "object",
        "properties": {
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string"
          },
          "proposed_reply": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "metadata": {
            "type": "object"
          }
        }
      },
      "InboxAutomationSendRequest": {
        "type": "object",
        "properties": {
          "workspace_id": {
            "type": "string",
            "format": "uuid"
          },
          "body": {
            "type": "string"
          },
          "send": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "InboxAutomationPolicyListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InboxAutomationPolicy"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "InboxAutomationPolicyResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/InboxAutomationPolicy"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "InboxAutomationCandidateListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InboxAutomationCandidate"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PageMeta"
          }
        }
      },
      "InboxAutomationCandidateResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/InboxAutomationCandidate"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "InboxAutomationRunEnvelopeResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/InboxAutomationRunResponse"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "AgentCreateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "goal": {
            "type": [
              "string",
              "null"
            ]
          },
          "criteria": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "discovery_platforms": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "x",
                "youtube",
                "tiktok",
                "linkedin"
              ]
            }
          },
          "source": {
            "type": "string",
            "description": "Convenience alias for one discovery platform, e.g. x or linkedin."
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "generate_reply_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "rejection_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/AgentStatus",
            "description": "Optional override. If omitted, create defaults to running with next_run_at set immediately. A non-running status disables auto-run."
          },
          "run_interval_minutes": {
            "type": "integer",
            "minimum": 15,
            "maximum": 10080,
            "description": "Recurring discovery interval. When omitted: 1440 (daily) if the agent's platforms run on Desearch People Search, otherwise 30 minutes."
          },
          "auto_run": {
            "type": "boolean",
            "default": true,
            "description": "Defaults to true to match UI creation. Set false to create without starting the first discovery run."
          },
          "manual_only": {
            "type": "boolean",
            "default": false,
            "description": "Alias for auto_run=false; creates the agent without starting or scheduling the first run."
          },
          "leads_per_run": {
            "type": "integer",
            "minimum": 5,
            "maximum": 200,
            "description": "Qualified people requested per People Search run, 5–200; defaults to 25 and is lowered when the workspace balance or the agent's monthly spending limit covers fewer. Backend selection is server-managed."
          },
          "monthly_spend_limit_usd": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 1,
            "maximum": 10000,
            "description": "Most this agent's lead charges may cost in a calendar month (UTC), in US dollars, $1–$10,000. When it is reached the agent pauses until the 1st of next month; raising it resumes the agent. null removes the limit. Also accepted on PATCH /v1/agents/{agent_id}."
          }
        }
      },
      "AgentUpdateRequest": {
        "type": "object",
        "required": [
          "workspace_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "goal": {
            "type": [
              "string",
              "null"
            ]
          },
          "criteria": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "discovery_platforms": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "x",
                "youtube",
                "tiktok",
                "linkedin"
              ]
            }
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "generate_reply_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "rejection_prompt": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/AgentStatus"
          },
          "run_interval_minutes": {
            "type": "integer",
            "minimum": 15,
            "maximum": 10080
          },
          "leads_per_run": {
            "type": "integer",
            "minimum": 5,
            "maximum": 200,
            "description": "Qualified people requested per People Search run, 5–200; defaults to 25 and is lowered when the workspace balance or the agent's monthly spending limit covers fewer. Backend selection is server-managed."
          },
          "monthly_spend_limit_usd": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 1,
            "maximum": 10000,
            "description": "Most this agent's lead charges may cost in a calendar month (UTC), in US dollars, $1–$10,000. When it is reached the agent pauses until the 1st of next month; raising it resumes the agent. null removes the limit. Also accepted on PATCH /v1/agents/{agent_id}."
          }
        }
      },
      "WorkspaceResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Workspace"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "WorkspacePatchRequest": {
        "type": "object",
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "Required when using the collection PATCH shorthand instead of the path parameter."
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_goal": {
            "type": [
              "string",
              "null"
            ],
            "description": "Workspace-level outreach goal used by agents and campaign drafting."
          },
          "goal": {
            "type": [
              "string",
              "null"
            ],
            "deprecated": true,
            "description": "Alias for ai_goal."
          },
          "ai_communication_style": {
            "type": [
              "string",
              "null"
            ],
            "description": "Workspace-level communication style used by agents and campaign drafting."
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ],
            "deprecated": true,
            "description": "Alias for ai_communication_style."
          }
        },
        "additionalProperties": false
      },
      "Company": {
        "type": "object",
        "required": [
          "id",
          "company_id",
          "organization_id",
          "name",
          "workspace_count"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "company_id": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "default_workspace_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "workspace_access": {
            "type": "string",
            "enum": [
              "all_current_and_future",
              "selected_workspaces",
              "default_workspace_only"
            ]
          },
          "workspace_count": {
            "type": "integer",
            "minimum": 0
          },
          "workspace_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "workspaces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Workspace"
            }
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "CompanyResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Company"
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "CompanyPatchRequest": {
        "type": "object",
        "properties": {
          "company_id": {
            "type": "string",
            "description": "Optional guard. Must match the authenticated company when provided."
          },
          "name": {
            "type": "string"
          },
          "company_name": {
            "type": "string",
            "deprecated": true,
            "description": "Alias for name."
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "company_description": {
            "type": [
              "string",
              "null"
            ],
            "deprecated": true,
            "description": "Alias for description."
          },
          "company": {
            "type": "object",
            "additionalProperties": true,
            "description": "Nested compatibility object with name/description."
          }
        },
        "additionalProperties": false
      },
      "OnboardingWebsiteAnalysisRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "website_url": {
            "type": "string",
            "format": "uri",
            "deprecated": true
          },
          "website": {
            "type": "string",
            "deprecated": true
          }
        },
        "additionalProperties": false
      },
      "OnboardingBusinessProfile": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "website_url": {
            "type": "string"
          },
          "company_name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "positioning": {
            "type": "string"
          },
          "target_customers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pain_points": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "value_props": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "workspace_name": {
            "type": "string"
          },
          "workspace_description": {
            "type": "string"
          },
          "ai_goal": {
            "type": "string"
          },
          "communication_style": {
            "type": "string"
          },
          "recommended_agent": {
            "type": "object",
            "additionalProperties": true
          },
          "recommended_campaign": {
            "type": "object",
            "additionalProperties": true
          },
          "next_questions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "OnboardingWebsiteAnalysisResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "analysis": {
                "$ref": "#/components/schemas/OnboardingBusinessProfile"
              },
              "source": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "OnboardingReadinessResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "workspace": {
                "$ref": "#/components/schemas/Workspace"
              },
              "company": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Company"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "readiness_score": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "is_empty_account": {
                "type": "boolean"
              },
              "counts": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                }
              },
              "sender_inventory": {
                "type": "object",
                "additionalProperties": true
              },
              "missing": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "next_actions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "safety": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "OnboardingSetupRequest": {
        "type": "object",
        "required": [
          "workspace_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "dry_run": {
            "type": "boolean",
            "default": false
          },
          "business_profile": {
            "$ref": "#/components/schemas/OnboardingBusinessProfile"
          },
          "analysis": {
            "$ref": "#/components/schemas/OnboardingBusinessProfile"
          },
          "company": {
            "$ref": "#/components/schemas/CompanyPatchRequest"
          },
          "workspace": {
            "$ref": "#/components/schemas/WorkspacePatchRequest"
          }
        },
        "additionalProperties": false
      },
      "OnboardingSetupResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "dry_run": {
                "type": "boolean"
              },
              "applied": {
                "type": "boolean"
              },
              "company_patch": {
                "type": "object",
                "additionalProperties": true
              },
              "workspace_patch": {
                "type": "object",
                "additionalProperties": true
              },
              "company": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Company"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "workspace": {
                "$ref": "#/components/schemas/Workspace"
              },
              "next_actions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "meta": {
            "$ref": "#/components/schemas/EnvelopeMeta"
          }
        }
      },
      "WhatsAppCampaignCreateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "whatsapp_account_id",
          "audience"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "connected_account_id": {
            "type": "string",
            "description": "Compatibility alias for whatsapp_account_id."
          },
          "audience": {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "groups",
                  "dynamic_groups",
                  "all_contacts",
                  "contacts",
                  "api_materialized"
                ]
              },
              "include_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "include_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "filters": {
                "type": "object",
                "additionalProperties": true
              },
              "suppression": {
                "type": "object",
                "properties": {
                  "exclude_previous_campaign_targets": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_existing_conversations": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_replied_contacts": {
                    "type": "boolean",
                    "default": true
                  }
                },
                "additionalProperties": true
              },
              "materialization": {
                "type": "object",
                "properties": {
                  "strategy": {
                    "type": "string",
                    "enum": [
                      "snapshot",
                      "none"
                    ],
                    "default": "snapshot"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "order": {
                  "type": "integer"
                },
                "body": {
                  "type": "string"
                },
                "delay_hours": {
                  "type": "integer"
                }
              },
              "additionalProperties": true
            },
            "description": "Text message steps; WhatsApp sends require enabled server rollout flags and account limits."
          },
          "schedule": {
            "type": "object",
            "additionalProperties": true
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "whatsapp_account_id": {
            "type": "string",
            "description": "Connected WhatsApp sender account in the same company. connected_account_id is accepted as an alias."
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "generation_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "goal": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_context": {
            "type": [
              "string",
              "null"
            ]
          },
          "include_already_contacted": {
            "type": "boolean",
            "default": false
          },
          "include_previous_campaign_targets": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "InstagramCampaignCreateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "instagram_account_id",
          "audience"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "connected_account_id": {
            "type": "string",
            "description": "Compatibility alias for instagram_account_id."
          },
          "audience": {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "groups",
                  "dynamic_groups",
                  "all_contacts",
                  "contacts",
                  "api_materialized"
                ]
              },
              "include_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "include_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "filters": {
                "type": "object",
                "additionalProperties": true
              },
              "suppression": {
                "type": "object",
                "properties": {
                  "exclude_previous_campaign_targets": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_existing_conversations": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_replied_contacts": {
                    "type": "boolean",
                    "default": true
                  }
                },
                "additionalProperties": true
              },
              "materialization": {
                "type": "object",
                "properties": {
                  "strategy": {
                    "type": "string",
                    "enum": [
                      "snapshot",
                      "none"
                    ],
                    "default": "snapshot"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "order": {
                  "type": "integer"
                },
                "body": {
                  "type": "string"
                },
                "delay_hours": {
                  "type": "integer"
                }
              },
              "additionalProperties": true
            },
            "description": "Text message steps; Instagram sends require enabled server rollout flags and account limits."
          },
          "schedule": {
            "type": "object",
            "additionalProperties": true
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "instagram_account_id": {
            "type": "string",
            "description": "Connected Instagram sender account in the same company. connected_account_id is accepted as an alias."
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "generation_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "goal": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_context": {
            "type": [
              "string",
              "null"
            ]
          },
          "include_already_contacted": {
            "type": "boolean",
            "default": false
          },
          "include_previous_campaign_targets": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "TelegramCampaignCreateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "telegram_account_id",
          "audience"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "connected_account_id": {
            "type": "string",
            "description": "Compatibility alias for telegram_account_id."
          },
          "audience": {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "groups",
                  "dynamic_groups",
                  "all_contacts",
                  "contacts",
                  "api_materialized"
                ]
              },
              "include_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "include_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "filters": {
                "type": "object",
                "additionalProperties": true
              },
              "suppression": {
                "type": "object",
                "properties": {
                  "exclude_previous_campaign_targets": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_existing_conversations": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_replied_contacts": {
                    "type": "boolean",
                    "default": true
                  }
                },
                "additionalProperties": true
              },
              "materialization": {
                "type": "object",
                "properties": {
                  "strategy": {
                    "type": "string",
                    "enum": [
                      "snapshot",
                      "none"
                    ],
                    "default": "snapshot"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "order": {
                  "type": "integer"
                },
                "body": {
                  "type": "string"
                },
                "delay_hours": {
                  "type": "integer"
                }
              },
              "additionalProperties": true
            },
            "description": "Text message steps. Supported template variables are the same as other campaign channels."
          },
          "schedule": {
            "type": "object",
            "additionalProperties": true
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "telegram_account_id": {
            "type": "string",
            "description": "Active Telegram sender account in the same company. connected_account_id is accepted as an alias."
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "generation_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "goal": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_context": {
            "type": [
              "string",
              "null"
            ]
          },
          "include_already_contacted": {
            "type": "boolean",
            "default": false
          },
          "include_previous_campaign_targets": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "XDMCampaignCreateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "x_account_id",
          "audience"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "audience": {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "groups",
                  "dynamic_groups",
                  "all_contacts",
                  "contacts",
                  "api_materialized"
                ]
              },
              "include_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "include_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "filters": {
                "type": "object",
                "additionalProperties": true
              },
              "suppression": {
                "type": "object",
                "properties": {
                  "exclude_previous_campaign_targets": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_existing_conversations": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_replied_contacts": {
                    "type": "boolean",
                    "default": true
                  }
                },
                "additionalProperties": true
              },
              "materialization": {
                "type": "object",
                "properties": {
                  "strategy": {
                    "type": "string",
                    "enum": [
                      "snapshot",
                      "none"
                    ],
                    "default": "snapshot"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "order": {
                  "type": "integer"
                },
                "body": {
                  "type": "string"
                },
                "delay_hours": {
                  "type": "integer"
                }
              },
              "additionalProperties": true
            },
            "description": "Text message steps. Supported template variables are the same as other campaign channels."
          },
          "schedule": {
            "type": "object",
            "additionalProperties": true
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "x_account_id": {
            "type": "string"
          },
          "connected_account_id": {
            "type": "string",
            "description": "Alias for x_account_id."
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "generation_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "goal": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_context": {
            "type": [
              "string",
              "null"
            ]
          },
          "include_already_contacted": {
            "type": "boolean",
            "default": false
          },
          "include_previous_campaign_targets": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "EmailCampaignCreateRequest": {
        "type": "object",
        "required": [
          "workspace_id",
          "name",
          "email_account_ids",
          "audience"
        ],
        "properties": {
          "workspace_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "audience": {
            "type": "object",
            "required": [
              "mode"
            ],
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "groups",
                  "dynamic_groups",
                  "all_contacts",
                  "contacts",
                  "api_materialized"
                ]
              },
              "include_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_group_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "include_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "exclude_contact_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "filters": {
                "type": "object",
                "additionalProperties": true
              },
              "suppression": {
                "type": "object",
                "properties": {
                  "exclude_previous_campaign_targets": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_existing_conversations": {
                    "type": "boolean",
                    "default": true
                  },
                  "exclude_replied_contacts": {
                    "type": "boolean",
                    "default": true
                  }
                },
                "additionalProperties": true
              },
              "materialization": {
                "type": "object",
                "properties": {
                  "strategy": {
                    "type": "string",
                    "enum": [
                      "snapshot",
                      "none"
                    ],
                    "default": "snapshot"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "order": {
                  "type": "integer"
                },
                "body": {
                  "type": "string"
                },
                "delay_hours": {
                  "type": "integer"
                },
                "subject": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            },
            "description": "Text message steps. Supported template variables are the same as other campaign channels."
          },
          "schedule": {
            "type": "object",
            "additionalProperties": true
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "email_account_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1
          },
          "communication_style": {
            "type": [
              "string",
              "null"
            ]
          },
          "generation_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "goal": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_context": {
            "type": [
              "string",
              "null"
            ]
          },
          "include_already_contacted": {
            "type": "boolean",
            "default": false
          },
          "include_previous_campaign_targets": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "CampaignTarget": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "campaign_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "contact_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_event_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "contact": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Contact"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "CampaignEmailEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "campaign_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "target_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "message_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "contact_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "tracking_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "event_type": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "CampaignSummary": {
        "type": "object",
        "properties": {
          "campaign": {
            "$ref": "#/components/schemas/Campaign"
          },
          "target_status_counts": {
            "type": "object",
            "additionalProperties": true
          },
          "email_event_counts": {
            "type": "object",
            "additionalProperties": true
          },
          "delivery_usage_counts": {
            "type": "object",
            "additionalProperties": true
          },
          "duplicate_sent_events": {
            "type": "object",
            "additionalProperties": true
          },
          "provider_status": {
            "type": "object",
            "additionalProperties": true
          },
          "evidence_limits": {
            "type": "object",
            "additionalProperties": true
          },
          "sender_accounts": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      }
    }
  }
}
