{ "openapi": "3.1.0", "info": { "title": "Databar.ai API", "description": "\n# Authentication\n\nDatabar uses API keys to allow access to the API. You can find your API key in your workspace home page, but to use the REST API you\u2019ll first need to schedule a call with us.\nOur API expects the API key to be included in all API requests to the server in the Header of your request with the key `x-apikey`.\nTo find your API key, head over to your Databar workspace and click Integrations.\n\n**Example:**\n\n`bash\ncurl https://api.databar.ai/v1/user/me -H x-apikey: {YOUR_API_KEY}`", "contact": { "email": "info@databar.ai" }, "version": "0.1.2" }, "paths": { "/v1/user/me": { "get": { "tags": [ "User" ], "summary": "Get user info", "description": "Get information about your current account.", "operationId": "me_v1_user_me_get", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "User info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "first_name": "David", "email": "david@databar.ai", "balance": 100.0, "plan": "Pro", "workspace": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } }, "429": { "description": "Upstream rate limit; retry after Retry-After when present", "content": { "application/json": { "example": { "detail": "Too many requests. Please retry later." } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Forbidden" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/enrichments/": { "get": { "tags": [ "Enrichment" ], "summary": "Get available enrichments", "description": "Retrieves enrichments available on Databar. Use the search parameter to filter results by keyword.\n\n**Pagination:** pass `page` to receive a paginated envelope (`{items, page, limit, has_next_page, total_count}`).\n\n**\u26a0\ufe0f Deprecated:** calling without `page` returns a plain JSON array for backward compatibility. This form will be removed in a future version \u2014 always pass `page` for new integrations.", "operationId": "Enrichments_v1_enrichments__get", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 3, "title": "Search Query", "description": "Query string used for searching through enrichments." }, "description": "Query string used for searching through enrichments.", "example": "Databar" }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page number. Omit for a plain list.", "title": "Page" }, "description": "Page number. Omit for a plain list." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Items per page (max 500). Only used with page.", "default": 50, "title": "Limit" }, "description": "Items per page (max 500). Only used with page." }, { "name": "authorized_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, hides enrichments that require a user-provided API key (BYOK) unless the user has already connected that integration.", "default": true, "title": "Authorized Only" }, "description": "When true, hides enrichments that require a user-provided API key (BYOK) unless the user has already connected that integration." }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by enrichment category name (e.g. 'Company Data', 'Contact Finding').", "title": "Category" }, "description": "Filter by enrichment category name (e.g. 'Company Data', 'Contact Finding')." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "List of enrichments (plain array or paginated envelope)", "content": { "application/json": { "schema": {}, "examples": { "plain_list": { "summary": "Without page param (default, backward-compatible)", "value": [ { "id": 1, "name": "Enrichment 1", "description": "Enrichment 1 description", "data_source": "api_example", "price": 0.01, "pricing": { "type": "fixed" }, "auth_method": "none", "rank": 100, "search_keywords": "keyword1, keyword2", "category": [ { "id": 1, "name": "Company Data" } ] } ] }, "paginated": { "summary": "With ?page=1&limit=50", "value": { "items": [ { "id": 1, "name": "Enrichment 1", "description": "Enrichment 1 description", "data_source": "api_example", "price": 0.01, "pricing": { "type": "fixed" }, "auth_method": "none", "rank": 100, "search_keywords": "keyword1, keyword2", "category": [ { "id": 1, "name": "Company Data" } ] }, { "id": 2, "name": "Enrichment with dynamic pricing", "description": "Price depends on size param", "data_source": "api_example", "price": 0.01, "pricing": { "type": "per_parameter", "parameter": "size" }, "auth_method": "none", "rank": 80, "search_keywords": "", "category": [] } ], "page": 1, "limit": 50, "has_next_page": false, "total_count": 2 } } } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/enrichments/{enrichment_id}": { "get": { "tags": [ "Enrichment" ], "summary": "Get a specific enrichment", "description": "Retrieve detailed information about a specific enrichment by its ID.", "operationId": "get_enrichment_v1_enrichments__enrichment_id__get", "parameters": [ { "name": "enrichment_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the enrichment to retrieve", "title": "Enrichment Id" }, "description": "The ID of the enrichment to retrieve" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentParams" }, "example": { "id": 1, "name": "Enrichment Example", "description": "Description for Enrichment Example", "price": 0.01, "pricing": { "type": "per_parameter", "parameter": "size" }, "params": [ { "name": "param1", "is_required": true, "type_field": "text", "description": "Enter a value" }, { "name": "country", "is_required": false, "type_field": "select", "description": "Select a country", "choices": { "mode": "inline", "items": [ { "id": "us", "name": "United States" }, { "id": "gb", "name": "United Kingdom" } ] } }, { "name": "industry", "is_required": false, "type_field": "select", "description": "Select an industry", "choices": { "mode": "remote", "endpoint": "/v1/enrichments/1/params/industry/choices" } }, { "name": "categories", "is_required": false, "type_field": "mselect", "description": "Select categories", "choices": { "mode": "inline", "items": [ { "id": "tech", "name": "Technology" }, { "id": "finance", "name": "Finance" } ] } } ], "response_fields": [ { "name": "field1", "type_field": "text" } ] } } } }, "403": { "description": "Forbidden access" }, "404": { "description": "Enrichment not found" }, "406": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Check the number of remaining credits or the tariff plan." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/enrichments/{enrichment_id}/run": { "post": { "tags": [ "Enrichment" ], "summary": "Run an enrichment task", "description": "Executes an enrichment task with the provided parameters.\n\n**Pricing:** for enrichments with `pricing.type == \"per_parameter\"`, the cost per request is `price \u00d7 params[pricing.parameter]`. Check `GET /v1/enrichments/{id}` to see the pricing details.", "operationId": "run_v1_enrichments__enrichment_id__run_post", "parameters": [ { "name": "enrichment_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the enrichment to run", "title": "Enrichment Id" }, "description": "The ID of the enrichment to run" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__enrichment__Request" }, "examples": { "normal": { "summary": "A standard request", "description": "Single-page enrichment run", "value": { "params": { "param1": "value1", "param2": "value2" } } }, "with_pagination": { "summary": "Request with pagination", "description": "Fetch 3 pages of results. Each page is billed separately.", "value": { "params": { "query": "software engineer", "location": "New York" }, "pagination": { "pages": 3 } } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__enrichment__Task" }, "example": { "task_id": "123e4567-e89b-12d3-a456-426614174000", "status": "processing" } } } }, "400": { "description": "Invalid params", "content": { "application/json": { "example": { "error": "INVALID_PARAMS", "detail": "Row 1: param1: This field is required.", "rows": [ { "position": 1, "fields": { "param1": [ "This field is required." ] } } ] } } } }, "406": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Check the number of remaining credits or the tariff plan." } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Forbidden" } } } }, "404": { "description": "Enrichment not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/enrichments/{enrichment_id}/bulk-run": { "post": { "tags": [ "Enrichment" ], "summary": "Run Bulk Enrichment", "description": "Submits a bulk enrichment run for the specified enrichment ID.\n\n**Pricing:** for enrichments with `pricing.type == \"per_parameter\"`, the cost per request is `price \u00d7 params[pricing.parameter]`. Check `GET /v1/enrichments/{id}` to see the pricing details.", "operationId": "bulk_run_v1_enrichments__enrichment_id__bulk_run_post", "parameters": [ { "name": "enrichment_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the enrichment to run", "title": "Enrichment Id" }, "description": "The ID of the enrichment to run" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__enrichment__BulkRequest" }, "examples": { "normal": { "summary": "A standard request", "description": "Single-page bulk enrichment run", "value": { "params": [ { "param1": "value1", "param2": "value2" } ] } }, "with_pagination": { "summary": "Bulk request with pagination", "description": "Fetch 3 pages per row. Each page per row is billed separately.", "value": { "params": [ { "query": "software engineer", "location": "New York" }, { "query": "data scientist", "location": "San Francisco" } ], "pagination": { "pages": 3 } } } } } } }, "responses": { "200": { "description": "Successfully submitted the bulk enrichment run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__enrichment__Task" }, "example": { "task_id": "123e4567-e89b-12d3-a456-426614174000", "status": "processing" } } } }, "406": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Check the number of remaining credits or the tariff plan." } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Forbidden" } } } }, "404": { "description": "Enrichment ID does not exist" }, "400": { "description": "Invalid params", "content": { "application/json": { "example": { "error": "INVALID_PARAMS", "detail": "Row 1: param1: This field is required.", "rows": [ { "position": 1, "fields": { "param1": [ "This field is required." ] } } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/enrichments/{enrichment_id}/params/{param_slug}/choices": { "get": { "tags": [ "Enrichment" ], "summary": "Get choices for a parameter", "description": "Returns paginated choices for a select/mselect parameter. Use the `q` parameter to search, and `page`/`limit` for pagination.", "operationId": "get_param_choices_v1_enrichments__enrichment_id__params__param_slug__choices_get", "parameters": [ { "name": "enrichment_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the enrichment", "title": "Enrichment Id" }, "description": "The ID of the enrichment" }, { "name": "param_slug", "in": "path", "required": true, "schema": { "type": "string", "description": "The parameter slug/name", "title": "Param Slug" }, "description": "The parameter slug/name" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Search query to filter choices", "title": "Q" }, "description": "Search query to filter choices" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number", "default": 1, "title": "Page" }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Items per page (max 500)", "default": 100, "title": "Limit" }, "description": "Items per page (max 500)" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Paginated list of choices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChoicesResponse" }, "example": { "items": [ { "id": "us", "name": "United States" }, { "id": "gb", "name": "United Kingdom" } ], "page": 1, "limit": 100, "has_next_page": false, "total_count": 2 } } } }, "403": { "description": "Forbidden access" }, "404": { "description": "Enrichment or parameter not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/exporters/": { "get": { "tags": [ "Exporter" ], "summary": "Get available exporters", "description": "Retrieves exporters (CRM/destination integrations) available on Databar.\n\n**Pagination:** pass `page` to receive a paginated envelope (`{items, page, limit, has_next_page, total_count}`).\n\n**Deprecated:** calling without `page` returns a plain JSON array for backward compatibility. This form will be removed in a future version -- always pass `page` for new integrations.", "operationId": "Exporters_v1_exporters__get", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 3, "title": "Search Query", "description": "Query string used for searching through exporters." }, "description": "Query string used for searching through exporters." }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Page number. Omit for a plain list.", "title": "Page" }, "description": "Page number. Omit for a plain list." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "description": "Items per page (max 500). Only used with page.", "default": 50, "title": "Limit" }, "description": "Items per page (max 500). Only used with page." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "List of exporters (plain array or paginated envelope)", "content": { "application/json": { "schema": {}, "examples": { "plain_list": { "summary": "Without page param (backward-compatible)", "value": [ { "id": 1, "name": "Google Sheets Exporter", "description": "Push data to Google Sheets", "dataset": 42 } ] }, "paginated": { "summary": "With ?page=1&limit=50", "value": { "items": [ { "id": 1, "name": "Google Sheets Exporter", "description": "Push data to Google Sheets", "dataset": 42 } ], "page": 1, "limit": 50, "has_next_page": false, "total_count": 1 } } } } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/exporters/{exporter_id}": { "get": { "tags": [ "Exporter" ], "summary": "Get a specific exporter", "description": "Retrieve detailed information about a specific exporter by its ID, including its input parameters and output fields.", "operationId": "get_exporter_v1_exporters__exporter_id__get", "parameters": [ { "name": "exporter_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The ID of the exporter to retrieve", "title": "Exporter Id" }, "description": "The ID of the exporter to retrieve" }, { "name": "authorization", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optional connection id used to fetch provider dynamic fields (HubSpot/Pipedrive properties). When omitted, the first active workspace connection is used.", "title": "Authorization" }, "description": "Optional connection id used to fetch provider dynamic fields (HubSpot/Pipedrive properties). When omitted, the first active workspace connection is used." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExporterParams" }, "example": { "id": 1, "name": "Create or update HubSpot company records", "description": "Push company data to HubSpot", "dataset": 42, "params": [ { "name": "id", "is_required": false, "type_field": "text", "description": "Company ID" } ], "additional_params": [ { "name": "domain", "label": "Company Domain Name" }, { "name": "name", "label": "Company name" } ], "response_fields": [ { "name": "id", "type_field": "text" } ] } } } }, "403": { "description": "Forbidden access" }, "404": { "description": "Exporter not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}": { "get": { "tags": [ "Get enrichment data or status" ], "summary": "Get task data or status", "description": "Retrieve the data (or results) of an enrichment run by the task id. If the request is still processing, the status field will show a 'processing' status, if the request is completed, your data will be returned in the 'data' key. The task_id is provided as a response when you launch an enrichment task.", "operationId": "get_status_request_v1_tasks__task_id__get", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the task whose status you are querying.", "title": "Task Id" }, "description": "The unique identifier of the task whose status you are querying." }, { "name": "include_partial", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Partial" }, "description": "While a bulk task is still running, also return the rows that have already finished. Off by default: it makes every poll read the whole result set." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "The task status along with any associated data or errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__task__Task" }, "examples": { "processing": { "summary": "Processing Task", "value": { "task_id": "abc123", "status": "processing", "credits_spent": 0 } }, "processing_bulk": { "summary": "Processing Bulk Task", "value": { "task_id": "abc123", "status": "processing", "progress": { "total": 100, "completed": 42, "failed": 3, "processing": 55 }, "credits_spent": 4.2 } }, "completed": { "summary": "Completed Task", "value": { "task_id": "abc123", "status": "completed", "data": { "some_key": "some_value" }, "credits_spent": 12 } }, "failed": { "summary": "Failed Task", "value": { "task_id": "abc123", "status": "failed", "error": "An error message", "credits_spent": 0 } } } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Forbidden" } } } }, "404": { "description": "Not Found: Task with specified ID does not exist." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/tasks/{task_id}/cancel": { "post": { "tags": [ "Get enrichment data or status" ], "summary": "Cancel a running task", "description": "Stop a running task and refund what its unfinished requests reserved. Rows that already finished keep their results, so poll the task afterwards to collect them. A task that has already reached a terminal status returns 409.", "operationId": "cancel_task_v1_tasks__task_id__cancel_post", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier of the task to cancel.", "title": "Task Id" }, "description": "The unique identifier of the task to cancel." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "The task was cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__task__Task" }, "example": { "task_id": "abc123", "status": "cancelled", "progress": { "total": 100, "completed": 42, "failed": 3, "processing": 55 }, "credits_spent": 4.2 } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Forbidden" } } } }, "404": { "description": "Not Found: Task with specified ID does not exist." }, "409": { "description": "The task has already finished.", "content": { "application/json": { "example": { "detail": "Task has already finished" } } } } } } }, "/v1/table/create": { "post": { "tags": [ "Table" ], "summary": "Create a table", "description": "Create a new table in your workspace. Optionally specify a name, column names, and number of empty rows. By default the table is created with columns column1/column2/column3 and 0 rows.", "operationId": "Create_a_table_v1_table_create_post", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateTableRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "200": { "description": "Table created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" }, "example": { "identifier": "123e4567-e89b-12d3-a456-426614174000", "name": "My Table", "created_at": "2023-05-01T12:00:00Z", "updated_at": "2023-05-01T12:00:00Z", "table_url": "https://databar.ai/tables?table=123e4567-e89b-12d3-a456-426614174000&workspace=abc12345-6789-0abc-def0-123456789abc" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "410": { "description": "Expired token", "content": { "application/json": { "example": { "detail": "The token has expired" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}": { "delete": { "tags": [ "Table" ], "summary": "Delete a table", "description": "Permanently delete a table and all its rows by UUID.", "operationId": "Delete_table_v1_table__table_uuid__delete", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table to delete", "title": "Table Uuid" }, "description": "The UUID of the table to delete" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "204": { "description": "Table deleted successfully" }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "404": { "description": "Table not found", "content": { "application/json": { "example": { "detail": "Table not found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Table" ], "summary": "Rename a table", "description": "Rename a table by its UUID.", "operationId": "Update_table_v1_table__table_uuid__patch", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameTableRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Table not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/": { "get": { "tags": [ "Table" ], "summary": "Get all workspace tables", "description": "Retrieves all tables currently in your workspace, including their name, created date, and identifiers.", "operationId": "Get_tables_v1_table__get", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Tables retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Table" }, "title": "Response Get Tables V1 Table Get" }, "example": [ { "identifier": "123e4567-e89b-12d3-a456-426614174000", "name": "My Table 1", "created_at": "2023-05-01T12:00:00Z", "updated_at": "2023-05-01T12:00:00Z", "table_url": "https://databar.ai/tables?table=123e4567-e89b-12d3-a456-426614174000&workspace=abc12345-6789-0abc-def0-123456789abc" }, { "identifier": "223e4567-e89b-12d3-a456-426614174001", "name": "My Table 2", "created_at": "2023-05-01T12:00:00Z", "updated_at": "2023-05-01T12:00:00Z", "table_url": "https://databar.ai/tables?table=223e4567-e89b-12d3-a456-426614174001&workspace=abc12345-6789-0abc-def0-123456789abc" } ] } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/rows": { "get": { "tags": [ "Table" ], "summary": "Get table rows", "description": "Get rows from a table with pagination and optional filtering.\n\n**Filtering:** Use the `filter` query parameter with a JSON-encoded object. Keys are column names, values are objects with one operator.\n\n**Operators:**\n- `equals` \u2014 exact match\n- `contains` \u2014 substring match (case-insensitive)\n- `not_equals` \u2014 excludes exact match\n- `is_empty` \u2014 column value is null (pass `true`)\n- `is_not_empty` \u2014 column value is not null (pass `true`)\n\nMultiple column filters use AND logic.\n\n**Examples:**\n- `?filter={\"company\":{\"equals\":\"OpenAI\"}}`\n- `?filter={\"name\":{\"contains\":\"Data\"}}`\n- `?filter={\"name\":{\"contains\":\"a\"},\"revenue\":{\"equals\":\"5000\"}}`\n- `?filter={\"email\":{\"is_not_empty\":true}}`", "operationId": "Get_table_rows_v1_table__table_uuid__rows_get", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table to retrieve", "title": "Table Uuid" }, "description": "The UUID of the table to retrieve" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "description": "Number of items per page (max 500).", "default": 100, "title": "Per Page" }, "description": "Number of items per page (max 500)." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Page number to retrieve.", "default": 1, "title": "Page" }, "description": "Page number to retrieve." }, { "name": "filter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "JSON-encoded filter object. Keys are column names, values are objects with one operator. Operators: equals, contains, not_equals, is_empty, is_not_empty. Example: {\"company\":{\"contains\":\"tech\"},\"status\":{\"equals\":\"active\"}}", "examples": [ "{\"company\":{\"contains\":\"tech\"}}", "{\"email\":{\"is_not_empty\":true}}" ], "title": "Filter" }, "description": "JSON-encoded filter object. Keys are column names, values are objects with one operator. Operators: equals, contains, not_equals, is_empty, is_not_empty. Example: {\"company\":{\"contains\":\"tech\"},\"status\":{\"equals\":\"active\"}}" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Table retrieved successfully", "content": { "application/json": { "schema": { "title": "Response Get Table Rows V1 Table Table Uuid Rows Get" }, "example": { "has_next_page": true, "total_count": 40, "page": 1, "data": [ { "id": "fec5c2e3-1f18-491b-a875-5c274f052357", "column1": "data1", "column2": "data2" } ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "404": { "description": "Table not found", "content": { "application/json": { "example": { "detail": "Table not found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Table" ], "summary": "Partial update of multiple rows", "description": "Update specific fields in multiple rows at once. Uses human-readable column names.\n\n**overwrite** controls whether existing non-empty values are replaced:\n- `true` (default) \u2014 always set the new value.\n- `false` \u2014 only fill in fields that are currently empty.\n\nIf a row UUID is not found the result entry will contain `\"ok\": false` with an error object `{\"code\": \"ROW_NOT_FOUND\"}`.", "operationId": "Batch_update_rows_v1_table__table_uuid__rows_patch", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpdateResponse" } } } }, "400": { "description": "Validation error (BATCH_TOO_LARGE, UNKNOWN_COLUMNS, INVALID_DATA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SDKErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Table" ], "summary": "Insert multiple rows into a table", "description": "Add rows to a table in batch. Uses human-readable column names.\n\n**options.allow_new_columns** \u2014 when `true`, any column name in `fields` that doesn't exist yet will be auto-created as a text column.\n\n**options.dedupe** \u2014 when `enabled: true`, rows whose `keys` columns match an existing row are skipped (`action: skipped_duplicate`) instead of inserted.", "operationId": "Batch_insert_rows_v1_table__table_uuid__rows_post", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchInsertRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchInsertResponse" } } } }, "400": { "description": "Validation error (BATCH_TOO_LARGE, UNKNOWN_COLUMNS, INVALID_DATA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SDKErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/rows/delete": { "post": { "tags": [ "Table" ], "summary": "Delete rows from a table", "description": "Delete specific rows from a table by their UUIDs.", "operationId": "Delete_rows_v1_table__table_uuid__rows_delete_post", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRowsRequest" } } } }, "responses": { "200": { "description": "Rows deleted successfully", "content": { "application/json": { "schema": {}, "example": { "status": "deleted" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Table not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/columns": { "get": { "tags": [ "Table" ], "summary": "Get table columns", "description": "Get a tables columns by its ID.", "operationId": "Get_table_columns_v1_table__table_uuid__columns_get", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table to retrieve", "title": "Table Uuid" }, "description": "The UUID of the table to retrieve" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Table retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Column" }, "title": "Response Get Table Columns V1 Table Table Uuid Columns Get" }, "example": [ { "identifier": "42902e11-fa09-4abd-a627-77c07fc40cde", "internal_name": "de7ed8b2f4f34991b32f597877f7e97f", "additional_intenal_name": "column1", "name": "Column1", "type_of_value": "text", "data_processor_id": 1 } ] } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "404": { "description": "Table not found", "content": { "application/json": { "example": { "detail": "Table not found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Table" ], "summary": "Add a column to a table", "description": "Create a new column on a table. Type defaults to 'text'.", "operationId": "Create_column_v1_table__table_uuid__columns_post", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateColumnRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateColumnResponse" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Table not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/columns/{column_id}": { "patch": { "tags": [ "Table" ], "summary": "Rename a column", "description": "Rename an existing column on a table.", "operationId": "Update_column_v1_table__table_uuid__columns__column_id__patch", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "column_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the column to rename", "title": "Column Id" }, "description": "The UUID of the column to rename" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameColumnRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateColumnResponse" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Table or column not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Table" ], "summary": "Delete a column from a table", "description": "Delete a column from a table by its UUID.", "operationId": "Delete_column_v1_table__table_uuid__columns__column_id__delete", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "column_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the column to delete", "title": "Column Id" }, "description": "The UUID of the column to delete" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Column deleted successfully", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Forbidden" }, "404": { "description": "Table or column not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/add-enrichment": { "post": { "tags": [ "Table" ], "summary": "Add enrichment to table", "description": "Add an enrichment to a table by its UUID.", "operationId": "Add_enrichment_to_table_v1_table__table_uuid__add_enrichment_post", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddEnrichment" }, "examples": { "with_column_uuid": { "summary": "Mapping with column UUID", "description": "Pass the column identifier (UUID) from GET /v1/table/{uuid}/columns.", "value": { "enrichment": 1, "mapping": { "email": { "value": "42902e11-fa09-4abd-a627-77c07fc40cde", "type": "mapping" }, "country": { "value": "US", "type": "simple" } } } }, "with_column_name": { "summary": "Mapping with column name from rows", "description": "Use the column name as it appears in GET /v1/table/{uuid}/rows response.", "value": { "enrichment": 1, "mapping": { "email": { "value": "email_address", "type": "mapping" }, "country": { "value": "US", "type": "simple" } } } } } } } }, "responses": { "200": { "description": "Enrichment added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddEnrichmentResponse" }, "example": { "id": 42, "enrichment_name": "Email Verification" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "404": { "description": "Table not found", "content": { "application/json": { "example": { "detail": "Table not found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/add-waterfall": { "post": { "tags": [ "Table" ], "summary": "Add waterfall to table", "description": "Add a waterfall to a table by its UUID. A waterfall tries multiple data providers in sequence until one returns a result.\n\nUse `GET /v1/waterfalls` to list available waterfalls and their parameters, enrichments, and email verifiers.\n\nAfter adding, run the waterfall with `POST /v1/table/{uuid}/run-enrichment/{id}`.", "operationId": "Add_waterfall_to_table_v1_table__table_uuid__add_waterfall_post", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddWaterfall" }, "examples": { "email_getter": { "summary": "Email finder waterfall", "description": "Find emails using first name, last name and company columns.", "value": { "waterfall": "email_getter", "enrichments": [ 833, 966 ], "mapping": { "first_name": "first_name", "last_name": "last_name", "company": "company" }, "email_verifier": 10 } }, "with_column_uuids": { "summary": "Mapping with column UUIDs", "description": "Pass column identifier UUIDs from GET /v1/table/{uuid}/columns.", "value": { "waterfall": "email_getter", "enrichments": [ 833, 966 ], "mapping": { "first_name": "42902e11-fa09-4abd-a627-77c07fc40cde", "last_name": "53013f22-gb10-5bce-b738-88d18gd51def", "company": "64124g33-hc21-6cdf-c849-99e29he62efg" } } } } } } }, "responses": { "200": { "description": "Waterfall added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddWaterfallResponse" }, "example": { "id": 42, "waterfall_name": "Email finder waterfall" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "404": { "description": "Table not found", "content": { "application/json": { "example": { "detail": "Table not found" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "detail": "Column 'company' not found in the table" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/enrichments": { "get": { "tags": [ "Table" ], "summary": "Get enrichments in table", "description": "List all enrichments configured on a table. Returns enrichment IDs, parameter mappings, and status for each enrichment attached to the specified table.", "operationId": "Get_table_enrichments_v1_table__table_uuid__enrichments_get", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Table enrichments retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Enrichment" }, "title": "Response Get Table Enrichments V1 Table Table Uuid Enrichments Get" }, "example": [ { "id": "1", "name": "Enrichment1" }, { "id": "2", "name": "My Table" } ] } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "404": { "description": "Table not found", "content": { "application/json": { "example": { "detail": "Table not found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/waterfalls": { "get": { "tags": [ "Table" ], "summary": "Get table waterfalls", "description": "Get all waterfalls installed on a table. Use the returned `id` with `POST /v1/table/{uuid}/run-enrichment/{id}` to run.", "operationId": "Get_table_waterfalls_v1_table__table_uuid__waterfalls_get", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Table waterfalls retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InstalledWaterfall" }, "title": "Response Get Table Waterfalls V1 Table Table Uuid Waterfalls Get" }, "example": [ { "id": 42, "waterfall_name": "Email finder waterfall" }, { "id": 55, "waterfall_name": "Phone number waterfall" } ] } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "404": { "description": "Table not found", "content": { "application/json": { "example": { "detail": "Table not found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/run-enrichment/{enrichment_id}": { "post": { "tags": [ "Table" ], "summary": "Run table enrichment or waterfall", "description": "Run a specific enrichment or waterfall on a table.\n\nWorks for both enrichments (from `POST /v1/table/{uuid}/add-enrichment`) and waterfalls (from `POST /v1/table/{uuid}/add-waterfall`). Use the `id` returned when adding.\n\n**run_strategy** controls which rows are processed:\n- `run_all` (default) \u2014 run on every row.\n- `run_empty` \u2014 only run on rows where the result is empty.\n\n**row_ids** (optional) \u2014 list of specific row UUIDs to process. When provided, only those rows are processed (subject to run_strategy).", "operationId": "Run_table_enrichment_or_waterfall_v1_table__table_uuid__run_enrichment__enrichment_id__post", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "enrichment_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the table enrichment to run", "title": "Enrichment Id" }, "description": "The ID of the table enrichment to run" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/RunEnrichmentRequest" }, { "type": "null" } ], "title": "Data" } } } }, "responses": { "200": { "description": "Enrichment run started successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunEnrichmentResponse" }, "example": { "status": "queued", "processing_rows": 150 } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "404": { "description": "Table or enrichment not found", "content": { "application/json": { "example": { "detail": "Not found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/add-exporter": { "post": { "tags": [ "Table" ], "summary": "Add exporter to table", "description": "Add an exporter (CRM/destination) to a table by its UUID.\n\nUse `GET /v1/exporters` to list available exporters and `GET /v1/exporters/{id}` to see required parameters.\n\nAfter adding, run the exporter with `POST /v1/table/{uuid}/run-enrichment/{id}`.", "operationId": "Add_exporter_to_table_v1_table__table_uuid__add_exporter_post", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddExporter" }, "examples": { "with_column_uuid": { "summary": "Mapping with column UUID", "value": { "exporter": 1, "mapping": { "email": { "value": "42902e11-fa09-4abd-a627-77c07fc40cde", "type": "mapping" } } } }, "with_column_name": { "summary": "Mapping with column name", "description": "Use the column name as it appears in GET /v1/table/{uuid}/rows response.", "value": { "exporter": 1, "mapping": { "email": { "value": "email_address", "type": "mapping" }, "list_id": { "value": "my-list-123", "type": "simple" } } } } } } } }, "responses": { "200": { "description": "Exporter added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddExporterResponse" }, "example": { "id": 42, "exporter_name": "Google Sheets Exporter" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "404": { "description": "Table not found", "content": { "application/json": { "example": { "detail": "Table not found" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "example": { "detail": "Column 'email' not found in the table" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/exporters": { "get": { "tags": [ "Table" ], "summary": "Get table exporters", "description": "Get all exporters installed on a table. Use the returned `id` with `POST /v1/table/{uuid}/run-enrichment/{id}` to run.", "operationId": "Get_table_exporters_v1_table__table_uuid__exporters_get", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Table exporters retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InstalledExporter" }, "title": "Response Get Table Exporters V1 Table Table Uuid Exporters Get" }, "example": [ { "id": 42, "name": "Google Sheets Exporter" }, { "id": 55, "name": "HubSpot CRM" } ] } } }, "403": { "description": "Forbidden", "content": { "application/json": { "example": { "detail": "Not allowed" } } } }, "404": { "description": "Table not found", "content": { "application/json": { "example": { "detail": "Table not found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/table/{table_uuid}/rows/upsert": { "post": { "tags": [ "Table" ], "summary": "Update or create rows by key", "description": "For each row, match on a single **key** column:\n\n- **0 matches** \u2192 a new row is created (`action: created`).\n- **1 match** \u2192 the existing row is updated (`action: updated`).\n- **>1 matches** \u2192 returns an `AMBIGUOUS_MATCH` error for that row.\n\nThe `key` dict must contain exactly one entry `{column_name: value}`.", "operationId": "Upsert_rows_v1_table__table_uuid__rows_upsert_post", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The UUID of the table", "title": "Table Uuid" }, "description": "The UUID of the table" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertResponse" } } } }, "400": { "description": "Validation error (BATCH_TOO_LARGE, UNKNOWN_COLUMNS, INVALID_DATA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SDKErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/waterfalls/": { "get": { "tags": [ "Waterfall" ], "summary": "Get available waterfalls", "description": "Retrieves a list of all waterfalls available on Databar.", "operationId": "Waterfalls_v1_waterfalls__get", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Waterfalls", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Waterfall" }, "title": "Response Waterfalls V1 Waterfalls Get" }, "example": [ { "identifier": "email_getter", "name": "Email finder waterfall", "description": "Get email from first name, last name and company", "input_params": [ { "name": "first_name", "type": "text", "required": true }, { "name": "last_name", "type": "text", "required": true }, { "name": "company", "type": "text", "required": true } ], "output_fields": [ { "name": "email", "label": "Email", "type": "text" } ], "available_enrichments": [ { "id": 833, "name": "General Enrichment", "description": "General data enrichment service", "price": "0.01", "params": [ "first_name", "last_name", "company" ] }, { "id": 966, "name": "Email Finder", "description": "Specialized email finding service", "price": "0.02", "params": [ "first_name", "last_name", "company" ] } ], "is_email_verifying": true, "email_verifiers": [ { "id": 10, "name": "Verify emails (Emailable)", "description": "Verify if emails are valid.", "price": "0.01" } ] }, { "identifier": "person_getter", "name": "Person finder waterfall", "description": "Get person information from email", "input_params": [ { "name": "email", "type": "text", "required": true } ], "output_fields": [ { "name": "first_name", "label": "First name", "type": "text" }, { "name": "last_name", "label": "Last name", "type": "text" }, { "name": "linkedin_url", "label": "Linkedin URL", "type": "text" } ], "available_enrichments": [ { "id": 833, "name": "General Enrichment", "description": "General data enrichment service", "price": "0.01", "params": [ "email" ] } ], "is_email_verifying": false, "email_verifiers": [] } ] } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/waterfalls/{waterfall_identifier}": { "get": { "tags": [ "Waterfall" ], "summary": "Get a specific waterfall", "description": "Retrieve detailed information about a specific waterfall by its identifier.", "operationId": "get_waterfall_v1_waterfalls__waterfall_identifier__get", "parameters": [ { "name": "waterfall_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The identifier of the waterfall to retrieve", "title": "Waterfall Identifier" }, "description": "The identifier of the waterfall to retrieve" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Waterfall" }, "example": { "identifier": "email_getter", "name": "Email finder waterfall", "description": "Get email from first name, last name and company", "input_params": [ { "name": "first_name", "type": "text", "required": true }, { "name": "last_name", "type": "text", "required": true }, { "name": "company", "type": "text", "required": true } ], "output_fields": [ { "name": "email", "label": "Email", "type": "text" } ], "available_enrichments": [ { "id": 833, "name": "General Enrichment", "description": "General data enrichment service", "price": "0.01", "params": [ "first_name", "last_name", "company" ] } ], "is_email_verifying": true, "email_verifiers": [ { "id": 10, "name": "Verify emails (Emailable)", "description": "Verify if emails are valid.", "price": "0.01" } ] } } } }, "403": { "description": "Forbidden access" }, "404": { "description": "Waterfall not found" }, "406": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Check the number of remaining credits or the tariff plan." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/waterfalls/{waterfall_identifier}/run": { "post": { "tags": [ "Waterfall" ], "summary": "Run a waterfall task", "description": "Executes a waterfall task with the provided parameters and enrichments. The enrichments field specifies which data providers to use for the waterfall. Please note: data is stored in our systems for 24 hours. After 24 hours, all data and requests made via enrichments and waterfalls will be removed and your request id will no longer be active.", "operationId": "run_v1_waterfalls__waterfall_identifier__run_post", "parameters": [ { "name": "waterfall_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The identifier of the waterfall to run", "title": "Waterfall Identifier" }, "description": "The identifier of the waterfall to run" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__waterfall__Request" }, "examples": { "email_getter": { "summary": "Email finder waterfall", "description": "Find email using first name, last name and company", "value": { "params": { "first_name": "John", "last_name": "Doe", "company": "example.com" }, "enrichments": [ 833, 966 ], "email_verifier": 10 } }, "person_getter": { "summary": "Person finder waterfall", "description": "Find person information using email", "value": { "params": { "email": "john.doe@example.com" }, "enrichments": [ 833 ] } } } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__waterfall__Task" }, "example": { "task_id": "123e4567-e89b-12d3-a456-426614174000", "status": "created" } } } }, "400": { "description": "Invalid params", "content": { "application/json": { "example": { "error": "INVALID_PARAMS", "detail": "Row 1: param1: This field is required.", "rows": [ { "position": 1, "fields": { "param1": [ "This field is required." ] } } ] } } } }, "406": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Check the number of remaining credits or the tariff plan." } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Forbidden" } } } }, "404": { "description": "Waterfall not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/waterfalls/{waterfall_identifier}/bulk-run": { "post": { "tags": [ "Waterfall" ], "summary": "Run Bulk Waterfall", "description": "Submits a bulk waterfall run for the specified waterfall identifier with custom enrichments. The enrichments field specifies which data providers to use for the waterfall. Please note: data is stored in our systems for 24 hours. After 24 hours, all data and requests made via enrichments and waterfalls will be removed and your request id will no longer be active.", "operationId": "bulk_run_v1_waterfalls__waterfall_identifier__bulk_run_post", "parameters": [ { "name": "waterfall_identifier", "in": "path", "required": true, "schema": { "type": "string", "description": "The identifier of the waterfall to run", "title": "Waterfall Identifier" }, "description": "The identifier of the waterfall to run" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__waterfall__BulkRequest" }, "examples": { "email_getter_bulk": { "summary": "Bulk email finder", "description": "Find emails for multiple people", "value": { "params": [ { "first_name": "John", "last_name": "Doe", "company": "example.com" }, { "first_name": "Jane", "last_name": "Smith", "company": "test.org" } ], "enrichments": [ 833, 966 ], "email_verifier": 10 } }, "person_getter_bulk": { "summary": "Bulk person finder", "description": "Find person information for multiple emails", "value": { "params": [ { "email": "john.doe@example.com" }, { "email": "jane.smith@test.org" } ], "enrichments": [ 833 ] } } } } } }, "responses": { "200": { "description": "Successfully submitted the bulk waterfall run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__waterfall__Task" }, "example": { "task_id": "123e4567-e89b-12d3-a456-426614174000", "status": "created" } } } }, "406": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Check the number of remaining credits or the tariff plan." } } } }, "403": { "description": "Forbidden access", "content": { "application/json": { "example": { "detail": "Forbidden" } } } }, "404": { "description": "Waterfall identifier does not exist" }, "400": { "description": "Invalid params", "content": { "application/json": { "example": { "detail": [ { "param1": [ "This field is required." ] } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/flows/": { "get": { "tags": [ "Flows" ], "summary": "List workspace flows", "description": "Returns all flows defined in your workspace, ordered by most recently updated.", "operationId": "list_flows_v1_flows__get", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "List of flows", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Flow" }, "title": "Response List Flows V1 Flows Get" }, "example": [ { "id": 1, "name": "Enrich company from domain", "description": "Takes a domain and returns company name, industry and headcount.", "inputs": [ { "id": "domain", "description": "Company domain", "type": "text", "required": true } ], "outputs": [ { "id": "company_name", "response_field_id": 42 }, { "id": "industry", "response_field_id": 43 }, { "id": "headcount", "response_field_id": 44 } ], "created_at": "2026-01-10T09:00:00Z", "updated_at": "2026-03-15T14:22:00Z" } ] } } }, "403": { "description": "Forbidden" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Flows" ], "summary": "Create a flow", "description": "Create a workspace flow from a config. The config is validated exactly as the editor validates it, so an invalid graph is rejected here rather than failing later on every run.", "operationId": "create_flow_v1_flows_post", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowCreateIn" } } } }, "responses": { "200": { "description": "The created flow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowDetail" } } } }, "400": { "description": "The config is not a valid flow; the message lists what is wrong" }, "403": { "description": "Forbidden" }, "406": { "description": "The workspace is at its plan's flow limit" } } } }, "/v1/flows/validate-config": { "post": { "tags": [ "Flows" ], "summary": "Check a flow config without saving", "description": "Check a (possibly unsaved) `config` without persisting anything. Runs the same checks a save runs, including the normalisation a save applies first. Always 200: an invalid config is a valid answer to \"would this be accepted?\".", "operationId": "validate_flow_config_v1_flows_validate_config_post", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowConfigIn" } } } }, "responses": { "200": { "description": "Whether the config would be accepted on save", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowValidateOut" } } } }, "403": { "description": "Forbidden" } } } }, "/v1/flows/cost-estimate": { "post": { "tags": [ "Flows" ], "summary": "Estimate the credit cost of one flow run", "description": "Credit-cost range of one run of the given (possibly unsaved) config. `min`/`max` because waterfalls stop at the first success and conditions skip branches. Call this before `POST /v1/flows/{flow_id}/run`.", "operationId": "estimate_flow_cost_v1_flows_cost_estimate_post", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowConfigIn" } } } }, "responses": { "200": { "description": "Credit-cost range of one run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowCostEstimateOut" } } } }, "400": { "description": "The config is not a valid flow; the message lists what is wrong" }, "403": { "description": "Forbidden" } } } }, "/v1/flows/{flow_id}": { "get": { "tags": [ "Flows" ], "summary": "Get a workspace flow", "description": "Retrieve a single flow by its identifier. Returns the graph in `config` and the `internal_version` token you need to edit it, plus the `inputs` array that tells you what `POST /v1/flows/{flow_id}/run` expects.", "operationId": "get_flow_v1_flows__flow_id__get", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow ID" }, "description": "Flow identifier, e.g. `fl_ab12cd34`" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Flow details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowDetail" }, "example": { "id": "fl_ab12cd34", "name": "Enrich company from domain", "description": "Takes a domain and returns company name, industry and headcount.", "inputs": [ { "id": "domain", "description": "Company domain", "type": "text", "required": true } ], "outputs": [ { "id": "company_name", "response_field_id": 42 }, { "id": "industry", "response_field_id": 43 }, { "id": "headcount", "response_field_id": 44 } ], "created_at": "2026-01-10T09:00:00Z", "updated_at": "2026-03-15T14:22:00Z", "config": { "inputs": [ { "id": "domain", "type": "text", "required": true } ], "nodes": [] }, "ui": {}, "internal_version": "0f4b2f9a-8b3e-4b0a-9a1e-2c9f0d5e7a11" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Flow not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Flows" ], "summary": "Replace a flow", "description": "Replace the whole flow. To change one node without resending the graph \u2014 and without risking the rest of it \u2014 use `PATCH /v1/flows/{flow_id}/config` instead.", "operationId": "replace_flow_v1_flows__flow_id__put", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow ID" }, "description": "Flow identifier, e.g. `fl_ab12cd34`" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowReplaceIn" } } } }, "responses": { "200": { "description": "The updated flow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowDetail" } } } }, "400": { "description": "The config is not a valid flow" }, "403": { "description": "Forbidden" }, "404": { "description": "Flow not found" }, "409": { "description": "`internal_version` is stale \u2014 the flow was modified by someone else" } } }, "patch": { "tags": [ "Flows" ], "summary": "Update flow fields", "description": "Update only the fields you send. A rename needs neither a config nor a token; `internal_version` is required alongside `config`.", "operationId": "update_flow_v1_flows__flow_id__patch", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow ID" }, "description": "Flow identifier, e.g. `fl_ab12cd34`" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowUpdateIn" } } } }, "responses": { "200": { "description": "The updated flow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowDetail" } } } }, "400": { "description": "Nothing to update, `internal_version` missing alongside `config`, or an invalid config" }, "403": { "description": "Forbidden" }, "404": { "description": "Flow not found" }, "409": { "description": "`internal_version` is stale" } } }, "delete": { "tags": [ "Flows" ], "summary": "Delete a flow", "description": "Delete a flow. Refused while table columns still run it \u2014 the column would survive with nothing behind it and fail on every row. Delete those columns first.", "operationId": "delete_flow_v1_flows__flow_id__delete", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow ID" }, "description": "Flow identifier, e.g. `fl_ab12cd34`" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "example": { "status": "deleted" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Flow not found" }, "409": { "description": "Table columns still run this flow; the message names them" } } } }, "/v1/flows/{flow_id}/run": { "post": { "tags": [ "Flows" ], "summary": "Run a flow", "description": "Start a flow execution and return a `task_id`. Poll `GET /v1/tasks/{task_id}` to check status and retrieve outputs. Inputs are passed as `{input_id: value}` \u2014 use `GET /v1/flows/{flow_id}` to discover the declared inputs.", "operationId": "run_flow_v1_flows__flow_id__run_post", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow ID" }, "description": "Flow identifier, e.g. `fl_ab12cd34`" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunFlowIn" }, "example": { "inputs": { "domain": "stripe.com" } } } } }, "responses": { "200": { "description": "Task created \u2014 poll GET /v1/tasks/{task_id} for results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__flow__Task" }, "example": { "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "processing" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Flow not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/flows/{flow_id}/bulk-run": { "post": { "tags": [ "Flows" ], "summary": "Bulk run a flow", "description": "Start a flow over many input sets and return one `task_id`. Poll `GET /v1/tasks/{task_id}`. Results are aligned to `inputs`: one element per input, in the same order, with `null` for misses \u2014 same contract as `POST /v1/enrichments/{id}/bulk-run`.", "operationId": "bulk_run_flow_v1_flows__flow_id__bulk_run_post", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow ID" }, "description": "Flow identifier, e.g. `fl_ab12cd34`" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkRunFlowIn" }, "example": { "inputs": [ { "domain": "stripe.com" }, { "domain": "databar.ai" } ] } } } }, "responses": { "200": { "description": "Task created \u2014 poll GET /v1/tasks/{task_id} for results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/app__api__v1__flow__Task" }, "example": { "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "processing" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Flow not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/flows/{flow_id}/config": { "patch": { "tags": [ "Flows" ], "summary": "Apply targeted edits to a flow config", "description": "Change part of a flow without resending the whole graph. Replacing the entire config to fix one word puts every other node in the request too, so a small fix carries the risk of a large one.\n\nThe batch is atomic \u2014 one bad op writes nothing \u2014 and the result is validated by the same rules a full replace runs. Omit `internal_version` and the ops are applied to the row under a lock, so a fix to one node does not lose a race with a change to another.", "operationId": "patch_flow_config_v1_flows__flow_id__config_patch", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow ID" }, "description": "Flow identifier, e.g. `fl_ab12cd34`" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowConfigOpsIn" } } } }, "responses": { "200": { "description": "The saved flow and the resulting config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowConfigOpsOut" } } } }, "400": { "description": "The batch could not be applied, or the result is not a valid flow" }, "403": { "description": "Forbidden" }, "404": { "description": "Flow not found" }, "409": { "description": "`internal_version` is stale" } } } }, "/v1/flows/{flow_id}/versions": { "get": { "tags": [ "Flows" ], "summary": "List a flow's edit history", "description": "Every save of this flow, newest first: what changed, who changed it and from which surface. The first entry is the version the flow is currently on.", "operationId": "list_flow_versions_v1_flows__flow_id__versions_get", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow ID" }, "description": "Flow identifier, e.g. `fl_ab12cd34`" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Versions, newest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FlowVersion" } } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Flow not found" } } } }, "/v1/flows/{flow_id}/versions/{number}": { "get": { "tags": [ "Flows" ], "summary": "Get one flow version", "description": "One stored version, including the graph it held \u2014 so you can inspect an old config before rolling back to it.", "operationId": "get_flow_version_v1_flows__flow_id__versions__number__get", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow ID" }, "description": "Flow identifier, e.g. `fl_ab12cd34`" }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version number" }, "description": "Version number from `GET /v1/flows/{flow_id}/versions`" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "The version and its config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowVersionDetail" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Flow or version not found" } } } }, "/v1/flows/{flow_id}/versions/{number}/restore": { "post": { "tags": [ "Flows" ], "summary": "Roll a flow back to an earlier version", "description": "Make an older version current.\n\nNothing is overwritten: the old config is written as a **new** version, so the rollback is itself revertible and the record of what ran when stays intact. A version that no longer validates \u2014 its enrichment was deleted, its dataset changed \u2014 is refused with the reasons.", "operationId": "restore_flow_version_v1_flows__flow_id__versions__number__restore_post", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow ID" }, "description": "Flow identifier, e.g. `fl_ab12cd34`" }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "title": "Version number" }, "description": "Version number from `GET /v1/flows/{flow_id}/versions`" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreFlowVersionIn" } } } }, "responses": { "200": { "description": "The restored flow and the version the rollback created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreFlowVersionOut" } } } }, "400": { "description": "That version no longer validates; the message lists why" }, "403": { "description": "Forbidden" }, "404": { "description": "Flow or version not found" }, "409": { "description": "`internal_version` is stale" } } } }, "/v1/connectors/": { "get": { "tags": [ "Connector" ], "summary": "List custom API connectors", "description": "Returns all custom API connectors configured in your workspace.", "operationId": "list_connectors_v1_connectors__get", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "List of connectors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Connector" }, "title": "Response List Connectors V1 Connectors Get" }, "example": [ { "id": 1, "name": "My Scoring API", "type": "enrichment", "method": "post", "url": "https://api.example.com/v1/score", "headers": [ { "name": "Authorization", "value": "Bearer sk-xxx" } ], "parameters": [], "body": [ { "name": "domain", "value": "" } ], "rate_limit": 10, "max_concurrency": 5, "created_at": "2025-01-15T10:30:00Z" } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Connector" ], "summary": "Create a custom API connector", "description": "Registers a new custom HTTP API endpoint as a connector in your workspace. Once created the connector appears as an enrichment/exporter you can use in tables.", "operationId": "create_connector_v1_connectors__post", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorCreate" }, "examples": { "enrichment": { "summary": "Enrichment connector (POST)", "value": { "name": "My Scoring API", "type": "enrichment", "method": "post", "url": "https://api.example.com/v1/score", "headers": [ { "name": "Authorization", "value": "Bearer sk-xxx" }, { "name": "Content-Type", "value": "application/json" } ], "parameters": [ { "name": "company_domain", "value": "" } ], "body": [ { "name": "domain", "value": "" }, { "name": "enrichment_type", "value": "full" } ], "rate_limit": 60, "max_concurrency": 5 } }, "simple_get": { "summary": "Simple GET connector", "value": { "name": "Company Lookup", "type": "enrichment", "method": "get", "url": "https://api.example.com/v1/company", "headers": [ { "name": "Authorization", "value": "Bearer sk-xxx" } ], "parameters": [ { "name": "domain", "value": "" } ] } } } } } }, "responses": { "201": { "description": "Connector created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connector" }, "example": { "id": 42, "name": "My Scoring API", "type": "enrichment", "method": "post", "url": "https://api.example.com/v1/score", "headers": [ { "name": "Authorization", "value": "Bearer sk-xxx" }, { "name": "Content-Type", "value": "application/json" } ], "parameters": [ { "name": "company_domain", "value": "" } ], "body": [ { "name": "domain", "value": "" }, { "name": "enrichment_type", "value": "full" } ], "rate_limit": 10, "max_concurrency": 5, "created_at": "2025-01-15T10:30:00Z" } } } }, "400": { "description": "Validation error" }, "406": { "description": "Connector limit reached for your plan" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/connectors/{connector_id}": { "get": { "tags": [ "Connector" ], "summary": "Get a connector", "description": "Retrieve details of a specific custom API connector.", "operationId": "get_connector_v1_connectors__connector_id__get", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The connector ID", "title": "Connector Id" }, "description": "The connector ID" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connector" } } } }, "404": { "description": "Connector not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Connector" ], "summary": "Update a connector", "description": "Replaces the configuration of an existing custom API connector.", "operationId": "update_connector_v1_connectors__connector_id__put", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The connector ID", "title": "Connector Id" }, "description": "The connector ID" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorCreate" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connector" } } } }, "404": { "description": "Connector not found" }, "400": { "description": "Validation error" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Connector" ], "summary": "Delete a connector", "description": "Permanently removes a custom API connector and its associated data.", "operationId": "delete_connector_v1_connectors__connector_id__delete", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The connector ID", "title": "Connector Id" }, "description": "The connector ID" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "204": { "description": "Connector deleted" }, "404": { "description": "Connector not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/folders": { "post": { "tags": [ "Folder" ], "summary": "Create a folder", "description": "Create a new folder to organize tables.", "operationId": "Create_folder_v1_folders_post", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Folder" ], "summary": "List all folders", "description": "List all folders in your workspace.", "operationId": "List_folders_v1_folders_get", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Folder" }, "title": "Response List Folders V1 Folders Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/folders/{folder_id}": { "patch": { "tags": [ "Folder" ], "summary": "Rename a folder", "description": "Rename an existing folder.", "operationId": "Rename_folder_v1_folders__folder_id__patch", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The folder ID", "title": "Folder Id" }, "description": "The folder ID" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameFolderRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Folder" ], "summary": "Delete a folder", "description": "Delete a folder. Tables in the folder are NOT deleted, they are moved to the root level.", "operationId": "Delete_folder_v1_folders__folder_id__delete", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "integer", "description": "The folder ID", "title": "Folder Id" }, "description": "The folder ID" }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "Folder deleted successfully", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Folder not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/folders/move-table": { "post": { "tags": [ "Folder" ], "summary": "Move a table into or out of a folder", "description": "Move a table into a folder, or remove it from its current folder.\n\nPass `folder_id: null` (or omit it) to remove the table from any folder.", "operationId": "Move_table_to_folder_v1_folders_move_table_post", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveTableRequest" } } } }, "responses": { "200": { "description": "Table moved successfully", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Table or folder not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/workbooks": { "get": { "tags": [ "Workbook" ], "summary": "List workbooks", "description": "List workbooks (multi-sheet documents) in the workspace.", "operationId": "list_workbooks", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkbookList" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } } } }, "/v1/workbooks/merge": { "post": { "tags": [ "Workbook" ], "summary": "Merge workbooks", "description": "Move every live table from the source workbooks onto the target.", "operationId": "merge_workbooks", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbook" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeWorkbooks" } } } } } }, "/v1/workbooks/{workbook_id}": { "get": { "tags": [ "Workbook" ], "summary": "Get a workbook", "description": "Get one workbook and its live sheets.", "operationId": "get_workbook", "parameters": [ { "name": "workbook_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Workbook identifier (wb_\u2026)." }, "description": "Workbook identifier (wb_\u2026)." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbook" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "Workbook" ], "summary": "Rename a workbook", "description": "Rename a workbook document.", "operationId": "rename_workbook", "parameters": [ { "name": "workbook_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Workbook identifier (wb_\u2026)." }, "description": "Workbook identifier (wb_\u2026)." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbook" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameWorkbook" } } } } }, "delete": { "tags": [ "Workbook" ], "summary": "Delete a workbook", "description": "Move a workbook and its live tables to Trash for 30 days.", "operationId": "delete_workbook", "parameters": [ { "name": "workbook_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Workbook identifier (wb_\u2026)." }, "description": "Workbook identifier (wb_\u2026)." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "status": "deleted" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } } } }, "/v1/workbooks/{workbook_id}/duplicate": { "post": { "tags": [ "Workbook" ], "summary": "Duplicate a workbook", "description": "Copy every sheet into a new workbook.", "operationId": "duplicate_workbook", "parameters": [ { "name": "workbook_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Workbook identifier (wb_\u2026)." }, "description": "Workbook identifier (wb_\u2026)." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbook" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } } } }, "/v1/workbooks/{workbook_id}/tables": { "post": { "tags": [ "Workbook" ], "summary": "Add a sheet", "description": "Add an empty table to a workbook.", "operationId": "add_workbook_table", "parameters": [ { "name": "workbook_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Workbook identifier (wb_\u2026)." }, "description": "Workbook identifier (wb_\u2026)." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkbookTable" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddWorkbookTable" } } } } } }, "/v1/workbooks/{workbook_id}/tables/reorder": { "post": { "tags": [ "Workbook" ], "summary": "Reorder sheets", "description": "table_ids must list every live table of the workbook exactly once.", "operationId": "reorder_workbook_tables", "parameters": [ { "name": "workbook_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Workbook identifier (wb_\u2026)." }, "description": "Workbook identifier (wb_\u2026)." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workbook" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderWorkbookTables" } } } } } }, "/v1/trash": { "get": { "tags": [ "Trash" ], "summary": "List trash", "description": "Binned workbooks and tables still inside the 30-day window.", "operationId": "list_trash", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashList" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } } } }, "/v1/trash/restore": { "post": { "tags": [ "Trash" ], "summary": "Restore from trash", "description": "Restore workbooks and/or tables. Pass at least one id.", "operationId": "restore_trash", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "status": "ok" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashAction" } } } } } }, "/v1/trash/delete-forever": { "post": { "tags": [ "Trash" ], "summary": "Permanently delete from trash", "description": "Permanently delete workbooks and/or tables from Trash.", "operationId": "purge_trash", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "status": "ok" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashAction" } } } } } }, "/v1/table/duplicate": { "post": { "tags": [ "Table" ], "summary": "Duplicate a table", "description": "Copy a table into a new workbook.", "operationId": "duplicate_table", "parameters": [ { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateTable" } } } } } }, "/v1/table/{table_uuid}/move": { "post": { "tags": [ "Table" ], "summary": "Move a table", "description": "Move a table into another workbook, or into a new one when new_workbook is true.", "operationId": "move_table", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the table." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveTableResult" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveTableToWorkbook" } } } } } }, "/v1/table/{table_uuid}/clear": { "post": { "tags": [ "Table" ], "summary": "Clear a table", "description": "Queue deletion of every row in the table.", "operationId": "clear_table", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the table." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "status": "queued" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } } } }, "/v1/table/{table_uuid}/export": { "post": { "tags": [ "Table" ], "summary": "Start a table export", "description": "Start an export. Poll GET /v1/table/{table_uuid}/export for the download URL. format is csv, xlsx, or sheets.", "operationId": "export_table", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the table." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportStatus" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportTable" } } } } }, "get": { "tags": [ "Table" ], "summary": "Get table export status", "description": "Status of the latest export, including the download URL when it is ready.", "operationId": "get_table_export", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the table." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportStatus" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } } } }, "/v1/table/{table_uuid}/rows/dedupe": { "post": { "tags": [ "Table" ], "summary": "Delete duplicate rows", "description": "Delete duplicate rows, keeping the oldest of each group. Omit columns to compare every main column.", "operationId": "dedupe_rows", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the table." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DedupeRowsResult" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DedupeRows" } } } } } }, "/v1/table/{table_uuid}/columns/{column_id}/reorder": { "post": { "tags": [ "Table" ], "summary": "Reorder a column", "description": "Move a column to a 0-based index among non-system columns.", "operationId": "reorder_column", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the table." }, { "name": "column_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the column." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "status": "ok" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderColumn" } } } } } }, "/v1/table/{table_uuid}/enrichments/{enrichment_id}": { "patch": { "tags": [ "Table" ], "summary": "Update an attached enrichment", "description": "Update the mapping and/or launch strategy of an enrichment already on the table. Pass mapping, launch_strategy, or both.", "operationId": "update_table_enrichment", "parameters": [ { "name": "table_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The UUID of the table." }, { "name": "enrichment_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Table enrichment id returned by add-enrichment." }, { "name": "x-apikey", "in": "header", "required": true, "schema": { "type": "string", "title": "API Key", "description": "API Key for authentication" }, "description": "API Key for authentication" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddEnrichmentResponse" } } } }, "401": { "description": "Missing or invalid API key" }, "404": { "description": "Not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnrichment" } } } } } }, "/health": { "get": { "summary": "Health Check", "description": "Returns the health status of the API", "operationId": "health_health_get", "responses": { "200": { "description": "The health status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" }, "example": { "status": "ok" } } } } } } } }, "components": { "schemas": { "AddEnrichment": { "properties": { "enrichment": { "type": "integer", "title": "Enrichment", "description": "The enrichment ID to add." }, "mapping": { "additionalProperties": { "$ref": "#/components/schemas/MappingEntry" }, "type": "object", "title": "Mapping", "description": "Parameter mapping. Keys are enrichment parameter slugs." }, "launch_strategy": { "type": "string", "enum": [ "run_on_click", "run_on_update" ], "title": "Launch Strategy", "description": "When to run: 'run_on_click' (manual only) or 'run_on_update' (auto-trigger when mapped input columns change).", "default": "run_on_click" } }, "type": "object", "required": [ "enrichment", "mapping" ], "title": "AddEnrichment" }, "AddEnrichmentResponse": { "properties": { "id": { "type": "integer", "title": "Id" }, "enrichment_name": { "type": "string", "title": "Enrichment Name" } }, "type": "object", "required": [ "id", "enrichment_name" ], "title": "AddEnrichmentResponse" }, "AddExporter": { "properties": { "exporter": { "type": "integer", "title": "Exporter", "description": "The exporter ID to add (from GET /v1/exporters)." }, "mapping": { "additionalProperties": { "$ref": "#/components/schemas/MappingEntry" }, "type": "object", "title": "Mapping", "description": "Parameter mapping for static dataset params. Keys are exporter parameter slugs from GET /v1/exporters/{id} params. Provider-fetched dynamic fields belong in additional_mapping.", "default": {} }, "additional_mapping": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/MappingEntry" }, "type": "object" }, { "type": "null" } ], "title": "Additional Mapping", "description": "Mapping for provider-fetched dynamic fields from GET /v1/exporters/{id} additional_params (e.g. HubSpot domain/name/city). Same entry format as mapping." }, "launch_strategy": { "type": "string", "enum": [ "run_on_click", "run_on_update" ], "title": "Launch Strategy", "description": "When to run: 'run_on_click' (manual only) or 'run_on_update' (auto-trigger when mapped input columns change).", "default": "run_on_click" }, "authorization": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Authorization", "description": "ID of the API key / OAuth connection to use for this exporter. Required for exporters that need user authorization. If omitted, the system auto-selects the first available key." }, "custom_body_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Body Template", "description": "Custom JSON body template. Column values are referenced via {column_internal_name} placeholders. When provided, body-typed params in mapping are ignored." } }, "type": "object", "required": [ "exporter" ], "title": "AddExporter" }, "AddExporterResponse": { "properties": { "id": { "type": "integer", "title": "Id" }, "exporter_name": { "type": "string", "title": "Exporter Name" } }, "type": "object", "required": [ "id", "exporter_name" ], "title": "AddExporterResponse" }, "AddWaterfall": { "properties": { "waterfall": { "type": "string", "title": "Waterfall", "description": "Waterfall identifier (e.g. 'email_getter'). Get from GET /v1/waterfalls." }, "enrichments": { "items": { "type": "integer" }, "type": "array", "title": "Enrichments", "description": "Provider IDs to use in the waterfall cascade, in order. Get available IDs from GET /v1/waterfalls/{identifier}. Omit or pass [] to attach the default cascade (providers with enabled_by_default=true)." }, "mapping": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Mapping", "description": "Maps waterfall parameter names to table column identifiers (UUID) or column names (the key used in GET /v1/table/{uuid}/rows response). Get column identifiers from GET /v1/table/{uuid}/columns." }, "email_verifier": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Email Verifier", "description": "Optional enrichment ID for email verification (only for email waterfalls)." } }, "type": "object", "required": [ "waterfall", "mapping" ], "title": "AddWaterfall" }, "AddWaterfallResponse": { "properties": { "id": { "type": "integer", "title": "Id" }, "waterfall_name": { "type": "string", "title": "Waterfall Name" } }, "type": "object", "required": [ "id", "waterfall_name" ], "title": "AddWaterfallResponse" }, "AuthorizationInfo": { "properties": { "required": { "type": "boolean", "title": "Required" }, "connections": { "items": { "$ref": "#/components/schemas/Connection" }, "type": "array", "title": "Connections" } }, "type": "object", "required": [ "required", "connections" ], "title": "AuthorizationInfo" }, "BatchInsertRequest": { "properties": { "rows": { "items": { "$ref": "#/components/schemas/InsertRow" }, "type": "array", "maxItems": 50, "minItems": 1, "title": "Rows", "description": "List of rows to insert (max 50)." }, "options": { "anyOf": [ { "$ref": "#/components/schemas/InsertOptions" }, { "type": "null" } ], "description": "Insert options (auto-create columns, deduplication)." }, "return_rows": { "type": "boolean", "title": "Return Rows", "description": "If true, each result includes full row_data after insert.", "default": false } }, "type": "object", "required": [ "rows" ], "title": "BatchInsertRequest", "example": { "options": { "allow_new_columns": true, "dedupe": { "enabled": true, "keys": [ "column1", "column2", "column3" ] } }, "return_rows": false, "rows": [ { "fields": { "email": "alice@example.com", "first_name": "Alice", "title": "PM" } }, { "fields": { "email": "bob@example.com", "first_name": "Bob" } } ] } }, "BatchInsertResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/BatchInsertResultItem" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "results" ], "title": "BatchInsertResponse", "example": { "results": [ { "action": "created", "id": "a1b2c3d4-0000-0000-0000-000000000001", "index": 0 }, { "action": "created", "id": "a1b2c3d4-0000-0000-0000-000000000002", "index": 1 } ] } }, "BatchInsertResultItem": { "properties": { "index": { "type": "integer", "title": "Index", "description": "Original index in the request array." }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "UUID of the created row (null if skipped)." }, "action": { "type": "string", "enum": [ "created", "skipped_duplicate" ], "title": "Action", "description": "'created' or 'skipped_duplicate'." }, "row_data": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Row Data", "description": "Full row data (only when return_rows=true)." } }, "type": "object", "required": [ "index", "action" ], "title": "BatchInsertResultItem" }, "BatchUpdateRequest": { "properties": { "rows": { "items": { "$ref": "#/components/schemas/BatchUpdateRow" }, "type": "array", "maxItems": 50, "minItems": 1, "title": "Rows", "description": "List of rows to update (max 50)." }, "overwrite": { "type": "boolean", "title": "Overwrite", "description": "If false, only empty fields are updated; existing values are kept.", "default": true }, "return_rows": { "type": "boolean", "title": "Return Rows", "description": "If true, each result includes full row_data after the update.", "default": false } }, "type": "object", "required": [ "rows" ], "title": "BatchUpdateRequest", "example": { "overwrite": true, "return_rows": false, "rows": [ { "fields": { "first_name": "Ivan", "title": "CTO" }, "id": "91f0e833-5dfc-4f63-be96-e3a28925190f" } ] } }, "BatchUpdateResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/BatchUpdateResultItem" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "results" ], "title": "BatchUpdateResponse", "example": { "results": [ { "id": "91f0e833-5dfc-4f63-be96-e3a28925190f", "ok": true }, { "error": { "code": "ROW_NOT_FOUND" }, "id": "00000000-0000-0000-0000-000000000000", "ok": false } ] } }, "BatchUpdateResultItem": { "properties": { "id": { "type": "string", "title": "Id", "description": "UUID of the row." }, "ok": { "type": "boolean", "title": "Ok", "description": "True if the row was updated successfully." }, "error": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Error", "description": "Error object if the row was not found, e.g. {\"code\": \"ROW_NOT_FOUND\"}." }, "row_data": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Row Data", "description": "Full row data (only when return_rows=true)." } }, "type": "object", "required": [ "id", "ok" ], "title": "BatchUpdateResultItem" }, "BatchUpdateRow": { "properties": { "id": { "type": "string", "title": "Id", "description": "UUID of the row to update." }, "fields": { "type": "object", "title": "Fields", "description": "Column values to set, keyed by human-readable column name.", "example": { "first_name": "Ivan", "title": "CTO" } } }, "type": "object", "required": [ "id", "fields" ], "title": "BatchUpdateRow" }, "CategoryInfo": { "properties": { "id": { "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "CategoryInfo" }, "ChoicesResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/app__api__v1__enrichment__ChoiceItem" }, "type": "array", "title": "Items" }, "page": { "type": "integer", "title": "Page" }, "limit": { "type": "integer", "title": "Limit" }, "has_next_page": { "type": "boolean", "title": "Has Next Page" }, "total_count": { "type": "integer", "title": "Total Count" } }, "type": "object", "required": [ "items", "page", "limit", "has_next_page", "total_count" ], "title": "ChoicesResponse" }, "Column": { "properties": { "identifier": { "type": "string", "title": "Identifier" }, "internal_name": { "type": "string", "title": "Internal Name" }, "additional_intenal_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Additional Intenal Name" }, "name": { "type": "string", "title": "Name" }, "type_of_value": { "type": "string", "title": "Type Of Value" }, "data_processor_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Data Processor Id" } }, "type": "object", "required": [ "identifier", "internal_name", "name", "type_of_value", "data_processor_id" ], "title": "Column" }, "Connection": { "properties": { "id": { "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "type": { "type": "string", "title": "Type" } }, "type": "object", "required": [ "id", "name", "type" ], "title": "Connection" }, "Connector": { "properties": { "id": { "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "type": { "type": "string", "title": "Type" }, "method": { "type": "string", "title": "Method" }, "url": { "type": "string", "title": "Url" }, "headers": { "items": { "$ref": "#/components/schemas/NameValue" }, "type": "array", "title": "Headers", "default": [] }, "parameters": { "items": { "$ref": "#/components/schemas/NameValue" }, "type": "array", "title": "Parameters", "default": [] }, "body": { "items": { "$ref": "#/components/schemas/NameValue" }, "type": "array", "title": "Body", "default": [] }, "body_template": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Body Template" }, "rate_limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rate Limit" }, "max_concurrency": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Concurrency" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "id", "name", "type", "method", "url" ], "title": "Connector" }, "ConnectorCreate": { "properties": { "name": { "type": "string", "maxLength": 256, "title": "Name", "description": "Display name for the connector" }, "type": { "type": "string", "title": "Type", "description": "Connector type: simple, enrichment, or exporter", "default": "enrichment" }, "method": { "type": "string", "title": "Method", "description": "HTTP method: get, post, put, or patch" }, "url": { "type": "string", "maxLength": 512, "title": "Url", "description": "Full API endpoint URL (e.g. https://api.example.com/v1/score)" }, "headers": { "items": { "$ref": "#/components/schemas/NameValue" }, "type": "array", "title": "Headers", "description": "HTTP headers to send with each request" }, "parameters": { "items": { "$ref": "#/components/schemas/NameValue" }, "type": "array", "title": "Parameters", "description": "Query parameters" }, "body": { "items": { "$ref": "#/components/schemas/NameValue" }, "type": "array", "title": "Body", "description": "Request body fields" }, "body_template": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ], "title": "Body Template", "description": "Jinja body template. When set, template variables become body params instead of 'body' list." }, "rate_limit": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Rate Limit", "description": "Max requests per minute (capped by plan)" }, "max_concurrency": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Max Concurrency", "description": "Max concurrent requests (capped by plan)" } }, "type": "object", "required": [ "name", "method", "url" ], "title": "ConnectorCreate" }, "CreateColumnRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Column display name." }, "type": { "type": "string", "title": "Type", "description": "Column type (default: 'text').", "default": "text" }, "config": { "type": "object", "title": "Config", "description": "Column config (default: empty dict)." } }, "type": "object", "required": [ "name" ], "title": "CreateColumnRequest" }, "CreateColumnResponse": { "properties": { "identifier": { "type": "string", "title": "Identifier" }, "name": { "type": "string", "title": "Name" }, "type_of_value": { "type": "string", "title": "Type Of Value" } }, "type": "object", "required": [ "identifier", "name", "type_of_value" ], "title": "CreateColumnResponse" }, "CreateFolderRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Folder name." } }, "type": "object", "required": [ "name" ], "title": "CreateFolderRequest" }, "CreateTableRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "columns": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Columns" }, "rows": { "type": "integer", "title": "Rows", "default": 0 } }, "type": "object", "title": "CreateTableRequest" }, "DedupeOptions": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "description": "Enable deduplication check before inserting.", "default": false }, "keys": { "items": { "type": "string" }, "type": "array", "title": "Keys", "description": "Column names to check for duplicates." } }, "type": "object", "title": "DedupeOptions" }, "DeleteRowsRequest": { "properties": { "row_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "minItems": 1, "title": "Row Ids", "description": "List of row UUIDs to delete." } }, "type": "object", "required": [ "row_ids" ], "title": "DeleteRowsRequest" }, "Enrichment": { "properties": { "id": { "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "Enrichment" }, "EnrichmentParams": { "properties": { "id": { "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "data_source": { "type": "string", "title": "Data Source" }, "price": { "type": "number", "title": "Price" }, "pricing": { "$ref": "#/components/schemas/PricingInfo" }, "auth_method": { "type": "string", "title": "Auth Method" }, "category": { "items": { "$ref": "#/components/schemas/CategoryInfo" }, "type": "array", "title": "Category", "default": [] }, "params": { "items": { "$ref": "#/components/schemas/app__api__v1__enrichment__Param" }, "type": "array", "title": "Params" }, "response_fields": { "items": { "$ref": "#/components/schemas/app__api__v1__exporter__ResponseField" }, "type": "array", "title": "Response Fields" }, "pagination": { "$ref": "#/components/schemas/PaginationInfo" } }, "type": "object", "required": [ "id", "name", "description", "data_source", "price", "pricing", "auth_method", "params", "response_fields", "pagination" ], "title": "EnrichmentParams" }, "ExporterParams": { "properties": { "id": { "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "dataset": { "type": "integer", "title": "Dataset" }, "params": { "items": { "$ref": "#/components/schemas/app__api__v1__exporter__Param" }, "type": "array", "title": "Params" }, "additional_params": { "items": { "$ref": "#/components/schemas/ExporterAdditionalParam" }, "type": "array", "title": "Additional Params", "description": "Provider-fetched dynamic fields (e.g. HubSpot company properties). Pass via additional_mapping on add-exporter.", "default": [] }, "response_fields": { "items": { "$ref": "#/components/schemas/app__api__v1__exporter__ResponseField" }, "type": "array", "title": "Response Fields" }, "authorization": { "$ref": "#/components/schemas/AuthorizationInfo" } }, "type": "object", "required": [ "id", "name", "description", "dataset", "params", "response_fields", "authorization" ], "title": "ExporterParams" }, "ExporterAdditionalParam": { "properties": { "name": { "type": "string", "title": "Name", "description": "Provider field name (key for additional_mapping)." }, "label": { "type": "string", "title": "Label", "description": "Human-readable field label." } }, "type": "object", "required": [ "name", "label" ], "title": "ExporterAdditionalParam" }, "Folder": { "properties": { "id": { "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" }, "table_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Table Count" } }, "type": "object", "required": [ "id", "name" ], "title": "Folder" }, "HTTPValidationError": { "properties": { "error": { "type": "string", "title": "Error", "description": "VALIDATION_ERROR" }, "detail": { "type": "string", "title": "Detail", "description": "Human-readable summary, one problem per field joined by '; '." }, "fields": { "type": "array", "title": "Fields", "items": { "type": "object", "properties": { "loc": { "type": "array", "items": {"type": "string"} }, "msg": {"type": "string"} }, "required": ["loc", "msg"] } } }, "type": "object", "required": ["error", "detail"], "title": "HTTPValidationError" }, "HealthStatus": { "properties": { "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "status" ], "title": "HealthStatus" }, "InsertOptions": { "properties": { "allow_new_columns": { "type": "boolean", "title": "Allow New Columns", "description": "If true, unknown column names in fields will be auto-created as text columns.", "default": false }, "dedupe": { "anyOf": [ { "$ref": "#/components/schemas/DedupeOptions" }, { "type": "null" } ], "description": "Deduplication settings." } }, "type": "object", "title": "InsertOptions" }, "InsertRow": { "properties": { "fields": { "type": "object", "title": "Fields", "description": "Column values for the new row, keyed by human-readable column name.", "example": { "email": "alice@example.com", "first_name": "Alice" } } }, "type": "object", "required": [ "fields" ], "title": "InsertRow" }, "InstalledExporter": { "properties": { "id": { "type": "integer", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "InstalledExporter" }, "InstalledWaterfall": { "properties": { "id": { "type": "integer", "title": "Id" }, "waterfall_name": { "type": "string", "title": "Waterfall Name" } }, "type": "object", "required": [ "id", "waterfall_name" ], "title": "InstalledWaterfall" }, "MappingEntry": { "properties": { "value": { "type": "string", "title": "Value", "description": "For type='mapping': the column identifier (UUID) or column name (the key used in GET /v1/table/{uuid}/rows response). Get identifiers from GET /v1/table/{uuid}/columns. For type='simple': a static value used for every row." }, "type": { "type": "string", "enum": [ "mapping", "simple" ], "title": "Type", "description": "'mapping' reads the value from a table column for each row. 'simple' uses the same static value for every row." } }, "type": "object", "required": [ "value", "type" ], "title": "MappingEntry" }, "MoveTableRequest": { "properties": { "table_uuid": { "type": "string", "format": "uuid", "title": "Table Uuid", "description": "UUID of the table to move." }, "folder_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Folder Id", "description": "ID of the target folder. Pass null or omit to remove the table from its current folder." } }, "type": "object", "required": [ "table_uuid" ], "title": "MoveTableRequest" }, "NameValue": { "properties": { "name": { "type": "string", "title": "Name" }, "value": { "type": "string", "title": "Value", "default": "" } }, "type": "object", "required": [ "name" ], "title": "NameValue" }, "PaginationInfo": { "properties": { "supported": { "type": "boolean", "title": "Supported" }, "per_page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Per Page" } }, "type": "object", "required": [ "supported" ], "title": "PaginationInfo" }, "PaginationOptions": { "properties": { "pages": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Pages", "description": "Number of pages to fetch", "default": 1 } }, "type": "object", "title": "PaginationOptions" }, "PricingInfo": { "properties": { "type": { "type": "string", "title": "Type", "description": "Pricing type: \"fixed\" (flat per-request) or \"per_parameter\" (price \u00d7 param value)" }, "parameter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parameter", "description": "Parameter name that multiplies the base price. Present only when type is per_parameter." } }, "type": "object", "required": [ "type" ], "title": "PricingInfo" }, "RenameColumnRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "New column display name." } }, "type": "object", "required": [ "name" ], "title": "RenameColumnRequest" }, "RenameFolderRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "New folder name." } }, "type": "object", "required": [ "name" ], "title": "RenameFolderRequest" }, "RenameTableRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "New table name." } }, "type": "object", "required": [ "name" ], "title": "RenameTableRequest" }, "RunEnrichmentRequest": { "properties": { "run_strategy": { "type": "string", "enum": [ "run_all", "run_empty", "run_errors" ], "title": "Run Strategy", "description": "Which rows to process: 'run_all' runs every row, 'run_empty' skips rows that already have a result, 'run_errors' reruns only rows that ended with an error.", "default": "run_all" }, "row_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Row Ids", "description": "Optional list of specific row UUIDs to process. When omitted, processes all rows (subject to run_strategy)." } }, "type": "object", "title": "RunEnrichmentRequest" }, "RunEnrichmentResponse": { "properties": { "status": { "type": "string", "title": "Status" }, "processing_rows": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Processing Rows" } }, "type": "object", "required": [ "status" ], "title": "RunEnrichmentResponse" }, "SDKErrorResponse": { "properties": { "error": { "type": "string", "title": "Error", "description": "Error code: BATCH_TOO_LARGE, UNKNOWN_COLUMNS, INVALID_DATA." }, "max_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Size", "description": "Maximum batch size (only for BATCH_TOO_LARGE)." }, "columns": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Columns", "description": "Unknown column names (only for UNKNOWN_COLUMNS)." }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail", "description": "Human-readable error message (only for INVALID_DATA)." } }, "type": "object", "required": [ "error" ], "title": "SDKErrorResponse" }, "Table": { "properties": { "identifier": { "type": "string", "title": "Identifier" }, "name": { "type": "string", "title": "Name" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" }, "workspace_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace Identifier" }, "workbook": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workbook", "description": "Parent workbook identifier (wb_\u2026)." }, "table_url": { "type": "string", "title": "Table Url", "readOnly": true } }, "type": "object", "required": [ "identifier", "name", "created_at", "updated_at", "table_url" ], "title": "Table" }, "UpsertRequest": { "properties": { "rows": { "items": { "$ref": "#/components/schemas/UpsertRow" }, "type": "array", "maxItems": 50, "minItems": 1, "title": "Rows", "description": "List of rows to upsert (max 50)." }, "return_rows": { "type": "boolean", "title": "Return Rows", "description": "If true, each result includes full row_data.", "default": false } }, "type": "object", "required": [ "rows" ], "title": "UpsertRequest", "example": { "return_rows": false, "rows": [ { "fields": { "company_name": "Acme", "first_name": "Ivan" }, "key": { "email": "ivan@example.com" } }, { "fields": { "first_name": "New Person", "title": "Engineer" }, "key": { "email": "new@example.com" } } ] } }, "UpsertResponse": { "properties": { "results": { "items": { "$ref": "#/components/schemas/UpsertResultItem" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "results" ], "title": "UpsertResponse", "example": { "results": [ { "action": "updated", "id": "91f0e833-5dfc-4f63-be96-e3a28925190f" }, { "action": "created", "id": "a1b2c3d4-0000-0000-0000-000000000000", "index": 1 } ] } }, "UpsertResultItem": { "properties": { "index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Index", "description": "Original index in the request array (present for created rows)." }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "UUID of the updated or newly created row." }, "action": { "anyOf": [ { "type": "string", "enum": [ "updated", "created" ] }, { "type": "null" } ], "title": "Action", "description": "'updated' or 'created'." }, "error": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Error", "description": "Error object, e.g. {\"code\": \"AMBIGUOUS_MATCH\", \"matches\": 3}." }, "row_data": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Row Data", "description": "Full row data (only when return_rows=true)." } }, "type": "object", "title": "UpsertResultItem" }, "UpsertRow": { "properties": { "key": { "type": "object", "maxProperties": 1, "minProperties": 1, "title": "Key", "description": "Exactly one column to match on: {column_name: value}. If no match \u2014 create, if one match \u2014 update, if multiple \u2014 AMBIGUOUS_MATCH error.", "example": { "email": "ivan@example.com" } }, "fields": { "type": "object", "title": "Fields", "description": "Column values to set/update, keyed by human-readable column name.", "example": { "company_name": "Acme", "first_name": "Ivan" } } }, "type": "object", "required": [ "key", "fields" ], "title": "UpsertRow" }, "User": { "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name" }, "email": { "type": "string", "title": "Email" }, "balance": { "type": "number", "title": "Balance" }, "plan": { "type": "string", "title": "Plan" }, "workspace": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workspace" } }, "type": "object", "required": [ "first_name", "email", "balance", "plan" ], "title": "User" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "Waterfall": { "properties": { "identifier": { "type": "string", "title": "Identifier" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "input_params": { "items": { "type": "object" }, "type": "array", "title": "Input Params" }, "output_fields": { "items": { "type": "object" }, "type": "array", "title": "Output Fields" }, "available_enrichments": { "items": { "type": "object" }, "type": "array", "title": "Available Enrichments" }, "is_email_verifying": { "type": "boolean", "title": "Is Email Verifying" }, "email_verifiers": { "items": { "type": "object" }, "type": "array", "title": "Email Verifiers" } }, "type": "object", "required": [ "identifier", "name", "description", "input_params", "output_fields", "available_enrichments", "is_email_verifying", "email_verifiers" ], "title": "Waterfall" }, "app__api__v1__enrichment__BulkRequest": { "properties": { "params": { "items": { "type": "object" }, "type": "array", "title": "Params" }, "pagination": { "anyOf": [ { "$ref": "#/components/schemas/PaginationOptions" }, { "type": "null" } ] } }, "type": "object", "required": [ "params" ], "title": "BulkRequest" }, "app__api__v1__enrichment__ChoiceItem": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "id", "name" ], "title": "ChoiceItem" }, "app__api__v1__enrichment__Choices": { "properties": { "mode": { "type": "string", "title": "Mode" }, "items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/app__api__v1__enrichment__ChoiceItem" }, "type": "array" }, { "type": "null" } ], "title": "Items" }, "endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Endpoint" } }, "type": "object", "required": [ "mode" ], "title": "Choices" }, "app__api__v1__enrichment__Param": { "properties": { "name": { "type": "string", "title": "Name" }, "is_required": { "type": "boolean", "title": "Is Required" }, "type_field": { "type": "string", "title": "Type Field" }, "description": { "type": "string", "title": "Description" }, "choices": { "anyOf": [ { "$ref": "#/components/schemas/app__api__v1__enrichment__Choices" }, { "type": "null" } ] } }, "type": "object", "required": [ "name", "is_required", "type_field", "description" ], "title": "Param" }, "app__api__v1__enrichment__Request": { "properties": { "params": { "type": "object", "title": "Params" }, "pagination": { "anyOf": [ { "$ref": "#/components/schemas/PaginationOptions" }, { "type": "null" } ] } }, "type": "object", "required": [ "params" ], "title": "Request" }, "app__api__v1__enrichment__Task": { "properties": { "task_id": { "type": "string", "title": "Task Id" }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "task_id", "status" ], "title": "Task" }, "app__api__v1__exporter__Param": { "properties": { "name": { "type": "string", "title": "Name" }, "is_required": { "type": "boolean", "title": "Is Required" }, "type_field": { "type": "string", "title": "Type Field" }, "description": { "type": "string", "title": "Description" }, "choices": { "anyOf": [ { "$ref": "#/components/schemas/app__api__v1__enrichment__Choices" }, { "type": "null" } ] } }, "type": "object", "required": [ "name", "is_required", "type_field", "description" ], "title": "Param" }, "app__api__v1__exporter__ResponseField": { "properties": { "name": { "type": "string", "title": "Name" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display Name" }, "type_field": { "type": "string", "title": "Type Field" } }, "type": "object", "required": [ "name", "type_field" ], "title": "ResponseField" }, "app__api__v1__task__Task": { "properties": { "task_id": { "type": "string", "title": "Task Id", "description": "Unique identifier of the task." }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id", "description": "Deprecated: use task_id instead. Same value as task_id.", "deprecated": true }, "status": { "type": "string", "title": "Status", "description": "Current status of the request. Can be 'processing', 'completed', 'partially_completed', 'failed' or 'cancelled'." }, "progress": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Progress", "description": "How far a bulk run has got: `total`, `completed`, `failed` and `processing` counts of inputs. `failed` covers every finished input that produced no data, clean misses included. Omitted for single (non-bulk) runs." }, "data": { "anyOf": [ { "items": {}, "type": "array" }, { "type": "object" }, { "type": "null" } ], "title": "Data", "description": "Resulting data once completed. For bulk runs this is an array aligned to the inputs: one element per input, in the same order they were submitted, with null for inputs that returned no data (len(data) equals the number of inputs, and data[i] is the result for input i). A single (non-bulk) run returns the result object directly." }, "error": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if the request has failed." }, "credits_spent": { "type": "number", "title": "Credits Spent", "description": "Total credits spent for this request.", "default": 0 } }, "type": "object", "required": [ "task_id", "status" ], "title": "Task" }, "app__api__v1__waterfall__BulkRequest": { "properties": { "params": { "items": { "type": "object" }, "type": "array", "title": "Params" }, "enrichments": { "items": { "type": "integer" }, "type": "array", "title": "Enrichments", "description": "Provider IDs to run, in order. Omit or pass [] to run the waterfall's default cascade (providers with enabled_by_default=true)." }, "email_verifier": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Email Verifier" } }, "type": "object", "required": [ "params" ], "title": "BulkRequest" }, "app__api__v1__waterfall__Request": { "properties": { "params": { "type": "object", "title": "Params" }, "enrichments": { "items": { "type": "integer" }, "type": "array", "title": "Enrichments", "description": "Provider IDs to run, in order. Omit or pass [] to run the waterfall's default cascade (providers with enabled_by_default=true)." }, "email_verifier": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Email Verifier" } }, "type": "object", "required": [ "params" ], "title": "Request" }, "FlowInput": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for this input (used as key in the `inputs` map when running the flow)." }, "description": { "type": "string", "title": "Description" }, "type": { "type": "string", "title": "Type", "description": "Data type of the input, e.g. `text`." }, "required": { "type": "boolean", "title": "Required" } }, "type": "object", "required": ["id", "description", "type", "required"], "title": "FlowInput" }, "FlowOutput": { "properties": { "id": { "type": "string", "title": "Id" }, "response_field_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Response Field Id" } }, "type": "object", "required": ["id"], "title": "FlowOutput" }, "Flow": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/FlowInput" }, "title": "Inputs" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/FlowOutput" }, "title": "Outputs" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "id", "name", "description", "inputs", "outputs", "created_at", "updated_at" ], "title": "Flow" }, "FlowDetail": { "description": "A flow plus the pieces needed to edit it. `config` is the graph, `ui` is editor-only metadata the runtime ignores, and `internal_version` is the concurrency token you send back on a write.", "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/FlowInput" }, "title": "Inputs" }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/FlowOutput" }, "title": "Outputs" }, "config": { "type": "object", "title": "Config", "description": "The flow definition: `inputs`, `nodes`, `output`." }, "ui": { "type": "object", "title": "Ui", "description": "Editor-only metadata. The runtime never reads it." }, "internal_version": { "type": "string", "title": "Internal Version", "description": "Concurrency token. Send it back on PUT (required) and on PATCH when changing `config`." }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "id", "name", "description", "inputs", "outputs", "config", "ui", "internal_version", "created_at", "updated_at" ], "title": "FlowDetail" }, "FlowCreateIn": { "properties": { "name": { "type": "string", "title": "Name", "description": "Display name of the flow." }, "config": { "type": "object", "title": "Config", "description": "Flow definition: `{inputs: [...], nodes: [...], output: {...}}`. Copy the shape of an existing flow from `GET /v1/flows/{flow_id}`." }, "description": { "type": "string", "title": "Description", "default": "" }, "ui": { "type": "object", "title": "Ui", "description": "Editor-only metadata. The runtime ignores it.", "default": {} } }, "type": "object", "required": [ "name", "config" ], "title": "FlowCreateIn" }, "FlowConfigIn": { "properties": { "config": { "type": "object", "title": "Config", "description": "Flow definition, possibly unsaved: `{inputs: [...], nodes: [...], output: {...}}`. Same shape `POST /v1/flows` and `GET /v1/flows/{flow_id}` use." } }, "type": "object", "required": [ "config" ], "title": "FlowConfigIn" }, "FlowConfigError": { "properties": { "node_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Node Id" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "message" ], "title": "FlowConfigError" }, "FlowValidateOut": { "properties": { "valid": { "type": "boolean", "title": "Valid" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/FlowConfigError" }, "title": "Errors", "description": "Why the config would be rejected on save. Empty when `valid` is true." } }, "type": "object", "required": [ "valid" ], "title": "FlowValidateOut" }, "FlowCostEstimateOut": { "properties": { "min": { "type": "string", "title": "Min", "description": "Cheapest one-run cost, in credits." }, "max": { "type": "string", "title": "Max", "description": "Most expensive one-run cost, in credits." }, "currency": { "type": "string", "title": "Currency", "default": "credits" } }, "type": "object", "required": [ "min", "max" ], "title": "FlowCostEstimateOut" }, "FlowReplaceIn": { "description": "Whole-flow replace. `internal_version` must be the value the last `GET /v1/flows/{flow_id}` returned.", "properties": { "name": { "type": "string", "title": "Name", "description": "Display name of the flow." }, "config": { "type": "object", "title": "Config", "description": "Flow definition: `{inputs: [...], nodes: [...], output: {...}}`. Copy the shape of an existing flow from `GET /v1/flows/{flow_id}`." }, "description": { "type": "string", "title": "Description", "default": "" }, "ui": { "type": "object", "title": "Ui", "description": "Editor-only metadata. The runtime ignores it.", "default": {} }, "internal_version": { "type": "string", "title": "Internal Version" } }, "type": "object", "required": [ "name", "config", "internal_version" ], "title": "FlowReplaceIn" }, "FlowUpdateIn": { "description": "Only the fields you send change. `internal_version` is required alongside `config`.", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "config": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Config" }, "ui": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Ui" }, "internal_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Internal Version" } }, "type": "object", "title": "FlowUpdateIn" }, "FlowConfigOpsIn": { "description": "A small, ordered batch of targeted edits, applied atomically: if any op fails, nothing is written. Op names: `set_input`, `remove_input`, `add_node`, `replace_node`, `update_node`, `remove_node`, `set_node_input`, `remove_node_input`, `set_node_output`, `remove_node_output`, `set_output`, `set_output_field`, `remove_output_field`.", "properties": { "ops": { "type": "array", "items": { "type": "object" }, "title": "Ops", "description": "Operations, applied in order. Each is `{\"op\": \"\", ...}`." }, "internal_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Internal Version", "description": "Optional. When set, the edit is refused if the flow changed since you read it. Omit it and the ops are applied to whatever is current." }, "validate_only": { "type": "boolean", "title": "Validate Only", "default": false, "description": "Apply and validate without saving; the response carries the config the batch would produce." } }, "type": "object", "required": [ "ops" ], "title": "FlowConfigOpsIn" }, "FlowConfigOpsOut": { "properties": { "valid": { "type": "boolean", "title": "Valid" }, "errors": { "type": "array", "items": { "type": "string" }, "title": "Errors", "description": "Why the resulting config would be rejected. Only ever non-empty under `validate_only`." }, "config": { "type": "object", "title": "Config" }, "flow": { "anyOf": [ { "$ref": "#/components/schemas/FlowDetail" }, { "type": "null" } ], "title": "Flow", "description": "The saved flow. Null when `validate_only` was set." } }, "type": "object", "required": [ "valid", "config" ], "title": "FlowConfigOpsOut" }, "FlowVersion": { "description": "One saved version of a flow. The list arrives newest first, so the first entry is the version the flow is currently on.", "properties": { "number": { "type": "integer", "title": "Number", "description": "1-based, monotonic within one flow." }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "changed_fields": { "type": "array", "items": { "type": "string" }, "title": "Changed Fields", "description": "Which of `name`, `description`, `config`, `ui` differ from the previous version \u2014 so a canvas-only move can be told from a graph edit." }, "source": { "type": "string", "enum": [ "ui", "api", "mcp", "admin", "system" ], "title": "Source", "description": "Where the edit came from." }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By", "description": "Email of the author, or null for edits made outside a user session." }, "restored_from": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Restored From", "description": "Set when this version was produced by a rollback." } }, "type": "object", "required": [ "number", "name", "description", "changed_fields", "source", "created_at", "created_by" ], "title": "FlowVersion" }, "FlowVersionDetail": { "properties": { "number": { "type": "integer", "title": "Number", "description": "1-based, monotonic within one flow." }, "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "changed_fields": { "type": "array", "items": { "type": "string" }, "title": "Changed Fields", "description": "Which of `name`, `description`, `config`, `ui` differ from the previous version \u2014 so a canvas-only move can be told from a graph edit." }, "source": { "type": "string", "enum": [ "ui", "api", "mcp", "admin", "system" ], "title": "Source", "description": "Where the edit came from." }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created By", "description": "Email of the author, or null for edits made outside a user session." }, "restored_from": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Restored From", "description": "Set when this version was produced by a rollback." }, "config": { "type": "object", "title": "Config" }, "ui": { "type": "object", "title": "Ui" } }, "type": "object", "required": [ "number", "name", "description", "changed_fields", "source", "created_at", "created_by", "config", "ui" ], "title": "FlowVersionDetail" }, "RestoreFlowVersionIn": { "properties": { "internal_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Internal Version", "description": "Optional concurrency check, same semantics as on update." } }, "type": "object", "title": "RestoreFlowVersionIn" }, "RestoreFlowVersionOut": { "properties": { "flow": { "$ref": "#/components/schemas/FlowDetail" }, "version": { "$ref": "#/components/schemas/FlowVersion" } }, "type": "object", "required": [ "flow", "version" ], "title": "RestoreFlowVersionOut" }, "app__api__v1__flow__Task": { "properties": { "task_id": { "type": "string", "title": "Task Id" }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "task_id", "status" ], "title": "Task" }, "RunFlowIn": { "properties": { "inputs": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Inputs", "description": "Maps flow input id → value string. Use `GET /v1/flows/{flow_id}` to discover the required input ids.", "default": {} } }, "type": "object", "title": "RunFlowIn" }, "BulkRunFlowIn": { "properties": { "inputs": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "minItems": 1, "title": "Inputs", "description": "One input set per record, in the order you want results back. Each object maps flow input id → value string, same shape as `POST /flows/{id}/run`." } }, "type": "object", "required": [ "inputs" ], "title": "BulkRunFlowIn" }, "app__api__v1__waterfall__Task": { "properties": { "task_id": { "type": "string", "title": "Task Id" }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "task_id", "status" ], "title": "Task" }, "WorkbookTable": { "type": "object", "title": "WorkbookTable", "properties": { "identifier": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "integer" } }, "required": [ "identifier", "name", "position" ] }, "Workbook": { "type": "object", "title": "Workbook", "properties": { "identifier": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "folder_id": { "type": [ "integer", "null" ] }, "tables": { "type": "array", "items": { "$ref": "#/components/schemas/WorkbookTable" } }, "tables_count": { "type": "integer" } }, "required": [ "identifier", "name", "created_at", "updated_at", "tables", "tables_count" ] }, "WorkbookList": { "type": "array", "items": { "$ref": "#/components/schemas/Workbook" }, "title": "WorkbookList" }, "RenameWorkbook": { "type": "object", "title": "RenameWorkbook", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "name" ] }, "MergeWorkbooks": { "type": "object", "title": "MergeWorkbooks", "properties": { "target": { "type": "string", "description": "Workbook that keeps the sheets." }, "sources": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "target", "sources" ] }, "AddWorkbookTable": { "type": "object", "title": "AddWorkbookTable", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128 } } }, "ReorderWorkbookTables": { "type": "object", "title": "ReorderWorkbookTables", "properties": { "table_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } }, "required": [ "table_ids" ] }, "TrashItem": { "type": "object", "title": "TrashItem", "properties": { "kind": { "type": "string" }, "identifier": { "type": "string" }, "name": { "type": "string" }, "trashed_at": { "type": [ "string", "null" ] }, "tables_count": { "type": [ "integer", "null" ] } }, "required": [ "kind", "identifier", "name" ] }, "TrashList": { "type": "array", "items": { "$ref": "#/components/schemas/TrashItem" }, "title": "TrashList" }, "TrashAction": { "type": "object", "title": "TrashAction", "properties": { "workbooks": { "type": "array", "items": { "type": "string" } }, "tables": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "DuplicateTable": { "type": "object", "title": "DuplicateTable", "properties": { "table": { "type": "string", "format": "uuid", "description": "UUID of the table to duplicate." } }, "required": [ "table" ] }, "MoveTableToWorkbook": { "type": "object", "title": "MoveTableToWorkbook", "properties": { "workbook": { "type": [ "string", "null" ] }, "new_workbook": { "type": "boolean", "default": false }, "name": { "type": [ "string", "null" ], "maxLength": 128 } } }, "MoveTableResult": { "type": "object", "title": "MoveTableResult", "properties": { "status": { "type": "string", "enum": [ "moved", "created", "unchanged" ] }, "workbook": { "type": "string" }, "table": { "type": "string" } }, "required": [ "status", "workbook", "table" ] }, "ExportTable": { "type": "object", "title": "ExportTable", "properties": { "format": { "type": "string", "enum": [ "csv", "xlsx", "sheets" ], "default": "csv" }, "kwargs": { "type": "object", "additionalProperties": true } } }, "ExportStatus": { "type": "object", "title": "ExportStatus", "properties": { "status": { "type": "string" }, "file_id": { "type": [ "integer", "null" ] }, "file": { "type": [ "string", "null" ], "description": "Download URL when the export is ready." }, "message": { "type": [ "string", "null" ] } }, "required": [ "status" ] }, "DedupeRows": { "type": "object", "title": "DedupeRows", "properties": { "columns": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "Column UUIDs to compare. Omit to compare every main column." } } }, "DedupeRowsResult": { "type": "object", "title": "DedupeRowsResult", "properties": { "count_all_rows": { "type": "integer" }, "count_rows_delete": { "type": "integer" } }, "required": [ "count_all_rows", "count_rows_delete" ] }, "ReorderColumn": { "type": "object", "title": "ReorderColumn", "properties": { "index": { "type": "integer", "minimum": 0 } }, "required": [ "index" ] }, "UpdateEnrichment": { "type": "object", "title": "UpdateEnrichment", "properties": { "mapping": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/MappingEntry" } }, "launch_strategy": { "type": [ "string", "null" ], "enum": [ "run_on_click", "run_on_update" ] } } } } }, "servers": [ { "url": "https://api.databar.ai", "description": "Production" } ] }