{"openapi":"3.1.0","info":{"title":"API Reference","version":"1.0.0"},"paths":{"/collections":{"get":{"operationId":"collections_list_collections_get","summary":"List Collections","description":"Retrieve all collections belonging to your organization.\n\nCollections are containers that group related data from one or more source\nconnections, enabling unified search across multiple data sources.\n\nResults are sorted by creation date (newest first) and support pagination\nand text search filtering.","tags":["collections"],"parameters":[{"name":"skip","in":"query","description":"Number of collections to skip for pagination","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","description":"Maximum number of collections to return (1-1000)","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"search","in":"query","description":"Search term to filter collections by name or readable_id","required":false,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}},"post":{"operationId":"collections_create_collections_post","summary":"Create Collection","description":"Create a new collection in your organization.\n\nCollections are containers for organizing and searching across data from multiple\nsources. After creation, add source connections to begin syncing data.\n\nThe collection will be assigned a unique `readable_id` based on the name you provide,\nwhich is used in URLs and API calls. You can optionally configure:\n\n- **Sync schedule**: How frequently to automatically sync data from all sources\n- **Custom readable_id**: Provide your own identifier (must be unique and URL-safe)","tags":["collections"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Created collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCreate"}}}}}},"/collections/{readable_id}":{"get":{"operationId":"collections_get_collections__readable_id__get","summary":"Get Collection","description":"Retrieve details of a specific collection by its readable ID.\n\nReturns the complete collection configuration including sync settings, status,\nand metadata. Use this to check the current state of a collection or to get\nconfiguration details before making updates.","tags":["collections"],"parameters":[{"name":"readable_id","in":"path","description":"The unique readable identifier of the collection (e.g., 'finance-data-ab123')","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Collection details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"Collection Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}},"patch":{"operationId":"collections_update_collections__readable_id__patch","summary":"Update Collection","description":"Update an existing collection's properties.\n\nYou can modify:\n- **Name**: The display name shown in the UI\n- **Sync configuration**: Schedule settings for automatic data synchronization\n\nNote that the `readable_id` cannot be changed after creation to maintain stable\nAPI endpoints and preserve existing integrations.","tags":["collections"],"parameters":[{"name":"readable_id","in":"path","description":"The unique readable identifier of the collection to update","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"Collection Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionUpdate"}}}}},"delete":{"operationId":"collections_delete_collections__readable_id__delete","summary":"Delete Collection","description":"Permanently delete a collection and all associated data.\n\nThis operation:\n- Removes all synced data from the vector database\n- Deletes all source connections within the collection\n- Cancels any scheduled sync jobs\n- Cleans up all related resources\n\n**Warning**: This action cannot be undone. All data will be permanently deleted.","tags":["collections"],"parameters":[{"name":"readable_id","in":"path","description":"The unique readable identifier of the collection to delete","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"Collection Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/collections/{readable_id}/search/instant":{"post":{"operationId":"collections_search_instant","summary":"Instant Search","description":"Direct vector search.","tags":["collections > search"],"parameters":[{"name":"readable_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchV2Response"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstantSearchRequest"}}}}}},"/collections/{readable_id}/search/classic":{"post":{"operationId":"collections_search_classic","summary":"Classic Search","description":"AI-optimized search.","tags":["collections > search"],"parameters":[{"name":"readable_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchV2Response"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassicSearchRequest"}}}}}},"/collections/{readable_id}/search/agentic":{"post":{"operationId":"collections_search_agentic","summary":"Agentic Search","description":"Agent that iteratively searches, reads, navigates hierarchies, and collects results.","tags":["collections > search"],"parameters":[{"name":"readable_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchV2Response"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticSearchRequest"}}}}}},"/collections/{readable_id}/search/agentic/stream":{"post":{"operationId":"collections_search_stream_agentic","summary":"Stream Agentic Search","description":"Streaming agentic search via Server-Sent Events. Returns real-time events as the agent searches.","tags":["collections > search"],"parameters":[{"name":"readable_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SSE stream of agentic search events.","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/AgenticSearchEvent"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticSearchRequest"}}}}}},"/source-connections":{"get":{"operationId":"sourceConnections_list_source_connections_get","summary":"List Source Connections","description":"Retrieve all source connections for your organization.\n\nReturns a lightweight list of source connections with essential fields for\ndisplay and navigation. Use the collection filter to see connections within\na specific collection.\n\nFor full connection details including sync history, use the GET /{id} endpoint.","tags":["source-connections"],"parameters":[{"name":"collection","in":"query","description":"Filter by collection readable ID","required":false,"schema":{"type":["string","null"]}},{"name":"skip","in":"query","description":"Number of connections to skip for pagination","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","description":"Maximum number of connections to return (1-1000)","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of source connections","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SourceConnectionListItem"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}},"post":{"operationId":"sourceConnections_create_source_connections_post","summary":"Create Source Connection","description":"Create a new source connection to sync data from an external source.\n\nThe authentication method determines the creation flow:\n\n- **Direct**: Provide credentials (API key, token) directly. Connection is created immediately.\n- **OAuth Browser**: Returns a connection with an `auth_url` to redirect users for authentication.\n- **OAuth Token**: Provide an existing OAuth token. Connection is created immediately.\n- **Auth Provider**: Use a pre-configured auth provider (e.g., Composio, Pipedream).\n\nAfter successful authentication, data sync can begin automatically or on-demand.","tags":["source-connections"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Created source connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceConnection"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceConnectionCreate"}}}}}},"/source-connections/{source_connection_id}":{"get":{"operationId":"sourceConnections_get_source_connections__source_connection_id__get","summary":"Get Source Connection","description":"Retrieve details of a specific source connection.\n\nReturns complete information about the connection including:\n- Configuration settings\n- Authentication status\n- Sync schedule and history\n- Entity statistics","tags":["source-connections"],"parameters":[{"name":"source_connection_id","in":"path","description":"Unique identifier of the source connection (UUID)","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Source connection details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceConnection"}}}},"404":{"description":"Source Connection Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}},"patch":{"operationId":"sourceConnections_update_source_connections__source_connection_id__patch","summary":"Update Source Connection","description":"Update an existing source connection's configuration.\n\nYou can modify:\n- **Name and description**: Display information\n- **Configuration**: Source-specific settings (e.g., repository name, filters)\n- **Schedule**: Cron expression for automatic syncs\n- **Authentication**: Update credentials (direct auth only)\n\nOnly include the fields you want to change; omitted fields retain their current values.","tags":["source-connections"],"parameters":[{"name":"source_connection_id","in":"path","description":"Unique identifier of the source connection to update (UUID)","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated source connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceConnection"}}}},"404":{"description":"Source Connection Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceConnectionUpdate"}}}}},"delete":{"operationId":"sourceConnections_delete_source_connections__source_connection_id__delete","summary":"Delete Source Connection","description":"Permanently delete a source connection and all its synced data.\n\n**What happens when you delete:**\n\n1. Any running sync is cancelled and the API waits (up to 15 s) for the\n   worker to stop writing.\n2. The source connection, sync configuration, job history, and entity\n   metadata are cascade-deleted from the database.\n3. A background cleanup workflow is scheduled to remove data from the\n   vector database (Vespa) and raw data storage (ARF). This may take\n   several minutes for large datasets but does **not** block the response.\n\nThe API returns immediately after step 2. Vector database cleanup happens\nasynchronously -- the data becomes unsearchable as soon as the database\nrecords are deleted.\n\n**Warning**: This action cannot be undone.","tags":["source-connections"],"parameters":[{"name":"source_connection_id","in":"path","description":"Unique identifier of the source connection to delete (UUID)","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted source connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceConnection"}}}},"404":{"description":"Source Connection Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/source-connections/{source_connection_id}/jobs":{"get":{"operationId":"sourceConnections_get_source_connection_jobs_source_connections__source_connection_id__jobs_get","summary":"List Sync Jobs","description":"Retrieve the sync job history for a source connection.\n\nReturns a list of sync jobs ordered by creation time (newest first). Each job\nincludes status, timing information, and entity counts.\n\nJob statuses:\n- **PENDING**: Job is queued, waiting for the worker to pick it up\n- **RUNNING**: Sync is actively pulling and processing data\n- **COMPLETED**: Sync finished successfully\n- **FAILED**: Sync encountered an unrecoverable error\n- **CANCELLING**: Cancellation has been requested. The worker is\n  gracefully stopping the pipeline and cleaning up destination data.\n- **CANCELLED**: Sync was cancelled. The worker has fully stopped\n  and destination data cleanup has been scheduled.","tags":["source-connections"],"parameters":[{"name":"source_connection_id","in":"path","description":"Unique identifier of the source connection (UUID)","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of jobs to return (1-1000)","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of sync jobs","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SourceConnectionJob"}}}}},"404":{"description":"Source Connection Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/source-connections/{source_connection_id}/run":{"post":{"operationId":"sourceConnections_run_source_connections__source_connection_id__run_post","summary":"Run Sync","description":"Trigger a data synchronization job for a source connection.\n\nStarts an asynchronous sync job that pulls the latest data from the connected\nsource. The job runs in the background and you can monitor its progress using\nthe jobs endpoint.\n\nFor continuous sync connections, this performs an incremental sync by default.\nUse `force_full_sync=true` to perform a complete re-sync of all data.","tags":["source-connections"],"parameters":[{"name":"source_connection_id","in":"path","description":"Unique identifier of the source connection to sync (UUID)","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"force_full_sync","in":"query","description":"Force a full sync ignoring cursor data. Only applies to continuous sync connections. Non-continuous connections always perform full syncs.","required":false,"schema":{"type":"boolean","default":false}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Created sync job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceConnectionJob"}}}},"404":{"description":"Source Connection Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"409":{"description":"Sync Already Running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/source-connections/{source_connection_id}/jobs/{job_id}/cancel":{"post":{"operationId":"sourceConnections_cancel_job_source_connections__source_connection_id__jobs__job_id__cancel_post","summary":"Cancel Sync Job","description":"Request cancellation of a running sync job.\n\n**State lifecycle**: `PENDING` / `RUNNING` → `CANCELLING` → `CANCELLED`\n\n1. The API immediately marks the job as **CANCELLING** in the database.\n2. A cancellation signal is sent to the Temporal workflow.\n3. The worker receives the signal, gracefully stops the sync pipeline\n   (cancels worker pool, source stream), and marks the job as **CANCELLED**.\n\nAlready-processed entities are retained in the vector database.\nIf the worker is unresponsive, a background cleanup job will force the\ntransition to CANCELLED after 3 minutes.\n\n**Note**: Only jobs in `PENDING` or `RUNNING` state can be cancelled.\nAttempting to cancel a `COMPLETED`, `FAILED`, or `CANCELLED` job returns 400.","tags":["source-connections"],"parameters":[{"name":"source_connection_id","in":"path","description":"Unique identifier of the source connection (UUID)","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"job_id","in":"path","description":"Unique identifier of the sync job to cancel (UUID)","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job with cancellation status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceConnectionJob"}}}},"404":{"description":"Job Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"409":{"description":"Job Cannot Be Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/sources":{"get":{"operationId":"sources_list_sources_get","summary":"List Sources","description":"Retrieve all available data source connectors.\n\nReturns the complete catalog of source types that Airweave can connect to,\nincluding their authentication methods, configuration requirements, and\nsupported features. Use this endpoint to discover which integrations are\navailable for your organization.\n\nEach source includes:\n- **Authentication methods**: How to connect (OAuth, API key, etc.)\n- **Configuration schemas**: What settings are required or optional\n- **Supported auth providers**: Pre-configured OAuth providers available","tags":["sources"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/sources/{short_name}":{"get":{"operationId":"sources_get_sources__short_name__get","summary":"Get Source","description":"Retrieve detailed information about a specific data source connector.\n\nReturns the complete configuration for a source type, including:\n\n- **Authentication fields**: Schema for credentials required to connect\n- **Configuration fields**: Schema for optional settings and customization\n- **Supported auth providers**: Pre-configured OAuth providers available for this source\n\nUse this endpoint before creating a source connection to understand what\nauthentication and configuration values are required.","tags":["sources"],"parameters":[{"name":"short_name","in":"path","description":"Technical identifier of the source type (e.g., 'github', 'stripe', 'slack')","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"404":{"description":"Source Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/webhooks/messages":{"get":{"operationId":"webhooks_get_messages_webhooks_messages_get","summary":"List Messages","description":"Retrieve all webhook messages for your organization.\n\nWebhook messages represent payloads that were sent (or attempted to be sent)\nto your subscribed endpoints. Each message contains the event type, payload data,\nand delivery status information.\n\nUse the `event_types` query parameter to filter messages by specific event types,\nsuch as `sync.completed` or `sync.failed`.","tags":["webhooks"],"parameters":[{"name":"event_types","in":"query","description":"Filter messages by event type(s). Accepts multiple values, e.g., `?event_types=sync.completed&event_types=sync.failed`.","required":false,"schema":{"type":["array","null"],"items":{"type":"string"}}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of webhook messages","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookMessage"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/webhooks/messages/{message_id}":{"get":{"operationId":"webhooks_get_message_webhooks_messages__message_id__get","summary":"Get Message","description":"Retrieve a specific webhook message by its ID.\n\nReturns the full message details including the event type, payload data,\ntimestamp, and delivery channel information. Use this to inspect the\nexact payload that was sent to your webhook endpoints.\n\nUse `include_attempts=true` to also retrieve delivery attempts for this message,\nwhich include HTTP response codes, response bodies, and timestamps for debugging\ndelivery failures.","tags":["webhooks"],"parameters":[{"name":"message_id","in":"path","description":"The unique identifier of the message to retrieve (UUID).","required":true,"schema":{"type":"string"}},{"name":"include_attempts","in":"query","description":"Include delivery attempts for this message. Each attempt includes the HTTP response code, response body, and timestamp.","required":false,"schema":{"type":"boolean","default":false}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook message details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookMessageWithAttempts"}}}},"404":{"description":"Message Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/webhooks/subscriptions":{"get":{"operationId":"webhooks_get_subscriptions_webhooks_subscriptions_get","summary":"List Subscriptions","description":"List all webhook subscriptions for your organization.\n\nReturns all configured webhook endpoints, including their URLs, subscribed\nevent types, and current status (enabled/disabled). Use this to audit\nyour webhook configuration or find a specific subscription.","tags":["webhooks"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of webhook subscriptions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}},"post":{"operationId":"webhooks_create_subscription_webhooks_subscriptions_post","summary":"Create Subscription","description":"Create a new webhook subscription.\n\nWebhook subscriptions allow you to receive real-time notifications when events\noccur in Airweave. When you create a subscription, you specify:\n\n- **URL**: The HTTPS endpoint where events will be delivered\n- **Event Types**: Which events you want to receive (e.g., `sync.completed`, `sync.failed`)\n- **Secret** (optional): A custom signing secret for verifying webhook signatures\n\nAfter creation, Airweave will send HTTP POST requests to your URL whenever\nmatching events occur. Each request includes a signature header for verification.","tags":["webhooks"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Created subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionRequest"}}}}}},"/webhooks/subscriptions/{subscription_id}":{"get":{"operationId":"webhooks_get_subscription_webhooks_subscriptions__subscription_id__get","summary":"Get Subscription","description":"Retrieve a specific webhook subscription with its recent delivery attempts.\n\nReturns the subscription configuration along with a history of message delivery\nattempts. This is useful for debugging delivery issues or verifying that your\nendpoint is correctly receiving events.\n\nUse `include_secret=true` to also retrieve the signing secret for webhook\nsignature verification. Keep this secret secure.","tags":["webhooks"],"parameters":[{"name":"subscription_id","in":"path","description":"The unique identifier of the subscription to retrieve (UUID).","required":true,"schema":{"type":"string"}},{"name":"include_secret","in":"query","description":"Include the signing secret for webhook signature verification. Keep this secret secure and use it to verify the 'svix-signature' header.","required":false,"schema":{"type":"boolean","default":false}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription with delivery attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionDetail"}}}},"404":{"description":"Subscription Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}},"patch":{"operationId":"webhooks_patch_subscription_webhooks_subscriptions__subscription_id__patch","summary":"Update Subscription","description":"Update an existing webhook subscription.\n\nUse this endpoint to modify a subscription's configuration. You can:\n\n- **Change the URL**: Update where events are delivered\n- **Update event types**: Modify which events trigger notifications\n- **Enable/disable**: Temporarily pause delivery without deleting the subscription\n- **Recover messages**: When re-enabling, optionally recover missed messages\n\nOnly include the fields you want to change. Omitted fields will retain their\ncurrent values.\n\nWhen re-enabling a subscription (`disabled: false`), you can optionally provide\n`recover_since` to automatically retry all messages that were generated while\nthe subscription was disabled.","tags":["webhooks"],"parameters":[{"name":"subscription_id","in":"path","description":"The unique identifier of the subscription to update (UUID).","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"404":{"description":"Subscription Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchSubscriptionRequest"}}}}},"delete":{"operationId":"webhooks_delete_subscription_webhooks_subscriptions__subscription_id__delete","summary":"Delete Subscription","description":"Permanently delete a webhook subscription.\n\nOnce deleted, Airweave will stop sending events to this endpoint immediately.\nThis action cannot be undone. Any pending message deliveries will be cancelled.\n\nIf you want to temporarily stop receiving events, consider disabling the\nsubscription instead using the PATCH endpoint.","tags":["webhooks"],"parameters":[{"name":"subscription_id","in":"path","description":"The unique identifier of the subscription to delete (UUID).","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"404":{"description":"Subscription Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/webhooks/subscriptions/{subscription_id}/recover":{"post":{"operationId":"webhooks_recover_failed_messages_webhooks_subscriptions__subscription_id__recover_post","summary":"Recover Failed Messages","description":"Retry failed message deliveries for a webhook subscription.\n\nTriggers a recovery process that replays all failed messages within the\nspecified time window. This is useful when:\n\n- Your endpoint was temporarily down and you want to catch up\n- You've fixed a bug in your webhook handler\n- You want to reprocess events after re-enabling a disabled subscription\n\nMessages are retried in chronological order. Successfully delivered messages\nare skipped; only failed or pending messages are retried.","tags":["webhooks"],"parameters":[{"name":"subscription_id","in":"path","description":"The unique identifier of the subscription to recover messages for (UUID).","required":true,"schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recovery task information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryTask"}}}},"404":{"description":"Subscription Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoverMessagesRequest"}}}}}}},"servers":[{"url":"https://api.airweave.ai","description":"Production"},{"url":"http://localhost:8001","description":"Local"}],"components":{"schemas":{"DestinationConfig":{"type":"object","properties":{"skip_vespa":{"type":"boolean","default":false,"description":"Skip writing to native Vespa"},"target_destinations":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"If set, ONLY write to these destination UUIDs"},"exclude_destinations":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"Skip these destination UUIDs"}},"description":"Controls where entities are written.","title":"DestinationConfig"},"HandlerConfig":{"type":"object","properties":{"enable_vector_handlers":{"type":"boolean","default":true,"description":"Enable VectorDBHandler"},"enable_raw_data_handler":{"type":"boolean","default":true,"description":"Enable RawDataHandler (ARF)"},"enable_postgres_handler":{"type":"boolean","default":true,"description":"Enable EntityPostgresHandler"}},"description":"Controls which handlers run during sync.","title":"HandlerConfig"},"CursorConfig":{"type":"object","properties":{"skip_load":{"type":"boolean","default":false,"description":"Don't load cursor (fetch all entities)"},"skip_updates":{"type":"boolean","default":false,"description":"Don't persist cursor progress"}},"description":"Controls incremental sync cursor behavior.","title":"CursorConfig"},"BehaviorConfig":{"type":"object","properties":{"skip_hash_comparison":{"type":"boolean","default":false,"description":"Force INSERT for all entities"},"replay_from_arf":{"type":"boolean","default":false,"description":"Replay from ARF storage instead of calling source"},"skip_guardrails":{"type":"boolean","default":false,"description":"Skip usage guardrails (entity count checks)"}},"description":"Miscellaneous execution behavior flags.","title":"BehaviorConfig"},"SyncConfig":{"type":"object","properties":{"destinations":{"$ref":"#/components/schemas/DestinationConfig"},"handlers":{"$ref":"#/components/schemas/HandlerConfig"},"cursor":{"$ref":"#/components/schemas/CursorConfig"},"behavior":{"$ref":"#/components/schemas/BehaviorConfig"}},"description":"Sync configuration with automatic env var loading.\n\nEnv vars use double underscore as delimiter:\n    SYNC_CONFIG__HANDLERS__ENABLE_VECTOR_HANDLERS=false","title":"SyncConfig"},"CollectionStatus":{"type":"string","enum":["ACTIVE","NEEDS SOURCE","ERROR"],"description":"Collection status enum.","title":"CollectionStatus"},"SourceConnectionSummary":{"type":"object","properties":{"short_name":{"type":"string"},"name":{"type":"string"}},"required":["short_name","name"],"description":"Lightweight summary of a source connection for collection list display.","title":"SourceConnectionSummary"},"Collection":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable display name for the collection."},"readable_id":{"type":"string","description":"URL-safe unique identifier used in API endpoints. This becomes non-optional once the collection is created."},"id":{"type":"string","format":"uuid","description":"Unique system identifier for the collection. This UUID is generated automatically and used for internal references."},"sync_config":{"oneOf":[{"$ref":"#/components/schemas/SyncConfig"},{"type":"null"}],"description":"Default sync configuration for all syncs in this collection. Overridable at sync and job level."},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the collection was created (ISO 8601 format)."},"modified_at":{"type":"string","format":"date-time","description":"Timestamp when the collection was last modified (ISO 8601 format)."},"organization_id":{"type":"string","format":"uuid","description":"Identifier of the organization that owns this collection. Collections are isolated per organization."},"created_by_email":{"type":["string","null"],"format":"email","description":"Email address of the user who created this collection."},"modified_by_email":{"type":["string","null"],"format":"email","description":"Email address of the user who last modified this collection."},"status":{"$ref":"#/components/schemas/CollectionStatus","description":"Current operational status of the collection:<br/>• **NEEDS_SOURCE**: Collection has no authenticated connections, or connections exist but haven't synced yet<br/>• **ACTIVE**: At least one connection has completed a sync or is currently syncing<br/>• **ERROR**: All connections have failed their last sync"},"vector_size":{"type":"integer","description":"Vector dimensions used by this collection (derived from deployment metadata)."},"embedding_model_name":{"type":"string","description":"Name of the embedding model used for this collection (derived from deployment metadata)."},"source_connection_summaries":{"type":"array","items":{"$ref":"#/components/schemas/SourceConnectionSummary"},"description":"Lightweight list of source connections attached to this collection. Contains only short_name and name, suitable for rendering icons in list views."}},"required":["name","readable_id","id","created_at","modified_at","organization_id","vector_size","embedding_model_name"],"description":"API-facing collection schema with embedding metadata.\n\nExtends CollectionRecord with vector_size and embedding_model_name, which\nare resolved by the CollectionService from the deployment metadata and the\ndense embedder registry.\n\nExcludes vector_db_deployment_metadata_id (internal FK).","title":"Collection"},"ValidationErrorDetail":{"type":"object","properties":{"loc":{"type":"array","items":{"type":"string"},"description":"Location of the error (e.g., ['body', 'url'])"},"msg":{"type":"string","description":"Human-readable error message"},"type":{"type":"string","description":"Error type identifier"}},"required":["loc","msg","type"],"description":"Details about a validation error for a specific field.","title":"ValidationErrorDetail"},"ValidationErrorResponse":{"type":"object","properties":{"detail":{"type":"array","items":{"$ref":"#/components/schemas/ValidationErrorDetail"},"description":"List of validation errors"}},"required":["detail"],"description":"Response returned when request validation fails (HTTP 422).\n\nThis occurs when the request body contains invalid data, such as\nmalformed URLs, invalid event types, or missing required fields.","title":"ValidationErrorResponse"},"RateLimitErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message explaining the rate limit"}},"required":["detail"],"description":"Response returned when rate limit is exceeded (HTTP 429).\n\nThe API enforces rate limits to ensure fair usage. When exceeded,\nwait for the duration specified in the Retry-After header before retrying.","title":"RateLimitErrorResponse"},"NotFoundErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message describing what was not found"}},"required":["detail"],"description":"Response returned when a resource is not found (HTTP 404).","title":"NotFoundErrorResponse"},"ValidationErrorLocItems":{"oneOf":[{"type":"string"},{"type":"integer"}],"title":"ValidationErrorLocItems"},"ValidationError":{"type":"object","properties":{"loc":{"type":"array","items":{"$ref":"#/components/schemas/ValidationErrorLocItems"}},"msg":{"type":"string"},"type":{"type":"string"}},"required":["loc","msg","type"],"title":"ValidationError"},"HTTPValidationError":{"type":"object","properties":{"detail":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}},"title":"HTTPValidationError"},"CollectionCreate":{"type":"object","properties":{"name":{"type":"string","minLength":4,"maxLength":64,"description":"Human-readable display name for the collection. This appears in the UI and should clearly describe the data contained within (e.g., 'Finance Data')."},"readable_id":{"type":["string","null"],"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"URL-safe unique identifier used in API endpoints. Must contain only lowercase letters, numbers, and hyphens. If not provided, it will be automatically generated from the collection name with a random suffix for uniqueness (e.g., 'finance-data-ab123')."},"sync_config":{"oneOf":[{"$ref":"#/components/schemas/SyncConfig"},{"type":"null"}],"description":"Default sync configuration for all syncs in this collection. This provides collection-level defaults that can be overridden at sync or job level."}},"required":["name"],"description":"Schema for creating a new collection.\n\nCollections serve as logical containers for organizing related data sources.\nOnce created, you can add source connections to populate the collection with data\nfrom various sources like databases, APIs, and file systems.\n\nYou can optionally set a default sync configuration that will apply to all syncs\nwithin this collection unless overridden at the sync or job level.","title":"CollectionCreate"},"CollectionUpdate":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":4,"maxLength":64,"description":"Updated display name for the collection. Must be between 4 and 64 characters."},"sync_config":{"oneOf":[{"$ref":"#/components/schemas/SyncConfig"},{"type":"null"}],"description":"Default sync configuration for all syncs in this collection. This provides collection-level defaults that can be overridden at sync or job level."}},"description":"Schema for updating an existing collection.\n\nAllows updating the collection's display name and default sync configuration.\nThe readable_id is immutable to maintain stable API endpoints and references.","title":"CollectionUpdate"},"airweave__domains__search__types__plan__RetrievalStrategy":{"type":"string","enum":["semantic","keyword","hybrid"],"description":"Supported retrieval strategies.","title":"airweave__domains__search__types__plan__RetrievalStrategy"},"FilterableField":{"type":"string","enum":["entity_id","name","created_at","updated_at","breadcrumbs.entity_id","breadcrumbs.name","breadcrumbs.entity_type","airweave_system_metadata.entity_type","airweave_system_metadata.source_name","airweave_system_metadata.original_entity_id","airweave_system_metadata.chunk_index","airweave_system_metadata.sync_id","airweave_system_metadata.sync_job_id"],"description":"Filterable fields in search.\n\nUses dot notation for nested fields (e.g., breadcrumbs.name,\nairweave_system_metadata.source_name).","title":"FilterableField"},"FilterOperator":{"type":"string","enum":["equals","not_equals","contains","greater_than","less_than","greater_than_or_equal","less_than_or_equal","in","not_in"],"description":"Supported filter operators.","title":"FilterOperator"},"FilterConditionValue":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"integer"}}],"description":"Value to compare against. Use a list for 'in' and 'not_in' operators.","title":"FilterConditionValue"},"FilterCondition":{"type":"object","properties":{"field":{"$ref":"#/components/schemas/FilterableField","description":"Field to filter on (use dot notation for nested fields)."},"operator":{"$ref":"#/components/schemas/FilterOperator","description":"The comparison operator to use."},"value":{"$ref":"#/components/schemas/FilterConditionValue","description":"Value to compare against. Use a list for 'in' and 'not_in' operators."}},"required":["field","operator","value"],"description":"A single filter condition.\n\nPydantic validates that:\n- ``field`` is a valid FilterableField enum value\n- ``operator`` is a valid FilterOperator enum value\n- ``value`` matches the expected types\n- The combination of field + operator + value is semantically valid\n\nInvalid filters raise ``pydantic.ValidationError`` automatically.\n\nExamples:\n    {\"field\": \"airweave_system_metadata.source_name\", \"operator\": \"equals\",\n     \"value\": \"notion\"}\n    {\"field\": \"created_at\", \"operator\": \"greater_than\",\n     \"value\": \"2024-01-01T00:00:00Z\"}\n    {\"field\": \"breadcrumbs.name\", \"operator\": \"contains\", \"value\": \"Engineering\"}","title":"FilterCondition"},"FilterGroup":{"type":"object","properties":{"conditions":{"type":"array","items":{"$ref":"#/components/schemas/FilterCondition"},"description":"Filter conditions within this group, combined with AND"}},"required":["conditions"],"description":"A group of filter conditions combined with AND.\n\nMultiple filter groups are combined with OR, allowing expressions like:\n(A AND B) OR (C AND D)\n\nExamples:\n    Single group (AND):\n        {\"conditions\": [\n            {\"field\": \"airweave_system_metadata.source_name\",\n             \"operator\": \"equals\", \"value\": \"slack\"},\n            {\"field\": \"airweave_system_metadata.entity_type\",\n             \"operator\": \"equals\", \"value\": \"SlackMessageEntity\"}\n        ]}\n\n    Multiple groups (OR between groups, AND within):\n        [\n            {\"conditions\": [{\"field\": \"name\", \"operator\": \"equals\",\n                             \"value\": \"doc1\"}]},\n            {\"conditions\": [{\"field\": \"name\", \"operator\": \"equals\",\n                             \"value\": \"doc2\"}]}\n        ]\n\n    Breadcrumb filtering:\n        {\"conditions\": [\n            {\"field\": \"breadcrumbs.name\", \"operator\": \"contains\",\n             \"value\": \"Engineering\"}\n        ]}","title":"FilterGroup"},"InstantSearchRequest":{"type":"object","properties":{"query":{"type":"string","description":"Search query text."},"retrieval_strategy":{"$ref":"#/components/schemas/airweave__domains__search__types__plan__RetrievalStrategy","description":"Which retrieval strategy to use."},"filter":{"type":["array","null"],"items":{"$ref":"#/components/schemas/FilterGroup"},"description":"Filter groups (combined with OR)."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100,"description":"Max results to return."},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of results to skip."}},"required":["query"],"description":"Instant search request — embed query, fire at Vespa, return results.","title":"InstantSearchRequest"},"SearchBreadcrumb":{"type":"object","properties":{"entity_id":{"type":"string","description":"ID of the entity in the source."},"name":{"type":"string","description":"Display name of the entity."},"entity_type":{"type":"string","description":"Entity class name (e.g., 'AsanaProjectEntity')."}},"required":["entity_id","name","entity_type"],"description":"Breadcrumb in search result.","title":"SearchBreadcrumb"},"SearchSystemMetadata":{"type":"object","properties":{"source_name":{"type":"string","description":"Name of the source this entity belongs to."},"entity_type":{"type":"string","description":"Type of the entity this entity represents in the source."},"sync_id":{"type":["string","null"],"description":"ID of the sync this entity belongs to (None for federated)."},"sync_job_id":{"type":["string","null"],"description":"ID of the sync job this entity belongs to (None for federated)."},"chunk_index":{"type":"integer","description":"Index of the chunk in the file."},"original_entity_id":{"type":"string","description":"Original entity ID"}},"required":["source_name","entity_type","chunk_index","original_entity_id"],"description":"System metadata in search result.","title":"SearchSystemMetadata"},"SearchAccessControl":{"type":"object","properties":{"viewers":{"type":["array","null"],"items":{"type":"string"},"description":"Principal IDs who can view this entity. None if unknown."},"is_public":{"type":["boolean","null"],"description":"Whether this entity is publicly accessible. None if unknown."}},"description":"Access control in search result.","title":"SearchAccessControl"},"SearchResult":{"type":"object","properties":{"entity_id":{"type":"string","description":"Original entity ID."},"name":{"type":"string","description":"Entity display name."},"relevance_score":{"type":"number","format":"double","description":"Relevance score from the search engine."},"breadcrumbs":{"type":"array","items":{"$ref":"#/components/schemas/SearchBreadcrumb"},"description":"Breadcrumbs showing entity hierarchy."},"created_at":{"type":["string","null"],"format":"date-time","description":"When the entity was created."},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the entity was last updated."},"textual_representation":{"type":"string","description":"Semantically searchable text content"},"airweave_system_metadata":{"$ref":"#/components/schemas/SearchSystemMetadata","description":"System metadata"},"access":{"$ref":"#/components/schemas/SearchAccessControl","description":"Access control"},"web_url":{"type":"string","description":"URL to view the entity in its source application (e.g., Notion, Asana)."},"url":{"type":["string","null"],"description":"Download URL for file entities. Only present for FileEntity types."},"raw_source_fields":{"type":"object","additionalProperties":{"description":"Any type"},"description":"All source-specific fields."}},"required":["entity_id","name","relevance_score","breadcrumbs","textual_representation","airweave_system_metadata","access","web_url","raw_source_fields"],"description":"Search result.","title":"SearchResult"},"SearchV2Response":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"},"description":"Search results ordered by relevance."}},"description":"Unified response for all search tiers.","title":"SearchV2Response"},"ClassicSearchRequest":{"type":"object","properties":{"query":{"type":"string","description":"Search query text."},"filter":{"type":["array","null"],"items":{"$ref":"#/components/schemas/FilterGroup"},"description":"Filter groups (combined with OR)."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100,"description":"Max results to return."},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of results to skip."}},"required":["query"],"description":"Classic search request — LLM generates a search plan, execute against Vespa.","title":"ClassicSearchRequest"},"AgenticSearchRequest":{"type":"object","properties":{"query":{"type":"string","description":"Search query text."},"thinking":{"type":"boolean","default":false,"description":"Enable extended thinking / chain-of-thought."},"filter":{"type":["array","null"],"items":{"$ref":"#/components/schemas/FilterGroup"},"description":"Filter groups (combined with OR)."},"limit":{"type":["integer","null"],"minimum":1,"description":"Max results. None means agent decides."}},"required":["query"],"description":"Agentic search request — full agent loop with tool calling.","title":"AgenticSearchRequest"},"AgenticSearchStartedEventType":{"type":"string","enum":["started"],"title":"AgenticSearchStartedEventType"},"AgenticSearchStartedEventFilterItems":{"type":"object","properties":{},"title":"AgenticSearchStartedEventFilterItems"},"AgenticSearchStartedEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AgenticSearchStartedEventType"},"request_id":{"type":"string"},"tier":{"type":"string"},"collection_readable_id":{"type":"string"},"query":{"type":"string"},"thinking":{"type":["boolean","null"]},"filter":{"type":["array","null"],"items":{"$ref":"#/components/schemas/AgenticSearchStartedEventFilterItems"}},"limit":{"type":["integer","null"]}},"required":["type","request_id","tier","collection_readable_id","query"],"title":"AgenticSearchStartedEvent"},"AgenticSearchThinkingEventType":{"type":"string","enum":["thinking"],"title":"AgenticSearchThinkingEventType"},"AgenticSearchThinkingEventDiagnostics":{"type":"object","properties":{"iteration":{"type":"integer"},"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"}},"title":"AgenticSearchThinkingEventDiagnostics"},"AgenticSearchThinkingEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AgenticSearchThinkingEventType"},"thinking":{"type":["string","null"],"description":"Extended reasoning text from the LLM."},"text":{"type":["string","null"],"description":"Conversational text output before tool calls."},"duration_ms":{"type":"integer"},"diagnostics":{"$ref":"#/components/schemas/AgenticSearchThinkingEventDiagnostics"}},"required":["type","duration_ms","diagnostics"],"title":"AgenticSearchThinkingEvent"},"AgenticSearchToolCallEventType":{"type":"string","enum":["tool_call"],"title":"AgenticSearchToolCallEventType"},"AgenticSearchToolCallEventToolName":{"type":"string","enum":["search","read","add_to_results","remove_from_results","count","get_children","get_siblings","get_parent","review_results","return_results_to_user"],"title":"AgenticSearchToolCallEventToolName"},"AgenticSearchToolCallEventDiagnosticsArguments":{"type":"object","properties":{},"description":"Full LLM-generated tool input.","title":"AgenticSearchToolCallEventDiagnosticsArguments"},"EntityTypeStats":{"type":"object","properties":{"count":{"type":"integer"},"last_updated":{"type":["string","null"],"format":"date-time"}},"required":["count"],"description":"Statistics for a specific entity type.","title":"EntityTypeStats"},"EntitySummary":{"type":"object","properties":{"total_entities":{"type":"integer","default":0},"by_type":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/EntityTypeStats"}},"entity_id":{"type":"string"},"name":{"type":"string"},"entity_type":{"type":"string"},"source_name":{"type":"string"},"relevance_score":{"type":["number","null"],"format":"double"}},"description":"Entity state summary.","title":"EntitySummary"},"SearchToolStats":{"type":"object","properties":{"result_count":{"type":"integer","description":"Total results returned."},"new_results":{"type":"integer","description":"Results not seen in previous searches."},"first_results":{"type":"array","items":{"$ref":"#/components/schemas/EntitySummary"}}},"description":"Stats from a search tool call.","title":"SearchToolStats"},"ReadToolStats":{"type":"object","properties":{"found":{"type":"integer","description":"Entities successfully read."},"not_found":{"type":"integer","description":"Entity IDs that weren't found."},"entities":{"type":"array","items":{"$ref":"#/components/schemas/EntitySummary"}},"context_label":{"type":["string","null"]}},"description":"Stats from a read tool call.","title":"ReadToolStats"},"CollectToolStats":{"type":"object","properties":{"added":{"type":"integer"},"already_collected":{"type":"integer"},"not_found":{"type":"integer"},"total_collected":{"type":"integer","description":"Total results collected after this operation."},"entities":{"type":"array","items":{"$ref":"#/components/schemas/EntitySummary"}}},"description":"Stats from add_to_results or remove_from_results.","title":"CollectToolStats"},"CountToolStats":{"type":"object","properties":{"count":{"type":"integer","description":"Number of entities matching the filter."}},"description":"Stats from a count tool call.","title":"CountToolStats"},"NavigateToolStats":{"type":"object","properties":{"result_count":{"type":"integer"},"context_label":{"type":"string","description":"Human-readable label, e.g. 'children of chan-engineering'."},"first_results":{"type":"array","items":{"$ref":"#/components/schemas/EntitySummary"}}},"description":"Stats from get_children, get_siblings, or get_parent.","title":"NavigateToolStats"},"ReviewToolStats":{"type":"object","properties":{"total_collected":{"type":"integer"},"entity_count":{"type":"integer"},"first_results":{"type":"array","items":{"$ref":"#/components/schemas/EntitySummary"}}},"description":"Stats from review_results.","title":"ReviewToolStats"},"FinishToolStats":{"type":"object","properties":{"accepted":{"type":"boolean","description":"Whether the agent accepted the result set."},"total_collected":{"type":"integer"},"warning":{"type":["string","null"],"description":"Warning if very few results collected relative to seen."}},"description":"Stats from return_results_to_user.","title":"FinishToolStats"},"ErrorToolStats":{"type":"object","properties":{"error":{"type":"string"}},"description":"Stats when a tool call errors.","title":"ErrorToolStats"},"AgenticSearchToolCallEventDiagnosticsStats":{"oneOf":[{"$ref":"#/components/schemas/SearchToolStats"},{"$ref":"#/components/schemas/ReadToolStats"},{"$ref":"#/components/schemas/CollectToolStats"},{"$ref":"#/components/schemas/CountToolStats"},{"$ref":"#/components/schemas/NavigateToolStats"},{"$ref":"#/components/schemas/ReviewToolStats"},{"$ref":"#/components/schemas/FinishToolStats"},{"$ref":"#/components/schemas/ErrorToolStats"}],"description":"Output stats. Shape depends on tool_name.","title":"AgenticSearchToolCallEventDiagnosticsStats"},"AgenticSearchToolCallEventDiagnostics":{"type":"object","properties":{"iteration":{"type":"integer"},"tool_call_id":{"type":"string"},"arguments":{"$ref":"#/components/schemas/AgenticSearchToolCallEventDiagnosticsArguments","description":"Full LLM-generated tool input."},"stats":{"$ref":"#/components/schemas/AgenticSearchToolCallEventDiagnosticsStats","description":"Output stats. Shape depends on tool_name."}},"title":"AgenticSearchToolCallEventDiagnostics"},"AgenticSearchToolCallEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AgenticSearchToolCallEventType"},"tool_name":{"$ref":"#/components/schemas/AgenticSearchToolCallEventToolName"},"duration_ms":{"type":"integer"},"diagnostics":{"$ref":"#/components/schemas/AgenticSearchToolCallEventDiagnostics"}},"required":["type","tool_name","duration_ms","diagnostics"],"title":"AgenticSearchToolCallEvent"},"AgenticSearchRerankingEventType":{"type":"string","enum":["reranking"],"title":"AgenticSearchRerankingEventType"},"AgenticSearchRerankingEventDiagnostics":{"type":"object","properties":{"input_count":{"type":"integer"},"output_count":{"type":"integer"},"model":{"type":"string"},"top_relevance_score":{"type":"number","format":"double"},"bottom_relevance_score":{"type":"number","format":"double"}},"title":"AgenticSearchRerankingEventDiagnostics"},"AgenticSearchRerankingEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AgenticSearchRerankingEventType"},"duration_ms":{"type":"integer"},"diagnostics":{"$ref":"#/components/schemas/AgenticSearchRerankingEventDiagnostics"}},"required":["type","duration_ms","diagnostics"],"title":"AgenticSearchRerankingEvent"},"AgenticSearchDoneEventType":{"type":"string","enum":["done"],"title":"AgenticSearchDoneEventType"},"AgenticSearchDoneEventDiagnostics":{"type":"object","properties":{"total_iterations":{"type":"integer"},"all_seen_entity_ids":{"type":"array","items":{"type":"string"}},"all_read_entity_ids":{"type":"array","items":{"type":"string"}},"all_collected_entity_ids":{"type":"array","items":{"type":"string"}},"max_iterations_hit":{"type":"boolean"},"total_llm_retries":{"type":"integer"},"stagnation_nudges_sent":{"type":"integer"},"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"cache_creation_input_tokens":{"type":"integer"},"cache_read_input_tokens":{"type":"integer"}},"title":"AgenticSearchDoneEventDiagnostics"},"AgenticSearchDoneEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AgenticSearchDoneEventType"},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"},"description":"Full result set."},"duration_ms":{"type":"integer"},"diagnostics":{"oneOf":[{"$ref":"#/components/schemas/AgenticSearchDoneEventDiagnostics"},{"type":"null"}]}},"required":["type","results","duration_ms"],"title":"AgenticSearchDoneEvent"},"AgenticSearchErrorEventType":{"type":"string","enum":["error"],"title":"AgenticSearchErrorEventType"},"AgenticSearchErrorEvent":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/AgenticSearchErrorEventType"},"message":{"type":"string","description":"Error message."},"duration_ms":{"type":"integer"}},"required":["type","message"],"title":"AgenticSearchErrorEvent"},"AgenticSearchEvent":{"oneOf":[{"$ref":"#/components/schemas/AgenticSearchStartedEvent"},{"$ref":"#/components/schemas/AgenticSearchThinkingEvent"},{"$ref":"#/components/schemas/AgenticSearchToolCallEvent"},{"$ref":"#/components/schemas/AgenticSearchRerankingEvent"},{"$ref":"#/components/schemas/AgenticSearchDoneEvent"},{"$ref":"#/components/schemas/AgenticSearchErrorEvent"}],"title":"AgenticSearchEvent"},"AuthenticationMethod":{"type":"string","enum":["direct","oauth_browser","oauth_token","oauth_byoc","auth_provider"],"description":"Authentication methods for source connections.","title":"AuthenticationMethod"},"SourceConnectionStatus":{"type":"string","enum":["active","pending_auth","syncing","error","needs_reauth","inactive","pending_sync"],"description":"Source connection status enum - represents overall connection state.","title":"SourceConnectionStatus"},"SourceConnectionListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the source connection"},"name":{"type":"string","description":"Display name of the connection"},"short_name":{"type":"string","description":"Source type identifier"},"readable_collection_id":{"type":"string","description":"Collection this connection belongs to"},"created_at":{"type":"string","format":"date-time","description":"When the connection was created (ISO 8601)"},"modified_at":{"type":"string","format":"date-time","description":"When the connection was last modified (ISO 8601)"},"is_authenticated":{"type":"boolean","description":"Whether the connection has valid credentials"},"entity_count":{"type":"integer","default":0,"description":"Total number of entities synced from this connection"},"federated_search":{"type":"boolean","default":false,"description":"Whether this source uses federated (real-time) search instead of syncing"},"auth_method":{"$ref":"#/components/schemas/AuthenticationMethod","description":"Get authentication method from database value."},"status":{"$ref":"#/components/schemas/SourceConnectionStatus","description":"Compute connection status from current state."}},"required":["id","name","short_name","readable_collection_id","created_at","modified_at","is_authenticated","auth_method","status"],"description":"Lightweight source connection representation for list views.\n\nContains essential fields for display and navigation. For full details\nincluding sync history and configuration, use the GET /{id} endpoint.","title":"SourceConnectionListItem"},"AuthenticationDetails":{"type":"object","properties":{"method":{"$ref":"#/components/schemas/AuthenticationMethod"},"authenticated":{"type":"boolean"},"authenticated_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"auth_url":{"type":["string","null"],"description":"For pending OAuth flows"},"auth_url_expires":{"type":["string","null"],"format":"date-time"},"redirect_url":{"type":["string","null"]},"claim_token":{"type":["string","null"],"description":"One-time token to verify OAuth flow ownership. Only returned when creating an OAuth browser connection."},"provider_readable_id":{"type":["string","null"]},"provider_id":{"type":["string","null"]}},"required":["method","authenticated"],"description":"Authentication information.","title":"AuthenticationDetails"},"ScheduleDetails":{"type":"object","properties":{"cron":{"type":["string","null"]},"next_run":{"type":["string","null"],"format":"date-time"},"continuous":{"type":"boolean","default":false},"cursor_field":{"type":["string","null"]}},"description":"Schedule information.","title":"ScheduleDetails"},"SyncJobStatus":{"type":"string","enum":["created","pending","running","completed","failed","cancelling","cancelled"],"description":"Sync job status enum.","title":"SyncJobStatus"},"SourceConnectionErrorCategory":{"type":"string","enum":["oauth_credentials_expired","api_key_invalid","auth_provider_account_gone","auth_provider_credentials_invalid","usage_limit_exceeded","rate_limited"],"description":"Error categories for credential/auth failures on source connections.","title":"SourceConnectionErrorCategory"},"SyncJobDetails":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/SyncJobStatus"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"duration_seconds":{"type":["number","null"],"format":"double"},"entities_inserted":{"type":"integer","default":0},"entities_updated":{"type":"integer","default":0},"entities_deleted":{"type":"integer","default":0},"entities_failed":{"type":"integer","default":0},"error":{"type":["string","null"]},"error_category":{"oneOf":[{"$ref":"#/components/schemas/SourceConnectionErrorCategory"},{"type":"null"}]}},"required":["id","status"],"description":"Sync job details.","title":"SyncJobDetails"},"SyncDetails":{"type":"object","properties":{"total_runs":{"type":"integer","default":0},"successful_runs":{"type":"integer","default":0},"failed_runs":{"type":"integer","default":0},"last_job":{"oneOf":[{"$ref":"#/components/schemas/SyncJobDetails"},{"type":"null"}]}},"description":"Sync execution details.","title":"SyncDetails"},"SourceConnection":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the source connection"},"organization_id":{"type":"string","format":"uuid","description":"Organization this connection belongs to"},"name":{"type":"string","description":"Display name of the connection"},"description":{"type":["string","null"],"description":"Optional description of the connection's purpose"},"short_name":{"type":"string","description":"Source type identifier"},"readable_collection_id":{"type":"string","description":"Collection this connection belongs to"},"status":{"$ref":"#/components/schemas/SourceConnectionStatus","description":"Current operational status of the connection"},"created_at":{"type":"string","format":"date-time","description":"When the connection was created (ISO 8601)"},"modified_at":{"type":"string","format":"date-time","description":"When the connection was last modified (ISO 8601)"},"auth":{"$ref":"#/components/schemas/AuthenticationDetails","description":"Authentication status and details"},"config":{"type":["object","null"],"additionalProperties":{"description":"Any type"},"description":"Source-specific configuration values"},"schedule":{"oneOf":[{"$ref":"#/components/schemas/ScheduleDetails"},{"type":"null"}],"description":"Sync schedule configuration"},"sync":{"oneOf":[{"$ref":"#/components/schemas/SyncDetails"},{"type":"null"}],"description":"Sync execution history and statistics"},"sync_id":{"type":["string","null"],"format":"uuid","description":"ID of the associated sync (internal use)"},"entities":{"oneOf":[{"$ref":"#/components/schemas/EntitySummary"},{"type":"null"}],"description":"Summary of synced entities by type"},"error_category":{"oneOf":[{"$ref":"#/components/schemas/SourceConnectionErrorCategory"},{"type":"null"}],"description":"Error category when status is needs_reauth (e.g. oauth_credentials_expired)"},"error_message":{"type":["string","null"],"description":"Human-readable error message when status is needs_reauth"},"provider_settings_url":{"type":["string","null"],"description":"URL to the auth provider's settings dashboard (for auth_provider errors)"},"provider_short_name":{"type":["string","null"],"description":"Auth provider short_name (e.g. 'composio', 'pipedream') for display"},"federated_search":{"type":"boolean","default":false,"description":"Whether this source uses federated (real-time) search instead of syncing"}},"required":["id","organization_id","name","short_name","readable_collection_id","status","created_at","modified_at","auth"],"description":"Complete source connection details including auth, config, sync status, and entities.\n\nThis schema provides full information about a source connection, suitable for\ndetail views and monitoring sync progress.","title":"SourceConnection"},"SourceConnectionJob":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the sync job"},"source_connection_id":{"type":"string","format":"uuid","description":"ID of the source connection this job belongs to"},"status":{"$ref":"#/components/schemas/SyncJobStatus","description":"Current status: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED, or CANCELLING"},"started_at":{"type":["string","null"],"format":"date-time","description":"When the job started execution (ISO 8601)"},"completed_at":{"type":["string","null"],"format":"date-time","description":"When the job finished (ISO 8601). Null if still running."},"duration_seconds":{"type":["number","null"],"format":"double","description":"Total execution time in seconds. Null if still running."},"entities_inserted":{"type":"integer","default":0,"description":"Number of new entities created during this sync"},"entities_updated":{"type":"integer","default":0,"description":"Number of existing entities updated during this sync"},"entities_deleted":{"type":"integer","default":0,"description":"Number of entities removed during this sync"},"entities_failed":{"type":"integer","default":0,"description":"Number of entities that failed to process"},"error":{"type":["string","null"],"description":"Error message if the job failed"},"error_category":{"oneOf":[{"$ref":"#/components/schemas/SourceConnectionErrorCategory"},{"type":"null"}],"description":"Error category for credential errors (e.g. oauth_credentials_expired)"},"error_details":{"type":["object","null"],"additionalProperties":{"description":"Any type"},"description":"Additional error context for debugging"}},"required":["id","source_connection_id","status"],"description":"A sync job representing a single synchronization run.\n\nSync jobs track the execution of data synchronization from a source connection.\nEach job includes timing information, entity counts, and error details if applicable.","title":"SourceConnectionJob"},"ScheduleConfig":{"type":"object","properties":{"cron":{"type":["string","null"],"description":"Cron expression for scheduled syncs"},"continuous":{"type":"boolean","default":false,"description":"Enable continuous sync mode"},"cursor_field":{"type":["string","null"],"description":"Field for incremental sync"}},"description":"Schedule configuration for syncs.","title":"ScheduleConfig"},"DirectAuthentication":{"type":"object","properties":{"credentials":{"type":"object","additionalProperties":{"description":"Any type"},"description":"Authentication credentials"}},"required":["credentials"],"description":"Direct authentication with API keys or passwords.","title":"DirectAuthentication"},"OAuthTokenAuthentication":{"type":"object","properties":{"access_token":{"type":"string","description":"OAuth access token"},"refresh_token":{"type":["string","null"],"description":"OAuth refresh token"},"expires_at":{"type":["string","null"],"format":"date-time","description":"Token expiry time"}},"required":["access_token"],"description":"OAuth authentication with pre-obtained token.","title":"OAuthTokenAuthentication"},"OAuthBrowserAuthentication":{"type":"object","properties":{"redirect_uri":{"type":["string","null"],"description":"OAuth redirect URI"},"client_id":{"type":["string","null"],"description":"OAuth2 client ID (for custom apps)"},"client_secret":{"type":["string","null"],"description":"OAuth2 client secret (for custom apps)"},"consumer_key":{"type":["string","null"],"description":"OAuth1 consumer key (for custom apps)"},"consumer_secret":{"type":["string","null"],"description":"OAuth1 consumer secret (for custom apps)"}},"description":"OAuth authentication via browser flow.\n\nSupports both OAuth2 and OAuth1 BYOC (Bring Your Own Client):\n- OAuth2 BYOC: Provide client_id + client_secret\n- OAuth1 BYOC: Provide consumer_key + consumer_secret","title":"OAuthBrowserAuthentication"},"AuthProviderAuthentication":{"type":"object","properties":{"provider_readable_id":{"type":"string","description":"Auth provider readable ID"},"provider_config":{"type":["object","null"],"additionalProperties":{"description":"Any type"},"description":"Provider-specific configuration"}},"required":["provider_readable_id"],"description":"Authentication via external provider.","title":"AuthProviderAuthentication"},"SourceConnectionCreateAuthentication":{"oneOf":[{"$ref":"#/components/schemas/DirectAuthentication"},{"$ref":"#/components/schemas/OAuthTokenAuthentication"},{"$ref":"#/components/schemas/OAuthBrowserAuthentication"},{"$ref":"#/components/schemas/AuthProviderAuthentication"}],"description":"Authentication configuration. Type is auto-detected from provided fields.","title":"SourceConnectionCreateAuthentication"},"SourceConnectionCreate":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":4,"maxLength":42,"description":"Display name for the connection. If not provided, defaults to '{Source Name} Connection'."},"short_name":{"type":"string","description":"Source type identifier (e.g., 'slack', 'github', 'notion')"},"readable_collection_id":{"type":"string","description":"The readable ID of the collection to add this connection to"},"description":{"type":["string","null"],"maxLength":255,"description":"Optional description of what this connection is used for"},"config":{"type":["object","null"],"additionalProperties":{"description":"Any type"},"description":"Source-specific configuration (e.g., repository name, filters)"},"schedule":{"oneOf":[{"$ref":"#/components/schemas/ScheduleConfig"},{"type":"null"}],"description":"Optional sync schedule configuration"},"sync_immediately":{"type":["boolean","null"],"description":"Run initial sync after creation. Defaults to True for direct/token/auth_provider, False for OAuth browser/BYOC flows (which sync after authentication)"},"authentication":{"oneOf":[{"$ref":"#/components/schemas/SourceConnectionCreateAuthentication"},{"type":"null"}],"description":"Authentication configuration. Type is auto-detected from provided fields."},"redirect_url":{"type":["string","null"],"description":"URL to redirect to after OAuth flow completes (only used for OAuth flows)"}},"required":["short_name","readable_collection_id"],"description":"Create a source connection with authentication configuration.\n\nSource connections link a data source (e.g., GitHub, Slack) to a collection.\nThe authentication method determines how credentials are provided and whether\nthe connection is created immediately or requires an OAuth flow.","title":"SourceConnectionCreate"},"SourceConnectionUpdateAuthentication":{"oneOf":[{"$ref":"#/components/schemas/DirectAuthentication"},{"$ref":"#/components/schemas/OAuthTokenAuthentication"},{"$ref":"#/components/schemas/OAuthBrowserAuthentication"},{"$ref":"#/components/schemas/AuthProviderAuthentication"}],"description":"Updated authentication credentials (direct auth only)","title":"SourceConnectionUpdateAuthentication"},"SourceConnectionUpdate":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":4,"maxLength":42,"description":"Updated display name for the connection"},"description":{"type":["string","null"],"maxLength":255,"description":"Updated description"},"config":{"type":["object","null"],"additionalProperties":{"description":"Any type"},"description":"Updated source-specific configuration"},"schedule":{"oneOf":[{"$ref":"#/components/schemas/ScheduleConfig"},{"type":"null"}],"description":"Updated sync schedule configuration"},"authentication":{"oneOf":[{"$ref":"#/components/schemas/SourceConnectionUpdateAuthentication"},{"type":"null"}],"description":"Updated authentication credentials (direct auth only)"}},"description":"Update an existing source connection's configuration.\n\nAll fields are optional. Only include fields you want to change;\nomitted fields retain their current values.","title":"SourceConnectionUpdate"},"ConflictErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message describing the conflict"}},"required":["detail"],"description":"Response returned when a resource conflict occurs (HTTP 409).\n\nThis typically occurs when attempting to create a resource that already exists,\nor when an operation cannot be completed due to the current state of a resource.","title":"ConflictErrorResponse"},"ConfigField":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"type":{"type":"string"},"required":{"type":"boolean","default":true},"items_type":{"type":["string","null"]},"feature_flag":{"type":["string","null"]},"is_secret":{"type":"boolean","default":false},"enum_values":{"type":["array","null"],"items":{"type":"string"}}},"required":["name","title","type"],"description":"Config field model.","title":"ConfigField"},"Fields":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/ConfigField"}}},"required":["fields"],"description":"Fields model.","title":"Fields"},"Source":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name of the data source connector (e.g., 'GitHub', 'Stripe', 'PostgreSQL')."},"description":{"type":["string","null"],"description":"Detailed description explaining what data this source can extract and its typical use cases."},"auth_methods":{"type":["array","null"],"items":{"type":"string"},"description":"List of supported authentication methods (e.g., 'direct', 'oauth_browser')."},"oauth_type":{"type":["string","null"],"description":"OAuth token type for OAuth sources (e.g., 'access_only', 'with_refresh')."},"requires_byoc":{"type":"boolean","default":false,"description":"Whether this OAuth source requires users to bring their own client."},"auth_config_class":{"type":["string","null"],"description":"Python class name that defines the authentication configuration fields required for this source (only for DIRECT auth)."},"config_class":{"type":["string","null"],"description":"Python class name that defines the source-specific configuration options and parameters."},"short_name":{"type":"string","description":"Technical identifier used internally to reference this source type. Must be unique across all sources."},"class_name":{"type":"string","description":"Python class name of the source implementation that handles data extraction logic."},"output_entity_definitions":{"type":"array","items":{"type":"string"},"description":"List of entity definition short names that this source can produce (e.g., ['asana_task_entity', 'asana_project_entity'])."},"labels":{"type":["array","null"],"items":{"type":"string"},"description":"Categorization tags to help users discover and filter sources by domain or use case."},"supports_continuous":{"type":"boolean","default":false,"description":"Whether this source supports cursor-based continuous syncing for incremental data extraction."},"federated_search":{"type":"boolean","default":false,"description":"Whether this source uses federated search instead of traditional syncing."},"supports_temporal_relevance":{"type":"boolean","default":true,"description":"Whether this source's entities have timestamps that enable recency-based ranking."},"supports_access_control":{"type":"boolean","default":false,"description":"Whether this source supports document-level access control."},"rate_limit_level":{"type":["string","null"],"description":"Rate limiting level for this source: 'org' (organization-wide), 'connection' (per-connection/per-user), or None (no rate limiting)."},"feature_flag":{"type":["string","null"],"description":"Feature flag required to access this source. If set, only organizations with this feature enabled can see/use this source."},"supports_browse_tree":{"type":"boolean","default":false,"description":"Whether this source supports lazy-loaded browse tree for selective node syncing."},"auth_fields":{"oneOf":[{"$ref":"#/components/schemas/Fields"},{"type":"null"}],"description":"Schema definition for authentication fields required to connect to this source."},"config_fields":{"$ref":"#/components/schemas/Fields","description":"Schema definition for configuration fields required to customize this source."},"supported_auth_providers":{"type":["array","null"],"items":{"type":"string"},"description":"List of auth provider short names that support this source."}},"required":["name","short_name","class_name","config_fields"],"description":"Complete source representation with authentication and configuration schemas.\n\nServed from the in-memory SourceRegistry — no database row needed.","title":"Source"},"WebhookMessage":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this message (UUID format)"},"event_type":{"type":"string","description":"The type of event (e.g., 'sync.completed', 'sync.failed')"},"payload":{"type":"object","additionalProperties":{"description":"Any type"},"description":"The event payload data, matching what is delivered to webhooks. Structure varies by event_type."},"timestamp":{"type":"string","format":"date-time","description":"When this message was created (ISO 8601 format, UTC)"},"channels":{"type":["array","null"],"items":{"type":"string"},"description":"Channels this message was sent to (typically matches the event type)"},"tags":{"type":["array","null"],"items":{"type":"string"},"description":"Tags associated with this message for filtering"}},"required":["id","event_type","payload","timestamp"],"description":"A webhook message that was sent (or attempted) to webhook subscribers.\n\nThe payload contains the actual event data matching the webhook delivery format.","title":"WebhookMessage"},"DeliveryAttempt":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this delivery attempt"},"message_id":{"type":"string","description":"The event message that was being delivered"},"endpoint_id":{"type":"string","description":"The subscription endpoint this was delivered to"},"response":{"type":["string","null"],"description":"The response body returned by your webhook endpoint (truncated to 1KB)"},"response_status_code":{"type":"integer","description":"HTTP status code returned by your webhook endpoint. 2xx codes indicate success; other codes trigger retries."},"status":{"type":"string","description":"Delivery status: `success` (2xx response), `pending` (awaiting delivery), or `failed` (non-2xx response or timeout)"},"timestamp":{"type":"string","format":"date-time","description":"When this delivery attempt occurred (ISO 8601 format, UTC)"},"url":{"type":["string","null"],"description":"The URL that was called"}},"required":["id","message_id","endpoint_id","response_status_code","status","timestamp"],"description":"A delivery attempt for a webhook message.\n\nEach time Airweave attempts to deliver a message to your webhook endpoint,\na delivery attempt is recorded. Failed attempts are automatically retried\nwith exponential backoff.","title":"DeliveryAttempt"},"WebhookMessageWithAttempts":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this message (UUID format)"},"event_type":{"type":"string","description":"The type of event (e.g., 'sync.completed', 'sync.failed')"},"payload":{"type":"object","additionalProperties":{"description":"Any type"},"description":"The event payload data, matching what is delivered to webhooks. Structure varies by event_type."},"timestamp":{"type":"string","format":"date-time","description":"When this message was created (ISO 8601 format, UTC)"},"channels":{"type":["array","null"],"items":{"type":"string"},"description":"Channels this message was sent to (typically matches the event type)"},"tags":{"type":["array","null"],"items":{"type":"string"},"description":"Tags associated with this message for filtering"},"delivery_attempts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/DeliveryAttempt"},"description":"Delivery attempts for this message."}},"required":["id","event_type","payload","timestamp"],"description":"A webhook message with delivery attempts.","title":"WebhookMessageWithAttempts"},"HealthStatus":{"type":"string","enum":["healthy","degraded","failing","unknown"],"description":"Health status of a webhook subscription based on recent delivery attempts.","title":"HealthStatus"},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this subscription (UUID format)"},"url":{"type":"string","description":"The URL where webhook events are delivered"},"filter_types":{"type":["array","null"],"items":{"type":"string"},"description":"Event types this subscription is filtered to receive. See EventType enum for all available types."},"disabled":{"type":"boolean","default":false,"description":"Whether this subscription is currently disabled. Disabled subscriptions do not receive event deliveries."},"description":{"type":["string","null"],"description":"Optional human-readable description of this subscription"},"created_at":{"type":"string","format":"date-time","description":"When this subscription was created (ISO 8601 format, UTC)"},"updated_at":{"type":"string","format":"date-time","description":"When this subscription was last updated (ISO 8601 format, UTC)"},"health_status":{"$ref":"#/components/schemas/HealthStatus","description":"Health status of this subscription based on recent delivery attempts. Values: 'healthy' (all recent deliveries succeeded), 'degraded' (mix of successes and failures), 'failing' (consecutive failures beyond threshold), 'unknown' (no delivery data yet)."}},"required":["id","url","created_at","updated_at"],"description":"A webhook subscription (endpoint) configuration.\n\nThis is the lightweight representation returned by list, create, update,\nand delete endpoints.  For the full detail view (delivery attempts,\nsigning secret) see ``WebhookSubscriptionDetail``.","title":"WebhookSubscription"},"WebhookSubscriptionDetail":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this subscription (UUID format)"},"url":{"type":"string","description":"The URL where webhook events are delivered"},"filter_types":{"type":["array","null"],"items":{"type":"string"},"description":"Event types this subscription is filtered to receive. See EventType enum for all available types."},"disabled":{"type":"boolean","default":false,"description":"Whether this subscription is currently disabled. Disabled subscriptions do not receive event deliveries."},"description":{"type":["string","null"],"description":"Optional human-readable description of this subscription"},"created_at":{"type":"string","format":"date-time","description":"When this subscription was created (ISO 8601 format, UTC)"},"updated_at":{"type":"string","format":"date-time","description":"When this subscription was last updated (ISO 8601 format, UTC)"},"health_status":{"$ref":"#/components/schemas/HealthStatus","description":"Health status of this subscription based on recent delivery attempts. Values: 'healthy' (all recent deliveries succeeded), 'degraded' (mix of successes and failures), 'failing' (consecutive failures beyond threshold), 'unknown' (no delivery data yet)."},"delivery_attempts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/DeliveryAttempt"},"description":"Recent delivery attempts for this subscription."},"secret":{"type":["string","null"],"description":"The signing secret for webhook signature verification. Only included when include_secret=true is passed to the API. Keep this secret secure."}},"required":["id","url","created_at","updated_at"],"description":"Full subscription detail, including delivery attempts and signing secret.\n\nReturned by ``GET /subscriptions/{id}`` only.","title":"WebhookSubscriptionDetail"},"EventType":{"type":"string","enum":["sync.pending","sync.running","sync.cancelling","sync.completed","sync.failed","sync.cancelled","entity.batch_processed","query.processed","access_control.batch_processed","collection.created","collection.updated","collection.deleted","source_connection.created","source_connection.auth_completed","source_connection.deleted","organization.created","organization.deleted","organization.member_added","organization.member_removed","search.started","search.completed","search.failed","search.reranking","search.thinking","search.tool_called"],"title":"EventType"},"CreateSubscriptionRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri","minLength":1,"maxLength":2083,"description":"The HTTPS URL where webhook events will be delivered. Must be a publicly accessible endpoint that returns a 2xx status code."},"event_types":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"description":"List of event types to subscribe to. Events not in this list will not be delivered to this subscription. Available types: `sync.pending`, `sync.running`, `sync.completed`, `sync.failed`, `sync.cancelled`, `source_connection.created`, `source_connection.auth_completed`, `source_connection.deleted`, `collection.created`, `collection.updated`, `collection.deleted`."},"secret":{"type":["string","null"],"minLength":24,"description":"Optional custom signing secret for webhook signature verification. If not provided, a secure secret will be auto-generated. Must be at least 24 characters if specified."}},"required":["url","event_types"],"description":"Create a new webhook subscription.\n\nWebhook subscriptions define where Airweave should send event notifications.\nYou can subscribe to specific event types to receive only the events you care about.","title":"CreateSubscriptionRequest"},"PatchSubscriptionRequest":{"type":"object","properties":{"url":{"type":["string","null"],"format":"uri","minLength":1,"maxLength":2083,"description":"New URL for webhook delivery. Must be a publicly accessible HTTPS endpoint."},"event_types":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EventType"},"description":"New list of event types to subscribe to. This replaces the existing list entirely."},"disabled":{"type":["boolean","null"],"description":"Set to `true` to pause delivery to this subscription, or `false` to resume. Disabled subscriptions will not receive events."},"recover_since":{"type":["string","null"],"format":"date-time","description":"When re-enabling a subscription (`disabled: false`), optionally recover failed messages from this timestamp. Only applies when enabling."}},"description":"Update an existing webhook subscription.\n\nAll fields are optional. Only provided fields will be updated;\nomitted fields retain their current values.\n\nWhen re-enabling a subscription (setting `disabled: false`), you can optionally\nprovide `recover_since` to replay messages that were missed while disabled.","title":"PatchSubscriptionRequest"},"RecoverMessagesRequest":{"type":"object","properties":{"since":{"type":"string","format":"date-time","description":"Start of the recovery time window (inclusive). All failed messages from this time onward will be retried."},"until":{"type":["string","null"],"format":"date-time","description":"End of the recovery time window (exclusive). If not specified, recovers all failed messages up to now."}},"required":["since"],"description":"Request to retry failed message deliveries.\n\nUse this to replay events that failed to deliver during a specific time window,\nfor example after fixing an issue with your webhook endpoint.","title":"RecoverMessagesRequest"},"RecoveryTask":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this recovery task (Svix internal ID)"},"status":{"type":"string","description":"Recovery task status: 'running' or 'completed'"}},"required":["id","status"],"description":"Information about a message recovery task.\n\nWhen you trigger a recovery of failed messages, this object is returned\nto track the recovery progress. The status indicates whether the recovery\nis still in progress or has completed.","title":"RecoveryTask"}},"securitySchemes":{"default":{"type":"apiKey","in":"header","name":"x-api-key"}}}}