{ "openapi": "3.1.0", "info": { "title": "Rastro Public API", "description": "Public API for enrichment, catalog management, workflows, activities, snapshots, taxonomy, and MCP integrations.", "version": "0.1.0" }, "servers": [ { "url": "https://catalogapi.rastro.ai/api" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/public/catalogs": { "get": { "tags": [ "Catalogs" ], "summary": "List Catalogs", "description": "List all catalogs accessible to the authenticated organization.\n\nReturns catalogs owned by the organization associated with the API key or user token.", "operationId": "list_catalogs_api_public_catalogs_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 10, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCatalogListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Catalogs" ], "summary": "Create Catalog Public", "description": "Create a new catalog (API key or user token).", "operationId": "create_catalog_public_api_public_catalogs_post", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCreateCatalogRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCatalogResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}": { "get": { "tags": [ "Catalogs" ], "summary": "Get Catalog", "description": "Get details of a specific catalog.\n\nArgs:\n catalog_id: The catalog ID\n\nReturns:\n Catalog details including schema information", "operationId": "get_catalog_api_public_catalogs__catalog_id__get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCatalogResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Catalogs" ], "summary": "Update Catalog Public", "description": "Update catalog settings (API key or user token).\n\nOnly provided fields are updated; omitted fields remain unchanged.", "operationId": "update_catalog_public_api_public_catalogs__catalog_id__put", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicUpdateCatalogRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCatalogResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Catalogs" ], "summary": "Delete Catalog Public", "description": "Delete a catalog and all its data (API key or user token).", "operationId": "delete_catalog_public_api_public_catalogs__catalog_id__delete", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/items": { "get": { "tags": [ "Catalogs" ], "summary": "List Catalog Items", "description": "List items in a catalog with pagination, search, and filtering.\n\nArgs:\n catalog_id: The catalog ID\n limit: Maximum number of items to return (default: 50, max: 1000)\n offset: Number of items to skip\n search: Text search across all fields\n sort: Sort by field and direction (field:asc or field:desc)\n\nReturns:\n Paginated list of catalog items", "operationId": "list_catalog_items_api_public_catalogs__catalog_id__items_get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Search across all fields", "title": "Search" }, "description": "Search across all fields" }, { "name": "search_query", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Alias for search across all fields", "title": "Search Query" }, "description": "Alias for search across all fields" }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort by field:direction (e.g., created_at:desc)", "title": "Sort" }, "description": "Sort by field:direction (e.g., created_at:desc)" }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Catalogs" ], "summary": "Upsert Item Public", "description": "Upsert a single item using the same shape as the public read API.", "operationId": "upsert_item_public_api_public_catalogs__catalog_id__items_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicUpsertItemRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicCatalogItem" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/items/{item_id}": { "get": { "tags": [ "Catalogs" ], "summary": "Get Catalog Item", "description": "Get a specific catalog item by ID.\n\nArgs:\n catalog_id: The catalog ID\n item_id: The item ID (database ID)\n\nReturns:\n The catalog item data", "operationId": "get_catalog_item_api_public_catalogs__catalog_id__items__item_id__get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Item Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Catalogs" ], "summary": "Update Catalog Item", "description": "Update a catalog item.\n\nArgs:\n catalog_id: The catalog ID\n item_id: The item ID (database ID)\n data: Updated data for the item (dynamic schema)\n\nReturns:\n The updated catalog item", "operationId": "update_catalog_item_api_public_catalogs__catalog_id__items__item_id__put", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Item Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Data" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Catalogs" ], "summary": "Delete Catalog Item", "description": "Delete a catalog item.\n\nArgs:\n catalog_id: The catalog ID\n item_id: The item ID (database ID)\n\nReturns:\n Success message", "operationId": "delete_catalog_item_api_public_catalogs__catalog_id__items__item_id__delete", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Item Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/items/bulk": { "post": { "tags": [ "Catalogs" ], "summary": "Bulk Insert Items", "description": "Bulk create catalog items.\n\nArgs:\n catalog_id: The catalog ID\n request: Bulk insert request with items\n\nReturns:\n Summary of the bulk operation", "operationId": "bulk_insert_items_api_public_catalogs__catalog_id__items_bulk_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInsertItemsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/quality-prompt": { "get": { "tags": [ "Catalogs" ], "summary": "Get Catalog Quality Prompt", "description": "Get the catalog's quality prompt (used by the judge and readiness checks).", "operationId": "get_catalog_quality_prompt_api_public_catalogs__catalog_id__quality_prompt_get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Catalogs" ], "summary": "Update Catalog Quality Prompt", "description": "Set the catalog's quality prompt (used by the judge and readiness checks).", "operationId": "update_catalog_quality_prompt_api_public_catalogs__catalog_id__quality_prompt_put", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_UpdateQualityPromptRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/catalog-md": { "get": { "tags": [ "Catalogs" ], "summary": "Get Catalog Md", "description": "Get the catalog's markdown context (catalog_md) injected into enrichment and mapping prompts.", "operationId": "get_catalog_md_api_public_catalogs__catalog_id__catalog_md_get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "put": { "tags": [ "Catalogs" ], "summary": "Update Catalog Md", "description": "Set the catalog's markdown context (catalog_md) injected into enrichment and mapping prompts.", "operationId": "update_catalog_md_api_public_catalogs__catalog_id__catalog_md_put", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_UpdateCatalogMdRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/products/{product_id}/items": { "post": { "tags": [ "Catalogs" ], "summary": "Create Product Variant Public", "description": "Create a new variant under a parent product item (API key or user token).\nThe product_id path parameter is the parent product catalog item database ID, not the business product_id field stored in row data.\nAccepts variant data with at least 'sku' or 'unique_identifier'.", "operationId": "create_product_variant_public_api_public_catalogs__catalog_id__products__product_id__items_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "description": "Parent product catalog item database ID, not the business product_id field value.", "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Product Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Variant Data" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/products/{product_id}": { "put": { "tags": [ "Catalogs" ], "summary": "Update Product Public", "description": "Update product-level fields on a parent product item (API key or user token).\nThe product_id path parameter is the parent product catalog item database ID, not the business product_id field stored in row data.\nOnly fields with 'product_' prefix will be applied.", "operationId": "update_product_public_api_public_catalogs__catalog_id__products__product_id__put", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "description": "Parent product catalog item database ID, not the business product_id field value.", "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Product Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Product Data" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/products/{product_id}/items/bulk": { "post": { "tags": [ "Catalogs" ], "summary": "Bulk Upsert Product Variants Public", "description": "Bulk upsert variants under a parent product item in a single call.\n\nThe product_id path parameter is the parent product catalog item database ID, not the business product_id field stored in row data.\nMerges provided product-level fields into each variant and upserts using the catalog's configured unique id field (e.g., 'sku').", "operationId": "bulk_upsert_product_variants_public_api_public_catalogs__catalog_id__products__product_id__items_bulk_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "description": "Parent product catalog item database ID, not the business product_id field value.", "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Product Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpsertProductVariantsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpsertProductResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/schema/fields": { "post": { "tags": [ "Catalog Schemas" ], "summary": "Add Catalog Field Public", "description": "Add a new field to the catalog schema (API key or user token).\n\nCreates a new schema version with the additional field.", "operationId": "add_catalog_field_public_api_public_catalogs__catalog_id__schema_fields_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSchemaFieldRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaFieldOperationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/schema/fields/batch": { "put": { "tags": [ "Catalog Schemas" ], "summary": "Batch Update Catalog Fields Public", "description": "Batch add, update, and/or remove schema fields in one atomic operation (API key or user token).\n\nCreates a single new schema version for all changes.", "operationId": "batch_update_catalog_fields_public_api_public_catalogs__catalog_id__schema_fields_batch_put", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchSchemaFieldRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaFieldOperationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/taxonomy": { "put": { "tags": [ "Catalog Taxonomies" ], "summary": "Set Catalog Taxonomy Public", "description": "Set or replace the catalog taxonomy (API key or user token).\n\nCreates a new schema version with the updated taxonomy.\n\nRequest body: taxonomy object with name, hierarchy_levels, and nodes.\nReturns the enriched taxonomy with computed fields (level, path, children, inherited_attributes).", "operationId": "set_catalog_taxonomy_public_api_public_catalogs__catalog_id__taxonomy_put", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Taxonomy" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Catalog Taxonomies" ], "summary": "Delete Catalog Taxonomy Public", "description": "Remove taxonomy from catalog (API key or user token).\n\nCreates a new schema version without the taxonomy.", "operationId": "delete_catalog_taxonomy_public_api_public_catalogs__catalog_id__taxonomy_delete", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "tags": [ "Catalog Taxonomies" ], "summary": "Get Catalog Taxonomy", "description": "Get catalog taxonomy with computed inheritance.\n\nReturns the taxonomy with enriched nodes that include level, path,\nchildren, inherited_attributes, and all_attributes.\nReturns null if catalog has no taxonomy configured.", "operationId": "get_catalog_taxonomy_api_public_catalogs__catalog_id__taxonomy_get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "if-none-match", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "If-None-Match" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/workflows": { "get": { "tags": [ "Flows" ], "summary": "List Workflows", "description": "List all workflows accessible to the authenticated organization.\n\nReturns workflows owned by the organization associated with the API key or user token.\n\n- **limit**: Maximum number of workflows to return (1-100, default: 50)\n- **offset**: Number of workflows to skip for pagination (default: 0)", "operationId": "list_workflows_api_public_workflows_get", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional case-insensitive search on workflow name/description", "title": "Search" }, "description": "Optional case-insensitive search on workflow name/description" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWorkflowListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/workflows/{workflow_id}/execute": { "post": { "tags": [ "Flows" ], "summary": "Execute Workflow", "description": "Execute a workflow with input data.\n\n- **workflow_id**: The ID of the workflow to execute\n- **input**: List of input data records to process\n\nReturns execution info including workflow_run_id for polling.", "operationId": "execute_workflow_api_public_workflows__workflow_id__execute_post", "parameters": [ { "name": "workflow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWorkflowExecuteRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWorkflowExecuteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/workflows/runs/{workflow_run_id}": { "get": { "tags": [ "Flows" ], "summary": "Get Workflow Run Status", "description": "Get status and results of a workflow run.\n\nReturns status info while running, and includes paginated results when completed.\n\n- **workflow_run_id**: The workflow run ID from the execute endpoint\n- **page**: Page number for results (default: 1)\n- **page_size**: Number of records per page (default: 50, max: 1000)", "operationId": "get_workflow_run_status_api_public_workflows_runs__workflow_run_id__get", "parameters": [ { "name": "workflow_run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Workflow Run Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 50, "title": "Page Size" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicWorkflowRunStatus" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/enrich": { "post": { "tags": [ "Enrich" ], "summary": "Enrich Data", "description": "Enrich items using web research, with optional taxonomy prediction.\n\nAccepts both `application/json` (plain JSON body) and `multipart/form-data`\n(with `request_json` field, optional `items_file`, and optional\n`knowledge_base_files`).\n\n**Two modes of operation:**\n\n1. **Direct mode**: Pass items and output_schema directly\n2. **Full-run mode**: Pass `source_activity_id` from a previous run to process all stored items\n\n**Example: Direct enrichment**\n```json\n{\n \"prompt\": \"Find product specifications\",\n \"items\": [{\"name\": \"iPhone 15 Pro\"}],\n \"output_schema\": [\n {\"name\": \"price\", \"type\": \"string\", \"description\": \"Current retail price\"},\n {\"name\": \"weight\", \"type\": \"string\", \"description\": \"Product weight\"}\n ]\n}\n```\n\n**Example: Dry run (process first 10 items)**\n```json\n{\n \"prompt\": \"Find product specifications\",\n \"items\": [... all 1000 items ...],\n \"output_schema\": [...],\n \"max_rows\": 10\n}\n```\n\n**Example: Full run from previous activity**\n```json\n{\n \"prompt\": \"Find product specifications\",\n \"source_activity_id\": \"abc123-previous-activity-id\"\n}\n```\n\n**Large jobs:** send multipart/form-data with a small `request_json` and\none `items_file` JSON upload. `items_file` must be a JSON array, or an\nobject with an `items` array. Do not send `items_storage_url`; it is internal.\n\nAll items are stored in the activity, so full runs can be triggered later using `source_activity_id`.", "operationId": "enrich_data_api_public_enrich_post", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichRequest" }, "examples": { "direct": { "summary": "Direct enrichment", "value": { "items": [ { "part_number": "6205-2RS", "name": "Deep Groove Ball Bearing" } ], "output_schema": [ { "name": "bore_diameter", "type": "string", "description": "Inner diameter in mm" }, { "name": "outer_diameter", "type": "string", "description": "Outer diameter in mm" } ], "speed": "fast" } }, "catalog": { "summary": "Use a catalog configuration", "value": { "catalog_id": "cat_123", "items": [ { "sku": "A1" } ], "speed": "deep" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "request_json" ], "properties": { "request_json": { "type": "string", "description": "JSON-encoded EnrichRequest. For large jobs with items_file, omit inline items from request_json." }, "items_file": { "type": "string", "format": "binary", "description": "Optional JSON upload containing either an array of items or an object with an items array. Use exactly one items_file for large jobs." }, "knowledge_base_files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Optional knowledge-base documents used for retrieval/citations during enrichment." }, "knowledge_base_metadata_json": { "type": "string", "description": "Optional JSON metadata for knowledge_base_files, keyed by file name or upload index." } }, "additionalProperties": false } } } } } }, "/public/judge": { "post": { "tags": [ "Enrich" ], "summary": "Judge Catalog Rows", "description": "Judge catalog rows against schema + quality criteria.\n\nWhen catalog_id is provided, automatically loads the schema and the catalog's\nreadiness_config quality_prompt. The optional `prompt` field appends extra instructions.", "operationId": "judge_catalog_rows_api_public_judge_post", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JudgeCatalogRowsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JudgeCatalogRowsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/enrich/jobs": { "get": { "tags": [ "Enrich" ], "summary": "List Enrichment Jobs", "description": "List enrichment jobs for your organization.\n\n**Query parameters:**\n- `status`: Filter by status (`running`, `completed`, `failed`, `cancelled`)\n- `limit`: Max results (1-100, default 20)\n- `offset`: Pagination offset (default 0)\n\n**Example:**\n```\nGET /api/public/enrich/jobs?status=running&limit=10\n```", "operationId": "list_enrichment_jobs_api_public_enrich_jobs_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/enrich/{job_id}/cancel": { "post": { "tags": [ "Enrich" ], "summary": "Cancel Enrichment Job", "description": "Cancel a running enrichment job.\n\nItems already processed will be kept and credits charged only for those items.\n\n**Example:**\n```\nPOST /api/public/enrich/{job_id}/cancel\n```", "operationId": "cancel_enrichment_job_api_public_enrich__job_id__cancel_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/enrich/{job_id}/to-catalog": { "post": { "tags": [ "Enrich" ], "summary": "Create Catalog From Run", "description": "Create a new catalog from an enrichment run's results.\n\nThe new catalog's schema carries field types AND descriptions from the run's\nenrichment template, and is populated with the run's enriched records. Works for\nupload-based (catalog-less) runs that otherwise have no catalog to export to.", "operationId": "create_catalog_from_run_api_public_enrich__job_id__to_catalog_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCatalogFromRunRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/enrich/{job_id}": { "get": { "tags": [ "Enrich" ], "summary": "Get Enrichment Job", "description": "Poll enrichment job status and get results.\n\nReturns results **progressively** — partial results are available while the job\nis still running, as each batch of items completes processing.\n\n**Flow:**\n1. Submit enrichment with `async_mode=true` → get `job_id`\n2. Poll this endpoint — results appear incrementally as items are processed\n3. When `status` changes to `completed`, all results are ready\n\n**Pagination:**\n- `page`: Page number (1-indexed, default: 1)\n- `page_size`: Results per page (default: 1000)\n- Response includes `page`, `page_size`, `total_pages`, `completed_items`\n\n**Statuses:**\n- `running`: Job is still processing (partial results may be available)\n- `completed`: Job finished, all results ready\n- `failed`: Job failed or was cancelled (partial results may still be available)\n\n**Example:**\n```\nGET /api/public/enrich/{job_id}?page=1&page_size=50\n\nResponse (running, partial results):\n{\n \"job_id\": \"08aa2b0d-...\",\n \"status\": \"running\",\n \"results\": [\n {\"after_data\": {...}, \"before_data\": {...}, \"sources\": {...}}\n ],\n \"total_items\": 500,\n \"completed_items\": 200,\n \"successful\": 0,\n \"credits_used\": 0,\n \"page\": 1,\n \"page_size\": 50,\n \"total_pages\": 4\n}\n```", "operationId": "get_enrichment_job_api_public_enrich__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "default": 1000, "title": "Page Size" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/infer-enrichment": { "post": { "tags": [ "Enrich" ], "summary": "Infer Enrichment", "description": "Analyze sample data and infer schema, taxonomy, and web enrichment fields.\n\nPass sample items and a description, get back:\n- **suggested_schema**: JSON Schema ready for catalog creation\n- **suggested_taxonomy**: Taxonomy ready for catalog creation\n- **web_enrichment_fields**: Fields to use with /public/enrich endpoint\n\n**Example request:**\n```json\n{\n \"prompt\": \"Audio products catalog - headphones and earbuds\",\n \"items\": [\n {\"name\": \"Sony WH-1000XM5\", \"sku\": \"WH1000XM5-B\", \"price\": \"$399.99\"},\n {\"name\": \"Apple AirPods Pro 2\", \"sku\": \"AIRPODS-PRO-2\", \"price\": \"$249.00\"}\n ]\n}\n```", "operationId": "infer_enrichment_api_public_infer_enrichment_post", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferEnrichmentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferEnrichmentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/infer-schema": { "post": { "tags": [ "Enrich" ], "summary": "Infer Schema From File", "description": "Analyze an uploaded file and infer enrichment configuration.\n\nUpload a CSV or Excel file, and get back:\n- **suggested_schema**: JSON Schema with all fields (existing + suggested enrichments)\n- **web_enrichment_fields**: Fields to use with /public/enrich endpoint\n- **suggested_taxonomy**: Category hierarchy (if generate_taxonomy=true)\n\nThis endpoint helps you configure an enrichment pipeline without manual schema definition.\n\n**Example usage:**\n1. Upload your data file with a description\n2. Use the returned `web_enrichment_fields` as `output_schema` in `/public/enrich`\n3. Use `suggested_taxonomy` with `predict_taxonomy=true` in `/public/enrich`\n\n**Supported file formats:**\n- CSV (.csv)\n- Excel (.xlsx, .xls)", "operationId": "infer_schema_from_file_api_public_infer_schema_post", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_infer_schema_from_file_api_public_infer_schema_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferSchemaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/enrichment-templates": { "get": { "tags": [ "Enrich" ], "summary": "List Enrichment Templates", "description": "List enabled enrichment templates for the authenticated organization.\n\nReturns only small manifests. Full configs are storage-backed and are applied\nserver-side when `template_id` is passed to POST /public/enrich.", "operationId": "list_enrichment_templates_api_public_enrichment_templates_get", "parameters": [ { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/enrichment-templates/{template_id}": { "get": { "tags": [ "Enrich" ], "summary": "Get Enrichment Template", "description": "Get enabled template metadata and hydrated config for the authenticated organization.\n\nThe list endpoint stays lightweight; this endpoint is used on explicit\nselection so the UI can show the template fields and taxonomy before run\ntime. Large taxonomies can use taxonomy_format=compact for fast selection.", "operationId": "get_enrichment_template_api_public_enrichment_templates__template_id__get", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } }, { "name": "include_taxonomy", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Hydrate and return the template taxonomy. Set false when only fields/prompts are needed.", "default": true, "title": "Include Taxonomy" }, "description": "Hydrate and return the template taxonomy. Set false when only fields/prompts are needed." }, { "name": "taxonomy_format", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(expanded|compact)$", "description": "Return hydrated taxonomy as expanded nodes or compact deduplicated nodes.", "default": "expanded", "title": "Taxonomy Format" }, "description": "Return hydrated taxonomy as expanded nodes or compact deduplicated nodes." }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/schema": { "get": { "tags": [ "Catalog Schemas" ], "summary": "Get Catalog Schema", "description": "Get catalog schema definition.\n\nReturns the schema for a catalog, including field definitions, types, and metadata.", "operationId": "get_catalog_schema_api_public_catalogs__catalog_id__schema_get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "version", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Specific schema version (defaults to current)", "title": "Version" }, "description": "Specific schema version (defaults to current)" }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSchemaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/activities": { "post": { "tags": [ "Catalog Activities" ], "summary": "Create Activity With Staged Changes", "description": "Create an activity with optional staged changes for a catalog.\n\nThis endpoint allows programmatic creation of review activities (e.g., from an MCP tool server).\nStaged changes represent proposed modifications to catalog items that can be reviewed and applied.", "operationId": "create_activity_with_staged_changes_api_public_catalogs__catalog_id__activities_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateActivityRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateActivityResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "tags": [ "Catalog Activities" ], "summary": "List Catalog Activities", "description": "List activities for a specific catalog.\n\nReturns activities associated with the given catalog, with optional filtering.", "operationId": "list_catalog_activities_api_public_catalogs__catalog_id__activities_get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by activity status", "title": "Status" }, "description": "Filter by activity status" }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by activity type", "title": "Type" }, "description": "Filter by activity type" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/raw-items": { "get": { "tags": [ "Catalogs" ], "summary": "List Catalog Raw Items", "description": "List raw catalog_items rows without public product transformation.\n\nThis endpoint is intended for MCP/tooling workloads that require full-fidelity\nrow data (id/entity_type/parent_id/current_version/data) for local transforms\nand deterministic diff pipelines.", "operationId": "list_catalog_raw_items_api_public_catalogs__catalog_id__raw_items_get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5000, "minimum": 1, "default": 1000, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "entity_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional entity_type filter: product|variant", "title": "Entity Type" }, "description": "Optional entity_type filter: product|variant" }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional text search across raw item data", "title": "Search" }, "description": "Optional text search across raw item data" }, { "name": "sort_field", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional raw sort field (data field or system column)", "title": "Sort Field" }, "description": "Optional raw sort field (data field or system column)" }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort direction: asc or desc", "default": "asc", "title": "Sort Order" }, "description": "Sort direction: asc or desc" }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/raw-items/{item_id}": { "get": { "tags": [ "Catalogs" ], "summary": "Get Catalog Raw Item", "description": "Get a single raw catalog item row for MCP/tooling use cases.", "operationId": "get_catalog_raw_item_api_public_catalogs__catalog_id__raw_items__item_id__get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Item Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/activities/{activity_id}/staged-changes/append": { "post": { "tags": [ "Activities" ], "summary": "Append Activity Staged Changes", "description": "Append staged changes to an existing activity.\n\nThis supports large one-command MCP updates by chunking staged changes across\nmultiple requests while keeping a single activity/review URL.", "operationId": "append_activity_staged_changes_api_public_activities__activity_id__staged_changes_append_post", "parameters": [ { "name": "activity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Activity Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendStagedChangesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendStagedChangesResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/activities/{activity_id}/pending-review": { "post": { "tags": [ "Activities" ], "summary": "Set Activity Pending Review Public", "description": "Move an existing activity to pending_review and return review URL.", "operationId": "set_activity_pending_review_public_api_public_activities__activity_id__pending_review_post", "parameters": [ { "name": "activity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Activity Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPendingReviewRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransformActivityResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/snapshots": { "get": { "tags": [ "Catalog Snapshots" ], "summary": "List Catalog Snapshots", "description": "List catalog snapshots for rollback/history flows.", "operationId": "list_catalog_snapshots_api_public_catalogs__catalog_id__snapshots_get", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "snapshot_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional snapshot type filter", "title": "Snapshot Type" }, "description": "Optional snapshot type filter" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Catalog Snapshots" ], "summary": "Create Catalog Snapshot", "description": "Create a manual snapshot for later restore.", "operationId": "create_catalog_snapshot_api_public_catalogs__catalog_id__snapshots_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogSnapshotCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/snapshots/{snapshot_id}/restore": { "post": { "tags": [ "Catalog Snapshots" ], "summary": "Restore Catalog Snapshot", "description": "Restore a catalog to a specific snapshot.", "operationId": "restore_catalog_snapshot_api_public_catalogs__catalog_id__snapshots__snapshot_id__restore_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Snapshot Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/duplicate": { "post": { "tags": [ "Catalogs" ], "summary": "Duplicate Catalog", "description": "Duplicate a catalog schema and optionally copy items.", "operationId": "duplicate_catalog_api_public_catalogs__catalog_id__duplicate_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogDuplicateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/activities/{activity_id}/save-workflow": { "post": { "tags": [ "Catalog Activities" ], "summary": "Save Activity As Workflow", "description": "Create a reusable workflow template from an activity's transform context.", "operationId": "save_activity_as_workflow_api_public_catalogs__catalog_id__activities__activity_id__save_workflow_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "activity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Activity Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveActivityAsWorkflowRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/public/catalogs/{catalog_id}/activities/custom-transform": { "post": { "tags": [ "Catalog Activities" ], "summary": "Create Custom Transform Activity", "description": "Create a custom transform activity with full audit metadata.\n\nThis is the primary endpoint for MCP tool servers to create reviewable activities\nwith script provenance, diff summaries, and validation reports.", "operationId": "create_custom_transform_activity_api_public_catalogs__catalog_id__activities_custom_transform_post", "parameters": [ { "name": "catalog_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Catalog Id" } }, { "name": "X-Organization-Id", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Organization-Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransformActivityRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransformActivityResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "AddSchemaFieldRequest": { "properties": { "field_name": { "type": "string", "title": "Field Name", "description": "Name of the field to add" }, "field_type": { "type": "string", "title": "Field Type", "description": "Field type: string, number, boolean, array, object" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Field description" }, "required": { "type": "boolean", "title": "Required", "description": "Whether field is required", "default": false }, "scope": { "type": "string", "title": "Scope", "description": "Field scope: variant, product, both. Accepted by the request model; the single-field public route does not apply scope metadata.", "default": "variant" }, "field_category": { "type": "string", "title": "Field Category", "description": "Field category: input or generated. Stored as workflow-tracking metadata when workflow_id is provided.", "default": "input" }, "position": { "type": "string", "title": "Position", "description": "Where to add field: top or bottom", "default": "bottom" }, "workflow_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflow Id", "description": "Workflow ID that's adding this field" }, "validation_rules": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Validation Rules", "description": "JSON Schema validation rules (pattern, enum, minLength, etc.)" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unit", "description": "Unit of measurement (e.g., 'V', 'W', 'kg', 'm')" }, "sample_values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Sample Values", "description": "Sample values to help understand expected formats" } }, "type": "object", "required": [ "field_name", "field_type" ], "title": "AddSchemaFieldRequest", "description": "Request to add a field to catalog schema" }, "AppendStagedChangesRequest": { "properties": { "staged_changes": { "items": { "$ref": "#/components/schemas/PublicStagedChangeInput" }, "type": "array", "title": "Staged Changes", "description": "Staged changes to append" } }, "type": "object", "title": "AppendStagedChangesRequest", "description": "Request to append staged changes to an existing activity." }, "AppendStagedChangesResponse": { "properties": { "activity_id": { "type": "string", "title": "Activity Id" }, "appended_count": { "type": "integer", "title": "Appended Count" }, "total_staged_changes": { "type": "integer", "title": "Total Staged Changes" } }, "type": "object", "required": [ "activity_id", "appended_count", "total_staged_changes" ], "title": "AppendStagedChangesResponse", "description": "Response after appending staged changes to an activity." }, "BatchSchemaFieldRequest": { "properties": { "fields_to_add": { "items": { "$ref": "#/components/schemas/AddSchemaFieldRequest" }, "type": "array", "title": "Fields To Add", "description": "Fields to add" }, "fields_to_update": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Fields To Update", "description": "Fields to update" }, "fields_to_remove": { "items": { "type": "string" }, "type": "array", "title": "Fields To Remove", "description": "Field names to remove" }, "workflow_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflow Id", "description": "Workflow ID making these changes" }, "reason": { "type": "string", "title": "Reason", "description": "Reason for the changes", "default": "Batch field operation" } }, "type": "object", "title": "BatchSchemaFieldRequest", "description": "Request to perform multiple schema field operations" }, "Body_infer_schema_from_file_api_public_infer_schema_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File", "description": "CSV or Excel file to analyze" }, "prompt": { "type": "string", "title": "Prompt", "description": "Description of the data (e.g., 'Product catalog for electronics retailer')" }, "generate_taxonomy": { "type": "boolean", "title": "Generate Taxonomy", "description": "If true, also generate a suggested taxonomy", "default": false }, "max_sample_rows": { "type": "integer", "title": "Max Sample Rows", "description": "Maximum rows to sample for analysis (default 20)", "default": 20 } }, "type": "object", "required": [ "file", "prompt" ], "title": "Body_infer_schema_from_file_api_public_infer_schema_post" }, "BulkInsertItemsRequest": { "properties": { "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items", "description": "List of item data to upsert" }, "source_info": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Info", "description": "Information about data source" }, "auto_evolve_schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Evolve Schema", "description": "Accepted for compatibility. Public bulk writes currently allow schema evolution from submitted item data." } }, "type": "object", "required": [ "items" ], "title": "BulkInsertItemsRequest", "description": "Request to bulk upsert catalog items" }, "BulkUpsertProductResponse": { "properties": { "product_id": { "type": "string", "title": "Product Id" }, "items_processed": { "type": "integer", "title": "Items Processed" }, "items_created": { "type": "integer", "title": "Items Created" }, "items_updated": { "type": "integer", "title": "Items Updated" }, "items_failed": { "type": "integer", "title": "Items Failed" }, "schema_evolved": { "type": "boolean", "title": "Schema Evolved" }, "new_schema_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "New Schema Version" }, "errors": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Errors", "default": [] }, "duplicates_in_payload": { "type": "integer", "title": "Duplicates In Payload", "default": 0 }, "error_summary": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Error Summary", "default": {} }, "warnings": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Warnings", "default": [] }, "warnings_summary": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Warnings Summary", "default": {} } }, "type": "object", "required": [ "product_id", "items_processed", "items_created", "items_updated", "items_failed", "schema_evolved" ], "title": "BulkUpsertProductResponse" }, "BulkUpsertProductVariantsRequest": { "properties": { "product": { "additionalProperties": true, "type": "object", "title": "Product", "default": {} }, "variants": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Variants" }, "source_info": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Info" }, "auto_evolve_schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Evolve Schema" } }, "type": "object", "required": [ "variants" ], "title": "BulkUpsertProductVariantsRequest", "description": "Bulk upsert variants for a product using variants payload.\n\n- product: product-level fields (typically keys prefixed with 'product_')\n- variants: list of variant objects\n- source_info: optional metadata recorded on items\n- auto_evolve_schema: accepted for compatibility; public bulk writes currently allow schema evolution from submitted item data" }, "CatalogDuplicateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Name for the new catalog copy" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description for the new catalog copy" }, "include_items": { "type": "boolean", "title": "Include Items", "description": "If true, copy all items from source catalog into the duplicate", "default": false } }, "type": "object", "title": "CatalogDuplicateRequest" }, "CatalogSchemaResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "catalog_id": { "type": "string", "title": "Catalog Id" }, "version": { "type": "string", "title": "Version" }, "schema_definition": { "additionalProperties": true, "type": "object", "title": "Schema Definition" }, "backward_compatible": { "type": "boolean", "title": "Backward Compatible" }, "migration_rules": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Migration Rules" }, "created_by": { "type": "string", "title": "Created By" }, "change_reason": { "type": "string", "title": "Change Reason" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "last_edited_by_workflow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Edited By Workflow" }, "last_edited_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Edited At" }, "fields_workflow_info": { "items": { "$ref": "#/components/schemas/FieldWorkflowInfo" }, "type": "array", "title": "Fields Workflow Info", "default": [] }, "total_fields": { "type": "integer", "title": "Total Fields", "default": 0 }, "input_fields_count": { "type": "integer", "title": "Input Fields Count", "default": 0 }, "generated_fields_count": { "type": "integer", "title": "Generated Fields Count", "default": 0 } }, "type": "object", "required": [ "id", "catalog_id", "version", "schema_definition", "backward_compatible", "created_by", "change_reason", "created_at" ], "title": "CatalogSchemaResponse", "description": "Response model for catalog schema" }, "CatalogSnapshotCreateRequest": { "properties": { "reason": { "type": "string", "title": "Reason", "description": "Reason for creating the snapshot", "default": "Public API manual snapshot" } }, "type": "object", "title": "CatalogSnapshotCreateRequest" }, "CreateActivityRequest": { "properties": { "type": { "type": "string", "title": "Type", "description": "Activity type (e.g., smart_import, custom_transform)", "default": "smart_import" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Human-readable description of the activity" }, "input_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Input Data", "description": "Optional full activity input data for audit context and apply-time hooks" }, "staged_changes": { "items": { "$ref": "#/components/schemas/PublicStagedChangeInput" }, "type": "array", "title": "Staged Changes", "description": "Staged changes to attach to the activity" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Initial activity status (defaults to 'pending_review' if staged_changes provided, else 'created')" } }, "type": "object", "title": "CreateActivityRequest", "description": "Request to create an activity with staged changes" }, "CreateActivityResponse": { "properties": { "activity_id": { "type": "string", "title": "Activity Id" }, "status": { "type": "string", "title": "Status" }, "staged_changes_count": { "type": "integer", "title": "Staged Changes Count" } }, "type": "object", "required": [ "activity_id", "status", "staged_changes_count" ], "title": "CreateActivityResponse", "description": "Response after creating an activity" }, "CreateCatalogFromRunRequest": { "properties": { "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "name" ], "title": "CreateCatalogFromRunRequest" }, "CreateTransformActivityRequest": { "properties": { "activity_message": { "type": "string", "title": "Activity Message", "description": "Human-readable description (e.g., 'Q2 price update')" }, "script": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Script", "description": "Transform script metadata: {filename, content, sha256}" }, "diff_summary": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Diff Summary", "description": "Diff summary: {rows_before, rows_after, rows_added, rows_removed, rows_modified, ...}" }, "validation_report": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Validation Report", "description": "Bundle validation report" }, "staged_changes": { "items": { "$ref": "#/components/schemas/PublicStagedChangeInput" }, "type": "array", "title": "Staged Changes", "description": "Staged changes" }, "schema_changes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schema Changes", "description": "Schema changes to apply alongside row changes" }, "taxonomy_changes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Taxonomy Changes", "description": "Taxonomy changes to apply alongside row changes" }, "attachments": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Attachments", "description": "Optional attachment metadata used in this session (files, urls, sheet names)" }, "activity_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Activity Context", "description": "Optional activity context for auditability (tool params, notes, attachment refs, etc.)" }, "session_context": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Session Context", "description": "Deprecated alias for activity_context.session_context" }, "base_snapshot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Base Snapshot Id", "description": "Optional snapshot ID for audit trail" } }, "type": "object", "required": [ "activity_message" ], "title": "CreateTransformActivityRequest", "description": "Request to create a custom transform activity with full audit metadata" }, "CreateTransformActivityResponse": { "properties": { "activity_id": { "type": "string", "title": "Activity Id" }, "status": { "type": "string", "title": "Status" }, "staged_count": { "type": "integer", "title": "Staged Count" }, "review_url": { "type": "string", "title": "Review Url" } }, "type": "object", "required": [ "activity_id", "status", "staged_count", "review_url" ], "title": "CreateTransformActivityResponse", "description": "Response after creating a custom transform activity" }, "EnrichItemResult": { "properties": { "original_data": { "additionalProperties": true, "type": "object", "title": "Original Data", "description": "The original input data" }, "after_data": { "additionalProperties": true, "type": "object", "title": "After Data", "description": "Complete enriched record with values, sources, and source_explanations" }, "all_sources": { "items": { "type": "string" }, "type": "array", "title": "All Sources", "description": "All web sources used across all fields" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if enrichment failed for this item" }, "category_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category Id", "description": "Predicted taxonomy node ID" }, "taxonomy_attributes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Taxonomy Attributes", "description": "Predicted taxonomy-specific attributes" }, "taxonomy_attribute_sources": { "anyOf": [ { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Taxonomy Attribute Sources", "description": "Per-attribute source URLs or input references used to derive taxonomy attribute values" }, "taxonomy_attribute_explanations": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Taxonomy Attribute Explanations", "description": "Per-attribute explanations of how values were derived from sources" }, "review_info": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Review Info", "description": "AI reasoning, flags for human review" }, "low_confidence_candidates": { "anyOf": [ { "items": { "$ref": "#/components/schemas/LowConfidenceCandidate" }, "type": "array" }, { "type": "null" } ], "title": "Low Confidence Candidates", "description": "Optional tail section of plausible but non-canonical field or taxonomy candidates" }, "low_confidence_fields": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Low Confidence Fields", "description": "Field or taxonomy attribute names that should be highlighted as low-confidence while remaining in after_data" }, "staged_change_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Staged Change Id", "description": "ID of the staged change record (if stage_changes=true)" } }, "type": "object", "required": [ "original_data" ], "title": "EnrichItemResult", "description": "Result for a single enriched item." }, "EnrichRequest": { "additionalProperties": false, "description": "Request to enrich item data.", "properties": { "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "", "description": "Search prompt for web enrichment (e.g., 'Find product specifications'). Optional - defaults to empty string.", "title": "Prompt" }, "items": { "description": "List of items to enrich. Required unless source_activity_id or source_catalog_id is provided.", "items": { "additionalProperties": true, "type": "object" }, "title": "Items", "type": "array" }, "output_schema": { "description": "Schema defining fields to extract. Required unless source_activity_id or source_catalog_id is provided.", "items": { "$ref": "#/components/schemas/FieldDefinition" }, "title": "Output Schema", "type": "array" }, "attribute_sets": { "anyOf": [ { "additionalProperties": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Canonical registry for requested-attribute jobs. Items carry attribute_set_id; workers expand that id to requested_attributes only at runtime. Per-row requested_attributes payloads are rejected by the public endpoint.", "title": "Attribute Sets" }, "source_hint_sets": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Canonical registry for repeated per-item source hints. Items carry source_hint_set_id; workers expand that id to source_hints only at runtime. Inline source_hints are rejected by the public endpoint.", "title": "Source Hint Sets" }, "allowed_domains": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Restrict web scraping to these domains only", "title": "Allowed Domains" }, "blocked_domains": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Domains to exclude from web search and URL fetches", "title": "Blocked Domains" }, "speed": { "default": "deep", "description": "Processing speed: 'fast' (quick), 'medium' (balanced), 'deep'/'slow' (thorough default), 'ultra_slow' (maximum reasoning / strongest model path)", "title": "Speed", "type": "string" }, "web_search": { "default": true, "description": "If true (default), performs web search to gather content. If false, skips web search and uses input data directly for extraction/validation.", "title": "Web Search", "type": "boolean" }, "max_rows": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Limit processing to first N items. All items are stored. Use source_activity_id to process remaining items later.", "title": "Max Rows" }, "taxonomy": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Taxonomy definition for category prediction (TaxonomyInput format)", "title": "Taxonomy" }, "predict_taxonomy": { "default": false, "description": "If true and taxonomy is provided, predict category_id for each item", "title": "Predict Taxonomy", "type": "boolean" }, "predict_taxonomy_attributes": { "default": true, "description": "If true, also predict taxonomy_attributes after classification. Set false for taxonomy classification only.", "title": "Predict Taxonomy Attributes", "type": "boolean" }, "validate_semantics": { "default": false, "description": "If true, AI validates that field values make sense given their descriptions (e.g., email field contains valid email format)", "title": "Validate Semantics", "type": "boolean" }, "review_mode": { "default": true, "description": "Run the enrich review agent after enrichment, apply clear output corrections, and attach activity.output.audit decisions. Public enrichment jobs keep this enabled.", "title": "Review Mode", "type": "boolean" }, "audit_decisions_enabled": { "default": true, "description": "When false, the post-enrichment audit still applies clear output corrections but suppresses human-facing audit decisions/suggestions.", "title": "Audit Decisions Enabled", "type": "boolean" }, "include_source_explanations": { "default": true, "description": "Include source_explanation for each enriched field (and taxonomy attribute) explaining how the value was derived from sources. Always enabled.", "title": "Include Source Explanations", "type": "boolean" }, "low_confidence": { "anyOf": [ { "$ref": "#/components/schemas/LowConfidenceConfig" }, { "type": "null" } ], "default": null, "description": "Optional add-on for returning low-confidence candidates at the end of each result" }, "catalog_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional catalog ID to link this enrichment job to", "title": "Catalog Id" }, "template_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional organization-scoped enrichment template key. Template extraction fields apply to omitted request fields; template-owned safety controls remain enforced.", "title": "Template Id" }, "async_mode": { "default": false, "description": "If true, returns immediately with job_id instead of waiting for results", "title": "Async Mode", "type": "boolean" }, "staged_status": { "default": "pending", "description": "Status for staged changes: 'pending' (default, visible to admin) or 'draft' (vendor draft, not visible to admin until submitted)", "title": "Staged Status", "type": "string" }, "source_activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Activity ID of a previous run. Processes all stored items using saved config.", "title": "Source Activity Id" }, "source_catalog_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Catalog UUID to read items FROM as the enrichment input. Independent of catalog_id (the write target).", "title": "Source Catalog Id" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Original file name if items were loaded from a file", "title": "File Name" }, "include_service_usage": { "default": false, "description": "If true, include detailed service_usage metrics (costs, tokens, per-item stats) in response", "title": "Include Service Usage", "type": "boolean" }, "include_debug_log": { "default": false, "description": "If true, capture full audit log per item (raw markdown, tool history, LLM responses) and upload to storage", "title": "Include Debug Log", "type": "boolean" }, "capture_source_artifacts": { "default": false, "description": "If true, preserve durable copies of consulted source material for audit trails. Web pages are captured as screenshots; PDFs are copied as PDF files.", "title": "Capture Source Artifacts", "type": "boolean" }, "reextract_from_activity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Activity ID to re-extract from. Skips web gather, reuses stored web research data. Supports prompt/schema overrides and feedback.", "title": "Reextract From Activity Id" }, "global_feedback": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Feedback to apply to all items during re-extraction (appended to prompt)", "title": "Global Feedback" }, "item_feedback": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Per-item feedback keyed by row index as string (e.g. {'0': 'Wrong product', '3': 'Price is in EUR not USD'})", "title": "Item Feedback" }, "source_row_indices": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Row indices to re-extract (others carried forward from source). Only used with reextract_from_activity_id.", "title": "Source Row Indices" }, "webhook_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "HTTPS URL to POST results to when job completes. Must use https://.", "title": "Webhook Url" }, "knowledge_base_enabled": { "default": false, "description": "If true, use an uploaded knowledge base (OpenAI vector store) for structured generation.", "title": "Knowledge Base Enabled", "type": "boolean" }, "knowledge_base_vector_store_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "OpenAI vector store ID containing uploaded knowledge base files.", "title": "Knowledge Base Vector Store Id" }, "knowledge_base_sources": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional SOURCE_X -> source URL mapping used for field-level citations (for example {'SOURCE_1': 'https://.../specs.pdf'}).", "title": "Knowledge Base Sources" }, "knowledge_base_metadata": { "anyOf": [ { "additionalProperties": { "additionalProperties": true, "type": "object" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional SOURCE_X -> metadata mapping for uploaded knowledge-base files (for example {'SOURCE_1': {'doc_type': 'approved_marketing'}}).", "title": "Knowledge Base Metadata" }, "host_media": { "default": false, "description": "If true, upload all media URLs (images, PDFs) found in enrichment results to hosted storage, replacing with hosted URLs.", "title": "Host Media", "type": "boolean" }, "strict_hosted_media": { "default": false, "description": "If true, media/document output fields are cleared unless the URL is successfully copied to hosted storage.", "title": "Strict Hosted Media", "type": "boolean" }, "image_processing": { "anyOf": [ { "$ref": "#/components/schemas/ImageProcessingConfig" }, { "type": "null" } ], "default": null, "description": "Optional deterministic post-processing for hosted images, such as square white-background catalog normalization." } }, "title": "EnrichRequest", "type": "object" }, "EnrichResponse": { "properties": { "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Job Id", "description": "Job ID for tracking (always returned). Use this with source_activity_id to trigger full run." }, "results": { "items": { "$ref": "#/components/schemas/EnrichItemResult" }, "type": "array", "title": "Results", "description": "Enrichment results for each item (empty if async_mode=true)" }, "total_items": { "type": "integer", "title": "Total Items", "description": "Number of items being processed (may be limited by max_rows)" }, "total_rows": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Rows", "description": "Total items passed in the request (before max_rows limit)" }, "successful": { "type": "integer", "title": "Successful", "description": "Number of successfully enriched items", "default": 0 }, "credits_used": { "type": "integer", "title": "Credits Used", "description": "Number of credits used (1 per successful item)", "default": 0 }, "status": { "type": "string", "title": "Status", "description": "Job status: 'running' (async) or 'completed' (sync)", "default": "completed" }, "service_usage": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Service Usage", "description": "Detailed API usage metrics (costs, calls, tokens) - only present when job is complete" }, "pricing_estimates": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Pricing Estimates", "description": "Estimated pricing breakdown (for example knowledge-base storage + model runtime costs when available)" }, "knowledge_base_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Knowledge Base Enabled", "description": "Whether this enrichment job used a knowledge base vector store" }, "knowledge_base_sources": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Knowledge Base Sources", "description": "SOURCE_X -> hosted document URL mapping for knowledge-base files used by the activity" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page", "description": "Current page number (1-indexed)" }, "page_size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Size", "description": "Number of results per page" }, "total_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total Pages", "description": "Total number of pages available" }, "completed_items": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Completed Items", "description": "Number of items with results available so far (useful while status=running)" } }, "type": "object", "required": [ "total_items" ], "title": "EnrichResponse", "description": "Response with enriched data for all items." }, "FieldDefinition": { "description": "Definition for a single field to extract - matches attribute mapper field schema.", "properties": { "name": { "description": "Field name", "title": "Name", "type": "string" }, "type": { "default": "string", "description": "Field type: string, number, integer, boolean, array", "title": "Type", "type": "string" }, "description": { "description": "Description of what to extract for this field", "title": "Description", "type": "string" }, "array_element_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "For array fields, the type of elements: string, number, integer, image_url", "title": "Array Element Type" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Units for numeric fields (e.g., 'kg', 'USD', 'cm')", "title": "Unit" }, "enum": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Constrain extraction to these specific values", "title": "Enum" }, "items_enum": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "For array fields, constrain items to these specific values", "title": "Items Enum" }, "sample_values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Example values to guide extraction", "title": "Sample Values" }, "required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the field is required", "title": "Required" }, "merge": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether to merge with existing values", "title": "Merge" }, "pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional regex pattern constraint for extracted text", "title": "Pattern" }, "pattern_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Human-readable guidance for the pattern constraint", "title": "Pattern Message" }, "min_length": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Minimum string length", "title": "Min Length" }, "max_length": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Maximum string length", "title": "Max Length" }, "minimum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Minimum numeric value", "title": "Minimum" }, "maximum": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Maximum numeric value", "title": "Maximum" }, "unique": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the field should be unique within the target catalog", "title": "Unique" }, "semantic_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional semantic type hint such as image_url or document_url", "title": "Semantic Type" } }, "required": [ "name", "description" ], "title": "FieldDefinition", "type": "object" }, "FieldWorkflowInfo": { "properties": { "field_name": { "type": "string", "title": "Field Name" }, "field_type": { "type": "string", "title": "Field Type" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "required": { "type": "boolean", "title": "Required", "default": false }, "field_category": { "type": "string", "title": "Field Category", "default": "input" }, "scope": { "type": "string", "title": "Scope", "default": "variant" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unit" }, "sample_values": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Sample Values" }, "added_by_workflow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Added By Workflow" }, "added_by_node": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Added By Node" }, "added_in_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Added In Version" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "last_edited_by_workflow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Edited By Workflow" }, "last_edited_by_node": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Edited By Node" }, "last_edited_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Edited At" }, "last_edited_in_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Edited In Version" }, "validation_rules": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Validation Rules" } }, "type": "object", "required": [ "field_name", "field_type" ], "title": "FieldWorkflowInfo", "description": "Workflow tracking information for a specific field" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ImageProcessingConfig": { "description": "Optional deterministic post-processing applied when media is hosted.", "properties": { "enabled": { "default": false, "description": "Whether to normalize hosted image assets.", "title": "Enabled", "type": "boolean" }, "make_square": { "default": true, "description": "Pad image onto a square canvas.", "title": "Make Square", "type": "boolean" }, "background_color": { "default": "#FFFFFF", "description": "Hex background color used for padding/transparency.", "title": "Background Color", "type": "string" }, "min_side_px": { "default": 500, "description": "Minimum output side length.", "maximum": 8192, "minimum": 1, "title": "Min Side Px", "type": "integer" }, "max_side_px": { "default": 1700, "description": "Maximum output side length.", "maximum": 8192, "minimum": 1, "title": "Max Side Px", "type": "integer" }, "output_format": { "default": "jpeg", "description": "Output format: jpeg, png, or webp.", "title": "Output Format", "type": "string" }, "quality": { "default": 92, "description": "Output quality for lossy formats.", "maximum": 100, "minimum": 1, "title": "Quality", "type": "integer" }, "force_reprocess_hosted": { "default": false, "description": "Re-download and normalize already-hosted catalog images.", "title": "Force Reprocess Hosted", "type": "boolean" }, "fields": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Optional field allow-list. If omitted, all detected image fields are processed.", "title": "Fields" } }, "title": "ImageProcessingConfig", "type": "object" }, "InferEnrichmentRequest": { "properties": { "prompt": { "type": "string", "title": "Prompt", "description": "Description of the data (e.g., 'Audio products catalog - headphones and earbuds')" }, "items": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Items", "description": "Sample items to analyze (5-20 items recommended)" } }, "type": "object", "required": [ "prompt", "items" ], "title": "InferEnrichmentRequest", "description": "Request to infer schema, taxonomy, and enrichment fields from sample data." }, "InferEnrichmentResponse": { "properties": { "suggested_schema": { "additionalProperties": true, "type": "object", "title": "Suggested Schema", "description": "JSON Schema for catalog creation with properties dict. Ready to use with catalog creation endpoint." }, "suggested_taxonomy": { "additionalProperties": true, "type": "object", "title": "Suggested Taxonomy", "description": "Taxonomy in TaxonomyInput format (name, description, hierarchy_levels, nodes). Ready to use with catalog creation endpoint." }, "web_enrichment_fields": { "items": { "$ref": "#/components/schemas/FieldDefinition" }, "type": "array", "title": "Web Enrichment Fields", "description": "Fields that should be enriched via web research. Ready to use as output_schema in /public/enrich endpoint." } }, "type": "object", "required": [ "suggested_schema", "suggested_taxonomy", "web_enrichment_fields" ], "title": "InferEnrichmentResponse", "description": "Response with inferred schema, taxonomy, and web enrichment fields." }, "InferSchemaResponse": { "properties": { "file_name": { "type": "string", "title": "File Name", "description": "Name of the uploaded file" }, "total_rows": { "type": "integer", "title": "Total Rows", "description": "Total rows in the file" }, "sample_rows_used": { "type": "integer", "title": "Sample Rows Used", "description": "Number of rows sampled for inference" }, "suggested_schema": { "additionalProperties": true, "type": "object", "title": "Suggested Schema", "description": "JSON Schema with all fields found in the data. 'x-field-category' indicates 'input' (existing) or 'enriched' (suggested to add via web)." }, "web_enrichment_fields": { "items": { "$ref": "#/components/schemas/FieldDefinition" }, "type": "array", "title": "Web Enrichment Fields", "description": "Fields to extract via web enrichment. Use as output_schema in /public/enrich." }, "suggested_taxonomy": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Suggested Taxonomy", "description": "Taxonomy in TaxonomyInput format. Only present if generate_taxonomy=true." } }, "type": "object", "required": [ "file_name", "total_rows", "sample_rows_used", "suggested_schema", "web_enrichment_fields" ], "title": "InferSchemaResponse", "description": "Response with inferred configuration for enrichment." }, "JudgeCatalogRowsRequest": { "properties": { "rows": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Rows", "description": "Rows to evaluate" }, "catalog_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Catalog Id", "description": "Catalog ID — fetches schema and quality_prompt automatically" }, "schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schema", "description": "Inline schema (only needed if no catalog_id)" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt", "description": "Extra instructions (appended to catalog's quality_prompt if present)" }, "model": { "type": "string", "title": "Model", "description": "Model preset: fast, medium, high", "default": "fast" }, "max_rows": { "type": "integer", "maximum": 500, "minimum": 1, "title": "Max Rows", "description": "Max rows to judge per request", "default": 200 }, "images": { "anyOf": [ { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "type": "object" }, { "type": "null" } ], "title": "Images", "description": "Explicit image URLs per row index, e.g. {\"0\": [\"https://...\"]}" } }, "type": "object", "required": [ "rows" ], "title": "JudgeCatalogRowsRequest", "description": "Request to judge catalog rows. Pulls schema + quality_prompt from catalog when catalog_id is provided.\n\nFor multimodal judging (e.g. verifying images match product data), pass ``images``\nas a dict mapping row index (string) to a list of image URLs. When images are\npresent the judge uses a vision model automatically." }, "JudgeCatalogRowsResponse": { "properties": { "judgments": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Judgments", "description": "Per-row judgments from the LLM" }, "meta": { "additionalProperties": true, "type": "object", "title": "Meta", "description": "Model, row counts, etc." } }, "type": "object", "title": "JudgeCatalogRowsResponse", "description": "Row-level quality judgments." }, "LowConfidenceCandidate": { "properties": { "scope": { "type": "string", "title": "Scope", "description": "Candidate scope: field, taxonomy_attribute, or category", "default": "field" }, "name": { "type": "string", "title": "Name", "description": "Canonical field or taxonomy attribute name" }, "candidate_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Candidate Value", "description": "Candidate value serialized as exact text or compact JSON" }, "confidence": { "type": "string", "title": "Confidence", "description": "Confidence level for this candidate", "default": "LOW" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Why this candidate is plausible but not strong enough for canonical output" }, "sources": { "items": { "type": "string" }, "type": "array", "title": "Sources", "description": "Resolved source URLs or input:* references supporting the candidate" }, "source_explanation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Explanation", "description": "Optional short explanation of where the candidate came from" } }, "type": "object", "required": [ "name" ], "title": "LowConfidenceCandidate", "description": "A plausible but non-canonical candidate that should not be merged into final output." }, "LowConfidenceConfig": { "description": "Optional request flag for emitting low-confidence candidates at the end of a result.", "properties": { "enabled": { "default": false, "description": "If true, return low-confidence candidates alongside canonical output", "title": "Enabled", "type": "boolean" }, "scopes": { "description": "Which candidate families to include", "items": { "type": "string" }, "title": "Scopes", "type": "array" }, "placement": { "default": "tail", "description": "Payload placement for low-confidence candidates. Only tail is currently supported", "title": "Placement", "type": "string" }, "max_candidates_per_item": { "default": 8, "description": "Maximum low-confidence candidates to return per item", "maximum": 20, "minimum": 1, "title": "Max Candidates Per Item", "type": "integer" } }, "title": "LowConfidenceConfig", "type": "object" }, "PaginatedResults": { "properties": { "data": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Data" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "data", "total", "page", "page_size", "has_more" ], "title": "PaginatedResults", "description": "Paginated result set" }, "PublicCatalogItem": { "properties": { "id": { "type": "string", "title": "Id" }, "data": { "additionalProperties": true, "type": "object", "title": "Data" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata" } }, "type": "object", "required": [ "id", "data", "metadata" ], "title": "PublicCatalogItem" }, "PublicCatalogListResponse": { "properties": { "catalogs": { "items": { "$ref": "#/components/schemas/PublicCatalogResponse" }, "type": "array", "title": "Catalogs" }, "total_count": { "type": "integer", "title": "Total Count" }, "page": { "type": "integer", "title": "Page", "default": 1 }, "page_size": { "type": "integer", "title": "Page Size", "default": 50 } }, "type": "object", "required": [ "catalogs", "total_count" ], "title": "PublicCatalogListResponse", "description": "Response model for listing catalogs" }, "PublicCatalogResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "organization_id": { "type": "string", "title": "Organization Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "current_schema_version": { "type": "string", "title": "Current Schema Version" }, "unique_id_field": { "type": "string", "title": "Unique Id Field" }, "product_id_field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id Field" }, "auto_evolve_schema": { "type": "boolean", "title": "Auto Evolve Schema" }, "strict_mode": { "type": "boolean", "title": "Strict Mode" }, "product_enabled": { "type": "boolean", "title": "Product Enabled" }, "item_count": { "type": "integer", "title": "Item Count" }, "created_by_user_id": { "type": "string", "title": "Created By User Id" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At" }, "schema": { "anyOf": [ { "$ref": "#/components/schemas/CatalogSchemaResponse" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "organization_id", "name", "current_schema_version", "unique_id_field", "auto_evolve_schema", "strict_mode", "product_enabled", "item_count", "created_by_user_id", "created_at" ], "title": "PublicCatalogResponse", "description": "Response model for catalog information" }, "PublicCreateCatalogRequest": { "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "title": "Name", "description": "Catalog name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Optional catalog description" }, "unique_id_field": { "type": "string", "title": "Unique Id Field", "description": "Legacy compatibility field required by the public create request. Include the intended business key, such as sku, in schema and item data; this request field is not a separate runtime selector." }, "product_id_field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product Id Field", "description": "Field name to use as product identifier" }, "auto_evolve_schema": { "type": "boolean", "title": "Auto Evolve Schema", "description": "Allow automatic schema evolution", "default": true }, "strict_mode": { "type": "boolean", "title": "Strict Mode", "description": "Reject unknown fields", "default": false }, "product_enabled": { "type": "boolean", "title": "Product Enabled", "description": "Whether this catalog supports product variants", "default": false }, "schema_definition": { "additionalProperties": true, "type": "object", "title": "Schema Definition", "description": "Initial JSON Schema for the catalog (from preview), including properties and required" }, "validation_rules": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Validation Rules", "description": "Catalog-level validation rules to copy or override" }, "catalog_md": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Catalog Md", "description": "Markdown catalog context to copy or override" }, "master_catalog_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Master Catalog Id", "description": "Explicit master catalog to inherit defaults from" }, "use_master_catalog_defaults": { "type": "boolean", "title": "Use Master Catalog Defaults", "description": "Whether to inherit defaults from the org's default master catalog", "default": true } }, "type": "object", "required": [ "name", "unique_id_field", "schema_definition" ], "title": "PublicCreateCatalogRequest", "description": "Request to create a new catalog" }, "PublicNodeOutputs": { "properties": { "node_type": { "type": "string", "title": "Node Type" }, "data": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Data" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" }, "has_more": { "type": "boolean", "title": "Has More" } }, "type": "object", "required": [ "node_type", "data", "total", "page", "page_size", "has_more" ], "title": "PublicNodeOutputs", "description": "Outputs from a single node (paginated)" }, "PublicStagedChangeInput": { "properties": { "catalog_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Catalog Item Id" }, "catalog_item_entity_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Catalog Item Entity Type" }, "before_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Before Data" }, "after_data": { "additionalProperties": true, "type": "object", "title": "After Data" }, "source_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Data" }, "is_new_item": { "type": "boolean", "title": "Is New Item", "default": false }, "row_index": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Row Index" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/app__models__staged_changes__StagedChangeStatus" }, { "type": "null" } ] } }, "type": "object", "required": [ "after_data" ], "title": "PublicStagedChangeInput", "description": "Input for a single staged change in the public API" }, "PublicUpdateCatalogRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 100, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Updated catalog name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Updated catalog description" }, "auto_evolve_schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Auto Evolve Schema", "description": "Allow automatic schema evolution" }, "strict_mode": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Strict Mode", "description": "Reject unknown fields" }, "catalog_md": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Catalog Md", "description": "Markdown context injected into enrichment and mapping prompts" } }, "type": "object", "title": "PublicUpdateCatalogRequest", "description": "Request to update catalog settings" }, "PublicUpsertItemRequest": { "properties": { "unique_identifier": { "type": "string", "title": "Unique Identifier", "description": "Legacy compatibility field. Put the business identifier inside data as well; public single-item upsert uses the submitted data for matching." }, "data": { "additionalProperties": true, "type": "object", "title": "Data" }, "source_info": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Source Info" } }, "type": "object", "required": [ "unique_identifier", "data" ], "title": "PublicUpsertItemRequest" }, "PublicWorkflowExecuteRequest": { "properties": { "input": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Input", "description": "Input data records to process through the workflow" }, "cancel_existing": { "type": "boolean", "title": "Cancel Existing", "description": "Cancel any currently running executions before starting this one", "default": false } }, "type": "object", "required": [ "input" ], "title": "PublicWorkflowExecuteRequest", "description": "Request to execute a workflow with input data" }, "PublicWorkflowExecuteResponse": { "properties": { "workflow_run_id": { "type": "string", "title": "Workflow Run Id" }, "workflow_id": { "type": "string", "title": "Workflow Id" }, "workflow_name": { "type": "string", "title": "Workflow Name" }, "status": { "type": "string", "title": "Status" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "poll_url": { "type": "string", "title": "Poll Url" }, "workflow_url": { "type": "string", "title": "Workflow Url" }, "total_nodes": { "type": "integer", "title": "Total Nodes" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "workflow_run_id", "workflow_id", "workflow_name", "status", "created_at", "poll_url", "workflow_url", "total_nodes", "message" ], "title": "PublicWorkflowExecuteResponse", "description": "Response from workflow execution start" }, "PublicWorkflowListResponse": { "properties": { "workflows": { "items": { "$ref": "#/components/schemas/PublicWorkflowSummary" }, "type": "array", "title": "Workflows" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "page_size": { "type": "integer", "title": "Page Size" } }, "type": "object", "required": [ "workflows", "total", "page", "page_size" ], "title": "PublicWorkflowListResponse", "description": "Response from listing workflows" }, "PublicWorkflowRunStatus": { "properties": { "workflow_run_id": { "type": "string", "title": "Workflow Run Id" }, "workflow_id": { "type": "string", "title": "Workflow Id" }, "workflow_name": { "type": "string", "title": "Workflow Name" }, "workflow_url": { "type": "string", "title": "Workflow Url" }, "status": { "type": "string", "title": "Status" }, "progress": { "type": "number", "title": "Progress" }, "current_step": { "type": "string", "title": "Current Step" }, "message": { "type": "string", "title": "Message" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At" }, "updates": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Updates" }, "results": { "anyOf": [ { "$ref": "#/components/schemas/PaginatedResults" }, { "type": "null" } ] }, "node_results": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/PublicNodeOutputs" }, "type": "object" }, { "type": "null" } ], "title": "Node Results" } }, "type": "object", "required": [ "workflow_run_id", "workflow_id", "workflow_name", "workflow_url", "status", "progress", "current_step", "message", "created_at", "updated_at", "completed_at", "updates", "results", "node_results" ], "title": "PublicWorkflowRunStatus", "description": "Status and results of a workflow run" }, "PublicWorkflowSummary": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "total_nodes": { "type": "integer", "title": "Total Nodes" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "workflow_url": { "type": "string", "title": "Workflow Url" } }, "type": "object", "required": [ "id", "name", "description", "total_nodes", "created_at", "updated_at", "workflow_url" ], "title": "PublicWorkflowSummary", "description": "Summary of a workflow for listing" }, "SaveActivityAsWorkflowRequest": { "properties": { "workflow_name": { "type": "string", "title": "Workflow Name", "description": "Workflow name" }, "workflow_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Workflow Description", "description": "Workflow description" }, "python_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Python Code", "description": "Optional custom Python code override for custom_code node" }, "attachments": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Attachments", "description": "Optional attachment metadata to persist on workflow/nodes" }, "timeout_seconds": { "type": "integer", "maximum": 1800, "minimum": 1, "title": "Timeout Seconds", "description": "Execution timeout for custom code node", "default": 120 } }, "type": "object", "required": [ "workflow_name" ], "title": "SaveActivityAsWorkflowRequest" }, "SchemaFieldOperationResponse": { "properties": { "success": { "type": "boolean", "title": "Success" }, "catalog_id": { "type": "string", "title": "Catalog Id" }, "new_schema_version": { "type": "string", "title": "New Schema Version" }, "previous_schema_version": { "type": "string", "title": "Previous Schema Version" }, "fields_added": { "items": { "type": "string" }, "type": "array", "title": "Fields Added", "default": [] }, "fields_updated": { "items": { "type": "string" }, "type": "array", "title": "Fields Updated", "default": [] }, "fields_removed": { "items": { "type": "string" }, "type": "array", "title": "Fields Removed", "default": [] }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "success", "catalog_id", "new_schema_version", "previous_schema_version", "message" ], "title": "SchemaFieldOperationResponse", "description": "Response for schema field operations" }, "SetPendingReviewRequest": { "properties": { "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Message", "description": "Optional review message" }, "output": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output", "description": "Optional output summary metadata" } }, "type": "object", "title": "SetPendingReviewRequest", "description": "Request to move an activity to pending_review." }, "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" }, "_UpdateCatalogMdRequest": { "properties": { "catalog_md": { "type": "string", "title": "Catalog Md" } }, "type": "object", "required": [ "catalog_md" ], "title": "_UpdateCatalogMdRequest" }, "_UpdateQualityPromptRequest": { "properties": { "prompt": { "type": "string", "title": "Prompt" } }, "type": "object", "required": [ "prompt" ], "title": "_UpdateQualityPromptRequest" }, "app__models__staged_changes__StagedChangeStatus": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected", "partially_accepted", "error" ], "title": "StagedChangeStatus", "description": "Status for individual staged changes" } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Rastro API key or user token" } } } }