Legacy V1 API reference
Deprecated interface. Existing authenticated V1 access remains available. New integrations use the HTTP API V2.
This static reference records 50 operations from backend revision 82cc247ab558bc404799badaf3986db9226e1122. It is an archive, not the current V2 contract. The JSON download contains the complete schemas and authentication definitions.
GET/v1/entity
List Entities
Operation schema, parameters, responses, and authentication
{
"description": "Get paginated list of entities with filtering.\n\nSupports filtering by:\n- icp_id: Entities in sheets belonging to ICP(s). Supports multiple values\n for filtering across ICPs (e.g., ?icp_id=abc&icp_id=def).\n- sheet_id: Entities in a specific sheet\n- entity_type: Entities of a specific type (company, person, etc.)\n- status: Filter by workflow status (supports multiple: ?status=new&status=reviewed)\n Valid values: new, reviewed, passed, contacted, null\n- hide_duplicates: When true, only show primary entities (filter out duplicates)\n\nAll results include enrichment fields for UI annotations.\n\nA person entity reads \"contacted\" when the person is marked contacted, in this\nICP or in another ICP. The status filter uses the status that the response shows.",
"operationId": "list_entities_v1_entity_get",
"parameters": [
{
"description": "Filter by ICP ID(s) - supports multiple",
"in": "query",
"name": "icp_id",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Filter by ICP ID(s) - supports multiple",
"title": "Icp Id"
}
},
{
"description": "Filter by sheet ID",
"in": "query",
"name": "sheet_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by sheet ID",
"title": "Sheet Id"
}
},
{
"description": "Filter by entity type",
"in": "query",
"name": "entity_type",
"required": false,
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/EntityType"
},
{
"type": "null"
}
],
"description": "Filter by entity type",
"title": "Entity Type"
}
},
{
"description": "Filter by an external record identifier (e.g. a Salesforce Account Id). Resolves to the org's entities carrying this external_id across all ICPs.",
"in": "query",
"name": "external_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by an external record identifier (e.g. a Salesforce Account Id). Resolves to the org's entities carrying this external_id across all ICPs.",
"title": "External Id"
}
},
{
"description": "External system that owns external_id (default: 'salesforce').",
"in": "query",
"name": "external_source",
"required": false,
"schema": {
"default": "salesforce",
"description": "External system that owns external_id (default: 'salesforce').",
"title": "External Source",
"type": "string"
}
},
{
"description": "Filter by status values (supports multiple: ?status=new&status=reviewed)",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Filter by status values (supports multiple: ?status=new&status=reviewed)",
"title": "Status"
}
},
{
"description": "Hide duplicate entities (show only primaries)",
"in": "query",
"name": "hide_duplicates",
"required": false,
"schema": {
"default": false,
"description": "Hide duplicate entities (show only primaries)",
"title": "Hide Duplicates",
"type": "boolean"
}
},
{
"description": "Comma-separated list of data fields to include (e.g., 'name,company,title'). Returns all fields if omitted.",
"in": "query",
"name": "fields",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Comma-separated list of data fields to include (e.g., 'name,company,title'). Returns all fields if omitted.",
"title": "Fields"
}
},
{
"description": "Page number (1-based)",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"description": "Page number (1-based)",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
{
"description": "Items per page",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 50,
"description": "Items per page",
"maximum": 200,
"minimum": 1,
"title": "Page Size",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "List Entities",
"tags": [
"Entities"
]
}GET/v1/entity/counts
Get Entity Counts
Operation schema, parameters, responses, and authentication
{
"description": "Get entity counts grouped by entity_type.\n\nReturns the count of entities for each entity_type (company, person, etc.)\nacross the organization. Supports optional filtering by ICP(s) or status.\n\nFiltering options:\n- icp_id: Filter by ICP ID(s). Supports multiple values for counting across\n ICPs (e.g., ?icp_id=abc&icp_id=def).\n- status: Filter by workflow status (supports multiple: ?status=new&status=reviewed)\n Valid values: new, reviewed, passed, contacted, null\n- hide_duplicates: When true, excludes duplicate entities from counts\n\nUsed by Entity Master List for accurate tab navigation counts.\n\nA person entity counts under the status that GET /entity shows: a person who is\nmarked contacted counts under \"contacted\", not under the stored status.",
"operationId": "get_entity_counts_v1_entity_counts_get",
"parameters": [
{
"description": "Filter by ICP ID(s) - supports multiple",
"in": "query",
"name": "icp_id",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Filter by ICP ID(s) - supports multiple",
"title": "Icp Id"
}
},
{
"description": "Filter by status values (supports multiple: ?status=new&status=passed)",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Filter by status values (supports multiple: ?status=new&status=passed)",
"title": "Status"
}
},
{
"description": "Exclude duplicate entities from counts (show only primaries)",
"in": "query",
"name": "hide_duplicates",
"required": false,
"schema": {
"default": false,
"description": "Exclude duplicate entities from counts (show only primaries)",
"title": "Hide Duplicates",
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityCountsResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Entity Counts",
"tags": [
"Entities"
]
}GET/v1/entity/export
Export Entities
Operation schema, parameters, responses, and authentication
{
"description": "Export entities as CSV.\n\nSupports two formats:\n\n**separate** (default):\n- One row per entity\n- Standard flat export\n- All entity types exported independently\n\n**combined**:\n- Pre-joined parent-child rows\n- Requires icp_id parameter\n- Child entity columns appear first, followed by parent columns\n- Columns prefixed with entity type (e.g., \"Person Name\", \"Company Industry\")\n- Parent data repeats for each child (one row per child)\n- Orphan parents (no children) appear as rows with empty child columns\n\n**Excluded Fields** (both formats):\n- id, sheet_id, parent_id, icp_id, entity_type, sheet_name, comments\n\n**Included Fields**:\n- All data.* fields (the actual enrichment data)\n- status, created_at, updated_at\n\n**Filtering**:\n- status: Filter by workflow status (supports multiple: ?status=new&status=contacted)\n Valid values: new, reviewed, passed, contacted, null\n\nArgs:\n icp_id: Filter by ICP ID(s). Supports multiple values for separate format\n (e.g., ?icp_id=abc&icp_id=def). Combined format only supports a single ICP.\n sheet_id: Filter by sheet ID\n entity_type: Filter by entity type (ignored for format=combined)\n entity_ids: Export specific entity IDs\n status: Filter by status values (multiple allowed)\n hide_duplicates: Exclude duplicate entities from export\n format: Export format - \"separate\" (default) or \"combined\"\n\nReturns:\n StreamingResponse with CSV content\n\nRaises:\n HTTPException 400: format=combined without icp_id, or invalid status value\n HTTPException 404: ICP, sheet, or entities not found\n\nThe status column and the status filter use the status that GET /entity shows: a\nperson entity reads \"contacted\" when the person is marked contacted, in this ICP\nor in another ICP.",
"operationId": "export_entities_v1_entity_export_get",
"parameters": [
{
"description": "Filter by ICP ID(s) - supports multiple",
"in": "query",
"name": "icp_id",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Filter by ICP ID(s) - supports multiple",
"title": "Icp Id"
}
},
{
"description": "Filter by sheet ID",
"in": "query",
"name": "sheet_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by sheet ID",
"title": "Sheet Id"
}
},
{
"description": "Filter by entity type",
"in": "query",
"name": "entity_type",
"required": false,
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/EntityType"
},
{
"type": "null"
}
],
"description": "Filter by entity type",
"title": "Entity Type"
}
},
{
"description": "Specific entity IDs",
"in": "query",
"name": "entity_ids",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Specific entity IDs",
"title": "Entity Ids"
}
},
{
"description": "Filter by status values (supports multiple: ?status=new&status=contacted)",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Filter by status values (supports multiple: ?status=new&status=contacted)",
"title": "Status"
}
},
{
"description": "Exclude duplicate entities from export (show only primaries)",
"in": "query",
"name": "hide_duplicates",
"required": false,
"schema": {
"default": false,
"description": "Exclude duplicate entities from export (show only primaries)",
"title": "Hide Duplicates",
"type": "boolean"
}
},
{
"description": "Export format: 'separate' (default) or 'combined' (joined parent-child rows)",
"in": "query",
"name": "format",
"required": false,
"schema": {
"default": "separate",
"description": "Export format: 'separate' (default) or 'combined' (joined parent-child rows)",
"enum": [
"separate",
"combined"
],
"title": "Format",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Export Entities",
"tags": [
"Entities"
]
}POST/v1/entity/export/bulk
Initiate Bulk Export
Operation schema, parameters, responses, and authentication
{
"description": "Initiate an async bulk export job.\n\nCreates an export job in Redis and launches a background task to process\nthe export. Returns immediately with a job ID for status polling.\n\n**Workflow:**\n1. Client calls this endpoint with filters (entity_type, status, etc.)\n2. API creates job state in Redis (status=pending)\n3. API launches BackgroundTask (non-blocking)\n4. API returns job_id immediately\n5. Client polls GET /entity/export/bulk/{job_id} every 3-5 seconds\n6. When status=completed, download_url is available\n\n**Features:**\n- Supports large datasets (50,000+ entities) without timeout\n- Real-time progress tracking via polling\n- S3 presigned URL delivery (1-hour expiration)\n- Automatic deduplication (only primary entities)\n- Default fields only (no custom enrichment fields)\n- Combined format (parent-child joined rows)\n\n**Job Persistence:**\n- Redis storage with 24-hour TTL\n- Automatic cleanup after expiration\n\nArgs:\n request: Export filters and options\n background_tasks: FastAPI background tasks manager\n user_context: Current user context (injected by auth)\n\nReturns:\n BulkExportJobResponse with job_id and initial status\n\nExample:\n POST /entity/export/bulk\n {\n \"entity_type\": \"company\",\n \"status\": [\"new\", \"reviewed\"]\n }\n\n Response:\n {\n \"job_id\": \"abc-123-def-456\",\n \"status\": \"pending\",\n \"created_at\": \"2026-01-30T12:00:00Z\"\n }",
"operationId": "initiate_bulk_export_v1_entity_export_bulk_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkExportRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkExportJobResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Initiate Bulk Export",
"tags": [
"Entities"
]
}GET/v1/entity/export/bulk/{job_id}
Get Bulk Export Status
Operation schema, parameters, responses, and authentication
{
"description": "Get status of a bulk export job.\n\nPoll this endpoint (3-5 second intervals) to track export progress.\nWhen status is \"completed\", download_url will contain the presigned S3 URL.\n\n**Status Values:**\n- pending: Job created, background task queued\n- processing: Task actively running, entities being exported\n- completed: Export finished, download_url available\n- failed: Export failed, error message in error field\n\n**Polling Strategy:**\n- Poll every 3-5 seconds while status is \"pending\" or \"processing\"\n- Stop polling when status is \"completed\" or \"failed\"\n- Download URL expires 1 hour after completion\n\nArgs:\n job_id: Export job ID (UUID from initiate_bulk_export)\n user_context: Current user context (injected by auth)\n\nReturns:\n BulkExportStatusResponse with current job status and results\n\nRaises:\n HTTPException 404: Job not found (expired or invalid job_id)\n HTTPException 403: Job belongs to different organization\n\nExample:\n GET /entity/export/bulk/abc-123-def-456\n\n Response (processing):\n {\n \"job_id\": \"abc-123-def-456\",\n \"status\": \"processing\",\n \"total_entities\": 5000,\n \"processed_entities\": 2500,\n \"download_url\": null,\n \"created_at\": \"2026-01-30T12:00:00Z\",\n \"completed_at\": null\n }\n\n Response (completed):\n {\n \"job_id\": \"abc-123-def-456\",\n \"status\": \"completed\",\n \"total_entities\": 5000,\n \"processed_entities\": 5000,\n \"download_url\": \"https://s3.amazonaws.com/...\",\n \"expires_at\": \"2026-01-30T13:00:00Z\",\n \"created_at\": \"2026-01-30T12:00:00Z\",\n \"completed_at\": \"2026-01-30T12:05:00Z\"\n }",
"operationId": "get_bulk_export_status_v1_entity_export_bulk__job_id__get",
"parameters": [
{
"description": "Export job ID from initiate_bulk_export",
"in": "path",
"name": "job_id",
"required": true,
"schema": {
"description": "Export job ID from initiate_bulk_export",
"title": "Job Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkExportStatusResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Bulk Export Status",
"tags": [
"Entities"
]
}GET/v1/entity/search
Search Entities
Operation schema, parameters, responses, and authentication
{
"description": "Search entities by text query.\n\nUses MongoDB Atlas Search for fuzzy text matching on entity names\nand company fields. Results are sorted by relevance.\n\nScope of search determined by filters:\n- sheet_id: Search within specific sheet\n- icp_id: Search across ICP sheet(s). Supports multiple values for searching\n across ICPs (e.g., ?icp_id=abc&icp_id=def).\n- No filters: Search org-wide\n\nAdditional filtering:\n- status: Filter by workflow status (supports multiple: ?status=new&status=reviewed)\n Valid values: new, reviewed, passed, contacted, null\n- hide_duplicates: When true, only show primary entities\n\nA person entity reads \"contacted\" when the person is marked contacted, in this\nICP or in another ICP. The status filter uses the status that the response shows.",
"operationId": "search_entities_v1_entity_search_get",
"parameters": [
{
"description": "Search query",
"in": "query",
"name": "q",
"required": true,
"schema": {
"description": "Search query",
"minLength": 1,
"title": "Q",
"type": "string"
}
},
{
"description": "Filter by ICP ID(s) - supports multiple",
"in": "query",
"name": "icp_id",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Filter by ICP ID(s) - supports multiple",
"title": "Icp Id"
}
},
{
"description": "Filter by sheet ID",
"in": "query",
"name": "sheet_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by sheet ID",
"title": "Sheet Id"
}
},
{
"description": "Filter by entity type",
"in": "query",
"name": "entity_type",
"required": false,
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/EntityType"
},
{
"type": "null"
}
],
"description": "Filter by entity type",
"title": "Entity Type"
}
},
{
"description": "Filter by status values (supports multiple: ?status=new&status=reviewed)",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Filter by status values (supports multiple: ?status=new&status=reviewed)",
"title": "Status"
}
},
{
"description": "Hide duplicate entities (show only primaries)",
"in": "query",
"name": "hide_duplicates",
"required": false,
"schema": {
"default": false,
"description": "Hide duplicate entities (show only primaries)",
"title": "Hide Duplicates",
"type": "boolean"
}
},
{
"description": "Page number",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"description": "Page number",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
{
"description": "Items per page",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 50,
"description": "Items per page",
"maximum": 200,
"minimum": 1,
"title": "Page Size",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntitySearchResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Search Entities",
"tags": [
"Entities"
]
}PATCH/v1/entity/status/bulk
Bulk Update Status
Operation schema, parameters, responses, and authentication
{
"description": "Update status for multiple entities at once with optional propagation.\n\nAccepts a list of entity IDs and a status value. The status can be:\n- \"new\", \"reviewed\", \"passed\", \"contacted\" (valid workflow statuses)\n- null (to clear the status)\n\nReturns the count of successfully updated entities and any failed IDs.\nEntities may fail to update if they have an invalid ID format or don't exist.\n\nPropagation flags control cascading updates:\n- propagate_to_family: Update parent/child of each entity (default: True)\n- propagate_to_duplicates: Update duplicate entities across ICPs (default: False)\n\nA write of \"contacted\" also marks each person entity that the write changed as\ncontacted, so the person reads \"contacted\" in every ICP. A write of another\nstatus (null included) removes that mark from those people.\n\nWHY: Bulk operations enable users to update status for many entities\nat once (e.g., mark all search results as \"reviewed\"), improving workflow\nefficiency versus N individual PUT calls.",
"operationId": "bulk_update_status_v1_entity_status_bulk_patch",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkUpdateStatusRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkUpdateStatusResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Bulk Update Status",
"tags": [
"Entities"
]
}DELETE/v1/entity/{entity_id}
Delete Entity
Operation schema, parameters, responses, and authentication
{
"description": "Delete an entity by ID.\n\nThis is a hard delete - the entity will be permanently removed. The entity\nalso leaves its duplicate group.",
"operationId": "delete_entity_v1_entity__entity_id__delete",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Delete Entity",
"tags": [
"Entities"
]
}GET/v1/entity/{entity_id}
Get Entity
Operation schema, parameters, responses, and authentication
{
"description": "Get a single entity by ID with enrichment.\n\nReturns the entity with sheet_name, entity_type, icp_id, and\nduplicate_info populated. duplicate_info is null if the entity\nhas no duplicates across ICPs.\n\nA person entity reads \"contacted\" when the person is marked contacted, in this\nICP or in another ICP.",
"operationId": "get_entity_v1_entity__entity_id__get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Entity",
"tags": [
"Entities"
]
}PUT/v1/entity/{entity_id}
Update Entity
Operation schema, parameters, responses, and authentication
{
"description": "Update entity status or comments with optional propagation.\n\nOnly status and comments can be updated via this endpoint.\nUse status=null to clear status, comments=null to clear comments.\n\nStatus must be one of: new, reviewed, passed, contacted, or null.\n\nPropagation flags control cascading updates:\n- propagate_to_family: Update parent/child entities (default: True)\n- propagate_to_duplicates: Update duplicate entities across ICPs (default: False)\n\nA status write of \"contacted\" also marks each person entity that the write\nchanged as contacted, so the person reads \"contacted\" in every ICP. A write of\nanother status (null included) removes that mark from those people. A\ncomments-only write does not change the mark. The response shows the status that\nGET /entity/{id} shows.",
"operationId": "update_entity_v1_entity__entity_id__put",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateEntityRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Update Entity",
"tags": [
"Entities"
]
}GET/v1/files
List Files
Operation schema, parameters, responses, and authentication
{
"description": "List uploaded files.\n\nReturns a paginated list of all files uploaded by your organization.\nFiles can be used as data sources for signal monitoring and ingest tasks.",
"operationId": "list_files_v1_files_get",
"parameters": [
{
"description": "Page number (1-based)",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"description": "Page number (1-based)",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
{
"description": "Items per page",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 20,
"description": "Items per page",
"maximum": 100,
"minimum": 1,
"title": "Page Size",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "List Files",
"tags": [
"Files"
]
}POST/v1/files/upload
Upload Csv File
Operation schema, parameters, responses, and authentication
{
"description": "Upload a CSV or XLSX file.\n\nUpload a data file for use in signal monitoring or ingest workflows. The file\nis stored securely and can be referenced when creating tasks. XLSX files are\nautomatically converted to CSV format (first sheet only).",
"operationId": "upload_csv_file_v1_files_upload_post",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_upload_csv_file_v1_files_upload_post"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUploadResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Upload Csv File",
"tags": [
"Files"
]
}GET/v1/files/{file_id}
Get File
Operation schema, parameters, responses, and authentication
{
"description": "Get file details by ID.\n\nReturns metadata for a specific file including name, size, and processing\nstatus. Use this to check if a file is ready for use in workflows.",
"operationId": "get_file_v1_files__file_id__get",
"parameters": [
{
"in": "path",
"name": "file_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "File Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileDetailResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get File",
"tags": [
"Files"
]
}GET/v1/icp
List Icps
Operation schema, parameters, responses, and authentication
{
"description": "List all ICPs for the organization.\n\nResults are scoped to your organization. Use the `mode` filter to\nseparate discovery ICPs (for finding new entities) from monitoring\nICPs (for tracking existing entities).",
"operationId": "list_icps_v1_icp_get",
"parameters": [
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 20,
"maximum": 100,
"minimum": 1,
"title": "Page Size",
"type": "integer"
}
},
{
"description": "Filter by ICP mode: 'discovery' or 'monitoring'",
"in": "query",
"name": "mode",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"discovery",
"monitoring"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by ICP mode: 'discovery' or 'monitoring'",
"title": "Mode"
}
},
{
"description": "Field to sort by (e.g., 'created_at', 'updated_at', 'name')",
"in": "query",
"name": "sort_by",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Field to sort by (e.g., 'created_at', 'updated_at', 'name')",
"title": "Sort By"
}
},
{
"description": "Sort order: -1 for descending, 1 for ascending",
"in": "query",
"name": "order",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": -1,
"description": "Sort order: -1 for descending, 1 for ascending",
"title": "Order"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ICPListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "List Icps",
"tags": [
"ICPs"
]
}POST/v1/icp
Create Icp
Operation schema, parameters, responses, and authentication
{
"description": "Create a new Ideal Customer Profile (ICP).\n\nICPs are the foundation of your research workflows. They define WHAT\nentities to target using business-level descriptions and filters,\nwithout specifying technical implementation details.\n\nCreate an ICP first, then link Sheets to it for entity storage.",
"operationId": "create_icp_v1_icp_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateICPRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ICPResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Create Icp",
"tags": [
"ICPs"
]
}DELETE/v1/icp/{icp_id}
Delete Icp
Operation schema, parameters, responses, and authentication
{
"description": "Delete an ICP and all related resources.\n\n**Cascade delete**: This permanently removes the ICP along with all\nassociated sheets, entities, schedules, tasks, signals, and actions.\nThis operation cannot be undone. Returns 404 when the ICP does not exist\nin the caller's organization, and then deletes nothing.",
"operationId": "delete_icp_v1_icp__icp_id__delete",
"parameters": [
{
"in": "path",
"name": "icp_id",
"required": true,
"schema": {
"title": "Icp Id",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Delete Icp",
"tags": [
"ICPs"
]
}GET/v1/icp/{icp_id}
Get Icp
Operation schema, parameters, responses, and authentication
{
"description": "Get a specific ICP by ID.",
"operationId": "get_icp_v1_icp__icp_id__get",
"parameters": [
{
"in": "path",
"name": "icp_id",
"required": true,
"schema": {
"title": "Icp Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ICPResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Icp",
"tags": [
"ICPs"
]
}PUT/v1/icp/{icp_id}
Update Icp
Operation schema, parameters, responses, and authentication
{
"description": "Update an existing ICP.\n\nOnly provided fields will be updated; omitted fields remain unchanged.",
"operationId": "update_icp_v1_icp__icp_id__put",
"parameters": [
{
"in": "path",
"name": "icp_id",
"required": true,
"schema": {
"title": "Icp Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateICPRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ICPResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Update Icp",
"tags": [
"ICPs"
]
}GET/v1/icp/{icp_id}/active_runs
Get Icp Active Runs
Operation schema, parameters, responses, and authentication
{
"description": "Get all active runs for an ICP.\n\nReturns runs in non-terminal states (RUNNING, SCHEDULED, PENDING).\nUseful for checking if workflows are currently processing this ICP\nbefore making changes.",
"operationId": "get_icp_active_runs_v1_icp__icp_id__active_runs_get",
"parameters": [
{
"in": "path",
"name": "icp_id",
"required": true,
"schema": {
"title": "Icp Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ICPRunningStatusResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Icp Active Runs",
"tags": [
"ICPs"
]
}GET/v1/icp/{icp_id}/delete-preview
Get Icp Delete Preview
Operation schema, parameters, responses, and authentication
{
"description": "Preview resources that will be cascade-deleted with an ICP.\n\nReturns counts for all resource types that will be permanently removed:\n- Sheets linked to this ICP\n- Entities within those sheets\n- Schedules referencing this ICP\n- Tasks bound to this ICP\n- Signals generated for this ICP\n- Actions generated for this ICP\n\nUse this endpoint before DELETE to show a confirmation dialog.",
"operationId": "get_icp_delete_preview_v1_icp__icp_id__delete_preview_get",
"parameters": [
{
"in": "path",
"name": "icp_id",
"required": true,
"schema": {
"title": "Icp Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ICPDeletePreviewResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Icp Delete Preview",
"tags": [
"ICPs"
]
}GET/v1/run
Get Runs
Operation schema, parameters, responses, and authentication
{
"description": "List all runs for the organization.\n\nRuns are workflow executions created from tasks. Filter by status to\nfind active runs (RUNNING, PENDING) or completed ones (COMPLETED, FAILED).",
"operationId": "get_runs_v1_run_get",
"parameters": [
{
"description": "Filter by agent ID (legacy)",
"in": "query",
"name": "agent_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by agent ID (legacy)",
"title": "Agent Id"
}
},
{
"description": "Filter by task ID",
"in": "query",
"name": "task_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by task ID",
"title": "Task Id"
}
},
{
"description": "Filter by run status (SCHEDULED, PENDING, RUNNING, COMPLETED, FAILED, CANCELED, CRASHED, PAUSED)",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/AgentRunState"
},
{
"type": "null"
}
],
"description": "Filter by run status (SCHEDULED, PENDING, RUNNING, COMPLETED, FAILED, CANCELED, CRASHED, PAUSED)",
"title": "Status"
}
},
{
"description": "Filter by agent type",
"in": "query",
"name": "agent_type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by agent type",
"title": "Agent Type"
}
},
{
"description": "Filter by task type (signal, search, profile, ingest)",
"in": "query",
"name": "task_type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by task type (signal, search, profile, ingest)",
"title": "Task Type"
}
},
{
"description": "Filter by ICP ID",
"in": "query",
"name": "icp_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by ICP ID",
"title": "Icp Id"
}
},
{
"description": "Filter runs created after this date (ISO 8601 format: 2024-01-15T10:30:00Z)",
"in": "query",
"name": "created_after",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter runs created after this date (ISO 8601 format: 2024-01-15T10:30:00Z)",
"title": "Created After"
}
},
{
"description": "Filter runs created before this date (ISO 8601 format)",
"in": "query",
"name": "created_before",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter runs created before this date (ISO 8601 format)",
"title": "Created Before"
}
},
{
"description": "Filter runs updated after this date (ISO 8601 format)",
"in": "query",
"name": "updated_after",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter runs updated after this date (ISO 8601 format)",
"title": "Updated After"
}
},
{
"description": "Filter runs updated before this date (ISO 8601 format)",
"in": "query",
"name": "updated_before",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter runs updated before this date (ISO 8601 format)",
"title": "Updated Before"
}
},
{
"description": "Page number (1-based)",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"description": "Page number (1-based)",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
{
"description": "Items per page (max 100)",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 20,
"description": "Items per page (max 100)",
"maximum": 100,
"minimum": 1,
"title": "Page Size",
"type": "integer"
}
},
{
"description": "Field to sort by (e.g., 'created_at', 'updated_at', 'agent_type')",
"in": "query",
"name": "sort_by",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Field to sort by (e.g., 'created_at', 'updated_at', 'agent_type')",
"title": "Sort By"
}
},
{
"description": "Sort order: -1 for descending, 1 for ascending",
"in": "query",
"name": "order",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": -1,
"description": "Sort order: -1 for descending, 1 for ascending",
"title": "Order"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Runs",
"tags": [
"Runs"
]
}POST/v1/run
Run Agent
Operation schema, parameters, responses, and authentication
{
"description": "Execute an agent by creating a new run.\n\nCreates a new workflow execution asynchronously. Prefer using\nPOST /v1/task/{task_id}/execute for task-based workflows.",
"operationId": "run_agent_v1_run_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteAgentRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Run Agent V1 Run Post",
"type": "object"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Run Agent",
"tags": [
"Runs"
]
}DELETE/v1/run/{run_id}
Delete Run
Operation schema, parameters, responses, and authentication
{
"description": "Delete a run.\n\nPermanently deletes the run record. This operation cannot be undone.\nReturns 404 when the run does not exist in the caller's organization.",
"operationId": "delete_run_v1_run__run_id__delete",
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Run Id",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Delete Run",
"tags": [
"Runs"
]
}GET/v1/run/{run_id}
Get Run
Operation schema, parameters, responses, and authentication
{
"description": "Get a specific run by ID.\n\nAutomatically refreshes status from Prefect if the run is still active.",
"operationId": "get_run_v1_run__run_id__get",
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Run Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Get Run V1 Run Run Id Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Run",
"tags": [
"Runs"
]
}POST/v1/run/{run_id}/cancel
Cancel Agent Run
Operation schema, parameters, responses, and authentication
{
"description": "Cancel a running workflow.\n\nCancels both the Prefect flow and updates the database record.\nOnly effective for non-terminal runs.",
"operationId": "cancel_agent_run_v1_run__run_id__cancel_post",
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Run Id",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Cancel Agent Run",
"tags": [
"Runs"
]
}GET/v1/run/{run_id}/queue
Get Run Queue
Operation schema, parameters, responses, and authentication
{
"description": "Get the queue status for a run.\n\nShows entities being processed by the workflow. States: queued\n(waiting), processing (active), completed (done), discarded (skipped).\nSet include_history=true to see all processed entities.",
"operationId": "get_run_queue_v1_run__run_id__queue_get",
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Run Id",
"type": "string"
}
},
{
"description": "Starting position in queue (0-indexed)",
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"description": "Starting position in queue (0-indexed)",
"minimum": 0,
"title": "Offset",
"type": "integer"
}
},
{
"description": "Maximum number of entities to return",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 20,
"description": "Maximum number of entities to return",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"description": "Filter by state: queued, processing, completed, discarded",
"in": "query",
"name": "state",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by state: queued, processing, completed, discarded",
"title": "State"
}
},
{
"description": "Include processing history from all states",
"in": "query",
"name": "include_history",
"required": false,
"schema": {
"default": false,
"description": "Include processing history from all states",
"title": "Include History",
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunQueueResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Run Queue",
"tags": [
"Runs"
]
}POST/v1/run/{run_id}/re-enrich
Re Enrich Discarded Entities
Operation schema, parameters, responses, and authentication
{
"description": "Re-enrich discarded entities from a run's queue history.\n\nAllows users to recover and enrich entities that were discarded during\nsearch runs. Creates a new ingest-ondemand run that processes the selected\nentities with NO-DISCARD policy.\n\nFlow:\n 1. Validates source run exists and belongs to org\n 2. Retrieves discarded queue items by queue_ids\n 3. Validates all items are in \"discarded\" state\n 4. Creates new ingest task with input_entities\n 5. Executes task to start re-enrichment workflow\n 6. Returns new run_id for tracking\n\nArgs:\n run_id: Source run ID containing the discarded entities\n request: Queue IDs and target ICP for re-enrichment\n\nReturns:\n ReEnrichResponse with new run_id and status\n\nRaises:\n 404: Source run not found\n 400: No valid discarded entities found, or queue_ids not in discarded state\n 500: Execution failure",
"operationId": "re_enrich_discarded_entities_v1_run__run_id__re_enrich_post",
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Run Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReEnrichRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReEnrichResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Re Enrich Discarded Entities",
"tags": [
"Runs"
]
}GET/v1/schedule
List Schedules
Operation schema, parameters, responses, and authentication
{
"description": "List schedules with pagination and optional filters.",
"operationId": "list_schedules_v1_schedule_get",
"parameters": [
{
"description": "Page number (1-based)",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"description": "Page number (1-based)",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
{
"description": "Items per page (max 100)",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 20,
"description": "Items per page (max 100)",
"maximum": 100,
"minimum": 1,
"title": "Page Size",
"type": "integer"
}
},
{
"description": "Filter by task",
"in": "query",
"name": "task_id",
"required": false,
"schema": {
"anyOf": [
{
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by task",
"title": "Task Id"
}
},
{
"description": "Filter by ICP",
"in": "query",
"name": "icp_id",
"required": false,
"schema": {
"anyOf": [
{
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by ICP",
"title": "Icp Id"
}
},
{
"description": "Filter by status",
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/ScheduleStatus"
},
{
"type": "null"
}
],
"description": "Filter by status",
"title": "Status"
}
},
{
"description": "Field to sort by (e.g., 'created_at')",
"in": "query",
"name": "sort_by",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Field to sort by (e.g., 'created_at')",
"title": "Sort By"
}
},
{
"description": "Sort order: -1 descending, 1 ascending",
"in": "query",
"name": "order",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": -1,
"description": "Sort order: -1 descending, 1 ascending",
"title": "Order"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "List Schedules",
"tags": [
"Schedules"
]
}POST/v1/schedule
Create Schedule
Operation schema, parameters, responses, and authentication
{
"description": "Create a new schedule.\n\nThe cron expression must be a daily, weekly, or monthly pattern.\nFor signal tasks, the cron frequency must match the task's\nmonitoring_frequency.",
"operationId": "create_schedule_v1_schedule_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateScheduleRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Create Schedule",
"tags": [
"Schedules"
]
}DELETE/v1/schedule/{schedule_id}
Delete Schedule
Operation schema, parameters, responses, and authentication
{
"description": "Delete a schedule.",
"operationId": "delete_schedule_v1_schedule__schedule_id__delete",
"parameters": [
{
"in": "path",
"name": "schedule_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Schedule Id",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Delete Schedule",
"tags": [
"Schedules"
]
}GET/v1/schedule/{schedule_id}
Get Schedule
Operation schema, parameters, responses, and authentication
{
"description": "Get a specific schedule by ID.",
"operationId": "get_schedule_v1_schedule__schedule_id__get",
"parameters": [
{
"in": "path",
"name": "schedule_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Schedule Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Schedule",
"tags": [
"Schedules"
]
}PATCH/v1/schedule/{schedule_id}
Update Schedule
Operation schema, parameters, responses, and authentication
{
"description": "Update a schedule.\n\nOnly provided fields will be updated. The cron expression is\nvalidated for frequency restrictions.",
"operationId": "update_schedule_v1_schedule__schedule_id__patch",
"parameters": [
{
"in": "path",
"name": "schedule_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Schedule Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateScheduleRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ScheduleResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Update Schedule",
"tags": [
"Schedules"
]
}GET/v1/sheet
List Sheets
Operation schema, parameters, responses, and authentication
{
"description": "List all sheets for the organization.\n\nFilter by ICP to see sheets for a specific targeting profile, or by\nentity type to see all company or person sheets.",
"operationId": "list_sheets_v1_sheet_get",
"parameters": [
{
"in": "query",
"name": "icp_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Icp Id"
}
},
{
"in": "query",
"name": "entity_type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Entity Type"
}
},
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"title": "Page",
"type": "integer"
}
},
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 20,
"title": "Page Size",
"type": "integer"
}
},
{
"description": "Field to sort by (e.g., 'created_at', 'updated_at', 'name')",
"in": "query",
"name": "sort_by",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Field to sort by (e.g., 'created_at', 'updated_at', 'name')",
"title": "Sort By"
}
},
{
"description": "Sort order: -1 for descending, 1 for ascending",
"in": "query",
"name": "order",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": -1,
"description": "Sort order: -1 for descending, 1 for ascending",
"title": "Order"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SheetListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "List Sheets",
"tags": [
"Sheets"
]
}POST/v1/sheet
Create Sheet
Operation schema, parameters, responses, and authentication
{
"description": "Create a new sheet linked to an ICP.\n\nSheets hold entities of a single type (company or person) and must\nreference an ICP. The entity type must match one of the ICP's\nconfigured entity targets.",
"operationId": "create_sheet_v1_sheet_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSheetRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SheetResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Create Sheet",
"tags": [
"Sheets"
]
}GET/v1/sheet/schema/default
Get Default Sheet Schema
Operation schema, parameters, responses, and authentication
{
"description": "Get the default schemas for all entity types.\n\nReturns JSON Schema definitions for company, person, job_board, and\nschool_district entity types. Use this to understand the standard\nfields available before adding custom fields.",
"operationId": "get_default_sheet_schema_v1_sheet_schema_default_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListDefaultSheetSchemas"
}
}
},
"description": "Successful Response"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Default Sheet Schema",
"tags": [
"Sheet Schema"
]
}GET/v1/sheet/schema/field
Get Default Sheet Field Definitions
Operation schema, parameters, responses, and authentication
{
"description": "Get the available field type definitions.\n\nReturns JSON Schema definitions for field types that can be used when\nadding custom fields to sheets.",
"operationId": "get_default_sheet_field_definitions_v1_sheet_schema_field_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListDefaultSheetFieldDefinitions"
}
}
},
"description": "Successful Response"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Default Sheet Field Definitions",
"tags": [
"Sheet Schema"
]
}DELETE/v1/sheet/schema/{sheet_id}
Delete Sheet Fields
Operation schema, parameters, responses, and authentication
{
"description": "Remove custom fields from a sheet's entity schema.\n\nOnly custom fields can be removed; default fields cannot be deleted.\nExisting entity data in removed fields remains in the database but\nbecomes inaccessible.",
"operationId": "delete_sheet_fields_v1_sheet_schema__sheet_id__delete",
"parameters": [
{
"in": "path",
"name": "sheet_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Sheet Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemoveFieldsFromSheetRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Delete Sheet Fields",
"tags": [
"Sheet Schema"
]
}GET/v1/sheet/schema/{sheet_id}
Get Sheet Schema
Operation schema, parameters, responses, and authentication
{
"description": "Get the schema for a specific sheet.\n\nReturns the sheet's current schema including default fields and any\ncustom fields that have been added.",
"operationId": "get_sheet_schema_v1_sheet_schema__sheet_id__get",
"parameters": [
{
"in": "path",
"name": "sheet_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Sheet Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JsonSchemaDefinition"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Sheet Schema",
"tags": [
"Sheet Schema"
]
}PUT/v1/sheet/schema/{sheet_id}
Add Sheet Fields
Operation schema, parameters, responses, and authentication
{
"description": "Add custom fields to a sheet's entity schema.\n\nCustom fields extend the default schema to capture additional data\npoints for entities in this sheet.",
"operationId": "add_sheet_fields_v1_sheet_schema__sheet_id__put",
"parameters": [
{
"in": "path",
"name": "sheet_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Sheet Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddCustomFieldsToSheetRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Add Sheet Fields",
"tags": [
"Sheet Schema"
]
}DELETE/v1/sheet/{sheet_id}
Delete Sheet
Operation schema, parameters, responses, and authentication
{
"description": "Delete a sheet and all its entities.\n\n**Cascade delete**: This permanently removes the sheet and all entities\nwithin it. This operation cannot be undone.",
"operationId": "delete_sheet_v1_sheet__sheet_id__delete",
"parameters": [
{
"in": "path",
"name": "sheet_id",
"required": true,
"schema": {
"title": "Sheet Id",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Delete Sheet",
"tags": [
"Sheets"
]
}GET/v1/sheet/{sheet_id}
Get Sheet
Operation schema, parameters, responses, and authentication
{
"description": "Get a specific sheet by ID.",
"operationId": "get_sheet_v1_sheet__sheet_id__get",
"parameters": [
{
"in": "path",
"name": "sheet_id",
"required": true,
"schema": {
"title": "Sheet Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SheetResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Sheet",
"tags": [
"Sheets"
]
}PUT/v1/sheet/{sheet_id}
Update Sheet
Operation schema, parameters, responses, and authentication
{
"description": "Update an existing sheet.\n\nOnly provided fields will be updated; omitted fields remain unchanged.\nThe ICP reference and entity_type cannot be changed after creation.",
"operationId": "update_sheet_v1_sheet__sheet_id__put",
"parameters": [
{
"in": "path",
"name": "sheet_id",
"required": true,
"schema": {
"title": "Sheet Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateSheetRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Update Sheet",
"tags": [
"Sheets"
]
}GET/v1/signal
List Signals
Operation schema, parameters, responses, and authentication
{
"description": "List signals for the organization (read-only).\n\nSignals are immutable event records detected by AI agents, such as\nfunding rounds, hiring events, and leadership changes. They cannot\nbe created or modified through the API.",
"operationId": "list_signals_v1_signal_get",
"parameters": [
{
"description": "Filter by ICP",
"in": "query",
"name": "icp_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by ICP",
"title": "Icp Id"
}
},
{
"description": "Filter by entity",
"in": "query",
"name": "entity_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by entity",
"title": "Entity Id"
}
},
{
"description": "Filter by an external record identifier (e.g. a Salesforce Account Id). Resolves to the org's entities carrying this external_id across all ICPs and returns the union of their signals.",
"in": "query",
"name": "external_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by an external record identifier (e.g. a Salesforce Account Id). Resolves to the org's entities carrying this external_id across all ICPs and returns the union of their signals.",
"title": "External Id"
}
},
{
"description": "External system that owns external_id (default: 'salesforce').",
"in": "query",
"name": "external_source",
"required": false,
"schema": {
"default": "salesforce",
"description": "External system that owns external_id (default: 'salesforce').",
"title": "External Source",
"type": "string"
}
},
{
"description": "Filter by type",
"in": "query",
"name": "signal_type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by type",
"title": "Signal Type"
}
},
{
"description": "Filter by strength",
"in": "query",
"name": "strength",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by strength",
"title": "Strength"
}
},
{
"description": "Search in signal summary or type",
"in": "query",
"name": "search_term",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Search in signal summary or type",
"title": "Search Term"
}
},
{
"description": "Number of days to look back",
"in": "query",
"name": "days",
"required": false,
"schema": {
"default": 30,
"description": "Number of days to look back",
"maximum": 90,
"minimum": 1,
"title": "Days",
"type": "integer"
}
},
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 20,
"maximum": 100,
"minimum": 1,
"title": "Page Size",
"type": "integer"
}
},
{
"description": "Field to sort by (e.g., 'created_at', 'updated_at', 'signal_type', 'strength')",
"in": "query",
"name": "sort_by",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Field to sort by (e.g., 'created_at', 'updated_at', 'signal_type', 'strength')",
"title": "Sort By"
}
},
{
"description": "Sort order: -1 for descending, 1 for ascending",
"in": "query",
"name": "order",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": -1,
"description": "Sort order: -1 for descending, 1 for ascending",
"title": "Order"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignalListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "List Signals",
"tags": [
"Signals"
]
}GET/v1/signal/{signal_id}
Get Signal
Operation schema, parameters, responses, and authentication
{
"description": "Get a specific signal by ID (read-only).",
"operationId": "get_signal_v1_signal__signal_id__get",
"parameters": [
{
"in": "path",
"name": "signal_id",
"required": true,
"schema": {
"title": "Signal Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignalResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Signal",
"tags": [
"Signals"
]
}GET/v1/task
List Tasks
Operation schema, parameters, responses, and authentication
{
"description": "List all tasks for the organization.\n\nTasks are reusable workflow templates. Filter by flow_name to see\nspecific workflow types (search, ingest, signal).",
"operationId": "list_tasks_v1_task_get",
"parameters": [
{
"description": "Page number (1-based)",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"description": "Page number (1-based)",
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
{
"description": "Items per page (max 100)",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 20,
"description": "Items per page (max 100)",
"maximum": 100,
"minimum": 1,
"title": "Page Size",
"type": "integer"
}
},
{
"description": "Filter by flow name",
"in": "query",
"name": "flow_name",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by flow name",
"title": "Flow Name"
}
},
{
"description": "Field to sort by (e.g., 'created_at', 'updated_at', 'name')",
"in": "query",
"name": "sort_by",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Field to sort by (e.g., 'created_at', 'updated_at', 'name')",
"title": "Sort By"
}
},
{
"description": "Sort order: -1 for descending, 1 for ascending",
"in": "query",
"name": "order",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": -1,
"description": "Sort order: -1 for descending, 1 for ascending",
"title": "Order"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "List Tasks",
"tags": [
"Tasks"
]
}POST/v1/task
Create Task
Operation schema, parameters, responses, and authentication
{
"description": "Create a new task template.\n\nTasks define reusable workflow configurations that reference Prefect\ndeployments. Execute a task to create runs.",
"operationId": "create_task_v1_task_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTaskRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Create Task",
"tags": [
"Tasks"
]
}DELETE/v1/task/{task_id}
Delete Task
Operation schema, parameters, responses, and authentication
{
"description": "Delete a task.\n\nA task cannot be deleted if it has active (non-terminal) runs.\nThis operation cannot be undone.",
"operationId": "delete_task_v1_task__task_id__delete",
"parameters": [
{
"in": "path",
"name": "task_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Task Id",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Delete Task",
"tags": [
"Tasks"
]
}GET/v1/task/{task_id}
Get Task
Operation schema, parameters, responses, and authentication
{
"description": "Get a specific task by ID.",
"operationId": "get_task_v1_task__task_id__get",
"parameters": [
{
"in": "path",
"name": "task_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Task Id",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Get Task",
"tags": [
"Tasks"
]
}PUT/v1/task/{task_id}
Update Task
Operation schema, parameters, responses, and authentication
{
"description": "Update an existing task.\n\nOnly provided fields will be updated; omitted fields remain unchanged.\nThe flow_name cannot be changed after creation.",
"operationId": "update_task_v1_task__task_id__put",
"parameters": [
{
"in": "path",
"name": "task_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Task Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTaskRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Update Task",
"tags": [
"Tasks"
]
}POST/v1/task/{task_id}/execute
Execute Task
Operation schema, parameters, responses, and authentication
{
"description": "Execute a task by creating a new run.\n\nCreates a new workflow execution asynchronously and returns tracking\ninformation immediately. Monitor the run status using the returned\nrun_id.",
"operationId": "execute_task_v1_task__task_id__execute_post",
"parameters": [
{
"in": "path",
"name": "task_id",
"required": true,
"schema": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Task Id",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteTaskRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExecuteTaskResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Execute Task",
"tags": [
"Tasks"
]
}Older reference bookmarks
If an older bookmark has no matching operation in this snapshot, use the operation list above or the migration guide. An unmatched bookmark does not identify a current V2 operation.
Shared schemas and authentication
OpenAPI components
{
"schemas": {
"AddCustomFieldsToSheetRequest": {
"properties": {
"fields": {
"items": {
"$ref": "#/components/schemas/CustomField"
},
"title": "Fields",
"type": "array"
}
},
"required": [
"fields"
],
"title": "AddCustomFieldsToSheetRequest",
"type": "object"
},
"AgentRun": {
"additionalProperties": true,
"type": "object"
},
"AgentRunMetadata": {
"description": "Metadata for agent runs.",
"properties": {
"data": {
"additionalProperties": true,
"title": "Data",
"type": "object"
},
"provider_credits": {
"additionalProperties": {
"$ref": "#/components/schemas/ProviderCreditUsage"
},
"description": "Provider API credits consumed with action breakdown, keyed by provider name",
"title": "Provider Credits",
"type": "object"
},
"token_usage": {
"additionalProperties": {
"$ref": "#/components/schemas/TokenUsage"
},
"description": "Token usage for the agent run, keyed by model code.",
"title": "Token Usage",
"type": "object"
}
},
"title": "AgentRunMetadata",
"type": "object"
},
"AgentRunState": {
"enum": [
"SCHEDULED",
"PENDING",
"RUNNING",
"COMPLETED",
"FAILED",
"CANCELED",
"CRASHED",
"PAUSED"
],
"title": "AgentRunState",
"type": "string"
},
"BlockEntityAttribute": {
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"display": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array"
},
{
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"readOnly": true,
"title": "Display"
},
"references": {
"description": "References to external resources.",
"items": {
"type": "string"
},
"title": "References",
"type": "array"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
},
"value": {
"description": "The value of the attribute.",
"oneOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"$ref": "#/components/schemas/Location"
},
{
"$ref": "#/components/schemas/SocialMediaProfile"
},
{
"$ref": "#/components/schemas/CriteriaMatch"
},
{
"$ref": "#/components/schemas/RevenueInfo"
}
],
"title": "Value"
}
},
"required": [
"value",
"references",
"display"
],
"title": "BlockEntityAttribute",
"type": "object"
},
"Body_upload_csv_file_v1_files_upload_post": {
"properties": {
"file": {
"description": "CSV or XLSX file to upload",
"format": "binary",
"title": "File",
"type": "string"
}
},
"required": [
"file"
],
"title": "Body_upload_csv_file_v1_files_upload_post",
"type": "object"
},
"BoolEntityAttribute": {
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"display": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array"
},
{
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"readOnly": true,
"title": "Display"
},
"references": {
"description": "References to external resources.",
"items": {
"type": "string"
},
"title": "References",
"type": "array"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
},
"value": {
"description": "The value of the attribute.",
"title": "Value",
"type": "boolean"
}
},
"required": [
"value",
"references",
"display"
],
"title": "BoolEntityAttribute",
"type": "object"
},
"BulkExportJobResponse": {
"description": "Response for bulk export job creation.\n\nReturns immediately with a job_id for status polling.\nThe export processing happens asynchronously in the background.\n\nExample:\n {\n \"job_id\": \"abc-123-def-456\",\n \"status\": \"pending\",\n \"created_at\": \"2026-01-30T12:00:00Z\"\n }",
"properties": {
"created_at": {
"description": "Job creation timestamp (UTC)",
"format": "date-time",
"title": "Created At",
"type": "string"
},
"job_id": {
"description": "Unique job identifier (UUID). Use this to poll job status.",
"example": "abc-123-def-456",
"title": "Job Id",
"type": "string"
},
"status": {
"description": "Initial job status (always 'pending' when created)",
"example": "pending",
"title": "Status",
"type": "string"
}
},
"required": [
"job_id",
"status",
"created_at"
],
"title": "BulkExportJobResponse",
"type": "object"
},
"BulkExportRequest": {
"description": "Request body for initiating a bulk export.\n\nFilters are applied to entities before export. All fields are optional,\nallowing org-wide exports or filtered exports.\n\nExample:\n {\n \"entity_type\": \"company\",\n \"status\": [\"new\", \"reviewed\"]\n }",
"properties": {
"entity_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by entity type (company, person, job_board, etc.)",
"example": "company",
"title": "Entity Type"
},
"format": {
"default": "combined",
"description": "Export format - always 'combined' for bulk exports (parent-child joined rows)",
"title": "Format",
"type": "string"
},
"icp_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by ICP ID (export only entities from this ICP's sheets)",
"example": "507f1f77bcf86cd799439011",
"title": "Icp Id"
},
"status": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Filter by workflow status values (new, reviewed, passed, contacted, null)",
"example": [
"new",
"reviewed"
],
"title": "Status"
}
},
"title": "BulkExportRequest",
"type": "object"
},
"BulkExportStatusResponse": {
"description": "Response for bulk export job status polling.\n\nPoll this endpoint every 3-5 seconds to track export progress.\nWhen status is 'completed', download_url will contain the S3 presigned URL.\n\nStatus Flow:\n- pending: Job created, background task queued\n- processing: Task actively running, entities being exported\n- completed: Export finished, download_url available\n- failed: Export failed, error message in error field\n\nExample (processing):\n {\n \"job_id\": \"abc-123-def-456\",\n \"status\": \"processing\",\n \"total_entities\": 5000,\n \"processed_entities\": 2500,\n \"download_url\": null,\n \"expires_at\": null,\n \"created_at\": \"2026-01-30T12:00:00Z\",\n \"completed_at\": null,\n \"error\": null\n }\n\nExample (completed):\n {\n \"job_id\": \"abc-123-def-456\",\n \"status\": \"completed\",\n \"total_entities\": 5000,\n \"processed_entities\": 5000,\n \"download_url\": \"https://s3.amazonaws.com/bucket/export.csv?...\",\n \"expires_at\": \"2026-01-30T13:00:00Z\",\n \"created_at\": \"2026-01-30T12:00:00Z\",\n \"completed_at\": \"2026-01-30T12:05:00Z\",\n \"error\": null\n }",
"properties": {
"completed_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Job completion timestamp (UTC, when status=completed or failed)",
"title": "Completed At"
},
"created_at": {
"description": "Job creation timestamp (UTC)",
"format": "date-time",
"title": "Created At",
"type": "string"
},
"download_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "S3 presigned download URL (when status=completed). Expires in 1 hour.",
"example": "https://s3.amazonaws.com/bucket/export.csv?X-Amz-Algorithm=...",
"title": "Download Url"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Error message (when status=failed)",
"example": "Failed to upload to S3: connection timeout",
"title": "Error"
},
"expires_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Download URL expiration timestamp (UTC, when status=completed)",
"title": "Expires At"
},
"job_id": {
"description": "Unique job identifier",
"example": "abc-123-def-456",
"title": "Job Id",
"type": "string"
},
"processed_entities": {
"default": 0,
"description": "Number of entities processed so far",
"example": 2500,
"title": "Processed Entities",
"type": "integer"
},
"status": {
"description": "Current job status: pending, processing, completed, or failed",
"example": "processing",
"title": "Status",
"type": "string"
},
"total_entities": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Total number of entities to export (when known)",
"example": 5000,
"title": "Total Entities"
}
},
"required": [
"job_id",
"status",
"created_at"
],
"title": "BulkExportStatusResponse",
"type": "object"
},
"BulkUpdateStatusRequest": {
"description": "Request to update status for multiple entities.\n\nAccepts entity_ids and a status value. The status can be any valid\nEntityStatus value or null to clear the status.\n\nWHY: Bulk operations enable users to update status for many entities\nat once (e.g., mark all search results as \"reviewed\"), improving workflow\nefficiency versus N individual PUT calls.\n\nPropagation flags control whether updates cascade to related entities:\n- propagate_to_family: Update parent/child of each entity (default: True)\n- propagate_to_duplicates: Update duplicate entities across ICPs (default: False)",
"properties": {
"entity_ids": {
"description": "List of entity IDs to update (1-1000 IDs)",
"items": {
"type": "string"
},
"maxItems": 1000,
"minItems": 1,
"title": "Entity Ids",
"type": "array"
},
"propagate_to_duplicates": {
"default": false,
"description": "Reflect status to duplicate entities across ICPs (default: False)",
"title": "Propagate To Duplicates",
"type": "boolean"
},
"propagate_to_family": {
"default": true,
"description": "Reflect status to parent/child of each entity (default: True)",
"title": "Propagate To Family",
"type": "boolean"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "New status value: new, reviewed, passed, contacted, or null to clear",
"title": "Status"
}
},
"required": [
"entity_ids",
"status"
],
"title": "BulkUpdateStatusRequest",
"type": "object"
},
"BulkUpdateStatusResponse": {
"description": "Response for bulk status update operation.\n\nWHY: Reports both success count and specific failures so the client\nknows exactly which entities were updated and which failed.",
"properties": {
"failed_ids": {
"description": "Entity IDs that failed to update (invalid format or not found)",
"items": {
"type": "string"
},
"title": "Failed Ids",
"type": "array"
},
"updated_count": {
"description": "Number of entities successfully updated",
"title": "Updated Count",
"type": "integer"
}
},
"required": [
"updated_count"
],
"title": "BulkUpdateStatusResponse",
"type": "object"
},
"CSVProcessingStatus": {
"description": "Processing status for CSV files.",
"enum": [
"pending",
"processing",
"completed",
"failed"
],
"title": "CSVProcessingStatus",
"type": "string"
},
"CreateICPRequest": {
"description": "Request to create a new ICP.",
"properties": {
"description": {
"minLength": 1,
"title": "Description",
"type": "string"
},
"entity_targets": {
"items": {
"$ref": "#/components/schemas/EntityTargetConfigRequest"
},
"minItems": 1,
"title": "Entity Targets",
"type": "array"
},
"name": {
"maxLength": 200,
"minLength": 1,
"title": "Name",
"type": "string"
}
},
"required": [
"name",
"description",
"entity_targets"
],
"title": "CreateICPRequest",
"type": "object"
},
"CreateScheduleRequest": {
"description": "Request model for creating a new schedule.\n\nAttributes:\n name: Human-readable name for the schedule.\n task_id: ID of the task to execute.\n icp_id: ID of the ICP context for execution.\n cron_expression: 5-part cron expression (must be daily/weekly/monthly).\n description: Optional description.\n parameters: Optional execution parameters.",
"properties": {
"cron_expression": {
"description": "Cron expression (5 parts: minute hour day month day_of_week). Must be daily, weekly, or monthly.",
"title": "Cron Expression",
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Schedule description",
"title": "Description"
},
"icp_id": {
"description": "ICP context for execution",
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
},
"name": {
"description": "Schedule name",
"maxLength": 200,
"minLength": 1,
"title": "Name",
"type": "string"
},
"parameters": {
"additionalProperties": true,
"description": "Execution parameters",
"title": "Parameters",
"type": "object"
},
"task_id": {
"description": "Task to execute",
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
}
},
"required": [
"name",
"task_id",
"icp_id",
"cron_expression"
],
"title": "CreateScheduleRequest",
"type": "object"
},
"CreateSheetRequest": {
"description": "Request to create a new sheet.",
"properties": {
"description": {
"minLength": 1,
"title": "Description",
"type": "string"
},
"entity_type": {
"$ref": "#/components/schemas/EntityType",
"description": "Type of entities to store"
},
"icp_id": {
"description": "ICP this sheet belongs to",
"title": "Icp Id",
"type": "string"
},
"name": {
"maxLength": 200,
"minLength": 1,
"title": "Name",
"type": "string"
}
},
"required": [
"name",
"description",
"icp_id",
"entity_type"
],
"title": "CreateSheetRequest",
"type": "object"
},
"CreateTaskRequest": {
"description": "Request model for creating a new task.\n\nUses TaskConfigRequest discriminated union for proper OpenAPI schema\ngeneration with type-based discrimination.\n\nAttributes:\n name: Human-readable name for the task.\n description: Detailed description of what this task accomplishes.\n flow_name: The Prefect flow name (e.g., 'search', 'ingest', 'signal').\n deployment_name: The Prefect deployment name for this flow.\n icp_id: Optional ICP ID for signal monitoring tasks.\n prompt: Template prompt for the task with optional placeholders.\n task_config: Flow-specific task configuration with type discriminator.",
"properties": {
"deployment_name": {
"description": "The Prefect deployment name for this flow",
"title": "Deployment Name",
"type": "string"
},
"description": {
"description": "Detailed description of what this task accomplishes",
"title": "Description",
"type": "string"
},
"flow_name": {
"description": "The Prefect flow name (e.g., 'search', 'ingest', 'signal')",
"title": "Flow Name",
"type": "string"
},
"icp_id": {
"anyOf": [
{
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional ICP ID for signal monitoring tasks",
"title": "Icp Id"
},
"name": {
"description": "Human-readable name for the task",
"maxLength": 200,
"minLength": 1,
"title": "Name",
"type": "string"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "",
"description": "Template prompt for the task. Can include placeholders for runtime parameters.",
"title": "Prompt"
},
"task_config": {
"anyOf": [
{
"discriminator": {
"mapping": {
"ingest": "#/components/schemas/IngestTaskConfigRequest",
"ingest-ondemand": "#/components/schemas/OnDemandIngestTaskConfigRequest",
"profile": "#/components/schemas/ProfilePromptConfigRequest",
"search": "#/components/schemas/SearchTaskConfigRequest",
"signal-csv": "#/components/schemas/SignalCSVConfigRequest",
"signal-sheet": "#/components/schemas/SignalSheetConfigRequest",
"signal-topic": "#/components/schemas/SignalTopicConfigRequest"
},
"propertyName": "type"
},
"oneOf": [
{
"$ref": "#/components/schemas/SearchTaskConfigRequest"
},
{
"$ref": "#/components/schemas/IngestTaskConfigRequest"
},
{
"$ref": "#/components/schemas/OnDemandIngestTaskConfigRequest"
},
{
"$ref": "#/components/schemas/ProfilePromptConfigRequest"
},
{
"$ref": "#/components/schemas/SignalTopicConfigRequest"
},
{
"$ref": "#/components/schemas/SignalCSVConfigRequest"
},
{
"$ref": "#/components/schemas/SignalSheetConfigRequest"
}
]
},
{
"type": "null"
}
],
"description": "Flow-specific task configuration with type discriminator",
"title": "Task Config"
}
},
"required": [
"name",
"description",
"flow_name",
"deployment_name"
],
"title": "CreateTaskRequest",
"type": "object"
},
"CreditUsageSummary": {
"description": "Structured credit usage information for internal tracking.",
"properties": {
"breakdown": {
"additionalProperties": {
"type": "number"
},
"description": "Credit usage by action type",
"title": "Breakdown",
"type": "object"
},
"total_credits": {
"description": "Total credits consumed",
"title": "Total Credits",
"type": "number"
}
},
"required": [
"total_credits",
"breakdown"
],
"title": "CreditUsageSummary",
"type": "object"
},
"CriteriaMatch": {
"description": "Custom field type for criteria match validation results.\n\nUsed for LLM-generated boolean assessments that include reasoning/evidence.\nEach criterion in the ICP generates a criteria_* field with this type.\n\nExamples:\n >>> match = CriteriaMatch(verified=True, reasoning=\"LinkedIn shows AI focus\")\n >>> match.to_display()\n 'Yes - LinkedIn shows AI focus'\n\n >>> match = CriteriaMatch(verified=False, reasoning=\"No funding found\")\n >>> match.to_display()\n 'No - No funding found'\n\n >>> match = CriteriaMatch(verified=None, reasoning=None)\n >>> match.to_display()\n 'Unverified'",
"properties": {
"reasoning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Evidence or explanation for the verification status (1 sentence)",
"title": "Reasoning"
},
"verified": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Whether the criterion is verified as met",
"title": "Verified"
}
},
"title": "CriteriaMatch",
"type": "object"
},
"CustomField": {
"description": "Definition for a custom field in a sheet.",
"properties": {
"additional_props": {
"additionalProperties": true,
"description": "Additional JSON schema properties",
"title": "Additional Props",
"type": "object"
},
"array_items": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Schema for array items when field_type is ARRAY",
"title": "Array Items"
},
"description": {
"default": "",
"description": "Field description",
"title": "Description",
"type": "string"
},
"enum_values": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"description": "List of allowed values when field_type is ENUM",
"title": "Enum Values"
},
"field_type": {
"$ref": "#/components/schemas/FieldType",
"description": "Field type"
},
"name": {
"description": "Field name",
"title": "Name",
"type": "string"
},
"properties": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Properties for object fields when field_type is OBJECT",
"title": "Properties"
},
"reference_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Referenced model name when field_type is REFERENCE",
"title": "Reference Model"
},
"required": {
"default": false,
"description": "Whether field is required - always false for custom fields",
"title": "Required",
"type": "boolean"
}
},
"required": [
"name",
"field_type"
],
"title": "CustomField",
"type": "object"
},
"DuplicateICPInfo": {
"description": "Info about an ICP containing a duplicate entity.\n\nUsed in DuplicateInfo to show which ICPs contain duplicate instances\nof the same entity.",
"properties": {
"icp_id": {
"description": "ICP ID",
"title": "Icp Id",
"type": "string"
},
"icp_name": {
"description": "ICP name",
"title": "Icp Name",
"type": "string"
}
},
"required": [
"icp_id",
"icp_name"
],
"title": "DuplicateICPInfo",
"type": "object"
},
"DuplicateInfo": {
"description": "Duplicate status information for an entity.\n\nIndicates whether an entity is part of a duplicate group and its role:\n- Primary entities: is_primary=True, has duplicate_entity_ids and duplicate_icps\n- Duplicate entities: is_duplicate=True, has primary_entity_id and primary_icp_name\n\nFor entities that have no duplicates, this field will be None/null in the\nEntityResponse.",
"properties": {
"duplicate_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Number of duplicate entities (primary only)",
"title": "Duplicate Count"
},
"duplicate_entity_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "IDs of duplicate entities (primary only)",
"title": "Duplicate Entity Ids"
},
"duplicate_icps": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/DuplicateICPInfo"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "ICPs containing duplicates (primary only)",
"title": "Duplicate Icps"
},
"is_duplicate": {
"description": "Whether this entity is a duplicate (not the primary)",
"title": "Is Duplicate",
"type": "boolean"
},
"is_primary": {
"description": "Whether this entity is the primary in a duplicate group",
"title": "Is Primary",
"type": "boolean"
},
"primary_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ID of the primary entity (duplicate only)",
"title": "Primary Entity Id"
},
"primary_icp_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ICP name of the primary entity (duplicate only)",
"title": "Primary Icp Name"
}
},
"required": [
"is_duplicate",
"is_primary"
],
"title": "DuplicateInfo",
"type": "object"
},
"Entity": {
"additionalProperties": true,
"type": "object"
},
"EntityCountsResponse": {
"description": "Response model for entity counts by type.\n\nReturns counts grouped by entity_type with an aggregate total.\nUsed by Entity Master List for tab navigation counts.",
"properties": {
"counts": {
"additionalProperties": {
"type": "integer"
},
"description": "Entity counts keyed by entity_type (company, person, etc.)",
"title": "Counts",
"type": "object"
},
"total": {
"description": "Sum of all entity counts",
"title": "Total",
"type": "integer"
}
},
"required": [
"total"
],
"title": "EntityCountsResponse",
"type": "object"
},
"EntityListResponse": {
"description": "Paginated list response for entities.\n\nAll entities include enrichment fields (sheet_name, entity_type, icp_id)\nto support UI annotations without additional API calls.",
"properties": {
"entities": {
"items": {
"$ref": "#/components/schemas/EntityResponse"
},
"title": "Entities",
"type": "array"
},
"page": {
"description": "Current page (1-based)",
"title": "Page",
"type": "integer"
},
"page_size": {
"description": "Items per page",
"title": "Page Size",
"type": "integer"
},
"total": {
"description": "Total matching entities (before pagination)",
"title": "Total",
"type": "integer"
}
},
"required": [
"entities",
"total",
"page",
"page_size"
],
"title": "EntityListResponse",
"type": "object"
},
"EntityResponse": {
"description": "Response model for single entity.\n\nIMPORTANT: Enrichment fields (sheet_name, entity_type, icp_id) are\nALWAYS populated to support UI annotations. Excludes embedding data\nfor HTTP efficiency.",
"properties": {
"comments": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "User comments",
"title": "Comments"
},
"created_at": {
"description": "Creation timestamp",
"format": "date-time",
"title": "Created At",
"type": "string"
},
"data": {
"additionalProperties": true,
"description": "Entity attribute data",
"title": "Data",
"type": "object"
},
"duplicate_info": {
"anyOf": [
{
"$ref": "#/components/schemas/DuplicateInfo"
},
{
"type": "null"
}
],
"description": "Duplicate status info. Null if entity has no duplicates."
},
"entity_type": {
"description": "Entity type (company, person, etc.)",
"title": "Entity Type",
"type": "string"
},
"external_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "External system identifier (e.g. a Salesforce Account Id)",
"title": "External Id"
},
"external_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "External system that owns external_id (e.g. 'salesforce')",
"title": "External Source"
},
"icp_id": {
"description": "ICP ID (via sheet)",
"title": "Icp Id",
"type": "string"
},
"id": {
"description": "Entity ID",
"title": "Id",
"type": "string"
},
"parent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Parent entity ID (for hierarchical entities)",
"title": "Parent Id"
},
"sheet_id": {
"description": "Sheet this entity belongs to",
"title": "Sheet Id",
"type": "string"
},
"sheet_name": {
"description": "Name of parent sheet",
"title": "Sheet Name",
"type": "string"
},
"status": {
"anyOf": [
{
"$ref": "#/components/schemas/EntityStatus"
},
{
"type": "null"
}
],
"description": "Workflow status (new, reviewed, passed, contacted)"
},
"updated_at": {
"description": "Last update timestamp",
"format": "date-time",
"title": "Updated At",
"type": "string"
}
},
"required": [
"id",
"sheet_id",
"data",
"created_at",
"updated_at",
"sheet_name",
"entity_type",
"icp_id"
],
"title": "EntityResponse",
"type": "object"
},
"EntitySearchResponse": {
"description": "Search response with pagination.\n\nAll entities include enrichment fields for UI annotations.",
"properties": {
"entities": {
"items": {
"$ref": "#/components/schemas/EntityResponse"
},
"title": "Entities",
"type": "array"
},
"page": {
"description": "Current page (1-based)",
"title": "Page",
"type": "integer"
},
"page_size": {
"description": "Items per page",
"title": "Page Size",
"type": "integer"
},
"query": {
"description": "Original search query",
"title": "Query",
"type": "string"
},
"total": {
"description": "Total matching entities",
"title": "Total",
"type": "integer"
}
},
"required": [
"entities",
"total",
"page",
"page_size",
"query"
],
"title": "EntitySearchResponse",
"type": "object"
},
"EntityStatus": {
"description": "Status values for entity workflow tracking.\n\nTransitions are user-driven (not automatic state machine):\n- new: Default for all newly created entities\n- reviewed: User has examined the entity\n- passed: Entity has been approved/qualified\n- contacted: Outreach has been initiated",
"enum": [
"new",
"reviewed",
"passed",
"contacted"
],
"title": "EntityStatus",
"type": "string"
},
"EntityStructureResponse": {
"description": "Response model for v2 entity structure entry.\n\nLightweight structure that defines entity types and their hierarchy\nwithout the business description (which lives on sheets in v2).",
"properties": {
"desired_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "For non-root entities, desired count per parent",
"title": "Desired Count"
},
"entity_type": {
"description": "Entity type (company, person, etc.)",
"title": "Entity Type",
"type": "string"
},
"root": {
"description": "If this is the root entity type",
"title": "Root",
"type": "boolean"
}
},
"required": [
"entity_type",
"root"
],
"title": "EntityStructureResponse",
"type": "object"
},
"EntityTargetConfigRequest": {
"description": "Request model for entity target configuration.\n\nSynchronized with core.schema.mongo.icp.EntityTargetConfig to ensure\nall fields available in the database model can be set via the API.\n\nAttributes:\n entity_type: The entity type to target (e.g., 'company', 'person').\n description: Business description of what makes a good target.\n root: If True, this is the root entity type of the search hierarchy.\n Only one entity target should be marked as root. Defaults to False\n for backward compatibility with existing API consumers.\n desired_count: For non-root entities, the desired number of entities\n per parent (minimum: 1). Uses `ge=1` Field constraint which\n generates `minimum: 1` in OpenAPI schema for SDK validation.\n If not specified, defaults to system minimum (typically 2).\n filters: Optional list of filter criteria to apply to the search.\n\nNote:\n The `root` and `desired_count` fields default to False and None\n respectively, making them optional in API requests for backward\n compatibility with existing integrations.",
"properties": {
"description": {
"description": "Business description of targets",
"title": "Description",
"type": "string"
},
"desired_count": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"description": "For non-root entities, desired count per parent (minimum: 1). If not specified, defaults to system minimum.",
"title": "Desired Count"
},
"entity_type": {
"description": "Entity type to target (company, person, etc.)",
"title": "Entity Type",
"type": "string"
},
"filters": {
"description": "Filters to apply",
"items": {
"type": "string"
},
"title": "Filters",
"type": "array"
},
"root": {
"default": false,
"description": "If this is the root entity type of the search. Only one entity target should be root.",
"title": "Root",
"type": "boolean"
}
},
"required": [
"entity_type",
"description"
],
"title": "EntityTargetConfigRequest",
"type": "object"
},
"EntityTargetConfigResponse": {
"description": "Response model for entity target configuration.\n\nSynchronized with core.schema.mongo.icp.EntityTargetConfig to return\nall configuration fields stored in the database to API consumers.\n\nAttributes:\n root: If True, this is the root entity type of the search hierarchy.\n entity_type: The entity type this config targets (e.g., 'company', 'person').\n description: Business description of what makes a good target.\n desired_count: For non-root entities, the desired number of entities\n per parent. Returns None if not explicitly set in the ICP.\n\nNote:\n The `desired_count` field is included in responses to enable API\n consumers to see the full configuration. When None, the system\n applies its default minimum (typically 2).",
"properties": {
"description": {
"description": "Business description of targets",
"title": "Description",
"type": "string"
},
"desired_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "For non-root entities, desired count per parent",
"title": "Desired Count"
},
"entity_type": {
"description": "Entity type (company, person, etc.)",
"title": "Entity Type",
"type": "string"
},
"root": {
"description": "If this is the root entity type",
"title": "Root",
"type": "boolean"
}
},
"required": [
"root",
"entity_type",
"description"
],
"title": "EntityTargetConfigResponse",
"type": "object"
},
"EntityType": {
"description": "Valid entity types for sheets.",
"enum": [
"company",
"person",
"job_board",
"school_district",
"product"
],
"title": "EntityType",
"type": "string"
},
"ExecuteAgentRequest": {
"properties": {
"agent_id": {
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
},
"icp_id": {
"anyOf": [
{
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
},
{
"type": "null"
}
],
"title": "Icp Id"
},
"parameters": {
"additionalProperties": true,
"title": "Parameters",
"type": "object"
}
},
"required": [
"agent_id",
"parameters"
],
"title": "ExecuteAgentRequest",
"type": "object"
},
"ExecuteTaskRequest": {
"description": "Request model for executing a task.\n\nAttributes:\n icp_id: Optional ICP ID to attach to this run.\n parameters: Runtime parameters to pass to the task execution.",
"properties": {
"icp_id": {
"anyOf": [
{
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional ICP ID to attach to this run for workflows that require ICP context",
"title": "Icp Id"
},
"parameters": {
"additionalProperties": true,
"description": "Runtime parameters to pass to the task execution",
"title": "Parameters",
"type": "object"
}
},
"title": "ExecuteTaskRequest",
"type": "object"
},
"ExecuteTaskResponse": {
"description": "Response model for task execution.\n\nAttributes:\n run_id: The ID of the created run.\n flow_run_id: The Prefect flow run ID.\n status: Initial status of the run.",
"example": {
"flow_run_id": "550e8400-e29b-41d4-a716-446655440000",
"run_id": "507f1f77bcf86cd799439011",
"status": "SCHEDULED"
},
"properties": {
"flow_run_id": {
"description": "The Prefect flow run ID",
"title": "Flow Run Id",
"type": "string"
},
"run_id": {
"description": "The ID of the created run",
"title": "Run Id",
"type": "string"
},
"status": {
"description": "Initial status of the run",
"title": "Status",
"type": "string"
}
},
"required": [
"run_id",
"flow_run_id",
"status"
],
"title": "ExecuteTaskResponse",
"type": "object"
},
"FieldType": {
"description": "Supported field types for custom fields.",
"enum": [
"string",
"number",
"integer",
"boolean",
"array",
"object",
"reference",
"enum"
],
"title": "FieldType",
"type": "string"
},
"FileDetailResponse": {
"description": "Response model for file details.",
"properties": {
"content_type": {
"description": "Content type of the file",
"title": "Content Type",
"type": "string"
},
"csv_metadata": {
"additionalProperties": true,
"default": {},
"description": "CSV metadata",
"title": "Csv Metadata",
"type": "object"
},
"file_id": {
"description": "The ID of the file",
"title": "File Id",
"type": "string"
},
"name": {
"description": "The name of the file",
"title": "Name",
"type": "string"
},
"original_file_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Original file type if converted (e.g., 'xlsx' if XLSX was converted to CSV)",
"title": "Original File Type"
},
"processing_status": {
"$ref": "#/components/schemas/CSVProcessingStatus",
"description": "Processing status"
},
"s3_uri": {
"description": "S3 URI of the file",
"title": "S3 Uri",
"type": "string"
},
"size_bytes": {
"description": "Size of the file in bytes",
"title": "Size Bytes",
"type": "integer"
}
},
"required": [
"file_id",
"name",
"s3_uri",
"content_type",
"size_bytes"
],
"title": "FileDetailResponse",
"type": "object"
},
"FileListItem": {
"description": "File item in list response.",
"properties": {
"file_id": {
"description": "The ID of the file",
"title": "File Id",
"type": "string"
},
"name": {
"description": "The name of the file",
"title": "Name",
"type": "string"
},
"size_bytes": {
"description": "Size of the file in bytes",
"title": "Size Bytes",
"type": "integer"
}
},
"required": [
"file_id",
"name",
"size_bytes"
],
"title": "FileListItem",
"type": "object"
},
"FileListResponse": {
"description": "Response model for file listing.",
"properties": {
"files": {
"description": "List of files",
"items": {
"$ref": "#/components/schemas/FileListItem"
},
"title": "Files",
"type": "array"
},
"page": {
"description": "Current page number",
"title": "Page",
"type": "integer"
},
"page_size": {
"description": "Number of items per page",
"title": "Page Size",
"type": "integer"
},
"total": {
"description": "Total number of files",
"title": "Total",
"type": "integer"
}
},
"required": [
"files",
"total",
"page",
"page_size"
],
"title": "FileListResponse",
"type": "object"
},
"FileUploadResponse": {
"description": "Response model for file upload.",
"properties": {
"content_type": {
"description": "Content type of the file",
"title": "Content Type",
"type": "string"
},
"csv_metadata": {
"additionalProperties": true,
"default": {},
"description": "CSV metadata",
"title": "Csv Metadata",
"type": "object"
},
"file_id": {
"description": "The ID of the uploaded file",
"title": "File Id",
"type": "string"
},
"name": {
"description": "The name of the file",
"title": "Name",
"type": "string"
},
"original_file_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Original file type if converted (e.g., 'xlsx' if XLSX was converted to CSV)",
"title": "Original File Type"
},
"processing_status": {
"$ref": "#/components/schemas/CSVProcessingStatus",
"description": "Processing status"
},
"s3_uri": {
"description": "S3 URI of the uploaded file",
"title": "S3 Uri",
"type": "string"
},
"size_bytes": {
"description": "Size of the file in bytes",
"title": "Size Bytes",
"type": "integer"
}
},
"required": [
"file_id",
"name",
"s3_uri",
"content_type",
"size_bytes",
"processing_status"
],
"title": "FileUploadResponse",
"type": "object"
},
"FloatEntityAttribute": {
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"display": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array"
},
{
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"readOnly": true,
"title": "Display"
},
"references": {
"description": "References to external resources.",
"items": {
"type": "string"
},
"title": "References",
"type": "array"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
},
"value": {
"description": "The value of the attribute.",
"title": "Value",
"type": "number"
}
},
"required": [
"value",
"references",
"display"
],
"title": "FloatEntityAttribute",
"type": "object"
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"title": "Detail",
"type": "array"
}
},
"title": "HTTPValidationError",
"type": "object"
},
"ICPDeletePreviewResponse": {
"description": "Preview of resources that will be deleted with an ICP.\n\nUsed by frontend to display confirmation dialog before cascade delete.\nShows counts for all resource types that will be permanently removed.",
"properties": {
"action_count": {
"description": "Number of actions to delete",
"minimum": 0,
"title": "Action Count",
"type": "integer"
},
"entity_count": {
"description": "Number of entities to delete",
"minimum": 0,
"title": "Entity Count",
"type": "integer"
},
"icp_id": {
"description": "The ICP ID to be deleted",
"title": "Icp Id",
"type": "string"
},
"icp_name": {
"description": "ICP name for confirmation dialog",
"title": "Icp Name",
"type": "string"
},
"schedule_count": {
"description": "Number of schedules to delete",
"minimum": 0,
"title": "Schedule Count",
"type": "integer"
},
"sheet_count": {
"description": "Number of sheets to delete",
"minimum": 0,
"title": "Sheet Count",
"type": "integer"
},
"signal_count": {
"description": "Number of signals to delete",
"minimum": 0,
"title": "Signal Count",
"type": "integer"
},
"task_count": {
"description": "Number of tasks to delete",
"minimum": 0,
"title": "Task Count",
"type": "integer"
},
"total_resource_count": {
"description": "Total count of all resources to delete",
"minimum": 0,
"title": "Total Resource Count",
"type": "integer"
}
},
"required": [
"icp_id",
"icp_name",
"entity_count",
"sheet_count",
"task_count",
"schedule_count",
"signal_count",
"action_count",
"total_resource_count"
],
"title": "ICPDeletePreviewResponse",
"type": "object"
},
"ICPListResponse": {
"description": "Response for listing ICPs.",
"properties": {
"icps": {
"items": {
"$ref": "#/components/schemas/ICPResponse"
},
"title": "Icps",
"type": "array"
},
"page": {
"title": "Page",
"type": "integer"
},
"page_size": {
"title": "Page Size",
"type": "integer"
},
"total": {
"title": "Total",
"type": "integer"
}
},
"required": [
"icps",
"total",
"page",
"page_size"
],
"title": "ICPListResponse",
"type": "object"
},
"ICPResponse": {
"description": "Response model for ICP.",
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"description": {
"title": "Description",
"type": "string"
},
"entity_structure": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/EntityStructureResponse"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "v2 entity structure (lightweight, no descriptions)",
"title": "Entity Structure"
},
"entity_targets": {
"items": {
"$ref": "#/components/schemas/EntityTargetConfigResponse"
},
"title": "Entity Targets",
"type": "array"
},
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"schema_version": {
"default": 1,
"description": "ICP schema version (1 or 2)",
"title": "Schema Version",
"type": "integer"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
}
},
"required": [
"id",
"name",
"description",
"entity_targets",
"created_at",
"updated_at"
],
"title": "ICPResponse",
"type": "object"
},
"ICPRunningStatusResponse": {
"description": "Response model for ICP running status.",
"properties": {
"runs": {
"items": {
"$ref": "#/components/schemas/RunStatusItem"
},
"title": "Runs",
"type": "array"
}
},
"required": [
"runs"
],
"title": "ICPRunningStatusResponse",
"type": "object"
},
"IngestPromptConfigResponse": {
"description": "Ingest prompt configuration in API responses.\n\nResponse model for prompt-based ingest task configs that excludes backend-managed\nfields from the API surface. This is for simple prompt-based ingest workflows,\ndistinct from IngestTaskConfigResponse which is for CSV enrichment tasks.\n\nAttributes:\n type: Config type discriminator (always \"ingest-prompt\").\n prompt: Task prompt template.\n webhook_url: Webhook URL for completion notification.",
"properties": {
"prompt": {
"description": "Task prompt template",
"title": "Prompt",
"type": "string"
},
"type": {
"const": "ingest-prompt",
"default": "ingest-prompt",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Webhook URL for completion notification",
"title": "Webhook Url"
}
},
"required": [
"prompt"
],
"title": "IngestPromptConfigResponse",
"type": "object"
},
"IngestTaskConfigRequest": {
"description": "CSV enrichment task configuration.\n\nEnriches entities from an uploaded CSV file with additional\ndata discovered by AI agents.\n\nAttributes:\n type: Config type discriminator (always \"ingest\").\n file_id: ID of the uploaded CSV file to process.\n primary_column: Column containing entity names for matching.\n csv_entity_type: Entity type in the CSV (e.g., 'person', 'company').\n webhook_url: Optional webhook URL for completion notification.\n\nExample:\n >>> config = IngestTaskConfigRequest(\n ... file_id=\"abc123\",\n ... primary_column=\"company_name\",\n ... csv_entity_type=\"company\"\n ... )",
"properties": {
"csv_entity_type": {
"description": "Entity type in the CSV (e.g., 'person', 'company')",
"title": "Csv Entity Type",
"type": "string"
},
"file_id": {
"description": "ID of the uploaded CSV file to process",
"title": "File Id",
"type": "string"
},
"primary_column": {
"description": "Column containing entity names for matching",
"title": "Primary Column",
"type": "string"
},
"type": {
"const": "ingest",
"default": "ingest",
"description": "Config type discriminator",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional webhook URL to notify when workflow completes",
"title": "Webhook Url"
}
},
"required": [
"file_id",
"primary_column",
"csv_entity_type"
],
"title": "IngestTaskConfigRequest",
"type": "object"
},
"IngestTaskConfigResponse": {
"description": "Ingest task configuration in API responses.\n\nResponse model for CSV enrichment task configs that excludes backend-managed\nfields from the API surface.\n\nAttributes:\n type: Config type discriminator (always \"ingest\").\n file_id: ID of the CSV file.\n primary_column: Column containing entity names.\n csv_entity_type: Entity type in CSV.\n webhook_url: Webhook URL for completion notification.",
"properties": {
"csv_entity_type": {
"description": "Entity type in CSV",
"title": "Csv Entity Type",
"type": "string"
},
"file_id": {
"description": "ID of the CSV file",
"title": "File Id",
"type": "string"
},
"primary_column": {
"description": "Column containing entity names",
"title": "Primary Column",
"type": "string"
},
"type": {
"const": "ingest",
"default": "ingest",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Webhook URL for completion notification",
"title": "Webhook Url"
}
},
"required": [
"file_id",
"primary_column",
"csv_entity_type"
],
"title": "IngestTaskConfigResponse",
"type": "object"
},
"IntEntityAttribute": {
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"display": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array"
},
{
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"readOnly": true,
"title": "Display"
},
"references": {
"description": "References to external resources.",
"items": {
"type": "string"
},
"title": "References",
"type": "array"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
},
"value": {
"description": "The value of the attribute.",
"title": "Value",
"type": "integer"
}
},
"required": [
"value",
"references",
"display"
],
"title": "IntEntityAttribute",
"type": "object"
},
"JsonSchemaDefinition": {
"description": "JSON schema for the sheet.",
"properties": {
"$defs": {
"additionalProperties": true,
"description": "Definitions for nested schemas",
"title": "$Defs",
"type": "object"
},
"properties": {
"additionalProperties": true,
"description": "The properties of the schema",
"title": "Properties",
"type": "object"
},
"required": {
"description": "Required fields in the schema",
"items": {
"type": "string"
},
"title": "Required",
"type": "array"
},
"title": {
"description": "The title of the schema",
"title": "Title",
"type": "string"
},
"type": {
"description": "The type of the schema",
"title": "Type",
"type": "string"
}
},
"required": [
"title",
"type"
],
"title": "JsonSchemaDefinition",
"type": "object"
},
"ListDefaultSheetFieldDefinitions": {
"description": "List of default field definitions for sheets.",
"properties": {
"fields": {
"additionalProperties": {
"$ref": "#/components/schemas/JsonSchemaDefinition"
},
"title": "Fields",
"type": "object"
}
},
"required": [
"fields"
],
"title": "ListDefaultSheetFieldDefinitions",
"type": "object"
},
"ListDefaultSheetSchemas": {
"description": "List of default schemas for sheets.",
"properties": {
"schemas": {
"additionalProperties": {
"$ref": "#/components/schemas/JsonSchemaDefinition"
},
"title": "Schemas",
"type": "object"
}
},
"required": [
"schemas"
],
"title": "ListDefaultSheetSchemas",
"type": "object"
},
"ListEntityAttribute": {
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"display": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array"
},
{
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"readOnly": true,
"title": "Display"
},
"references": {
"description": "References to external resources.",
"items": {
"type": "string"
},
"title": "References",
"type": "array"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
},
"value": {
"description": "The value of the attribute.",
"items": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"oneOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"$ref": "#/components/schemas/Location"
},
{
"$ref": "#/components/schemas/SocialMediaProfile"
},
{
"$ref": "#/components/schemas/CriteriaMatch"
},
{
"$ref": "#/components/schemas/RevenueInfo"
}
]
},
{
"type": "null"
}
]
},
"title": "Value",
"type": "array"
}
},
"required": [
"value",
"references",
"display"
],
"title": "ListEntityAttribute",
"type": "object"
},
"Location": {
"properties": {
"city": {
"description": "City",
"title": "City",
"type": "string"
},
"country": {
"description": "Country",
"title": "Country",
"type": "string"
},
"state": {
"description": "State",
"title": "State",
"type": "string"
},
"street": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Street address",
"title": "Street"
},
"zip_code": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ZIP code",
"title": "Zip Code"
}
},
"required": [
"city",
"state",
"country"
],
"title": "Location",
"type": "object"
},
"NoneEntityAttribute": {
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"display": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array"
},
{
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"readOnly": true,
"title": "Display"
},
"references": {
"description": "References to external resources.",
"items": {
"type": "string"
},
"title": "References",
"type": "array"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
},
"value": {
"description": "The value of the attribute.",
"title": "Value",
"type": "null"
}
},
"required": [
"value",
"references",
"display"
],
"title": "NoneEntityAttribute",
"type": "object"
},
"OnDemandIngestTaskConfigRequest": {
"description": "On-demand ingest task configuration for adding entities to existing ICPs.\n\nCreates a task that ingests additional entities from a CSV file into an\nexisting ICP. Supports declaring which existing sheet fields can be nullable\nfor the new entities and adding new enrichment fields to the sheet schema.\n\nAttributes:\n type: Config type discriminator (always \"ingest-ondemand\").\n file_id: ID of the uploaded CSV file to process.\n primary_column: Column containing entity names for matching.\n csv_entity_type: Entity type in the CSV (e.g., 'person', 'company').\n ignored_fields: Existing sheet fields allowed to be nullable for new entities.\n new_custom_fields: New enrichment fields to add to the sheet schema.\n webhook_url: Optional webhook URL for completion notification.",
"properties": {
"csv_entity_type": {
"description": "Entity type in the CSV (e.g., 'person', 'company')",
"title": "Csv Entity Type",
"type": "string"
},
"file_id": {
"description": "ID of the uploaded CSV file to process",
"title": "File Id",
"type": "string"
},
"ignored_fields": {
"description": "Existing sheet fields allowed to be nullable for new entities",
"items": {
"type": "string"
},
"title": "Ignored Fields",
"type": "array"
},
"new_custom_fields": {
"description": "New enrichment fields to add to sheet schema ({name, description})",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "New Custom Fields",
"type": "array"
},
"primary_column": {
"description": "Column containing entity names for matching",
"title": "Primary Column",
"type": "string"
},
"type": {
"const": "ingest-ondemand",
"default": "ingest-ondemand",
"description": "Config type discriminator",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional webhook URL to notify when workflow completes",
"title": "Webhook Url"
}
},
"required": [
"file_id",
"primary_column",
"csv_entity_type"
],
"title": "OnDemandIngestTaskConfigRequest",
"type": "object"
},
"OnDemandIngestTaskConfigResponse": {
"description": "On-demand ingest task configuration in API responses.\n\nResponse model for on-demand ingest task configs that excludes backend-managed\nfields from the API surface.\n\nAttributes:\n type: Config type discriminator (always \"ingest-ondemand\").\n file_id: ID of the CSV file.\n primary_column: Column containing entity names.\n csv_entity_type: Entity type in CSV.\n ignored_fields: Existing sheet fields allowed to be nullable.\n new_custom_fields: New enrichment fields added to sheet schema.\n webhook_url: Webhook URL for completion notification.",
"properties": {
"csv_entity_type": {
"description": "Entity type in CSV",
"title": "Csv Entity Type",
"type": "string"
},
"file_id": {
"description": "ID of the CSV file",
"title": "File Id",
"type": "string"
},
"ignored_fields": {
"description": "Existing sheet fields allowed to be nullable",
"items": {
"type": "string"
},
"title": "Ignored Fields",
"type": "array"
},
"new_custom_fields": {
"description": "New enrichment fields added to sheet schema",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "New Custom Fields",
"type": "array"
},
"primary_column": {
"description": "Column containing entity names",
"title": "Primary Column",
"type": "string"
},
"type": {
"const": "ingest-ondemand",
"default": "ingest-ondemand",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Webhook URL for completion notification",
"title": "Webhook Url"
}
},
"required": [
"file_id",
"primary_column",
"csv_entity_type"
],
"title": "OnDemandIngestTaskConfigResponse",
"type": "object"
},
"ProfilePromptConfigRequest": {
"description": "Profile prompt task configuration.\n\nConfigures a profile workflow with a custom prompt template.\n\nAttributes:\n type: Config type discriminator (always \"profile\").\n prompt: Jinja2 template for task instructions.\n webhook_url: Optional webhook URL for completion notification.\n\nExample:\n >>> config = ProfilePromptConfigRequest(\n ... prompt=\"Analyze {{ company_name }} and extract key metrics.\"\n ... )",
"properties": {
"prompt": {
"description": "Jinja2 template for task instructions",
"title": "Prompt",
"type": "string"
},
"type": {
"const": "profile",
"default": "profile",
"description": "Config type discriminator",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional webhook URL to notify when workflow completes",
"title": "Webhook Url"
}
},
"required": [
"prompt"
],
"title": "ProfilePromptConfigRequest",
"type": "object"
},
"ProfilePromptConfigResponse": {
"description": "Profile prompt configuration in API responses.\n\nResponse model for profile prompt task configs that excludes backend-managed\nfields from the API surface.\n\nAttributes:\n type: Config type discriminator (always \"profile\").\n prompt: Task prompt template.\n webhook_url: Webhook URL for completion notification.",
"properties": {
"prompt": {
"description": "Task prompt template",
"title": "Prompt",
"type": "string"
},
"type": {
"const": "profile",
"default": "profile",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Webhook URL for completion notification",
"title": "Webhook Url"
}
},
"required": [
"prompt"
],
"title": "ProfilePromptConfigResponse",
"type": "object"
},
"ProviderCreditUsage": {
"description": "Track external provider API credit consumption with action-level granularity.",
"properties": {
"cache_by_action": {
"additionalProperties": {
"type": "number"
},
"description": "Cache hits by action type",
"title": "Cache By Action",
"type": "object"
},
"credits_by_action": {
"additionalProperties": {
"type": "number"
},
"description": "Credits consumed by action type (search_person, enrich_person, etc.)",
"title": "Credits By Action",
"type": "object"
},
"from_cache_count": {
"default": 0,
"description": "Number of cached responses",
"title": "From Cache Count",
"type": "number"
},
"requests_by_action": {
"additionalProperties": {
"type": "number"
},
"description": "Total requests by action type",
"title": "Requests By Action",
"type": "object"
},
"total_credits": {
"default": 0,
"description": "Total credits consumed from provider",
"title": "Total Credits",
"type": "number"
},
"total_requests": {
"default": 0,
"description": "Total requests made to provider",
"title": "Total Requests",
"type": "integer"
}
},
"title": "ProviderCreditUsage",
"type": "object"
},
"ReEnrichRequest": {
"description": "Request to re-enrich discarded entities from a run's queue.",
"properties": {
"icp_id": {
"description": "ICP ID to use for re-enrichment (target ICP for new entities)",
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
},
"queue_ids": {
"description": "Queue IDs of discarded entities to re-enrich",
"items": {
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"title": "Queue Ids",
"type": "array"
}
},
"required": [
"queue_ids",
"icp_id"
],
"title": "ReEnrichRequest",
"type": "object"
},
"ReEnrichResponse": {
"description": "Response from re-enrich endpoint.",
"properties": {
"entity_count": {
"description": "Number of entities being re-enriched",
"title": "Entity Count",
"type": "integer"
},
"flow_run_id": {
"description": "Prefect flow run ID for tracking",
"title": "Flow Run Id",
"type": "string"
},
"run_id": {
"description": "ID of the newly created re-enrichment run",
"title": "Run Id",
"type": "string"
},
"status": {
"description": "Initial run status (typically SCHEDULED)",
"title": "Status",
"type": "string"
}
},
"required": [
"run_id",
"flow_run_id",
"status",
"entity_count"
],
"title": "ReEnrichResponse",
"type": "object"
},
"RemoveFieldsFromSheetRequest": {
"properties": {
"fields": {
"items": {
"type": "string"
},
"title": "Fields",
"type": "array"
}
},
"required": [
"fields"
],
"title": "RemoveFieldsFromSheetRequest",
"type": "object"
},
"ResourceTrackingSummary": {
"description": "Summary of resources created/modified during workflow execution.\n\nContains only IDs for reference - actual entity data is stored separately\nin the database to avoid duplication.",
"properties": {
"entities_created": {
"description": "IDs of created entities",
"items": {
"example": "5eb7cf5a86d9755df3a6c593",
"title": "Id",
"type": "string"
},
"title": "Entities Created",
"type": "array"
},
"entities_updated": {
"description": "IDs of updated entities",
"items": {
"example": "5eb7cf5a86d9755df3a6c593",
"title": "Id",
"type": "string"
},
"title": "Entities Updated",
"type": "array"
},
"signals_created": {
"description": "IDs of created signals",
"items": {
"example": "5eb7cf5a86d9755df3a6c593",
"title": "Id",
"type": "string"
},
"title": "Signals Created",
"type": "array"
}
},
"title": "ResourceTrackingSummary",
"type": "object"
},
"RevenueInfo": {
"description": "Structured revenue information with source type.\n\nThis replaces the simple string revenue field to provide:\n- amount: The formatted revenue string (e.g., \"$50M\", \"$2B-$3B\")\n- type: The source/confidence level of the revenue data\n\nExamples:\n >>> revenue = RevenueInfo(amount=\"$50M\", type=\"validated\")\n >>> revenue.to_display()\n '$50M'\n\n >>> revenue = RevenueInfo(amount=None, type=\"estimated\")\n >>> revenue.to_display()\n 'Undisclosed'",
"properties": {
"amount": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Formatted revenue amount (e.g., '$50M', '$2B-$3B', '$500K')",
"title": "Amount"
},
"type": {
"$ref": "#/components/schemas/RevenueType",
"default": "validated",
"description": "Source/confidence type: validated, cited, or estimated"
}
},
"title": "RevenueInfo",
"type": "object"
},
"RevenueType": {
"description": "Revenue source/confidence type.\n\n- validated: Authoritative source (Apollo, SEC filings, public earnings)\n- cited: Third-party source with URL reference (news, press releases)\n- estimated: AI-estimated based on company signals",
"enum": [
"validated",
"cited",
"estimated"
],
"title": "RevenueType",
"type": "string"
},
"RunListResponse": {
"description": "Response schema for paginated list of agent runs.\n\nFollows the established pattern from other list endpoints:\n- SheetListResponse (src/api/schema/sheet.py)\n- ICPListResponse (src/api/schema/icp.py)\n\nAttributes:\n runs: List of AgentRun objects for the current page (metadata excluded)\n total: Total number of runs matching the filter criteria\n page: Current page number (1-based)\n page_size: Number of items per page",
"properties": {
"page": {
"title": "Page",
"type": "integer"
},
"page_size": {
"title": "Page Size",
"type": "integer"
},
"runs": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Runs",
"type": "array"
},
"total": {
"title": "Total",
"type": "integer"
}
},
"required": [
"runs",
"total",
"page",
"page_size"
],
"title": "RunListResponse",
"type": "object"
},
"RunQueueResponse": {
"description": "Response schema for run queue status with optional history.\n\nProvides a read-only view into the current state of a run's entity queue,\nincluding queued entities, processing history, and statistics.\n\nAttributes:\n entities: List of entities (current queue or full history based on request)\n stats: Queue statistics or state counts\n total: Total number of entities returned\n offset: Offset used for pagination (0-indexed)\n limit: Maximum number of entities returned\n state_counts: Optional breakdown of entities by state\n include_history: Whether response includes historical data\n queue_data_available: Whether queue data is still available in Redis\n queue_data_message: Optional message about queue data availability",
"properties": {
"entities": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Entities",
"type": "array"
},
"include_history": {
"default": false,
"title": "Include History",
"type": "boolean"
},
"limit": {
"title": "Limit",
"type": "integer"
},
"offset": {
"title": "Offset",
"type": "integer"
},
"queue_data_available": {
"default": true,
"title": "Queue Data Available",
"type": "boolean"
},
"queue_data_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Queue Data Message"
},
"state_counts": {
"anyOf": [
{
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "State Counts"
},
"stats": {
"additionalProperties": true,
"title": "Stats",
"type": "object"
},
"total": {
"title": "Total",
"type": "integer"
}
},
"required": [
"entities",
"stats",
"total",
"offset",
"limit"
],
"title": "RunQueueResponse",
"type": "object"
},
"RunStatusItem": {
"description": "Individual run status item for API responses.\n\nIncludes both agent_type (execution context) and task_type (workflow type) fields\nto support filtering and display during the transition from legacy runs.\n\nAttributes:\n id: Unique run identifier (ObjectId as string)\n agent_type: HOW the run was triggered (for example, \"task\")\n task_type: WHAT workflow runs (\"signal\", \"search\", \"profile\", \"ingest\").\n None for legacy runs without this field.\n created_at: When the run was created",
"properties": {
"agent_type": {
"description": "Execution context (for example, task)",
"title": "Agent Type",
"type": "string"
},
"created_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"description": "Creation timestamp",
"title": "Created At"
},
"id": {
"description": "Run ID",
"title": "Id",
"type": "string"
},
"task_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Workflow type for task-based runs (signal, search, profile, ingest)",
"title": "Task Type"
}
},
"required": [
"id",
"agent_type"
],
"title": "RunStatusItem",
"type": "object"
},
"ScheduleListResponse": {
"description": "Response model for paginated schedule list.\n\nAttributes:\n schedules: List of schedules.\n total: Total number of schedules matching filters.\n page: Current page number (1-based).\n page_size: Number of items per page.",
"properties": {
"page": {
"description": "Current page number (1-based)",
"title": "Page",
"type": "integer"
},
"page_size": {
"description": "Number of items per page",
"title": "Page Size",
"type": "integer"
},
"schedules": {
"description": "List of schedules",
"items": {
"$ref": "#/components/schemas/ScheduleResponse"
},
"title": "Schedules",
"type": "array"
},
"total": {
"description": "Total number of schedules matching filters",
"title": "Total",
"type": "integer"
}
},
"required": [
"schedules",
"total",
"page",
"page_size"
],
"title": "ScheduleListResponse",
"type": "object"
},
"ScheduleResponse": {
"description": "Response model for schedule data.\n\nAttributes:\n id: Schedule ID.\n name: Schedule name.\n task_id: Task ID.\n icp_id: ICP ID.\n cron_expression: Cron expression.\n status: Schedule status.\n description: Optional description.\n parameters: Execution parameters.\n created_at: Creation timestamp.\n updated_at: Last update timestamp.",
"properties": {
"created_at": {
"description": "Creation timestamp",
"format": "date-time",
"title": "Created At",
"type": "string"
},
"cron_expression": {
"description": "Cron expression",
"title": "Cron Expression",
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Description",
"title": "Description"
},
"icp_id": {
"description": "ICP ID",
"title": "Icp Id",
"type": "string"
},
"id": {
"description": "Schedule ID",
"title": "Id",
"type": "string"
},
"name": {
"description": "Schedule name",
"title": "Name",
"type": "string"
},
"parameters": {
"additionalProperties": true,
"description": "Execution parameters",
"title": "Parameters",
"type": "object"
},
"status": {
"description": "Schedule status",
"title": "Status",
"type": "string"
},
"task_id": {
"description": "Task ID",
"title": "Task Id",
"type": "string"
},
"updated_at": {
"description": "Last update timestamp",
"format": "date-time",
"title": "Updated At",
"type": "string"
}
},
"required": [
"id",
"name",
"task_id",
"icp_id",
"cron_expression",
"status",
"created_at",
"updated_at"
],
"title": "ScheduleResponse",
"type": "object"
},
"ScheduleStatus": {
"description": "Schedule status values.\n\nACTIVE: Schedule is eligible for execution\nPAUSED: Temporarily suspended but can be resumed\nDISABLED: Permanently disabled (requires manual intervention)",
"enum": [
"active",
"paused",
"disabled"
],
"title": "ScheduleStatus",
"type": "string"
},
"SearchTaskConfigRequest": {
"description": "Search task configuration for finding companies and contacts.\n\nCreates a v3.0 search workflow that uses AI agents to discover\nentities matching your ICP criteria.\n\nAttributes:\n type: Config type discriminator (always \"search\").\n desired_contact_count: Number of contacts to find per company (minimum: 1).\n user_feedback: Optional feedback to refine search behavior.\n webhook_url: Optional webhook URL for completion notification.\n\nExample:\n >>> config = SearchTaskConfigRequest(desired_contact_count=5)\n >>> mongo_config = config.to_mongo_config()\n >>> mongo_config.version\n 'v3.0'",
"properties": {
"company_input": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Known company name or URL for company lookup mode",
"title": "Company Input"
},
"desired_contact_count": {
"default": 1,
"description": "Number of contacts to find per company (minimum: 1)",
"minimum": 1,
"title": "Desired Contact Count",
"type": "integer"
},
"type": {
"const": "search",
"default": "search",
"description": "Config type discriminator",
"title": "Type",
"type": "string"
},
"user_feedback": {
"default": "",
"description": "Optional feedback to refine search behavior",
"title": "User Feedback",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional webhook URL to notify when workflow completes",
"title": "Webhook Url"
}
},
"title": "SearchTaskConfigRequest",
"type": "object"
},
"SearchTaskConfigResponse": {
"description": "Search task configuration in API responses.\n\nResponse model for search task configs that excludes backend-managed fields\n(version, config_type) from the API surface.\n\nAttributes:\n type: Config type discriminator (always \"search\").\n desired_contact_count: Number of contacts to find per company.\n user_feedback: Feedback to refine search behavior.\n webhook_url: Webhook URL for completion notification.",
"properties": {
"company_input": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Known company name or URL for company lookup mode",
"title": "Company Input"
},
"desired_contact_count": {
"description": "Number of contacts to find per company",
"title": "Desired Contact Count",
"type": "integer"
},
"type": {
"const": "search",
"default": "search",
"title": "Type",
"type": "string"
},
"user_feedback": {
"description": "Feedback to refine search behavior",
"title": "User Feedback",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Webhook URL for completion notification",
"title": "Webhook Url"
}
},
"required": [
"desired_contact_count",
"user_feedback"
],
"title": "SearchTaskConfigResponse",
"type": "object"
},
"SheetListResponse": {
"description": "Response model for sheet list.",
"properties": {
"page": {
"title": "Page",
"type": "integer"
},
"page_size": {
"title": "Page Size",
"type": "integer"
},
"sheets": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Sheets",
"type": "array"
},
"total": {
"title": "Total",
"type": "integer"
}
},
"required": [
"sheets",
"total",
"page",
"page_size"
],
"title": "SheetListResponse",
"type": "object"
},
"SheetResponse": {
"description": "Response model for sheet.",
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"description": {
"title": "Description",
"type": "string"
},
"entity_schema": {
"additionalProperties": true,
"title": "Entity Schema",
"type": "object"
},
"entity_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Entity Type"
},
"icp_id": {
"title": "Icp Id",
"type": "string"
},
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
}
},
"required": [
"id",
"name",
"description",
"icp_id",
"entity_schema",
"created_at",
"updated_at"
],
"title": "SheetResponse",
"type": "object"
},
"SignalCSVConfigRequest": {
"description": "CSV-based signal monitoring configuration.\n\nMonitors signals for entities uploaded via CSV file.\n\nAttributes:\n type: Config type discriminator (always \"signal-csv\").\n file_id: ID of the uploaded CSV file.\n signal_types: Types of signals to monitor.\n entity_type: Type of entity being monitored (default: company).\n primary_column: Column containing entity names (default: \"name\").\n monitoring_frequency: How often to check (daily/weekly/monthly).\n webhook_url: Optional webhook URL for completion notification.\n\nExample:\n >>> config = SignalCSVConfigRequest(\n ... file_id=\"abc123\",\n ... signal_types=[SignalTypeConfig(type=\"hiring_surge\", ...)]\n ... )",
"properties": {
"entity_type": {
"$ref": "#/components/schemas/EntityType",
"default": "company",
"description": "Type of entity being monitored"
},
"file_id": {
"description": "ID of the uploaded CSV file",
"title": "File Id",
"type": "string"
},
"monitoring_frequency": {
"default": "weekly",
"description": "How often to check for new signals",
"enum": [
"daily",
"weekly",
"monthly"
],
"title": "Monitoring Frequency",
"type": "string"
},
"primary_column": {
"default": "name",
"description": "Column containing entity names",
"title": "Primary Column",
"type": "string"
},
"signal_types": {
"description": "Types of signals to monitor",
"items": {
"$ref": "#/components/schemas/SignalTypeConfig"
},
"title": "Signal Types",
"type": "array"
},
"type": {
"const": "signal-csv",
"default": "signal-csv",
"description": "Config type discriminator",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional webhook URL to notify when workflow completes",
"title": "Webhook Url"
}
},
"required": [
"file_id",
"signal_types"
],
"title": "SignalCSVConfigRequest",
"type": "object"
},
"SignalCSVConfigResponse": {
"description": "Signal CSV configuration in API responses.\n\nResponse model for CSV-based signal monitoring configs.\n\nAttributes:\n type: Config type discriminator (always \"signal-csv\").\n file_id: CSV file ID.\n signal_types: Types of signals to monitor.\n entity_type: Type of entity being monitored.\n primary_column: Primary column for entity names.\n monitoring_frequency: How often to check for signals.\n webhook_url: Webhook URL for completion notification.",
"properties": {
"entity_type": {
"$ref": "#/components/schemas/EntityType",
"description": "Entity type"
},
"file_id": {
"description": "CSV file ID",
"title": "File Id",
"type": "string"
},
"monitoring_frequency": {
"description": "Monitoring frequency",
"enum": [
"daily",
"weekly",
"monthly"
],
"title": "Monitoring Frequency",
"type": "string"
},
"primary_column": {
"description": "Primary column",
"title": "Primary Column",
"type": "string"
},
"signal_types": {
"description": "Signal types",
"items": {
"$ref": "#/components/schemas/SignalTypeConfig"
},
"title": "Signal Types",
"type": "array"
},
"type": {
"const": "signal-csv",
"default": "signal-csv",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Webhook URL for completion notification",
"title": "Webhook Url"
}
},
"required": [
"file_id",
"signal_types",
"entity_type",
"primary_column",
"monitoring_frequency"
],
"title": "SignalCSVConfigResponse",
"type": "object"
},
"SignalListResponse": {
"description": "Response for listing signals.",
"properties": {
"page": {
"title": "Page",
"type": "integer"
},
"page_size": {
"title": "Page Size",
"type": "integer"
},
"signals": {
"items": {
"$ref": "#/components/schemas/SignalResponse"
},
"title": "Signals",
"type": "array"
},
"total": {
"title": "Total",
"type": "integer"
}
},
"required": [
"signals",
"total",
"page",
"page_size"
],
"title": "SignalListResponse",
"type": "object"
},
"SignalResponse": {
"description": "Response model for signals (read-only).",
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"entity_ids": {
"items": {
"type": "string"
},
"title": "Entity Ids",
"type": "array"
},
"icp_id": {
"title": "Icp Id",
"type": "string"
},
"id": {
"title": "Id",
"type": "string"
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"references": {
"items": {
"type": "string"
},
"title": "References",
"type": "array"
},
"score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Score"
},
"signal_display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Signal Display Name"
},
"signal_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Signal Type"
},
"strength": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Strength"
},
"summary": {
"title": "Summary",
"type": "string"
}
},
"required": [
"id",
"icp_id",
"entity_ids",
"summary",
"signal_type",
"strength",
"score",
"references",
"created_at"
],
"title": "SignalResponse",
"type": "object"
},
"SignalSheetConfigRequest": {
"description": "Sheet-based signal monitoring configuration.\n\nMonitors signals for entities from an existing discovery ICP's sheet.\n\nAttributes:\n type: Config type discriminator (always \"signal-sheet\").\n source_icp_id: ID of the discovery ICP containing entities to monitor.\n signal_types: Types of signals to monitor.\n entity_type: Type of entity being monitored (default: company).\n entity_filters: Optional MongoDB query to filter entities.\n monitoring_frequency: How often to check (daily/weekly/monthly).\n webhook_url: Optional webhook URL for completion notification.\n\nExample:\n >>> config = SignalSheetConfigRequest(\n ... source_icp_id=\"icp123\",\n ... signal_types=[SignalTypeConfig(type=\"leadership_change\", ...)]\n ... )",
"properties": {
"entity_filters": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Optional MongoDB query to filter entities",
"title": "Entity Filters"
},
"entity_type": {
"$ref": "#/components/schemas/EntityType",
"default": "company",
"description": "Type of entity being monitored"
},
"monitoring_frequency": {
"default": "weekly",
"description": "How often to check for new signals",
"enum": [
"daily",
"weekly",
"monthly"
],
"title": "Monitoring Frequency",
"type": "string"
},
"signal_types": {
"description": "Types of signals to monitor",
"items": {
"$ref": "#/components/schemas/SignalTypeConfig"
},
"title": "Signal Types",
"type": "array"
},
"source_icp_id": {
"description": "ID of the discovery ICP containing entities to monitor",
"title": "Source Icp Id",
"type": "string"
},
"type": {
"const": "signal-sheet",
"default": "signal-sheet",
"description": "Config type discriminator",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional webhook URL to notify when workflow completes",
"title": "Webhook Url"
}
},
"required": [
"source_icp_id",
"signal_types"
],
"title": "SignalSheetConfigRequest",
"type": "object"
},
"SignalSheetConfigResponse": {
"description": "Signal sheet configuration in API responses.\n\nResponse model for sheet-based signal monitoring configs.\n\nAttributes:\n type: Config type discriminator (always \"signal-sheet\").\n source_icp_id: Source ICP ID containing entities to monitor.\n signal_types: Types of signals to monitor.\n entity_type: Type of entity being monitored.\n entity_filters: Optional MongoDB query to filter entities.\n monitoring_frequency: How often to check for signals.\n webhook_url: Webhook URL for completion notification.",
"properties": {
"entity_filters": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Entity filters",
"title": "Entity Filters"
},
"entity_type": {
"$ref": "#/components/schemas/EntityType",
"description": "Entity type"
},
"monitoring_frequency": {
"description": "Monitoring frequency",
"enum": [
"daily",
"weekly",
"monthly"
],
"title": "Monitoring Frequency",
"type": "string"
},
"signal_types": {
"description": "Signal types",
"items": {
"$ref": "#/components/schemas/SignalTypeConfig"
},
"title": "Signal Types",
"type": "array"
},
"source_icp_id": {
"description": "Source ICP ID",
"title": "Source Icp Id",
"type": "string"
},
"type": {
"const": "signal-sheet",
"default": "signal-sheet",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Webhook URL for completion notification",
"title": "Webhook Url"
}
},
"required": [
"source_icp_id",
"signal_types",
"entity_type",
"monitoring_frequency"
],
"title": "SignalSheetConfigResponse",
"type": "object"
},
"SignalTopicConfigRequest": {
"description": "Topic-based signal monitoring configuration.\n\nMonitors for signals based on topic criteria without requiring\npre-existing entities.\n\nAttributes:\n type: Config type discriminator (always \"signal-topic\").\n topic_criteria: Natural language description of what to monitor.\n signal_types: Types of signals to monitor.\n entity_type: Type of entity being monitored (default: company).\n monitoring_frequency: How often to check (daily/weekly/monthly).\n geographic_filters: Optional geographic regions to focus on.\n industry_filters: Optional industries to focus on.\n company_size_filters: Optional company size criteria.\n webhook_url: Optional webhook URL for completion notification.\n\nExample:\n >>> config = SignalTopicConfigRequest(\n ... topic_criteria=\"AI startups raising Series A\",\n ... signal_types=[SignalTypeConfig(type=\"funding\", ...)]\n ... )",
"properties": {
"company_size_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Company size criteria",
"title": "Company Size Filters"
},
"entity_type": {
"$ref": "#/components/schemas/EntityType",
"default": "company",
"description": "Type of entity being monitored"
},
"geographic_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Geographic regions to focus on",
"title": "Geographic Filters"
},
"industry_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Industries to focus on",
"title": "Industry Filters"
},
"monitoring_frequency": {
"default": "weekly",
"description": "How often to check for new signals",
"enum": [
"daily",
"weekly",
"monthly"
],
"title": "Monitoring Frequency",
"type": "string"
},
"signal_types": {
"description": "Types of signals to monitor",
"items": {
"$ref": "#/components/schemas/SignalTypeConfig"
},
"title": "Signal Types",
"type": "array"
},
"topic_criteria": {
"description": "Natural language description of what to monitor",
"title": "Topic Criteria",
"type": "string"
},
"type": {
"const": "signal-topic",
"default": "signal-topic",
"description": "Config type discriminator",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional webhook URL to notify when workflow completes",
"title": "Webhook Url"
}
},
"required": [
"topic_criteria",
"signal_types"
],
"title": "SignalTopicConfigRequest",
"type": "object"
},
"SignalTopicConfigResponse": {
"description": "Signal topic configuration in API responses.\n\nResponse model for topic-based signal monitoring configs.\n\nAttributes:\n type: Config type discriminator (always \"signal-topic\").\n topic_criteria: Topic criteria for monitoring.\n signal_types: Types of signals to monitor.\n entity_type: Type of entity being monitored.\n monitoring_frequency: How often to check for signals.\n geographic_filters: Geographic regions to focus on.\n industry_filters: Industries to focus on.\n company_size_filters: Company size criteria.\n webhook_url: Webhook URL for completion notification.",
"properties": {
"company_size_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Size filters",
"title": "Company Size Filters"
},
"entity_type": {
"$ref": "#/components/schemas/EntityType",
"description": "Entity type"
},
"geographic_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Geographic filters",
"title": "Geographic Filters"
},
"industry_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Industry filters",
"title": "Industry Filters"
},
"monitoring_frequency": {
"description": "Monitoring frequency",
"enum": [
"daily",
"weekly",
"monthly"
],
"title": "Monitoring Frequency",
"type": "string"
},
"signal_types": {
"description": "Signal types",
"items": {
"$ref": "#/components/schemas/SignalTypeConfig"
},
"title": "Signal Types",
"type": "array"
},
"topic_criteria": {
"description": "Topic criteria",
"title": "Topic Criteria",
"type": "string"
},
"type": {
"const": "signal-topic",
"default": "signal-topic",
"title": "Type",
"type": "string"
},
"webhook_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Webhook URL for completion notification",
"title": "Webhook Url"
}
},
"required": [
"topic_criteria",
"signal_types",
"entity_type",
"monitoring_frequency"
],
"title": "SignalTopicConfigResponse",
"type": "object"
},
"SignalType": {
"description": "Categories of business signals that indicate important entity changes.",
"enum": [
"funding",
"leadership_change",
"layoff",
"product_launch",
"partnership",
"acquisition",
"expansion",
"award",
"pivot",
"regulatory",
"rfp",
"contract_renewal",
"hiring_surge",
"infrastructure",
"compliance",
"job_posting",
"other"
],
"title": "SignalType",
"type": "string"
},
"SignalTypeConfig": {
"description": "Configuration for a single signal type to monitor.\n\nAllows both standard signal types and custom types using OTHER.",
"properties": {
"description": {
"description": "Detailed description of what to monitor",
"title": "Description",
"type": "string"
},
"display": {
"description": "Display name for this signal type",
"title": "Display",
"type": "string"
},
"type": {
"$ref": "#/components/schemas/SignalType",
"description": "Signal type to monitor (use OTHER for custom types)"
}
},
"required": [
"type",
"display",
"description"
],
"title": "SignalTypeConfig",
"type": "object"
},
"SocialMediaProfile": {
"properties": {
"platform": {
"description": "Social media platform name",
"enum": [
"linkedin",
"x",
"instagram",
"unkown"
],
"title": "Platform",
"type": "string"
},
"url": {
"description": "URL of the social media profile",
"title": "Url",
"type": "string"
}
},
"required": [
"platform",
"url"
],
"title": "SocialMediaProfile",
"type": "object"
},
"StringEntityAttribute": {
"properties": {
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"display": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "array"
},
{
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"readOnly": true,
"title": "Display"
},
"references": {
"description": "References to external resources.",
"items": {
"type": "string"
},
"title": "References",
"type": "array"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
},
"value": {
"description": "The value of the attribute.",
"title": "Value",
"type": "string"
}
},
"required": [
"value",
"references",
"display"
],
"title": "StringEntityAttribute",
"type": "object"
},
"StructuredOutput": {
"additionalProperties": false,
"description": "Unified output format for all workflow executions.\n\nExposes structured information to users including:\n- Credit consumption tracking\n- Resource creation/modification summary (entity/signal IDs only)\n- Workflow execution timing\n\nNOTE: Raw entity data is NOT stored here - entities are already persisted\nin the database. Only IDs are stored for reference purposes.",
"properties": {
"credits": {
"anyOf": [
{
"$ref": "#/components/schemas/CreditUsageSummary"
},
{
"type": "null"
}
],
"description": "Credit consumption details"
},
"resources": {
"anyOf": [
{
"$ref": "#/components/schemas/ResourceTrackingSummary"
},
{
"type": "null"
}
],
"description": "Resources created/modified (IDs only)"
},
"run_time": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"description": "Flow run duration in seconds",
"title": "Run Time"
},
"version": {
"default": "1.0",
"description": "Output format version",
"title": "Version",
"type": "string"
}
},
"title": "StructuredOutput",
"type": "object"
},
"TaskListResponse": {
"description": "Response model for paginated task list.\n\nAttributes:\n tasks: List of tasks.\n total: Total number of tasks matching filters.\n page: Current page number (1-based).\n page_size: Number of items per page.",
"properties": {
"page": {
"description": "Current page number (1-based)",
"title": "Page",
"type": "integer"
},
"page_size": {
"description": "Number of items per page",
"title": "Page Size",
"type": "integer"
},
"tasks": {
"description": "List of tasks",
"items": {
"$ref": "#/components/schemas/TaskResponse"
},
"title": "Tasks",
"type": "array"
},
"total": {
"description": "Total number of tasks matching filters",
"title": "Total",
"type": "integer"
}
},
"required": [
"tasks",
"total",
"page",
"page_size"
],
"title": "TaskListResponse",
"type": "object"
},
"TaskResponse": {
"description": "Response model for task data.\n\nUses TaskConfigResponse discriminated union for proper OpenAPI schema\ngeneration with type-based discrimination.\n\nAttributes:\n id: Task ID.\n name: Task name.\n description: Task description.\n icp_id: Task ICP ID.\n flow_name: Prefect flow name.\n deployment_name: Prefect deployment name.\n prompt: Template prompt for the task.\n task_config: Flow-specific task configuration.\n created_at: Creation timestamp.\n updated_at: Last update timestamp.",
"properties": {
"created_at": {
"description": "Creation timestamp",
"format": "date-time",
"title": "Created At",
"type": "string"
},
"deployment_name": {
"description": "Prefect deployment name",
"title": "Deployment Name",
"type": "string"
},
"description": {
"description": "Task description",
"title": "Description",
"type": "string"
},
"flow_name": {
"description": "Prefect flow name",
"title": "Flow Name",
"type": "string"
},
"icp_id": {
"anyOf": [
{
"example": "5eb7cf5a86d9755df3a6c593",
"title": "Id",
"type": "string"
},
{
"type": "null"
}
],
"description": "Task ICP ID",
"title": "Icp Id"
},
"id": {
"description": "Task ID",
"title": "Id",
"type": "string"
},
"name": {
"description": "Task name",
"title": "Name",
"type": "string"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": "",
"description": "Template prompt for the task. Can include placeholders for runtime parameters.",
"title": "Prompt"
},
"task_config": {
"anyOf": [
{
"discriminator": {
"mapping": {
"ingest": "#/components/schemas/IngestTaskConfigResponse",
"ingest-ondemand": "#/components/schemas/OnDemandIngestTaskConfigResponse",
"ingest-prompt": "#/components/schemas/IngestPromptConfigResponse",
"profile": "#/components/schemas/ProfilePromptConfigResponse",
"search": "#/components/schemas/SearchTaskConfigResponse",
"signal-csv": "#/components/schemas/SignalCSVConfigResponse",
"signal-sheet": "#/components/schemas/SignalSheetConfigResponse",
"signal-topic": "#/components/schemas/SignalTopicConfigResponse"
},
"propertyName": "type"
},
"oneOf": [
{
"$ref": "#/components/schemas/SearchTaskConfigResponse"
},
{
"$ref": "#/components/schemas/IngestTaskConfigResponse"
},
{
"$ref": "#/components/schemas/OnDemandIngestTaskConfigResponse"
},
{
"$ref": "#/components/schemas/IngestPromptConfigResponse"
},
{
"$ref": "#/components/schemas/ProfilePromptConfigResponse"
},
{
"$ref": "#/components/schemas/SignalTopicConfigResponse"
},
{
"$ref": "#/components/schemas/SignalCSVConfigResponse"
},
{
"$ref": "#/components/schemas/SignalSheetConfigResponse"
}
]
},
{
"type": "null"
}
],
"description": "Flow-specific task configuration",
"title": "Task Config"
},
"updated_at": {
"description": "Last update timestamp",
"format": "date-time",
"title": "Updated At",
"type": "string"
}
},
"required": [
"id",
"name",
"description",
"flow_name",
"deployment_name",
"created_at",
"updated_at"
],
"title": "TaskResponse",
"type": "object"
},
"TokenUsage": {
"properties": {
"total_cached_input_token_count": {
"default": 0,
"title": "Total Cached Input Token Count",
"type": "integer"
},
"total_input_token_count": {
"default": 0,
"title": "Total Input Token Count",
"type": "integer"
},
"total_output_token_count": {
"default": 0,
"title": "Total Output Token Count",
"type": "integer"
}
},
"title": "TokenUsage",
"type": "object"
},
"UpdateEntityRequest": {
"description": "Request to update entity fields.\n\nAll fields optional for partial updates. Status can be updated to any\nvalid EntityStatus value (new, reviewed, passed, contacted) or null to clear.\n\nPropagation flags control whether updates cascade to related entities:\n- propagate_to_family: Update parent/child entities (default: True)\n- propagate_to_duplicates: Update duplicate entities across ICPs (default: False)",
"properties": {
"comments": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Update comments (null to clear)",
"title": "Comments"
},
"propagate_to_duplicates": {
"default": false,
"description": "Reflect updates to duplicate entities across ICPs (default: False)",
"title": "Propagate To Duplicates",
"type": "boolean"
},
"propagate_to_family": {
"default": true,
"description": "Reflect updates to parent/child entities (default: True)",
"title": "Propagate To Family",
"type": "boolean"
},
"status": {
"anyOf": [
{
"$ref": "#/components/schemas/EntityStatus"
},
{
"type": "null"
}
],
"description": "Update workflow status (new, reviewed, passed, contacted)"
}
},
"title": "UpdateEntityRequest",
"type": "object"
},
"UpdateICPRequest": {
"description": "Request to update an ICP.",
"properties": {
"description": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"entity_targets": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/EntityTargetConfigRequest"
},
"minItems": 1,
"type": "array"
},
{
"type": "null"
}
],
"title": "Entity Targets"
},
"name": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
}
},
"title": "UpdateICPRequest",
"type": "object"
},
"UpdateScheduleRequest": {
"description": "Request model for updating a schedule.\n\nAt least one field must be provided.\n\nAttributes:\n name: Updated schedule name.\n description: Updated description.\n cron_expression: Updated cron expression (validated for frequency).\n parameters: Updated execution parameters.\n status: Updated schedule status.",
"properties": {
"cron_expression": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Updated cron expression",
"title": "Cron Expression"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Updated description",
"title": "Description"
},
"name": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Updated schedule name",
"title": "Name"
},
"parameters": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Updated execution parameters",
"title": "Parameters"
},
"status": {
"anyOf": [
{
"$ref": "#/components/schemas/ScheduleStatus"
},
{
"type": "null"
}
],
"description": "Updated status (active, paused, disabled)"
}
},
"title": "UpdateScheduleRequest",
"type": "object"
},
"UpdateSheetRequest": {
"description": "Request to update a sheet.",
"properties": {
"description": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"icp_id": {
"anyOf": [
{
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
},
{
"type": "null"
}
],
"title": "Icp Id"
},
"name": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
}
},
"title": "UpdateSheetRequest",
"type": "object"
},
"UpdateTaskRequest": {
"description": "Request model for updating an existing task.\n\nUses TaskConfigRequest discriminated union for proper OpenAPI schema\ngeneration with type-based discrimination.\n\nAttributes:\n name: Updated task name.\n description: Updated task description.\n deployment_name: Updated deployment name.\n icp_id: Updated ICP Connection.\n prompt: Updated task prompt template.\n task_config: Updated flow-specific task configuration.",
"properties": {
"deployment_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Updated deployment name",
"title": "Deployment Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Updated task description",
"title": "Description"
},
"icp_id": {
"anyOf": [
{
"example": "5eb7cf5a86d9755df3a6c593",
"pattern": "^[0-9a-fA-F]{24}$",
"title": "Id",
"type": "string"
},
{
"type": "null"
}
],
"description": "Updated ICP Connection",
"title": "Icp Id"
},
"name": {
"anyOf": [
{
"maxLength": 200,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"description": "Updated task name",
"title": "Name"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Updated task prompt template",
"title": "Prompt"
},
"task_config": {
"anyOf": [
{
"discriminator": {
"mapping": {
"ingest": "#/components/schemas/IngestTaskConfigRequest",
"ingest-ondemand": "#/components/schemas/OnDemandIngestTaskConfigRequest",
"profile": "#/components/schemas/ProfilePromptConfigRequest",
"search": "#/components/schemas/SearchTaskConfigRequest",
"signal-csv": "#/components/schemas/SignalCSVConfigRequest",
"signal-sheet": "#/components/schemas/SignalSheetConfigRequest",
"signal-topic": "#/components/schemas/SignalTopicConfigRequest"
},
"propertyName": "type"
},
"oneOf": [
{
"$ref": "#/components/schemas/SearchTaskConfigRequest"
},
{
"$ref": "#/components/schemas/IngestTaskConfigRequest"
},
{
"$ref": "#/components/schemas/OnDemandIngestTaskConfigRequest"
},
{
"$ref": "#/components/schemas/ProfilePromptConfigRequest"
},
{
"$ref": "#/components/schemas/SignalTopicConfigRequest"
},
{
"$ref": "#/components/schemas/SignalCSVConfigRequest"
},
{
"$ref": "#/components/schemas/SignalSheetConfigRequest"
}
]
},
{
"type": "null"
}
],
"description": "Updated flow-specific task configuration with type discriminator",
"title": "Task Config"
}
},
"title": "UpdateTaskRequest",
"type": "object"
},
"ValidationError": {
"properties": {
"ctx": {
"title": "Context",
"type": "object"
},
"input": {
"title": "Input"
},
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"title": "Location",
"type": "array"
},
"msg": {
"title": "Message",
"type": "string"
},
"type": {
"title": "Error Type",
"type": "string"
}
},
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError",
"type": "object"
},
"_General": {
"description": "General custom field for any type of data.\n\nUses PrivateAttr to store data directly without the problematic 'value' field\nthat caused double-nesting issues. Provides backwards compatibility for\nlegacy formats while ensuring new entities use clean, consistent structure.",
"properties": {},
"title": "_General",
"type": "object"
}
},
"securitySchemes": {
"ApiKeyAuth": {
"description": "API key for authentication. Get your key from the Linkt dashboard.",
"in": "header",
"name": "x-api-key",
"type": "apiKey"
}
}
}