openapi: 3.1.0 info: title: LightOn API version: 3.15.0 (v3) description: LightOn gives you an API to search, parse, and ingest documents at scale. Build knowledge-retrieval pipelines without managing vector databases or OCR models. paths: /api/v3/billing/budget: get: operationId: api_v3_billing_budget_retrieve description: Return the company's monthly budget configuration, current spend, and alert thresholds. summary: Get company budget tags: - Budget security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/BudgetResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' put: operationId: api_v3_billing_budget_update description: Set or update the company's monthly spend budget. Requires CompanyAdmin role. Creates the budget on first call; updates it on subsequent calls. summary: Create or update company budget tags: - Budget requestBody: content: application/json: schema: $ref: '#/components/schemas/BudgetCreateOrUpdateRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/BudgetCreateOrUpdateRequest' multipart/form-data: schema: $ref: '#/components/schemas/BudgetCreateOrUpdateRequest' required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/BudgetResponse' description: '' '201': content: application/json: schema: $ref: '#/components/schemas/BudgetResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_billing_budget_destroy description: Delete the company's budget and all associated alerts. Requires CompanyAdmin role. summary: Delete company budget tags: - Budget security: - bearerAuth: [] responses: '204': description: No response body '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/billing/budget/alerts: get: operationId: api_v3_billing_budget_alerts_retrieve description: Return all alert thresholds for the company's budget. summary: List budget alerts tags: - Budget security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/BudgetAlertListResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_billing_budget_alerts_create description: Add an alert threshold to the company's budget. Requires CompanyAdmin role. summary: Create budget alert tags: - Budget requestBody: content: application/json: schema: $ref: '#/components/schemas/BudgetAlertCreateRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/BudgetAlertCreateRequest' multipart/form-data: schema: $ref: '#/components/schemas/BudgetAlertCreateRequest' required: true security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/BudgetAlertResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_billing_budget_alerts_toggle_all description: Enable or disable all alert thresholds for the company's budget in a single operation. Requires CompanyAdmin role. summary: Toggle all budget alerts tags: - Budget requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedBudgetAlertBulkToggleRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedBudgetAlertBulkToggleRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedBudgetAlertBulkToggleRequest' required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/BudgetAlertBulkToggleResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/billing/budget/alerts/{id}: patch: operationId: api_v3_billing_budget_alerts_partial_update description: Update an existing alert threshold. Requires CompanyAdmin role. summary: Update budget alert parameters: - in: path name: id schema: type: integer required: true tags: - Budget requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedBudgetAlertUpdateRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedBudgetAlertUpdateRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedBudgetAlertUpdateRequest' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/BudgetAlertResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_billing_budget_alerts_destroy description: Delete an alert threshold. Requires CompanyAdmin role. summary: Delete budget alert parameters: - in: path name: id schema: type: integer required: true tags: - Budget security: - bearerAuth: [] responses: '204': description: No response body '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/credits: get: operationId: api_v3_credits_retrieve description: |- Returns the company's cumulative metered-API-call spend in euros plus the free-tier budget and a per-playground-endpoint estimate of how many operations the remaining credits buy at current list price. `limit_eur`, `remaining_eur` and `estimates` are populated only for non-exempt companies while `LIMIT_ENFORCEMENT_ENABLED` is on; otherwise they are `null`/empty. **Free-tier only.** Credits are a free-tier concept, so a company that is *not* on the free tier — a paid or otherwise exempt tier, or any company while `LIMIT_ENFORCEMENT_ENABLED` is off — receives **403 Forbidden** by design. The 403 is expected, not a failure: clients should treat it as "no free-tier credits apply to this company" (e.g. hide the credits banner) rather than surfacing it as an error. summary: Company free-tier credits tags: - Usage security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/CompanyCreditsResponse' description: '' '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotOnFreeTier: value: id: null code: 403 error: insufficient_permissions detail: Free-tier credits are only available to companies on the free tier. doc_url: https://developers.lighton.ai/errors#insufficient_permissions summary: Not on free tier description: Company is not on the free tier (paid/exempt tier, or enforcement disabled) — expected, not an error. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/storage: get: operationId: api_v3_storage_retrieve description: Returns the company's current ingested-file footprint in bytes plus its tier's included/free storage allowance. `limit_bytes` is the tier allowance (5 GB for free / pay-as-you-go, 100 GB for business) — a hard cap only for the free tier; for paid tiers it is the free allowance above which storage is metered. `limit_bytes` is `null` only when limit enforcement is disabled. summary: Company storage usage tags: - Usage security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/CompanyStorageResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/storage/cost: get: operationId: api_v3_storage_cost_retrieve description: |- Return the storage charge the caller's company has accrued so far in the current billing month, alongside the quantities it is derived from. `cost` is computed by the same code path that produces the invoice's storage line item, so the two always agree: the month's **peak** footprint is rounded up to whole GiB, `free_gib` is subtracted, and the remainder is billed at the published per-GiB monthly rate. Because the charge follows the peak rather than the current footprint, deleting files mid-month does not reduce it. `cost` is `0` while the company stays within its allowance. For the current footprint in bytes and the free-tier cap, use `GET /api/v3/storage`. summary: Get month-to-date storage cost tags: - Usage security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/CompanyStorageCostResponse' description: '' '401': description: Unauthenticated - missing or invalid API key. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/system/status: get: operationId: api_v3_system_status_retrieve description: |- Returns the current maintenance state: active maintenance periods and the active announcement. This endpoint is always exempt from maintenance blocking. Poll it every 30 seconds to drive frontend maintenance banners and overlays. The `maintenance.periods` list is pre-filtered for the caller: authenticated requests receive only periods that apply to their company; unauthenticated requests receive only instance-wide periods. Company IDs are never exposed in the response. summary: System status tags: - System responses: '200': content: application/json: schema: $ref: '#/components/schemas/SystemStatus' examples: NoMaintenance: value: maintenance: active: false periods: [] announcement: active: false summary: No maintenance GlobalMaintenance: value: maintenance: active: true periods: - frontend_mode: full_shutdown reason: Database upgrade started_at: '2026-06-22T22:00:00Z' announcement: active: true message: We will be upgrading the database. The platform will be unavailable. expected_start: '2026-06-22T22:00:00Z' expected_end: '2026-06-23T06:00:00Z' summary: Global maintenance ScopedMaintenance(authenticated): value: maintenance: active: true periods: - endpoint_category_names: - Search & Ask frontend_mode: warning_banner reason: Model endpoint update started_at: '2026-06-22T22:00:00Z' announcement: active: false summary: Scoped maintenance (authenticated) description: Current system maintenance state. /api/v3/usage: get: operationId: api_v3_usage_retrieve description: |- Return a per-day breakdown of metered usage over the last 30 days (oldest first), including a list-price cost estimate per feature and per day. Days with no usage are returned with an empty `usage` object so the response is dense. By default the histogram aggregates across every non-revoked API key owned by the authenticated user. Pass `api_key_id` as a query parameter to scope the response to a single key. **Authorization:** when `api_key_id` is provided, the authenticated user must own that key — the existence of keys belonging to other users is not disclosed. summary: Get 30-day usage histogram for the authenticated user tags: - Usage security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/UsageHistogramResponse' description: '' '401': description: Unauthenticated - missing or invalid API key. '404': description: Not Found - api_key_id not owned by the caller. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/usage/current-period: get: operationId: api_v3_usage_current_period_retrieve description: |- Recap what the caller's company has accrued in the billing period now open: a `total_cost` plus a per-feature breakdown, highest cost first. Billing periods are calendar months, so the period runs from `period_start` to the day before `next_period_start` — the date this period's invoice is issued. The figures come from the same code paths that build the invoice: metered counters (parsing, ingestion, extraction, search, rag) summed over the period, plus `storage` as a peak-based GiB charge net of the free allowance. Two caveats keep this an estimate rather than a promise: usage recorded moments ago may still be settling, and an invoice also sweeps up usage that belongs to an earlier period but only became queryable after that period closed. Company-wide, not per-user or per-API-key. Free-tier companies are not billed — use `GET /api/v3/credits` for their remaining allowance instead. summary: Get spend for the open billing period tags: - Usage security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/CurrentPeriodSpendResponse' description: '' '401': description: Unauthenticated - missing or invalid API key. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/agents: get: operationId: api_v3_agents_list description: 'Get a paginated list of agents (ChatSettings) accessible to the user. Access control: Sys-admin users can access all agents from all companies. Company admin users can access all agents from their company. Regular users can only access agents linked to groups they belong to.' summary: List all agents parameters: - in: query name: company_id schema: type: integer description: Filter agents by company ID. Sys-admins can filter by any company ID. Company admins and regular users can only filter by their own company ID. - in: query name: group_id schema: type: integer description: Filter agents by group ID - in: query name: is_current_user_favorite schema: type: string description: 'Filter agents by favorite status. Accepted values: ''true'', ''false'', ''1'', ''0'', ''yes'', ''no''' - in: query name: is_default schema: type: string description: 'Filter agents by is_default status. Accepted values: ''true'', ''false'', ''1'', ''0'', ''yes'', ''no''' - in: query name: name schema: type: string description: Filter agents by name (prefix search, case-insensitive) - in: query name: page schema: type: integer description: Page number for pagination - in: query name: page_size schema: type: integer description: 'Number of results per page (default: 50, max: 100)' - in: query name: user_id schema: type: integer description: Filter agents by user ID - returns agents linked to groups of which the specified user is a member. Sys-admins can filter by any user ID. Company admins can only filter by user IDs of users inside their company. Regular users can only filter by their own user ID. tags: - Agents security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentListResponseSchema' description: '' '400': content: application/json: schema: description: Invalid query parameters description: '' '403': content: application/json: schema: description: Permission denied for company_id or user_id filter description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_agents_create description: |- Create a new agent (ChatSettings) with specified tools and MCP servers. **Access control:** - Users can create agents in their personal groups - Company admins can create agents in any group within their company - Sys-admin users can create agents in any group **Model configuration:** - `ml_model`: UUID of an ML model to set as default for this agent - `ml_model_alias`: UUID of an alias to set as default for this agent - These fields are mutually exclusive — provide one or neither, not both - When neither is provided, the agent uses the company default model summary: Create a new agent tags: - Agents requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateAgentRequest' multipart/form-data: schema: $ref: '#/components/schemas/CreateAgentRequest' required: true security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/AgentSchema' description: '' '400': content: application/json: schema: description: Invalid request data description: '' '403': content: application/json: schema: description: Permission denied description: '' '404': content: application/json: schema: description: Company, group, tool, or MCP server not found description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/agents/favorites: get: operationId: api_v3_agents_favorites_retrieve description: Get a list of the current user's favorited agents, ordered by newest first. summary: List agent favorites tags: - Agents security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentFavoriteListResponseSchema' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_agents_favorites_create description: Favorite an agent for the current user. summary: Create agent favorite tags: - Agents requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentFavoriteRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateAgentFavoriteRequest' multipart/form-data: schema: $ref: '#/components/schemas/CreateAgentFavoriteRequest' required: true security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/AgentFavoriteSchema' description: '' '200': content: application/json: schema: $ref: '#/components/schemas/AgentFavoriteSchema' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_agents_favorites_destroy_by_agent_id description: Remove an agent from the current user's favorites by agent id. summary: Delete agent favorite by agent id parameters: - in: query name: agent_id schema: type: integer required: true tags: - Agents security: - bearerAuth: [] responses: '204': content: application/json: schema: description: Favorite deleted description: '' '404': content: application/json: schema: description: Favorite not found description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/agents/favorites/{id}: delete: operationId: api_v3_agents_favorites_destroy description: Remove an agent from the current user's favorites by favorite id. summary: Delete agent favorite parameters: - in: path name: id schema: type: integer required: true tags: - Agents security: - bearerAuth: [] responses: '204': content: application/json: schema: description: Favorite deleted description: '' '404': content: application/json: schema: description: Favorite not found description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/agents/{id}: get: operationId: api_v3_agents_retrieve description: 'Get detailed information about a specific agent (ChatSettings) by ID. Access control: Sys-admin users can access all agents from all companies. Company admin users can access all agents from their company. Regular users can only access agents linked to groups they belong to.' summary: Retrieve a single agent parameters: - in: path name: id schema: type: integer description: ID of the agent to retrieve required: true tags: - Agents security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentSchema' description: '' '404': content: application/json: schema: description: Agent not found or not accessible description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_agents_partial_update description: |- Partially update an agent (ChatSettings) by ID. **Access control:** - Users can update agents in their personal groups - Company admins can update agents in any group within their company - Sys-admin users can update any agent **Model configuration:** - `ml_model` and `ml_model_alias` are mutually exclusive — provide one or neither, not both - Setting one automatically clears the other - Explicitly sending `null` clears the field (agent falls back to company default) - Omitting the field leaves the current value unchanged summary: Update an agent parameters: - in: path name: id schema: type: integer description: ID of the agent to update required: true tags: - Agents requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedUpdateAgentRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedUpdateAgentRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedUpdateAgentRequest' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentSchema' description: '' '400': content: application/json: schema: description: Invalid request data description: '' '403': content: application/json: schema: description: Permission denied description: '' '404': content: application/json: schema: description: Agent, tool, or MCP server not found description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_agents_destroy description: 'Delete an agent (ChatSettings) by ID. Access control: Users can delete agents in their personal groups. Company admins can delete agents in any group within their company. Sys-admin users can delete any agent. Default agents cannot be deleted.' summary: Delete an agent parameters: - in: path name: id schema: type: integer description: ID of the agent to delete required: true tags: - Agents security: - bearerAuth: [] responses: '204': content: application/json: schema: description: Agent deleted successfully description: '' '403': content: application/json: schema: description: Permission denied description: '' '404': content: application/json: schema: description: Agent not found description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/agents/{id}/files: get: operationId: api_v3_agents_files_list description: |- Retrieve a paginated list of files (documents) accessible to the authenticated user. Results are ordered by upload date (newest first) by default. When using the `search` parameter, results are ordered by relevance. **Public datasets:** instance admins (holding `MANAGE_PUBLIC_DATASET`) always see public-dataset files. A company that has opted in (`allow_access_to_public_datasets`) with a workspace-scoped API key granting a public workspace also sees its files — filter with `workspace_id` to scope the list to it. summary: List files scoped to an agent parameters: - in: query name: created_at_after schema: type: string format: date-time description: Filter by created_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?created_at_after=2024-01-01&created_at_before=2024-01-01T23:59:59) - in: query name: created_at_before schema: type: string format: date-time description: Filter by created_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?created_at_after=2024-01-01&created_at_before=2024-01-01T23:59:59) - in: query name: extension schema: type: array items: type: string description: Filter by file extensions (comma-separated, e.g., ?extension=pdf,docx) explode: false style: form - in: query name: external_metadata__doc_type schema: type: string description: Filter by external document type (case-insensitive partial match, e.g., ?external_metadata__doc_type=gitlab) - in: query name: external_metadata__external_id schema: type: string description: Filter by external document ID (exact match, e.g., ?external_metadata__external_id=SN-12345) - in: query name: filename schema: type: string description: Filter by filename (case-insensitive partial match) - in: query name: group_id schema: type: array items: type: integer description: Filter by user group IDs (comma-separated, e.g., ?group_id=1,2,3) explode: false style: form - in: path name: id schema: type: integer required: true - name: ordering required: false in: query description: Which field to use when ordering the results. schema: type: string - in: query name: owner_id schema: type: array items: type: integer description: Filter by owner user IDs (comma-separated, e.g., ?owner_id=1,2,3) explode: false style: form - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer - in: query name: status schema: type: array items: type: string description: Filter by status values (comma-separated, e.g., ?status=pending,embedded) explode: false style: form - in: query name: status_vision schema: type: array items: type: string description: Filter by vision status values (comma-separated, e.g., ?status_vision=pending,embedded) explode: false style: form - in: query name: tag_id schema: type: array items: type: integer description: Filter by tag IDs (comma-separated, e.g., ?tags=1,2,3) explode: false style: form - in: query name: title schema: type: string description: Filter by title (case-insensitive partial match) - in: query name: total_pages_max schema: type: - integer - 'null' maximum: 2147483647 minimum: -2147483648 description: Filter by total pages range (e.g., ?total_pages_min=10&total_pages_max=50) - in: query name: total_pages_min schema: type: - integer - 'null' maximum: 2147483647 minimum: -2147483648 description: Filter by total pages range (e.g., ?total_pages_min=10&total_pages_max=50) - in: query name: updated_at_after schema: type: string format: date-time description: Filter by updated_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?updated_at_after=2024-01-01&updated_at_before=2024-01-01T23:59:59) - in: query name: updated_at_before schema: type: string format: date-time description: Filter by updated_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?updated_at_after=2024-01-01&updated_at_before=2024-01-01T23:59:59) - in: query name: upload_session_uuid schema: type: string description: Filter by upload session UUID (e.g., ?upload_session_uuid=123e4567-e89b-12d3-a456-426614174000) - in: query name: workspace_id schema: type: array items: type: integer description: Filter by workspace IDs (comma-separated, e.g., ?workspace_id=1,2,3) explode: false style: form tags: - Agents security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedFileListResponseSerializerV3List' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/agents/{id}/icon: get: operationId: api_v3_agents_icon_retrieve description: 'Retrieve the icon for an agent as a WebP image file. Access control: Sys-admin users can access icons for all agents from all companies. Company admin users can access icons for all agents from their company. Regular users can only access icons for agents linked to groups they belong to.' summary: Get agent icon parameters: - in: query name: download schema: type: string description: Set to 'true' to download the icon as an attachment - in: path name: id schema: type: integer description: ID of the agent required: true tags: - Agents security: - bearerAuth: [] responses: '200': content: application/json: schema: type: string format: binary description: WebP image file content description: '' '404': content: application/json: schema: description: Agent or icon not found description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' put: operationId: api_v3_agents_icon_update description: 'Upload or update an icon for an agent. Maximum file size: 5MB. Access control: Users can upload icons for agents in their personal groups. Company admins can upload icons for agents in any group within their company. Sys-admin users can upload icons for any agent.' summary: Upload agent icon parameters: - in: path name: id schema: type: integer description: ID of the agent required: true tags: - Agents requestBody: content: multipart/form-data: schema: type: object properties: icon: type: string format: binary description: Image file to upload as agent icon (max 5MB) required: - icon security: - bearerAuth: [] responses: '200': content: application/json: schema: description: Icon uploaded successfully description: '' '400': content: application/json: schema: description: Invalid file, missing icon, or file size exceeds 5MB description: '' '403': content: application/json: schema: description: Permission denied description: '' '404': content: application/json: schema: description: Agent not found description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/agents/{id}/tags: get: operationId: api_v3_agents_tags_list description: Return a non-paginated list of tags used in documents within workspaces scoped to the specified agent. If the agent is default, tags are computed across all workspaces accessible to the user. If the agent is not default, tags are computed only across workspaces linked to the agent's group, intersected with workspaces accessible to the user. summary: List tags used in workspaces for an agent parameters: - in: query name: auto_assign schema: type: boolean description: Filter tags by auto_assign flag - in: path name: id schema: type: integer description: ID of the agent required: true - in: query name: tag schema: type: string description: Filter tags by tag title (case-insensitive partial match) tags: - Agents security: - bearerAuth: [] responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/TagListResponseSerializerV3' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/agents/{id}/tools: get: operationId: api_v3_agents_tools_retrieve description: Get available native tools and MCP servers with their tools for a given agent ID. summary: List native tools and MCP servers available for a specific agent parameters: - in: path name: id schema: type: integer description: ID of the agent to fetch tools for required: true tags: - Agents security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ToolListResponse' description: '' '404': content: application/json: schema: description: Agent not found or not accessible description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/threads: get: operationId: api_v3_threads_list description: List conversation threads for the authenticated user with cursor-based pagination. summary: List conversation threads parameters: - in: query name: creation_source schema: type: string minLength: 1 description: Filter threads by creation source (api or web) - in: query name: ending_before schema: type: string minLength: 1 description: ID to end pagination before - in: query name: limit schema: type: integer maximum: 100 minimum: 1 default: 10 - in: query name: search schema: type: string minLength: 1 description: Search threads by name - in: query name: starting_after schema: type: string minLength: 1 description: ID to start pagination after tags: - Threads security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListThreadsResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_threads_create description: |- Create a new conversation thread. Note: `chat_setting_id` has been deprecated, now use `agent_id` instead, `chat_settings_id` is still supported for back-compatibility purposes. If no `agent_id` nor `chat_setting_id` is provided, the default agent for the company is used. summary: Create a conversation thread tags: - Threads requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateThreadRequest' examples: CreateThreadRequest: value: name: My new conversation agent_id: 1 is_ephemeral: false summary: Create thread request application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateThreadRequest' multipart/form-data: schema: $ref: '#/components/schemas/CreateThreadRequest' security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/ThreadResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/threads/turns: post: operationId: api_v3_threads_create_with_turn description: "Create a new thread and immediately ask a query in a single request.\ \ \nThis endpoint combines thread creation and turn creation to reduce round\ \ trips. \n\nSupports synchronous and background processing modes. Streaming\ \ is not supported.If you need to use streaming mode then directly use the\ \ endpoint to create a turn within a thread\n\nNote: `chat_setting_id` has\ \ been deprecated, now use `agent_id` instead, `chat_settings_id` is still\ \ supported for back-compatibility purposes. If no `agent_id` nor `chat_setting_id`\ \ is provided, the default agent for the company is used." summary: Create a conversation thread with initial turn tags: - Threads requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateThreadWithTurnRequest' examples: CreateThreadWithSimpleQuery: value: agent_id: 1 query: What is the capital of France? summary: Create thread with simple query CreateThreadWithBackgroundProcessing: value: agent_id: 1 query: What is the capital of France? background: true summary: Create thread with background processing CreateThreadWithResponseFormat: value: agent_id: 1 query: What is the capital of France? response_format: type: object properties: capital: type: string country: type: string required: - capital - country summary: Create thread with response format CreateThreadWithForcedTool: value: agent_id: 1 query: 781+8171? force_tool: code_execution summary: Create thread with forced tool CreateThreadWithImmediateFinalAnswer: value: agent_id: 1 query: What is the capital of France? immediate_final_answer: true summary: Create thread with immediate final answer CreateThreadWithCustomDocumentSearchParameters: value: agent_id: 1 query: What is the company revenue? force_tool: document_search tool_parameters: document_search: top_k: 20 top_n: 10 summary: Create thread with custom document search parameters application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateThreadWithTurnRequest' multipart/form-data: schema: $ref: '#/components/schemas/CreateThreadWithTurnRequest' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AnswerResponse' description: Final answer returned synchronously. '202': content: application/json: schema: $ref: '#/components/schemas/AnswerResponse' description: Answer accepted and still processing. The payload contains the current answer resource; clients should poll or listen for updates until the status is final. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/threads/{id}: get: operationId: api_v3_threads_retrieve description: Get a thread by ID. summary: Retrieve a conversation thread parameters: - in: path name: id schema: type: string required: true tags: - Threads security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ThreadResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_threads_partial_update description: Update a thread by ID. Use query parameters 'anonymize=true' to anonymize an ephemeral thread or 'cancel=true' to cancel the current turn processing. summary: Update a conversation thread parameters: - in: query name: anonymize schema: type: boolean description: Set to true to anonymize an ephemeral thread - in: query name: cancel schema: type: boolean description: Set to true to cancel the current turn processing - in: path name: id schema: type: string required: true tags: - Threads requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedUpdateThreadRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedUpdateThreadRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedUpdateThreadRequest' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ThreadResponse' description: Thread updated successfully or action performed '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_threads_destroy description: Delete a thread by ID. summary: Delete a conversation thread parameters: - in: path name: id schema: type: string required: true tags: - Threads security: - bearerAuth: [] responses: '204': description: No response body '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/threads/{id}/resume: get: operationId: api_v3_threads_resume_retrieve description: Resume streaming the last turn of a thread. summary: Resume a turn generation parameters: - in: path name: id schema: type: string required: true tags: - Threads security: - bearerAuth: [] responses: '200': content: application/json: schema: description: Event stream of the last turn of the thread description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/threads/{id}/suggested_queries: get: operationId: api_v3_threads_suggested_queries_retrieve description: Get AI-generated suggested follow-up queries for a thread. summary: Get suggested queries for a conversation thread parameters: - in: path name: id schema: type: string required: true tags: - Threads security: - bearerAuth: [] responses: '200': content: application/json: schema: description: List of suggested queries description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/threads/{id}/turns: get: operationId: api_v3_threads_turns_retrieve description: List all turns (answers) for a thread with cursor-based pagination. summary: List conversation turns in a thread parameters: - in: query name: ending_before schema: type: string minLength: 1 description: ID to end pagination before - in: path name: id schema: type: string required: true - in: query name: limit schema: type: integer maximum: 100 minimum: 1 default: 10 - in: query name: starting_after schema: type: string minLength: 1 description: ID to start pagination after tags: - Threads security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListAnswerResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_threads_turns_create description: |- Ask a query to the agent. Behaviour: - Returns 200 with the final answer when the task completes quickly within the request. - Returns 202 Accepted with the current answer payload when processing continues in the background; clients should poll the turn status or subscribe to updates until completion. - If `stream=true`, the endpoint responds with Server-Sent Events (SSE) and streams tokens/events until completion (content-type: text/event-stream). - If `background=true`, the endpoint enqueues processing and returns the created answer immediately. summary: Create a conversation turn in a thread parameters: - in: path name: id schema: type: string required: true tags: - Threads requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAnswerRequest' examples: CreateTurnWithSimpleQuery: value: query: What is the capital of France? summary: Create turn with simple query CreateTurnWithStreaming: value: query: What is the capital of France? stream: true summary: Create turn with streaming CreateTurnWithBackgroundProcessing: value: query: What is the capital of France? background: true summary: Create turn with background processing CreateTurnWithResponseFormat: value: query: What is the capital of France? response_format: type: object properties: capital: type: string country: type: string required: - capital - country summary: Create turn with response format CreateTurnWithForcedTool: value: query: 781+8171? force_tool: code_execution summary: Create turn with forced tool CreateTurnWithImmediateFinalAnswer: value: query: What is the capital of France? immediate_final_answer: true summary: Create turn with immediate final answer CreateTurnWithCustomDocumentSearchParameters: value: query: What is the company revenue? force_tool: document_search tool_parameters: document_search: top_k: 20 top_n: 10 summary: Create turn with custom document search parameters application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateAnswerRequest' multipart/form-data: schema: $ref: '#/components/schemas/CreateAnswerRequest' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AnswerResponse' description: Final answer returned synchronously. '202': content: application/json: schema: $ref: '#/components/schemas/AnswerResponse' description: Answer accepted and still processing. The payload contains the current answer resource; clients should poll or listen for updates until the status is final. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/threads/{id}/turns/{turn_id}: patch: operationId: api_v3_threads_turns_partial_update description: 'Update a turn by ID. Use query parameter ''action'' to specify the action: ''like_dislike'' to send like/dislike feedback, ''copied'' to mark as copied, or ''flag'' to create a flag.' summary: Update a conversation turn in a thread parameters: - in: query name: action schema: type: string enum: - copied - flag - like_dislike description: 'The action to perform: ''like_dislike'', ''copied'', or ''flag''' required: true - in: path name: id schema: type: string required: true - in: path name: turn_id schema: type: string required: true tags: - Threads requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedTurnActionRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedTurnActionRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedTurnActionRequest' security: - bearerAuth: [] responses: '200': description: Action performed successfully '201': description: Flag created successfully '400': description: Bad request - invalid action or data '404': description: Turn not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/tools: get: operationId: api_v3_tools_retrieve description: Returns native tools available to the authenticated user's company. If the company has no tool restrictions configured, all native tools are returned. Sys-admins can pass `company_id` to inspect another company's allowed tools. summary: List native tools parameters: - in: query name: company_id schema: type: integer description: Filter by company allowlist (sys-admins only). tags: - Tools security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/NativeToolListResponse' description: '' '400': content: application/json: schema: description: Invalid company_id parameter description: '' '403': content: application/json: schema: description: Permission denied description: '' '404': content: application/json: schema: description: Company not found description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/aliases: get: operationId: api_v3_aliases_list description: List all aliases for the authenticated user's company. Sysadmins can filter by company_id to view aliases from any company. summary: List aliases tags: - Models security: - bearerAuth: [] responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/Alias' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_aliases_create description: Create a new model alias for the authenticated user's company. summary: Create alias tags: - Models requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAliasRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateAliasRequest' multipart/form-data: schema: $ref: '#/components/schemas/CreateAliasRequest' required: true security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/AliasDetails' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/aliases/{id}: get: operationId: api_v3_aliases_retrieve description: Retrieve an alias with its linked models. summary: Get alias details parameters: - in: path name: id schema: type: string format: uuid required: true tags: - Models security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AliasDetails' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_aliases_partial_update description: Partially update an alias. summary: Update alias parameters: - in: path name: id schema: type: string format: uuid required: true tags: - Models requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedUpdateAliasRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedUpdateAliasRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedUpdateAliasRequest' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AliasDetails' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_aliases_destroy description: Delete an alias and all its model mappings. summary: Delete alias parameters: - in: path name: id schema: type: string format: uuid required: true tags: - Models security: - bearerAuth: [] responses: '204': description: No response body '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/aliases/{id}/models: post: operationId: api_v3_aliases_models_create description: Link an ML model to this alias with a priority rank. summary: Add model to alias parameters: - in: path name: id schema: type: string format: uuid required: true tags: - Models requestBody: content: application/json: schema: $ref: '#/components/schemas/AddModelToAliasRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/AddModelToAliasRequest' multipart/form-data: schema: $ref: '#/components/schemas/AddModelToAliasRequest' required: true security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/AliasDetails' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/aliases/{id}/models/{uuid}: patch: operationId: api_v3_aliases_models_partial_update description: Update the priority of a model linked to this alias. summary: Update model priority in alias parameters: - in: path name: id schema: type: string format: uuid required: true - in: path name: uuid schema: type: string format: uuid required: true tags: - Models requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedUpdateModelPriorityRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedUpdateModelPriorityRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedUpdateModelPriorityRequest' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AliasDetails' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_aliases_models_destroy description: Soft-delete the link between a model and this alias. summary: Remove model from alias parameters: - in: path name: id schema: type: string format: uuid required: true - in: path name: uuid schema: type: string format: uuid required: true tags: - Models security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AliasDetails' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/aliases/{id}/route: get: operationId: api_v3_aliases_route_retrieve description: |- Simulate the routing resolution for this alias as it would happen at request time. Returns the model that would be selected as primary, the ordered list of fallbacks, and any models currently excluded from routing (e.g. because they are unhealthy). This is useful for debugging alias configuration and verifying that health checks and priority settings produce the expected routing outcome. summary: Preview alias routing parameters: - in: path name: id schema: type: string format: uuid required: true tags: - Models security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AliasRoutingResult' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/chat/completions: post: operationId: api_v3_chat_completions_create description: |- This endpoint can be used to generate chat completions from a Large Language Model. It is a simple proxy forwarding your requests to the desired model. Any LightOn model is deployed on a vLLM-based image. **Model resolution:** The `model` field accepts either a model technical name or an alias technical name. If the value matches an alias technical name for the authenticated user's company, the alias routing is used to resolve the effective model (even if a model with the same technical name exists). Otherwise, the model is resolved directly by technical name. **Response Types:** - When `stream=false` **(default)**: Returns a complete JSON response with all completion choices - When `stream=true`: Returns Server-Sent Events (SSE) with incremental completion chunks **Streaming Format:** Each SSE event contains a JSON object with incremental text. The stream ends with `data: [DONE]`. summary: Generate a chat completion tags: - Models requestBody: content: application/json: schema: $ref: '#/components/schemas/ChatCompletionsRequest' examples: LightOnModelExample: value: model: alfred-4.2 messages: - role: system content: You are a helpful assistant. - role: user content: Hello! summary: LightOn model example StreamingRequestExample: value: model: alfred-4.2 messages: - role: system content: You are a helpful assistant. - role: user content: Hello! stream: true summary: Streaming request example application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/ChatCompletionsRequest' multipart/form-data: schema: $ref: '#/components/schemas/ChatCompletionsRequest' required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ChatCompletionsResponse' examples: LightOnModelExample: value: model: alfred-4.2 messages: - role: system content: You are a helpful assistant. - role: user content: Hello! summary: LightOn model example StreamingRequestExample: value: model: alfred-4.2 messages: - role: system content: You are a helpful assistant. - role: user content: Hello! stream: true summary: Streaming request example description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/embeddings: post: operationId: api_v3_embeddings_create description: |- This endpoint can be used to convert text chunks into embeddings. It is a simple proxy forwarding your requests to the desired model. **Model resolution:** The `model` field accepts either a model technical name or an alias technical name. If the value matches an alias technical name for the authenticated user's company, the alias routing is used to resolve the effective model (even if a model with the same technical name exists). Otherwise, the model is resolved directly by technical name. **Input Format:** - `input`: Text string to convert to embeddings - `encoding_format`: Format for returned embeddings (float or base64) - `dimensions`: Optional dimension specification for output embeddings summary: Create embeddings tags: - Models requestBody: content: application/json: schema: $ref: '#/components/schemas/EmbeddingsRequest' examples: BasicEmbeddingExample: value: model: multilingual-e5-large input: Hello, world! summary: Basic embedding example application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/EmbeddingsRequest' multipart/form-data: schema: $ref: '#/components/schemas/EmbeddingsRequest' required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/EmbeddingsResponse' examples: BasicEmbeddingExample: value: model: multilingual-e5-large input: Hello, world! summary: Basic embedding example description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/external_keys: get: operationId: api_v3_external_keys_retrieve description: 'Returns active provider API keys for the current user and their company. Key values are never returned. Each item includes a `scope` field: ''user'' or ''company''.' summary: List external API keys tags: - Models security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedExternalAPIKeyResponseList' description: 'Active provider API keys for the current user and their company. Key values are never returned. Each item includes a `scope` field: ''user'' or ''company''.' '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/external_keys/{provider}: put: operationId: api_v3_external_keys_update description: Creates or replaces the active personal API key for the given provider. The previous key (if any) is deactivated. Key value is never returned. summary: Set personal external API key parameters: - in: path name: provider schema: type: string required: true tags: - Models requestBody: content: application/json: schema: $ref: '#/components/schemas/SetExternalAPIKeyRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SetExternalAPIKeyRequest' multipart/form-data: schema: $ref: '#/components/schemas/SetExternalAPIKeyRequest' required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ExternalAPIKeyResponse' description: Key saved. The previous active key for this provider (if any) has been deactivated. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_external_keys_destroy description: Soft-deletes the active personal API key for the given provider. summary: Deactivate personal external API key parameters: - in: path name: provider schema: type: string required: true tags: - Models security: - bearerAuth: [] responses: '204': description: Key deactivated successfully. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/extract: post: operationId: api_v3_extract_create description: |- Pull specific fields from a document into a typed schema. Accepts exactly one of: a **file upload** (multipart/form-data), a **document URL** (JSON body), or a **`file_id`** referencing an already-ingested document (from `POST /v3/files`), plus a **JSON Schema** (the `schema` field) describing what to extract. ### Sync mode (default) Blocks until extraction completes and returns **200** with the full result. ```bash curl -X POST https://api.lighton.ai/api/v3/extract \ -H 'Authorization: Bearer $TOKEN' \ -F file=@invoice.pdf \ -F 'schema={"type":"object","properties":{"invoice_number":{"type":"string"}}}' ``` ### Async mode (`options.async = true`) Returns **202** immediately with an `ext_` job id. Poll `GET /api/v3/extract/{id}` with that same id until `status` is `completed` or `failed`. ```bash curl -X POST https://api.lighton.ai/api/v3/extract \ -H 'Authorization: Bearer $TOKEN' \ -H 'Content-Type: application/json' \ -d '{"document": "https://example.com/report.pdf", "schema": {"type": "object", "properties": {"title": {"type": "string"}}}, "options": {"async": true}}' ``` For multipart uploads, pass `options` as a JSON-encoded form field: `-F 'options={"async":true}'`. **Supported file types:** `.pdf`, `.png`, `.jpg`, `.jpeg`, `.pptx`, `.ppt`, `.odp`, `.docx`, `.odt`, `.doc`, `.html` **Sync limits:** 20 MB file size, 15 pages. **Async limits:** 100 MB file size, 1000 pages. summary: Extract structured data from a document tags: - Models requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/ExtractRequest' examples: ExtractViaFileUpload(sync): value: file: (binary) schema: type: object properties: invoice_number: type: string summary: Extract via file upload (sync) description: Upload a PDF and provide a JSON Schema to extract specific fields. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/ExtractRequest' application/json: schema: $ref: '#/components/schemas/ExtractRequest' examples: ExtractViaDocumentURL(sync): value: document: https://example.com/invoice.pdf schema: type: object properties: invoice_number: type: string description: The invoice reference number total: type: number description: The total amount due summary: Extract via document URL (sync) description: Provide a publicly accessible document URL and a JSON Schema. ExtractAsynchronously: value: document: https://example.com/large-report.pdf schema: type: object properties: title: type: string options: async: true summary: Extract asynchronously description: Same as above with options.async=true. Returns 202 with a job ID. ExtractViaFileId(sync): value: file_id: 42 schema: type: object properties: invoice_number: type: string total: type: number summary: Extract via file_id (sync) description: Reference an already-ingested document (from POST /v3/files) by id. required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ExtractJobResponse' examples: SyncExtractionResponse: value: id: ext_0196e4b2a3c14d5e8f7a9b2c1d0e3f4a status: completed created_at: '2026-03-31T10:00:00+00:00' completed_at: '2026-03-31T10:00:04+00:00' processing_time_ms: 3200 document: filename: invoice.pdf page_count: 3 file_size_bytes: 245120 mime_type: application/pdf result: data: - invoice_number: INV-2026-001 total: null line_items: null - invoice_number: null total: 1250.0 line_items: - description: Widget A quantity: 10 unit_price: 50.0 - description: Widget B quantity: 5 unit_price: 150.0 - invoice_number: null total: null line_items: null pagination: page: 1 page_size: 15 total_items: 3 total_pages: 1 has_next: false has_prev: false usage: pages_processed: 3 progress: percentage: 100 pages_processed: 3 summary: Sync extraction response description: Extraction completed (sync mode). '202': content: application/json: schema: $ref: '#/components/schemas/ExtractJobResponse' examples: AsyncAcceptedResponse: value: id: ext_0196e4b2a3c14d5e8f7a9b2c1d0e3f4a status: pending created_at: '2026-03-31T10:00:00+00:00' completed_at: null processing_time_ms: null document: filename: large-report.pdf page_count: null file_size_bytes: 5242880 mime_type: application/pdf result: null usage: null progress: null summary: Async accepted response description: Extraction accepted (async mode). Poll GET /v3/extract/{id} for status. '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: MissingSource: value: id: null code: 400 error: missing_input detail: A file upload, document URL, or file_id is required. doc_url: https://developers.lighton.ai/errors#missing_input summary: Missing source AmbiguousSource: value: id: null code: 400 error: ambiguous_input detail: 'Provide exactly one of: file upload, document URL, or file_id.' doc_url: https://developers.lighton.ai/errors#ambiguous_input summary: Ambiguous source PageLimitExceeded: value: id: null code: 400 error: max_pages_exceeded detail: Document has 1200 pages, exceeding the async limit of 1000 pages. doc_url: https://developers.lighton.ai/errors#max_pages_exceeded summary: Page limit exceeded description: Bad request — missing/ambiguous source, unsupported format, or page limit exceeded. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: DocumentNotFoundOrUnauthorized: value: id: null code: 404 error: not_found detail: Document not found or access denied. doc_url: https://developers.lighton.ai/errors#not_found summary: Document not found or unauthorized DocumentFileMissing: value: id: null code: 404 error: document_file_not_found detail: The document's stored file could not be found. doc_url: https://developers.lighton.ai/errors#document_file_not_found summary: Document file missing description: '`file_id` does not exist, is not authorized for the requesting user, or its stored file is missing.' '413': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: PayloadTooLarge: value: id: null code: 413 error: payload_too_large detail: File size (157286400 bytes) exceeds the 100MB async limit. doc_url: https://developers.lighton.ai/errors/payload_too_large summary: Payload too large description: File exceeds the size limit (20 MB sync, 100 MB async). '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: MalformedJSONSchema: value: id: null code: 422 error: validation_error detail: The provided JSON Schema is malformed. doc_url: https://developers.lighton.ai/errors#validation_error fields: schema: - error: invalid detail: 'JSON Schema is not valid: missing ''type'' keyword.' summary: Malformed JSON Schema description: JSON Schema is malformed, uses unsupported features, or exceeds limits. '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: id: null code: 429 error: too_many_requests detail: Too many requests. Please try again later. doc_url: https://developers.lighton.ai/errors#too_many_requests summary: Too Many Requests description: Too many requests '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/extract/{job_id}: get: operationId: api_v3_extract_retrieve description: |- Poll for the status and result of an async extract job submitted via `POST /api/v3/extract` with `options.async=true`. Returns the same envelope shape as the synchronous extract endpoint once `status` is `completed`. ```bash curl https://api.lighton.ai/api/v3/extract/ext_0196e4b2a3c14d5e \ -H 'Authorization: Bearer $TOKEN' ``` **Pagination:** when completed, `result.data` is paginated with a fixed page size of 15. Use the `page` query param (1-based) to navigate; `result.pagination` reports `total_items`, `total_pages`, `has_next`, `has_prev`. **Recommended polling cadence:** 1s for the first 10s, then 5s, capped at 30s. Stop polling once `status` is in `{completed, failed}`. summary: Get the status and result of an async extract job parameters: - in: path name: job_id schema: type: string required: true - in: query name: page schema: type: integer default: 1 description: 1-based page index for navigating `result.data`. Fixed page size of 15 items. An out-of-range page is rejected. tags: - Models security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ExtractJobResponse' examples: CompletedJob: value: id: ext_0196e4b2a3c14d5e8f7a9b2c1d0e3f4a status: completed created_at: '2026-03-31T10:00:00+00:00' completed_at: '2026-03-31T10:00:04+00:00' processing_time_ms: 3200 document: filename: invoice.pdf page_count: 3 file_size_bytes: 245120 mime_type: application/pdf result: data: - invoice_number: INV-2026-001 total: null - invoice_number: null total: 1250.0 - invoice_number: null total: null pagination: page: 1 page_size: 15 total_items: 3 total_pages: 1 has_next: false has_prev: false usage: pages_processed: 3 progress: percentage: 100 pages_processed: 3 summary: Completed job ProcessingJob: value: id: ext_0196e4b2a3c14d5e8f7a9b2c1d0e3f4d status: processing created_at: '2026-03-31T10:00:00+00:00' completed_at: null processing_time_ms: null document: filename: large-report.pdf page_count: 450 file_size_bytes: 5242880 mime_type: application/pdf result: null usage: null progress: percentage: 27 pages_processed: 120 summary: Processing job description: A worker is extracting page-by-page. `progress` is the completion percentage [0, 100] so clients can show a determinate progress bar. Keep polling. PendingJob: value: id: ext_0196e4b2a3c14d5e8f7a9b2c1d0e3f4b status: pending created_at: '2026-03-31T10:00:00+00:00' completed_at: null processing_time_ms: null document: filename: large-report.pdf page_count: null file_size_bytes: 5242880 mime_type: application/pdf result: null usage: null progress: null summary: Pending job FailedJob: value: id: ext_0196e4b2a3c14d5e8f7a9b2c1d0e3f4c status: failed created_at: '2026-03-31T10:00:00+00:00' completed_at: '2026-03-31T10:00:05+00:00' processing_time_ms: null document: filename: corrupted.pdf page_count: null file_size_bytes: 102400 mime_type: application/pdf result: null usage: null progress: null summary: Failed job description: Extract job status (pending, processing, completed, or failed). '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/ocr: post: operationId: api_v3_ocr_create description: |- **Deprecated: Use the v3 parse endpoint instead.** Upload a file for synchronous OCR processing. This endpoint is intended for lightweight, low-volume document parsing and returns results inline in the response. For large documents, high-throughput workloads, or asynchronous processing, use the `/files` endpoints, which are optimized for those use cases. **Supported file types:** `.pdf`, `.png`, `.jpg`, `.jpeg`, `.pptx`, `.ppt`, `.odp`, `.docx`, `.odt`, `.doc`, `.html` A maximum of **16 pages** are processed per request. For documents exceeding this limit, split the content across multiple sequential calls using the `pages` parameter (e.g., `pages="1-16"` for the first call, `pages="17-32"` for the second). **Concurrency limit:** Only one OCR request per user can run at a time. A second concurrent request will be rejected with a `429` status. summary: Parse a document to Markdown via VLM tags: - Models requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/OcrRequest' examples: ParseAPDFWithAPageRange: value: file: (binary) pages: 1-16 summary: Parse a PDF with a page range description: Upload a PDF and parse the first 16 pages. PaginateALargeDocument(secondChunk): value: file: (binary) pages: 17-32 summary: Paginate a large document (second chunk) description: Parse pages 17-32 of a large document. Combine with a first call using pages=1-16. ParseSpecificPagesWithCustomModel: value: file: (binary) model: LightOnOCR pages: 1-10,15,20 enable_antilooping: true temperature: 0.2 max_tokens: 5888 summary: Parse specific pages with custom model description: Upload a file with a specific model and custom sampling parameters. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/OcrRequest' required: true security: - bearerAuth: [] deprecated: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/OcrResponse' examples: SuccessfulOCRResponse: value: model: LightOnOCR total_pages: 3 pages_parsed: - 1 - 2 - 3 processing_time_ms: 4520 enable_antilooping: true sampling_params: temperature: 0.2 max_tokens: 5888 repetition_penalty: null pages: - index: 1 markdown: |- # Invoice | Item | Qty | Price | |---|---|---| | Widget A | 10 | $5.00 | - index: 2 markdown: |- ## Terms and Conditions Payment is due within 30 days... - index: 3 markdown: |- ## Appendix ![Figure 1: Sales chart summary] summary: Successful OCR response description: Document parsed successfully. '400': description: Bad request — unsupported document format or max pages exceeded. '401': description: Authentication credentials were not provided or are invalid. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '429': description: Only one OCR request per user can run at a time. Wait for the current request to complete before submitting another. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/parse: post: operationId: api_v3_parse_create description: |- Convert a document into readable, structured Markdown content. Accepts either a **file upload** (multipart/form-data) or a **document URL** (JSON body). ### Sync mode (default) Blocks until parsing completes and returns **200** with the full markdown result. ```bash curl -X POST https://api.lighton.ai/api/v3/parse \ -H 'Authorization: Bearer $TOKEN' \ -F file=@invoice.pdf ``` ### Async mode (`options.async = true`) Returns **202** immediately with a `parse_` job id. Poll `GET /api/v3/parse/{id}` with that same id until `status` is `completed` or `failed`. ```bash curl -X POST https://api.lighton.ai/api/v3/parse \ -H 'Authorization: Bearer $TOKEN' \ -H 'Content-Type: application/json' \ -d '{"document": "https://example.com/report.pdf", "options": {"async": true}}' ``` For multipart uploads, pass `options` as a JSON-encoded form field: `-F 'options={"async":true}'`. **Supported file types:** `.pdf`, `.png`, `.jpg`, `.jpeg`, `.pptx`, `.ppt`, `.odp`, `.docx`, `.odt`, `.doc`, `.html` **Sync limits:** 20 MB file size, 15 pages. **Async limits:** 100 MB file size, 1000 pages. summary: Parse a document to Markdown tags: - Models requestBody: content: application/json: schema: $ref: '#/components/schemas/ParseJsonRequest' examples: Sync—DocumentURL: value: document: https://example.com/invoice.pdf summary: Sync — document URL description: Provide a publicly accessible document URL. Returns 200 with the markdown result. Async—DocumentURL: value: document: https://example.com/report.pdf options: async: true summary: Async — document URL description: Async variant of the URL-based request. Set `options.async=true` in the JSON body. multipart/form-data: schema: $ref: '#/components/schemas/ParseMultipartRequest' examples: Sync—FileUpload: value: file: (binary) summary: Sync — file upload description: Upload a PDF directly for synchronous parsing. Returns 200 with the markdown result. Async—FileUpload: value: file: (binary) options: '{"async": true}' summary: Async — file upload description: Queue the document by setting `options.async=true`. For multipart, pass `options` as a JSON-encoded form field. Response is 202 with a `parse_` job id to poll. required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ParseResponse' examples: Sync—Completed: value: id: parse_0196e4b2a3c14d5e8f7a9b2c1d0e3f4a status: completed created_at: '2026-03-31T10:00:00+00:00' completed_at: '2026-03-31T10:00:03+00:00' processing_time_ms: 2840 document: filename: invoice.pdf page_count: 3 file_size_bytes: 245120 mime_type: application/pdf result: pages: - index: 1 markdown: |- # Invoice Invoice Number: INV-2026-001 Date: March 15, 2026 - index: 2 markdown: |- ## Terms Payment is due within 30 days... - index: 3 markdown: |- ## Appendix Line items continued... usage: pages_processed: 3 summary: Sync — completed description: Returned by the default (sync) path. Body contains the full markdown result. description: Sync parse — document parsed successfully. '202': content: application/json: schema: $ref: '#/components/schemas/ParseAsyncResponse' examples: Async—Accepted: value: id: parse_Kg status: pending created_at: '2026-03-31T10:00:00+00:00' summary: Async — accepted description: Returned when `options.async=true` is set. `id` is the token to poll with. description: Async parse — job accepted. Poll `GET /api/v3/parse/{id}` with the returned `id` until `status` is `completed` or `failed`. '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: PageLimitExceeded: value: id: null code: 400 error: max_pages_exceeded detail: Document has 1200 pages, exceeding the async limit of 1000 pages. doc_url: https://developers.lighton.ai/errors#max_pages_exceeded summary: Page limit exceeded description: Bad request — unsupported format, or page limit exceeded (15 pages sync / 1000 pages async). '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: MissingDocument: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: document: - error: required detail: A file upload or document URL is required. summary: Missing document description: Validation error — missing document, both a file and a URL provided, or an invalid document URL. '413': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: PayloadTooLarge: value: id: null code: 413 error: payload_too_large detail: File size (157286400 bytes) exceeds the 100MB async limit. doc_url: https://developers.lighton.ai/errors/payload_too_large summary: Payload too large description: File exceeds the size limit (20 MB sync / 100 MB async). '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: id: null code: 429 error: too_many_requests detail: Too many requests. Please try again later. doc_url: https://developers.lighton.ai/errors#too_many_requests summary: Too Many Requests description: Too many requests '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/parse/{id}: get: operationId: api_v3_parse_retrieve description: |- Poll for the status and result of an async parse job submitted via `POST /api/v3/parse` with `options.async=true`. Returns the same envelope shape as the synchronous parse endpoint once `status` is `completed`. ```bash curl https://api.lighton.ai/api/v3/parse/parse_Kg \ -H 'Authorization: Bearer $TOKEN' ``` **Recommended polling cadence:** 1s for the first 10s, then 5s, capped at 30s. Stop polling once `status` is in `{completed, failed}`. summary: Get the status and result of an async parse job parameters: - in: path name: id schema: type: string description: Public parse job id (e.g. `parse_Kg`) returned by `POST /api/v3/parse` with `options.async=true`. Malformed or unknown tokens return 404. required: true examples: AsyncJobId: value: parse_Kg summary: Async job id tags: - Models security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ParseJobStatus' examples: Pending—JustSubmitted: value: id: parse_Kg status: pending created_at: '2026-03-31T10:00:00+00:00' completed_at: null processing_time_ms: null document: filename: report.pdf page_count: null file_size_bytes: 245120 mime_type: application/pdf result: null usage: null progress: null error: null summary: Pending — just submitted description: Returned immediately after the 202; the job has not been picked up yet. Processing—InFlight: value: id: parse_Kg status: processing created_at: '2026-03-31T10:00:00+00:00' completed_at: null processing_time_ms: null document: filename: report.pdf page_count: null file_size_bytes: 245120 mime_type: application/pdf result: null usage: null progress: percentage: 27 pages_processed: 120 error: null summary: Processing — in flight description: A worker has picked up the job. `progress` reports pages parsed so far and the completion `percentage` [0, 100] so clients can show a determinate progress bar. Keep polling. Completed—TerminalSuccess: value: id: parse_Kg status: completed created_at: '2026-03-31T10:00:00+00:00' completed_at: '2026-03-31T10:00:18+00:00' processing_time_ms: 18420 document: filename: report.pdf page_count: 3 file_size_bytes: 245120 mime_type: application/pdf result: pages: - index: 1 markdown: |- # Report ... - index: 2 markdown: |- ## Section 2 ... - index: 3 markdown: |- ## Section 3 ... usage: pages_processed: 3 progress: percentage: 100 pages_processed: 3 error: null summary: Completed — terminal success description: Terminal success. `result.pages` and `usage.pages_processed` are populated; stop polling. Failed—TerminalFailure: value: id: parse_Kg status: failed created_at: '2026-03-31T10:00:00+00:00' completed_at: '2026-03-31T10:00:08+00:00' processing_time_ms: 5120 document: filename: report.pdf page_count: null file_size_bytes: 245120 mime_type: application/pdf result: null usage: null progress: null error: message: Parsing failed. summary: Failed — terminal failure description: Terminal failure. `error.message` carries the failure reason; stop polling. description: Async parse job status and (once terminal) result. `status` is `pending`/`processing` while in flight, `completed` on success, `failed` on failure. The `result` and `usage` blocks are populated only on success; the `error` block is populated only on failure. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: id: null code: 429 error: too_many_requests detail: Too many requests. Please try again later. doc_url: https://developers.lighton.ai/errors#too_many_requests summary: Too Many Requests description: Too many requests '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/preview: post: operationId: api_v3_preview_create description: |- Convert a document into a PDF suitable for inline preview. Accepts a **file upload** (multipart/form-data), a **document URL**, or a **file_id** referencing a document already ingested in the platform (JSON body). The conversion is synchronous — the PDF bytes are returned directly. **Supported file types:** `.pdf`, `.png`, `.jpg`, `.jpeg`, `.pptx`, `.ppt`, `.odp`, `.docx`, `.odt`, `.doc`, `.html`, `.xhtml` **Size limit:** 20 MB. summary: Render a document as PDF tags: - Models requestBody: content: multipart/form-data: schema: multipart/form-data: type: object properties: file: type: string format: binary description: The document to convert. application/json: type: object properties: document: type: string format: uri description: Publicly accessible URL of the document to convert. file_id: type: integer description: ID of a document already ingested in the platform. Mutually exclusive with `document`. examples: RenderAPDFViaFileUpload: value: file: (binary) summary: Render a PDF via file upload description: Upload a document file directly for synchronous PDF rendering. application/x-www-form-urlencoded: schema: multipart/form-data: type: object properties: file: type: string format: binary description: The document to convert. application/json: type: object properties: document: type: string format: uri description: Publicly accessible URL of the document to convert. file_id: type: integer description: ID of a document already ingested in the platform. Mutually exclusive with `document`. application/json: schema: multipart/form-data: type: object properties: file: type: string format: binary description: The document to convert. application/json: type: object properties: document: type: string format: uri description: Publicly accessible URL of the document to convert. file_id: type: integer description: ID of a document already ingested in the platform. Mutually exclusive with `document`. examples: RenderADocumentViaURL: value: document: https://example.com/report.docx summary: Render a document via URL description: Provide a publicly accessible document URL. RenderAnIngestedDocumentByID: value: file_id: 42 summary: Render an ingested document by ID description: Reference a document already ingested in the platform. security: - bearerAuth: [] responses: '200': description: PDF rendered successfully. Response body is the raw PDF bytes. '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: UnsupportedFormat: value: id: null code: 400 error: unsupported_format detail: Unsupported document format. doc_url: https://developers.lighton.ai/errors#unsupported_format summary: Unsupported format description: Bad request — missing document, unsupported format, or invalid URL. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '413': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: PayloadTooLarge: value: id: null code: 413 error: payload_too_large detail: File exceeds the 20 MB size limit. doc_url: https://developers.lighton.ai/errors#payload_too_large summary: Payload too large description: File exceeds the 20 MB size limit. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: ConversionFailed: value: id: null code: 422 error: validation_error detail: Conversion failed — corrupt file or LibreOffice error. doc_url: https://developers.lighton.ai/errors#validation_error summary: Conversion failed description: Conversion failed — corrupt file or LibreOffice error. '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: id: null code: 429 error: too_many_requests detail: Too many requests. Please try again later. doc_url: https://developers.lighton.ai/errors#too_many_requests summary: Too Many Requests description: Too many requests '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/mcp: get: operationId: api_v3_mcp_list description: List MCP servers available to the authenticated user (servers only; tools are not included). summary: List MCP servers parameters: - in: query name: company_id schema: type: integer description: Optional company to filter MCP server availability. Only allowed for users with instance-level permissions to view MCP servers. - in: query name: is_global schema: type: boolean description: Optional filter by global servers (true) vs company-scoped servers (false). tags: - MCP security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/MCPServerListResponse' description: '' '401': description: Unauthorized '403': description: Insufficient permissions '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_mcp_create description: | Create a new MCP server scoped to the authenticated user's personal group. The server is automatically linked to the user's company and personal group — users cannot create servers for other companies or groups. `authentication_method` determines how the server authenticates requests. Possible values: - `none`: no authentication required - `url`: credentials are appended to the `url` as the `apiKey` query parameter - `bearer_token`: credentials are sent as a Bearer token in the Authorization header (provide the token in the `credentials` field) summary: Create MCP server tags: - MCP requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateMCPServerRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateMCPServerRequest' multipart/form-data: schema: $ref: '#/components/schemas/CreateMCPServerRequest' required: true security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/MCPServerResponse' description: '' '400': description: Invalid request data '401': description: Unauthorized '403': description: No personal group or company found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/mcp/{id}: get: operationId: api_v3_mcp_retrieve description: Get details of a specific MCP server. URL is redacted unless user has secret read permissions. summary: Get MCP server details parameters: - in: path name: id schema: type: string format: uuid required: true tags: - MCP security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/MCPServerResponse' description: '' '401': description: Unauthorized '403': description: Insufficient permissions '404': description: MCP server not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_mcp_partial_update description: | Update an existing MCP server. All fields are optional. `authentication_method` determines how the server authenticates requests. Possible values: - `none`: no authentication required - `url`: credentials are appended to the `url` as the `apiKey` query parameter - `bearer_token`: credentials are sent as a Bearer token in the Authorization header (provide the token in the `credentials` field) summary: Update MCP server parameters: - in: path name: id schema: type: string format: uuid required: true tags: - MCP requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedUpdateMCPServerRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedUpdateMCPServerRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedUpdateMCPServerRequest' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/MCPServerResponse' description: '' '400': description: Invalid request data '401': description: Unauthorized '403': description: Insufficient permissions '404': description: MCP server not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_mcp_destroy description: Delete an MCP server. This will remove it from all agents using it. summary: Delete MCP server parameters: - in: path name: id schema: type: string format: uuid required: true tags: - MCP security: - bearerAuth: [] responses: '200': description: MCP server deleted successfully '401': description: Unauthorized '403': description: Insufficient permissions '404': description: MCP server not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/mcp/{id}/tools: get: operationId: api_v3_mcp_tools_list description: Returns the tools registered for a specific MCP server. Returns 403 if the server does not exist or is not accessible. summary: List tools for an MCP server parameters: - in: path name: id schema: type: string description: UUID of the MCP server required: true tags: - MCP security: - bearerAuth: [] responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/ToolResponse' description: '' '401': description: Unauthorized '403': description: MCP server not found or insufficient permissions '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/sources: get: operationId: api_v3_sources_retrieve description: Unified endpoint to list document and web sources with filtering. summary: List or retrieve sources parameters: - in: query name: id schema: type: string description: Unique identifier of the source - in: query name: page schema: type: integer description: Page number for pagination - in: query name: per_page schema: type: integer description: 'Items per page (default: 20, max: 100)' - in: query name: source_type schema: type: string description: 'Filter by source type: "document" or "web"' - in: query name: thread_id schema: type: string description: Filter by thread ID; verifies the source belongs to the thread - in: query name: tool_call_id schema: type: string description: Filter by tool call ID; verifies the source belongs to the tool call - in: query name: turn_id schema: type: string description: Filter by turn ID; verifies the source belongs to the turn tags: - Sources security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/SourcesResponse' description: '' '401': description: Unauthorized '403': description: Insufficient permissions to access agent '404': description: Source not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/artifacts/{id}: get: operationId: api_v3_artifacts_retrieve description: Retrieve an artifact by ID. summary: Retrieve an artifact parameters: - in: path name: id schema: type: string required: true tags: - Artifacts security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileArtifact' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/artifacts/{id}/content: get: operationId: api_v3_artifacts_content_retrieve description: Get the content of an artifact. Returns the file content if the user is authorized to access it. summary: Retrieve an artifact content parameters: - in: path name: id schema: type: string required: true tags: - Artifacts security: - bearerAuth: [] responses: '200': content: application/json: schema: type: string format: binary description: File content description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/agent/chat_settings/{id}/tools: get: operationId: api_v3_agent_chat_settings_tools_retrieve description: |- Get available native tools and MCP servers with their tools for a given chat setting ID. DEPRECATION WARNING: `chat_settings` are now becoming `agents`, please use the `agents` endpoint. summary: List agent tools and MCP servers for a chat setting parameters: - in: path name: id schema: type: string description: ID of the chat setting to fetch tools for required: true tags: - Agent security: - bearerAuth: [] deprecated: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ToolListResponse' description: '' '404': content: application/json: schema: description: Chat setting not found or not accessible description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/files: get: operationId: api_v3_files_list description: |- Retrieve a paginated list of files (documents) accessible to the authenticated user. Results are ordered by upload date (newest first) by default. When using the `search` parameter, results are ordered by relevance. **Public datasets:** instance admins (holding `MANAGE_PUBLIC_DATASET`) always see public-dataset files. A company that has opted in (`allow_access_to_public_datasets`) with a workspace-scoped API key granting a public workspace also sees its files — filter with `workspace_id` to scope the list to it. summary: List files accessible to the authenticated user parameters: - in: query name: attribute schema: type: string description: '[Facet] Filter by attribute value. **Repeated `attribute` entries are ANDed; values inside one entry are ORed with `|`** (pipe is the recommended OR delimiter — comma also works but can be ambiguous with multi-key values). Example: `attribute=fiscal_year:2024|2025&attribute=status:active` → (fiscal_year 2024 OR 2025) AND (status active). Formats: `name` (has any value), `name:value` (exact), `name:>value` / `name:>=value` (gt/gte), `name:2024-01-01 summary: Date lower bound DateYearFilter: value: filing_date:2023 summary: Date year filter DateYear-monthFilter: value: filing_date:2023-06 summary: Date year-month filter NumericLowerBound: value: contract_value:>50000 summary: Numeric lower bound Multi-selectMembership: value: jurisdiction:FR summary: Multi-select membership Multi-selectOR: value: jurisdiction:FR|US summary: Multi-select OR ScopedToContentType: value: content_type(legal:compliance).regulation:AML summary: Scoped to content type AND-of-ORs(repeatParam): value: fiscal_year:2024|2025 summary: AND-of-ORs (repeat param) description: Repeat attribute for AND logic across different attributes. Each param's values are ORed. Use pipe (|) as the OR delimiter to avoid ambiguity with comma. - in: query name: content_type schema: type: string description: '[Facet] Filter by content type path. Multiple values are OR. Exact-or-subtree matching by default (e.g. `legal` matches legal, legal:contract). Wildcards: `*contract*` (contains), `legal:contract*` (prefix).' examples: EmptySample: value: '' summary: Empty sample LegalNDASample: value: legal:contract:nda summary: Legal NDA sample TechDesignDocSample: value: tech:specification:design-doc summary: Tech design doc sample BothSampleRecords: value: legal:contract:nda,tech:specification:design-doc summary: Both sample records ContainsContract: value: '*contract*' summary: Contains contract TechSpecificationSubtree: value: tech:specification* summary: Tech specification subtree - in: query name: created_at_after schema: type: string format: date-time description: Filter by created_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?created_at_after=2024-01-01&created_at_before=2024-01-01T23:59:59) - in: query name: created_at_before schema: type: string format: date-time description: Filter by created_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?created_at_after=2024-01-01&created_at_before=2024-01-01T23:59:59) - in: query name: extension schema: type: string description: Filter by file extensions (comma-separated, e.g., ?extension=pdf,docx) - in: query name: external_metadata__doc_type schema: type: string description: 'Filter by external document type (case-insensitive partial match). Only returns documents that have external metadata. Example: ?external_metadata__doc_type=gitlab matches ''gitlab issue'', ''gitlab ticket'', ''Gitlab MR'', etc.' - in: query name: external_metadata__external_id schema: type: string description: 'Filter by external document ID (exact match). Matches the doc_id stored in the document''s external metadata. Only returns documents that have external metadata. Example: ?external_metadata__external_id=SN-12345' - in: query name: filename schema: type: string description: Filter by filename (case-insensitive partial match) - in: query name: group_id schema: type: string description: Filter by group IDs (comma-separated, e.g., ?group_id=1,2,3) - in: query name: include_details schema: type: boolean description: 'Include detail fields (e.g., TLSH signature, parser, summaries, and content type attribute values). Default: false.' - in: query name: max_documents schema: type: integer description: 'Maximum number of documents to return (default: 50, minimum: 1, maximum: 500)' - in: query name: ordering schema: type: string description: 'Sort results by field. Prefix with ''-'' for descending order. Allowed fields: created_at, filename, title, total_pages, size. Default: -created_at (newest first). Ignored when ''search'' is provided (results ordered by relevance).' - in: query name: owner_id schema: type: string description: Filter by owner user IDs (comma-separated, e.g., ?owner_id=1,2,3) - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer - in: query name: search schema: type: string description: Semantic search query. When provided, results are ordered by combined retrieval score descending. No relevance scoring is applied — scores.relevance is always null in search_details chunks. - in: query name: search_details schema: type: boolean description: When true (and search is provided), include top relevant chunk(s) per document. - in: query name: search_details_chunks_limit schema: type: integer description: 'Max number of relevant chunks to return per document when search_details=true (1-10, default: 3).' - in: query name: status schema: type: string enum: - converting - embedded - embedding - embedding_failed - fail - parsed - parsing - parsing_failed - pending - pending_conversion - updating description: Filter by status values (comma-separated, e.g., ?status=pending,embedded) - in: query name: status_vision schema: type: string enum: - '-' - embedded - fail - pending - processing description: Filter by vision status values (comma-separated, e.g., ?status_vision=pending,embedded) - in: query name: tag_id schema: type: string description: Filter by tag IDs (comma-separated, e.g., ?tag_id=1,2,3) - in: query name: title schema: type: string description: Filter by title (case-insensitive partial match) - in: query name: total_pages_max schema: type: - integer - 'null' maximum: 2147483647 minimum: -2147483648 description: Filter by total pages range (e.g., ?total_pages_min=10&total_pages_max=50) - in: query name: total_pages_min schema: type: - integer - 'null' maximum: 2147483647 minimum: -2147483648 description: Filter by total pages range (e.g., ?total_pages_min=10&total_pages_max=50) - in: query name: updated_at_after schema: type: string format: date-time description: Filter by updated_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?updated_at_after=2024-01-01&updated_at_before=2024-01-01T23:59:59) - in: query name: updated_at_before schema: type: string format: date-time description: Filter by updated_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?updated_at_after=2024-01-01&updated_at_before=2024-01-01T23:59:59) - in: query name: upload_session_uuid schema: type: string description: Filter by upload session UUID (e.g., ?upload_session_uuid=123e4567-e89b-12d3-a456-426614174000) - in: query name: workspace_id schema: type: string description: Filter by workspace IDs (comma-separated, e.g., ?workspace_id=1,2,3) tags: - Files security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedFileListResponseSerializerV3List' examples: DefaultCompactResponse: value: count: 123 next: http://api.example.org/accounts/?page=4 previous: http://api.example.org/accounts/?page=2 results: - - id: 124 filename: customer_nda.pdf workspace: id: 3 name: Legal Team workspace_type: shared summaries: [] title: Customer NDA extension: pdf status: embedded status_vision: embedded created_at: '2024-01-14T14:20:00Z' updated_at: '2024-01-14T14:22:00Z' total_pages: 8 tags: - id: 7 name: confidential auto_assigned: true - id: 12 name: Q1-2026 auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe external_metadata: external_id: legal-doc-456789 doc_type: nda additional_metadata: external_url: https://contracts.example.com/legal/customer-nda content_types: - path: legal:contract:nda label: Non-Disclosure Agreement thumbnail: status: READY url: /api/v3/files/124/thumbnail - id: 123 filename: design_doc.pdf workspace: id: 1 name: Engineering Team workspace_type: shared summaries: - language: en summary: This document outlines Q4 initiatives... title: Retrieval Service Design Document extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:35:00Z' total_pages: 25 size: 2458624 tags: - id: 10 name: Project X auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe content_types: [] thumbnail: status: READY url: /api/v3/files/123/thumbnail summary: Default compact response description: Compact content types (path and label only — no attribute values). Null fields omitted. WithIncludeDetails=true(mid-expanded): value: count: 123 next: http://api.example.org/accounts/?page=4 previous: http://api.example.org/accounts/?page=2 results: - - id: 124 filename: customer_nda.pdf workspace: id: 3 name: Legal Team workspace_type: custom summaries: - language: en summary: Non-disclosure agreement between LightOn and Nimbus Labs. title: Customer NDA extension: pdf status: embedded status_vision: embedded created_at: '2024-01-14T14:20:00Z' updated_at: '2024-01-14T14:22:00Z' total_pages: 8 tags: - id: 7 name: confidential auto_assigned: true - id: 12 name: Q1-2026 auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2 parser: v2.2.1 content_types: - code: nda path: legal:contract:nda label: Non-Disclosure Agreement breadcrumb: - code: legal path: legal label: Legal - code: contract path: legal:contract label: Contract - code: nda path: legal:contract:nda label: Non-Disclosure Agreement attribute_values: jurisdiction: value: - FR - US type: multi-select label: Jurisdiction is_mutual: value: true type: boolean label: Is Mutual summary: With include_details=true (mid-expanded) description: Adds summaries, signature, parser. Content types gain code, structured breadcrumb (ancestor chain with code/path/label per node), and attribute values. Attribute values use compact format (no schema metadata). WithSearch+SearchDetails=true: value: count: 123 next: http://api.example.org/accounts/?page=4 previous: http://api.example.org/accounts/?page=2 results: - - id: 123 filename: design_doc.pdf workspace: id: 1 name: Engineering Team workspace_type: shared summaries: - language: en summary: This document outlines Q4 initiatives... title: Retrieval Service Design Document extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:35:00Z' total_pages: 25 size: 2458624 tags: - id: 10 name: Project X auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe content_types: - path: tech:specification:design-doc label: Design Document search_details: relevant_chunks: - text: This paragraph is a representative excerpt of the highest-ranked chunk. chunk_type: text score: 1.84 scores: text: 0.82 vision: null keyword: 0.71 multivector: 0.6 relevance: null summary: With search + search_details=true description: When search is active with search_details=true, each file includes relevant chunks. ListOfFiles(withIncludeDetails=true): value: count: 123 next: http://api.example.org/accounts/?page=4 previous: http://api.example.org/accounts/?page=2 results: - - id: 123 filename: design_doc.pdf workspace: id: 1 name: Engineering Team workspace_type: shared summaries: - language: en summary: This document outlines Q4 initiatives... title: Retrieval Service Design Document extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:35:00Z' total_pages: 25 size: 2458624 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2 parser: v2.2.1 content_types: - path: tech:specification:design-doc label: Design Document attributes: - name: owner_team label: Owner Team value: Platform Engineering type: text - name: maturity label: Maturity value: Approved type: select - name: component label: Component value: Document Retrieval Service type: text - id: 124 filename: customer_nda.pdf workspace: id: 3 name: Legal Team workspace_type: shared summaries: [] title: Customer NDA extension: pdf status: embedded status_vision: embedded created_at: '2024-01-14T14:20:00Z' updated_at: '2024-01-14T14:22:00Z' total_pages: 8 tags: [] created_by: id: 43 first_name: John last_name: Smith username: jsmith signature: T1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2G3 parser: v2.2.1 content_types: - path: legal:contract:nda label: Non-Disclosure Agreement attributes: - name: jurisdiction label: Jurisdiction value: - FR - US type: multi_select - name: confidentiality_level label: Confidentiality Level value: Confidential type: select - name: parties label: Parties value: LightOn, Nimbus Labs type: text - name: contract_status label: Contract Status value: Executed type: select - name: counterparty label: Counterparty value: Nimbus Labs type: text - name: is_mutual label: Is Mutual value: true type: boolean summary: List of files (with include_details=true) description: List of files accessible to the authenticated user '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: id: null code: 429 error: too_many_requests detail: Too many requests. Please try again later. doc_url: https://developers.lighton.ai/errors#too_many_requests summary: Too Many Requests description: Too many requests '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_files_create description: |+ Upload a file to a workspace. Files are added to an upload session and queued for asynchronous processing. To track progress, retrieve the file details using the GET endpoints to check the current status. **Idempotent upload:** When `external_metadata.external_id` is provided and a manually-uploaded document with the same external ID already exists in the target workspace, the existing document is returned with `200 OK` instead of creating a duplicate. This makes bulk re-runs safe without requiring a pre-check. Datasource-imported documents are not affected. **Accepted file formats:** `csv`, `doc`, `docx`, `htm`, `html`, `jpeg`, `jpg`, `md`, `odp`, `odt`, `pdf`, `png`, `ppt`, `pptx`, `txt`, `xhtml`, `xls`, `xlsx` **Customization Options:** - `title`: Customize the document title (defaults to filename without extension) - `filename`: Override the uploaded filename - `parser`: Specify a custom ingestion pipeline instead of using the default summary: Upload a file tags: - Files requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/FileCreateRequestSerializerV3' examples: BasicFileUpload: value: file: (binary file data) workspace_id: 42 summary: Basic file upload description: Upload a PDF file with only required fields FileUploadWithCustomMetadataAndTags: value: file: (binary file data) workspace_id: 42 filename: Q4_Report_2025.pdf title: Q4 Financial Report tags: - 1 - 2 summary: File upload with custom metadata and tags description: 'Upload a file with custom filename, title, and manual tag assignment. Tags can be sent as a JSON array string (e.g., ''[1,2]'') or as multiple form fields with the same name. ' IdempotentUploadWithExternalId: value: file: (binary file data) workspace_id: 42 external_metadata: external_id: hupd:13144833 summary: Idempotent upload with external_id description: Upload with `external_id` for idempotent re-runs. If a manually-uploaded document with the same `external_id` already exists in the workspace, the server returns 200 OK with the existing document instead of creating a duplicate. Datasource-imported documents are not affected — idempotency is scoped to manual uploads only. FileUploadWithExternalMetadata: value: file: (binary file data) workspace_id: 42 external_metadata: external_id: SRV-456789 doc_type: incident additional_metadata: external_url: https://servicenow.example.com/incident/SRV-456789 external_full_path: ServiceNow > Incidents > SRV-456789 created_at: '2024-01-10T08:00:00Z' modified_at: '2024-01-12T16:45:00Z' summary: File upload with external metadata description: Upload a file that originates from an external system (e.g. ServiceNow, SharePoint). `external_metadata` must be sent as a JSON string when using multipart/form-data. `external_id` is required; `doc_type` and `additional_metadata` are optional. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/FileCreateRequestSerializerV3' examples: BasicFileUpload: value: file: (binary file data) workspace_id: 42 summary: Basic file upload description: Upload a PDF file with only required fields FileUploadWithCustomMetadataAndTags: value: file: (binary file data) workspace_id: 42 filename: Q4_Report_2025.pdf title: Q4 Financial Report tags: - 1 - 2 summary: File upload with custom metadata and tags description: 'Upload a file with custom filename, title, and manual tag assignment. Tags can be sent as a JSON array string (e.g., ''[1,2]'') or as multiple form fields with the same name. ' IdempotentUploadWithExternalId: value: file: (binary file data) workspace_id: 42 external_metadata: external_id: hupd:13144833 summary: Idempotent upload with external_id description: Upload with `external_id` for idempotent re-runs. If a manually-uploaded document with the same `external_id` already exists in the workspace, the server returns 200 OK with the existing document instead of creating a duplicate. Datasource-imported documents are not affected — idempotency is scoped to manual uploads only. FileUploadWithExternalMetadata: value: file: (binary file data) workspace_id: 42 external_metadata: external_id: SRV-456789 doc_type: incident additional_metadata: external_url: https://servicenow.example.com/incident/SRV-456789 external_full_path: ServiceNow > Incidents > SRV-456789 created_at: '2024-01-10T08:00:00Z' modified_at: '2024-01-12T16:45:00Z' summary: File upload with external metadata description: Upload a file that originates from an external system (e.g. ServiceNow, SharePoint). `external_metadata` must be sent as a JSON string when using multipart/form-data. `external_id` is required; `doc_type` and `additional_metadata` are optional. required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileCreateResponseSerializerV3' examples: Idempotent—DocumentAlreadyExists: value: id: 12345 filename: 13144833.md workspace: id: 42 name: My Workspace workspace_type: shared title: Patent 13144833 extension: md status: embedded status_vision: null created_at: '2025-03-01T10:30:00Z' updated_at: '2025-03-01T10:30:00Z' total_pages: 3 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe upload_session_uuid: null external_metadata: external_id: hupd:13144833 doc_type: '' additional_metadata: {} message: Document already exists (idempotent) summary: Idempotent — document already exists description: The document with this external_id was already uploaded to this workspace. No new document is created. The response body is identical to a normal upload response. description: Document already exists (idempotent). Returned when `external_metadata.external_id` matches a manually-uploaded document in the same workspace. The existing document is returned without creating a duplicate. '201': content: application/json: schema: $ref: '#/components/schemas/FileCreateResponseSerializerV3' examples: FileUploadedSuccessfully: value: id: 12345 filename: document.pdf workspace: id: 42 name: My Workspace workspace_type: shared summaries: [] title: document extension: pdf status: pending status_vision: null created_at: '2025-03-01T10:30:00Z' updated_at: '2025-03-01T10:30:00Z' total_pages: 0 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe upload_session_uuid: 550e8400-e29b-41d4-a716-446655440000 external_metadata: null message: File queued for processing thumbnail: status: MISSING url: null summary: File uploaded successfully FileUploadedWithTags: value: id: 12346 filename: compliance_doc.pdf workspace: id: 42 name: My Workspace workspace_type: shared summaries: [] title: Compliance Document extension: pdf status: pending status_vision: null created_at: '2025-03-01T10:35:00Z' updated_at: '2025-03-01T10:35:00Z' total_pages: 0 tags: - id: 1 name: Compliance auto_assigned: false - id: 2 name: Legal auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe upload_session_uuid: 550e8400-e29b-41d4-a716-446655440000 external_metadata: null message: File queued for processing summary: File uploaded with tags FileUploadedWithExternalMetadata: value: id: 12348 filename: SRV-456789.pdf workspace: id: 42 name: My Workspace workspace_type: shared summaries: [] title: SRV-456789 extension: pdf status: pending status_vision: null created_at: '2025-03-01T10:40:00Z' updated_at: '2025-03-01T10:40:00Z' total_pages: 0 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe upload_session_uuid: 550e8400-e29b-41d4-a716-446655440000 external_metadata: external_id: SRV-456789 doc_type: incident additional_metadata: external_url: https://servicenow.example.com/incident/SRV-456789 external_full_path: ServiceNow > Incidents > SRV-456789 message: File queued for processing summary: File uploaded with external metadata description: Upload response when external_metadata was provided. The record is created synchronously and returned immediately. description: File queued for processing successfully '207': content: application/json: schema: $ref: '#/components/schemas/FileCreateResponseSerializerV3' examples: FileUploadedWithTagError: value: id: 12347 filename: document.pdf workspace: id: 42 name: My Workspace workspace_type: shared summaries: [] title: document extension: pdf status: pending status_vision: null created_at: '2025-03-01T10:40:00Z' updated_at: '2025-03-01T10:40:00Z' total_pages: 0 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe upload_session_uuid: 550e8400-e29b-41d4-a716-446655440000 external_metadata: null message: 'Document uploaded successfully, but tag assignment failed: Invalid or unauthorized tag IDs: 999' summary: File uploaded with tag error description: Document uploaded successfully but tags failed to assign description: Document uploaded but tag assignment failed (partial success) '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: StorageLimitReached: value: id: null code: 400 error: STORAGE_LIMIT_REACHED detail: The custom workspace storage limit for your company is 500 MB and you are currently using 487.3 MB. Delete stale documents or ask your company admin to request an increase of your storage quota. doc_url: https://developers.lighton.ai/errors#STORAGE_LIMIT_REACHED summary: Storage limit reached UploadsDisabled: value: id: null code: 400 error: UPLOADS_DISABLED detail: Uploads are disabled for the custom workspace. The storage limit is set to 0 MB. Ask your company admin to request an increase of your storage quota. doc_url: https://developers.lighton.ai/errors#UPLOADS_DISABLED summary: Uploads disabled description: Domain error — the upload exceeds the workspace storage limit or uploads are disabled. The domain code is carried in `error` and the limit/usage in `detail`. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: MissingRequiredField: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: workspace_id: - error: required detail: This field is required. summary: Missing required field InvalidFileType: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: file: - error: invalid detail: File extension not supported. summary: Invalid file type SyncedWorkspace: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: non_field_errors: - error: invalid detail: Cannot manually upload documents to a workspace configured for synced documents. summary: Synced workspace description: Validation error — missing/invalid fields or a synced workspace. Per-field errors in `fields`. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: id: null code: 429 error: too_many_requests detail: Too many requests. Please try again later. doc_url: https://developers.lighton.ai/errors#too_many_requests summary: Too Many Requests description: Too many requests '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/files/bulk-delete: post: operationId: api_v3_files_bulk_delete_create description: |- Permanently delete multiple files in a single request. **Authorization (applied to every file in the request):** - Visibility: file must be accessible to the user → 404 if any are not found - Delete permission: user must have the right to delete each file → 403 if any are denied - Workspace type: workspace must not be sync-managed → 400 if any are synced **Public datasets:** instance admins (`MANAGE_PUBLIC_DATASET`) can bulk-delete public-dataset files. A workspace-scoped API key with read-only access to a public dataset can see the file (so it counts toward visibility) but gets 403 on the delete-permission check — public datasets are read-only for opted-in companies. Returns 204 (No Content) on success. summary: Delete multiple files in a single request tags: - Files requestBody: content: application/json: schema: $ref: '#/components/schemas/FileBulkDeleteRequestSerializerV3' examples: BulkDeleteRequest: value: ids: - 123 - 124 - 125 summary: Bulk delete request required: true security: - bearerAuth: [] responses: '204': description: Files deleted successfully (no content returned) '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: SyncedWorkspace: value: id: null code: 400 error: bad_request detail: Cannot manually delete documents from a workspace configured for synced documents. Documents in this workspace can only be managed through external datasources. doc_url: https://developers.lighton.ai/errors#bad_request summary: Synced workspace description: Synced workspace constraint — documents can only be managed through external datasources. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/files/{id}: get: operationId: api_v3_files_retrieve description: |- Retrieve detailed information for a single file by its ID. Only files that the authenticated user is authorized to access will be returned. Returns 404 if the file does not exist or the user does not have access. Query Parameters: - include_content: Set to 'true' to include the full text content of the document (default: false) The response includes comprehensive document details including: - Basic metadata (id, filename, title, extension, dates, page count) - Full text content of the document (only when include_content=true) - Processing status (status, status_vision, status_detail if failed) - Associated tags and workspace information - File size (if available) - Parser/ingestion pipeline (if available, after parsing starts) - Signature (TLSH hash for duplicate detection) - Facet content types and nested attribute values (full expanded with attribute definitions) **Public datasets:** reachable by instance admins (`MANAGE_PUBLIC_DATASET`) unconditionally, and by a company that has opted in (`allow_access_to_public_datasets`) with a workspace-scoped API key granting the file's public workspace. summary: Retrieve a single file by ID parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this Document. required: true - in: query name: include_content schema: type: boolean description: 'When true, include the full text content of the document in the response (default: false). Recommended to only enable when needed as content can be large.' tags: - Files security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileRetrieveResponseSerializerV3' examples: FileDetail(fullExpanded): value: id: 124 filename: customer_nda.pdf workspace: id: 3 name: Legal Team workspace_type: custom summaries: - language: en summary: Non-disclosure agreement between LightOn and Nimbus Labs. title: Customer NDA extension: pdf status: embedded status_vision: embedded created_at: '2024-01-14T14:20:00Z' updated_at: '2024-01-14T14:22:00Z' total_pages: 8 tags: - id: 7 name: confidential auto_assigned: true - id: 12 name: Q1-2026 auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2 external_metadata: external_id: legal-doc-456789 doc_type: nda additional_metadata: external_url: https://contracts.example.com/legal/customer-nda content_types: - code: nda path: legal:contract:nda label: Non-Disclosure Agreement breadcrumb: - code: legal path: legal label: Legal - code: contract path: legal:contract label: Contract - code: nda path: legal:contract:nda label: Non-Disclosure Agreement attribute_values: jurisdiction: value: - FR - US type: multi-select attribute: name: jurisdiction label: Jurisdiction type: multi-select required: true choices: - FR - US - UK - DE is_mutual: value: true type: boolean attribute: name: is_mutual label: Is Mutual type: boolean required: false counterparty: value: Nimbus Labs type: text attribute: name: counterparty label: Counterparty type: text required: false thumbnail: status: READY url: /api/v3/files/124/thumbnail summary: File detail (full expanded) description: Detail always includes summaries, signature, and full expanded content types with code, breadcrumb, and attribute definitions (type, required, choices). FileDetailWithContent: value: id: 123 filename: design_doc.pdf workspace: id: 1 name: Engineering Team workspace_type: custom summaries: - language: en summary: This document outlines Q4 initiatives... title: Retrieval Service Design Document extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:35:00Z' total_pages: 25 size: 2458624 tags: - id: 10 name: Project X auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2 content: |- Retrieval Service Design Document Overview This document outlines the service architecture, retrieval flow, and implementation decisions... pages: - index: 1 markdown: |- # Retrieval Service Design Document ## Overview ... - index: 2 markdown: |- ## Retrieval flow ... content_types: - code: design-doc path: tech:specification:design-doc label: Design Document breadcrumb: - code: tech path: tech label: Tech - code: specification path: tech:specification label: Specification - code: design-doc path: tech:specification:design-doc label: Design Document attribute_values: maturity: value: Approved type: select label: Maturity attribute: name: maturity label: Maturity type: select required: true choices: - Draft - In Review - Approved - Deprecated owner_team: value: Platform Engineering type: text label: Owner Team attribute: name: owner_team label: Owner Team type: text required: false summary: File detail with content description: With include_content=true, the full document text is included as the flat `content` string and as canonical per-page objects under `pages` (`{ index, markdown }`, the same shape returned by /parse and /ocr). `content` is retained for now; prefer `pages`. description: Detailed file information. Always uses full expanded content types (Tier 3) with breadcrumb, code, and attribute definitions including type, required, and choices. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_files_partial_update description: | Update mutable fields of a file (document). **Updatable fields:** - `title`: Update the document title - `tags`: Replace ALL tags for the document (both manual and auto-assigned) - `external_metadata`: Create or update external source metadata **Tag replacement behavior:** - Providing a tags array replaces ALL existing tags (manual and auto-assigned) - To remove all tags, send `[0]` (sentinel value for multipart format) - Omitting `tags` field leaves tags unchanged - New tags are marked as manually assigned (`auto_assigned=False`) **External metadata behavior:** - When creating for the first time, `external_id` is required - When updating existing metadata, `external_id` is optional (existing value is preserved) - Fields in `additional_metadata` are merged (not replaced) with existing values **Validation:** - Returns 400 if only immutable fields are provided (mutable fields: 'external_metadata', 'tags', 'title') - Returns 400 if tag IDs are invalid or don't belong to user's company - Returns 404 if document doesn't exist or user doesn't have access **Public datasets:** editing a public-dataset file requires the instance-admin `MANAGE_PUBLIC_DATASET` permission. A workspace-scoped API key with read access (company opted in via `allow_access_to_public_datasets`) can see the file but gets 403, not 404, when attempting to edit it — public datasets are read-only. summary: Update file metadata parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this Document. required: true tags: - Files requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/PatchedFileUpdateRequestSerializerV3' examples: UpdateTitleOnly: value: title: Updated Document Title summary: Update title only description: Update only the document title ReplaceAllTags: value: tags: - 1 - 2 summary: Replace all tags description: Replace all existing tags (both manual and auto-assigned) with new ones. Tags can be sent as a JSON array string (e.g., '[1,2]') or as multiple form fields with the same name. RemoveAllTags: value: tags: - 0 summary: Remove all tags description: Remove all tags using sentinel value [0] CreateExternalMetadata: value: external_metadata: external_id: gitlab-issue-456 doc_type: gitlab_issue additional_metadata: external_url: https://gitlab.example.com/project/-/issues/456 name: Fix authentication bug summary: Create external metadata description: Attach external source metadata to a document that has none yet. `external_id` is required for creation. `external_metadata` must be sent as a JSON string when using multipart/form-data. UpdateExistingExternalMetadata: value: external_metadata: additional_metadata: last_synced_at: '2024-01-15T10:00:00Z' name: Updated Name summary: Update existing external metadata description: Update fields on an existing external metadata record. `external_id` is optional when a record already exists — it will be preserved if omitted. Fields inside `additional_metadata` are merged with existing values, not replaced. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedFileUpdateRequestSerializerV3' examples: UpdateTitleOnly: value: title: Updated Document Title summary: Update title only description: Update only the document title ReplaceAllTags: value: tags: - 1 - 2 summary: Replace all tags description: Replace all existing tags (both manual and auto-assigned) with new ones. Tags can be sent as a JSON array string (e.g., '[1,2]') or as multiple form fields with the same name. RemoveAllTags: value: tags: - 0 summary: Remove all tags description: Remove all tags using sentinel value [0] CreateExternalMetadata: value: external_metadata: external_id: gitlab-issue-456 doc_type: gitlab_issue additional_metadata: external_url: https://gitlab.example.com/project/-/issues/456 name: Fix authentication bug summary: Create external metadata description: Attach external source metadata to a document that has none yet. `external_id` is required for creation. `external_metadata` must be sent as a JSON string when using multipart/form-data. UpdateExistingExternalMetadata: value: external_metadata: additional_metadata: last_synced_at: '2024-01-15T10:00:00Z' name: Updated Name summary: Update existing external metadata description: Update fields on an existing external metadata record. `external_id` is optional when a record already exists — it will be preserved if omitted. Fields inside `additional_metadata` are merged with existing values, not replaced. security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileRetrieveResponseSerializerV3' examples: FileUpdatedSuccessfully: value: id: 123 filename: project_proposal.pdf workspace: id: 1 name: Engineering Team summaries: - language: en summary: This document outlines Q4 initiatives... title: Updated Document Title extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T11:45:00Z' total_pages: 25 size: 2458624 tags: - id: 1 name: Compliance auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2 parser: v2.2.1 external_metadata: null content_types: - path: tech:specification:design-doc label: Design Document labels: - Tech - Specification - Design Document attributes: - name: owner_team label: Owner Team value: Platform Engineering type: text - name: maturity label: Maturity value: Approved type: select - name: component label: Component value: Document Retrieval Service type: text summary: File updated successfully FileUpdatedWithExternalMetadata: value: id: 124 filename: customer_nda.pdf workspace: id: 3 name: Legal Team summaries: [] title: Customer NDA extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T11:45:00Z' total_pages: 3 size: 102400 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2 external_metadata: external_id: legal-doc-456789 doc_type: nda additional_metadata: external_url: https://contracts.example.com/legal/customer-nda last_synced_at: '2024-01-15T10:00:00Z' content_types: - path: legal:contract:nda label: Non-Disclosure Agreement labels: - Legal - Contract - Non-Disclosure Agreement attributes: - name: jurisdiction label: Jurisdiction value: - FR - US type: multi-select - name: confidentiality_level label: Confidentiality Level value: Confidential type: select - name: parties label: Parties value: LightOn, Nimbus Labs type: text - name: contract_status label: Contract Status value: Executed type: select - name: counterparty label: Counterparty value: Nimbus Labs type: text - name: is_mutual label: Is Mutual value: true type: boolean summary: File updated with external metadata description: File updated successfully '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_files_destroy description: |- Permanently delete a file and all associated data. **Requirements:** - Delete permission on the document - Workspace must allow manual document management (not sync-only) **Public datasets:** deleting a public-dataset file requires the instance-admin `MANAGE_PUBLIC_DATASET` permission. A workspace-scoped API key with read access (company opted in via `allow_access_to_public_datasets`) can see the file but gets 403, not 404, when attempting to delete it — public datasets are read-only. Returns 204 (No Content) on success. summary: Delete a file parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this Document. required: true tags: - Files security: - bearerAuth: [] responses: '204': description: File deleted successfully (no content returned) '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: SyncedWorkspace: value: id: null code: 400 error: bad_request detail: Cannot manually delete documents from a workspace configured for synced documents. Documents in this workspace can only be managed through external datasources. doc_url: https://developers.lighton.ai/errors#bad_request summary: Synced workspace description: Cannot delete from a synced workspace. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal Server Error description: An unexpected error occurred '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/files/{id}/download: get: operationId: api_v3_files_download_retrieve description: Download a document file. Returns the original file by default. Use the purpose parameter to request a specific version (e.g. rendered_pdf for frontend viewers). summary: Download a document file parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this Document. required: true - in: query name: purpose schema: type: string enum: - original - rendered_pdf - transcript description: Which file version to serve. Defaults to 'original'. Falls back to 'original' if the requested purpose has no associated file. tags: - Files security: - bearerAuth: [] responses: '200': description: Binary file content or sanitized markdown text '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/files/{id}/thumbnail: get: operationId: api_v3_files_thumbnail_retrieve description: 'Returns the 256x256 WebP thumbnail for a document. Thumbnails are generated asynchronously after ingestion completes: poll the `thumbnail.status` field on the file resource and request this endpoint once it reads `READY`.' summary: Get document thumbnail parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this Document. required: true tags: - Files security: - bearerAuth: [] responses: '200': description: WebP thumbnail image stream (`image/webp`) '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/content-types: get: operationId: api_v3_content_types_retrieve description: |- List your classification trees: the content types you've adopted from the starter templates or created from scratch. This is where you see what's available to classify your documents with. **Content types are tree-based.** Each tree is an independent classification hierarchy (e.g., `legal` → `contract` → `nda`). You can have multiple trees side by side (`legal`, `finance`, `compliance`), and a single document can be classified under **multiple trees** simultaneously. For instance, a contract can be both `legal:contract:nda` and `finance:investment:term-sheet`. Each node in the tree can carry **custom attributes** (metadata fields like `jurisdiction`, `effective_date`, `contract_value`). Attributes are inherited down the tree: a document at `legal:contract:nda` gets attributes from all three levels. **New here?** Start by browsing available templates at `GET /api/v3/content-types/templates`, then adopt the ones you need via `POST /api/v3/content-types {"action": "adopt"}`. **Query params:** - `?query=5G antennas`: filter to content types relevant to a search query (uses a first-pass retrieval). Without this param, the full catalog is returned. - `?path=legal`: filter to a specific subtree - `?path=legal,finance`: multiple subtrees (comma-separated) - `?depth=0`: roots only. `?depth=N`: N levels of children. - `?include_attributes=true` (default): include attribute definitions per node - `?include_attributes=false`: omit attribute definitions for a lighter response `query` and `path` can be combined: returns the intersection (only matched content types under the requested paths). Returns an empty list if no content types have been set up yet. summary: List content types parameters: - in: query name: depth schema: type: integer description: Tree depth limit. Omitted = full tree. 0 = roots only. - in: query name: include_attributes schema: type: boolean description: 'Include attribute definitions per content type node. Default: true.' - in: query name: path schema: type: string description: Content type path(s) to filter (comma-separated). - in: query name: query schema: type: string description: When provided, filter the catalog to content types found in a first-pass retrieval for this query. Without this parameter, the full company catalog is returned (existing behavior). tags: - Facets security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ContentTypesListResponse' examples: CompanyContentTypes(default,WithAttributes): value: content_types: - path: legal code: legal label: Legal description: 'Legal documents: contracts, litigation, compliance.' inherit_attributes: true attributes: - name: jurisdiction label: Jurisdiction type: multi-select required: false description: Legal jurisdiction(s) governing the document choices: - FR - US - UK - DE - name: confidentiality_level label: Confidentiality Level type: select required: false description: '' choices: - Public - Internal - Confidential - Strictly Confidential children: - path: legal:contract code: contract label: Contract description: Binding agreements between parties. inherit_attributes: true attributes: - name: jurisdiction label: Jurisdiction type: multi-select required: false description: Legal jurisdiction(s) governing the document choices: - FR - US - UK - DE inherited: true - name: effective_date label: Effective Date type: date required: false description: '' choices: [] children: - path: legal:contract:nda code: nda label: Non-Disclosure Agreement description: '' inherit_attributes: true attributes: - name: jurisdiction label: Jurisdiction type: multi-select required: false description: Legal jurisdiction(s) governing the document choices: - FR - US - UK - DE inherited: true - name: effective_date label: Effective Date type: date required: false description: '' choices: [] inherited: true - name: counterparty label: Counterparty type: text required: true description: Name of the other party choices: [] - name: is_mutual label: Is Mutual type: boolean required: false description: '' choices: [] can_edit: true summary: Company content types (default, with attributes) description: Full tree with attribute definitions per node. Children nested recursively. WithoutAttributes(?includeAttributes=false): value: content_types: - path: legal code: legal label: Legal description: 'Legal documents: contracts, litigation, compliance.' inherit_attributes: true children: - path: legal:contract code: contract label: Contract description: Binding agreements between parties. inherit_attributes: true can_edit: true summary: Without attributes (?include_attributes=false) description: Lighter response, tree structure only, no attribute definitions. description: Company content type tree with optional attribute definitions. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_content_types_create description: |- Create, modify, and organise your company's content-type trees and their attributes. Every action is idempotent, safe to re-run. **Two ways to build your schema:** 1. **Adopt from starter templates**: import ready-made trees from the seed catalog (`GET /api/v3/content-types/templates`). Once adopted, they're yours to customize. 2. **Build from scratch**: create your own trees, nodes, and attributes entirely with `define_content_type` and `define_attribute`. You can mix both: adopt `legal` from the seeds, then add a custom `compliance` tree alongside it. Each tree is independent. **Actions:** - `adopt`: import trees from the seed catalog (starter templates) - `define_content_type`: create or update a tree node (root or child) - `undefine_content_type`: delete a node and its entire subtree - `define_attribute`: add or update a metadata field on a node - `undefine_attribute`: remove a metadata field **Building a tree from scratch, example flow:** 1. Create a root: ```json {"action": "define_content_type", "code": "compliance", "label": "Compliance"} ``` 2. Add children: ```json {"action": "define_content_type", "parent_path": "compliance", "code": "audit-report", "label": "Audit Report"} ``` 3. Add attributes: ```json {"action": "define_attribute", "content_type_path": "compliance", "name": "owner", "attribute_type": "text"} ``` 4. Classify files via `POST /api/v3/files/{id}/facets`: ```json {"action": "classify", "content_type_path": "compliance:audit-report"} ``` **Attributes** are metadata fields you define on each node. Types: `text`, `number`, `date`, `boolean`, `select`, `multi-select`, `rich-text`. `select` and `multi-select` require `choices`. Attributes inherit down the tree: define `jurisdiction` on `legal` and it's available on all children. **Description best practices:** The `description` field on attributes feeds into the scope inference endpoint (`POST /api/v3/content-types/scope`), where it helps the LLM generate accurate search filters. Use keywords that signal the attribute's nature: - **Person names**: include "name", "examiner", "inventor", or "author" → enables `*value*` wildcard syntax hints - **Codes/identifiers**: include "code", "classification", or "identifier" → enables exact-match hints (don't guess from topic keywords) **Multi-classification:** A single document can be classified under multiple content types from different trees (e.g., both `legal:contract:nda` and `compliance:audit-report`). Available seed roots for `adopt`: finance, healthcare, legal, manufacturing, tech Requires admin-level access to modify the company's schema. summary: Define content types and attributes tags: - Facets requestBody: content: application/json: schema: $ref: '#/components/schemas/ContentTypeActionRequest' examples: AdoptSeedRoots: value: action: adopt content_types: - legal - finance summary: Adopt seed roots DefineACompany-originalRootNode: value: action: define_content_type code: compliance label: Compliance description: Internal compliance artefacts summary: Define a company-original root node DefineAChildNodeUnderAnExistingParent: value: action: define_content_type parent_path: compliance code: audit-report label: Audit Report summary: Define a child node under an existing parent UpdateAnExistingNode'sLabel: value: action: define_content_type parent_path: compliance code: audit-report label: Internal Audit Report summary: Update an existing node's label description: Same (parent_path, code) as an earlier call, updates in place. DeleteANodeAndCascadeItsSubtree: value: action: undefine_content_type content_type_path: compliance:audit-report summary: Delete a node and cascade its subtree DefineAnAttributeColumnOnANode: value: action: define_attribute content_type_path: legal:contract:nda name: jurisdiction attribute_type: multi-select choices: - FR - US - UK - DE - CH summary: Define an attribute column on a node DefineATextAttribute(personName): value: action: define_attribute content_type_path: legal:contract:nda name: counterparty attribute_type: text description: Name of the counterparty or signing entity required: true summary: Define a text attribute (person name) DefineATextAttribute(code/identifier): value: action: define_attribute content_type_path: patent name: uspc_class attribute_type: text description: USPC classification code for the patent summary: Define a text attribute (code/identifier) DefineANumberAttribute: value: action: define_attribute content_type_path: finance:report name: amount attribute_type: number summary: Define a number attribute DefineADateAttribute: value: action: define_attribute content_type_path: legal:contract name: effective_date attribute_type: date summary: Define a date attribute DefineABooleanAttribute: value: action: define_attribute content_type_path: legal:contract:nda name: is_mutual attribute_type: boolean summary: Define a boolean attribute DefineASelectAttribute: value: action: define_attribute content_type_path: tech:specification name: maturity attribute_type: select choices: - Draft - Approved - Deprecated summary: Define a select attribute DefineARichTextAttribute: value: action: define_attribute content_type_path: legal name: summary attribute_type: rich-text description: Long-form human-authored summary text. summary: Define a rich text attribute RemoveAnAttributeColumn: value: action: undefine_attribute content_type_path: legal:contract:nda name: jurisdiction summary: Remove an attribute column required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ContentTypeWrite200Response' examples: AdoptedLegalSeed: value: content_types: - path: legal code: legal label: Legal children: - path: legal:contract code: contract label: Contract summary: Adopted legal seed UpdatedCompanyNode: value: path: compliance:audit-report code: audit-report label: Internal Audit Report summary: Updated company node description: 'Action completed: existing node updated or already-present attribute replaced' '201': content: application/json: schema: $ref: '#/components/schemas/ContentTypeWrite201Response' examples: NewCompanyNode: value: path: compliance code: compliance label: Compliance summary: New company node NewSelectAttribute: value: name: maturity label: Maturity type: select required: false description: '' choices: - Draft - Approved - Deprecated summary: New select attribute description: New node or attribute column created '204': description: Node or attribute deleted (cascade for nodes) '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: AttributeTypeImmutable: value: id: null code: 400 error: attribute_type_immutable detail: Cannot change the type of attribute 'jurisdiction' from 'text' to 'select'. Delete and recreate the attribute to change its type. doc_url: https://developers.lighton.ai/errors#attribute_type_immutable summary: Attribute type immutable AttributeNameReserved: value: id: null code: 400 error: attribute_name_reserved detail: '''id'' is a reserved attribute name.' doc_url: https://developers.lighton.ai/errors#attribute_name_reserved summary: Attribute name reserved AttributeNameConflict: value: id: null code: 400 error: attribute_name_conflict detail: Attribute 'jurisdiction' is already defined on 'legal' in the same tree. Attribute names must be unique across the entire tree. doc_url: https://developers.lighton.ai/errors#attribute_name_conflict summary: Attribute name conflict ContentTypeDepthExceeded: value: id: null code: 400 error: content_type_depth_exceeded detail: Content type depth would exceed the maximum of 4 levels (got depth 4). doc_url: https://developers.lighton.ai/errors#content_type_depth_exceeded summary: Content type depth exceeded description: Invalid request or attribute constraint violated '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: ContentTypeNotFound: value: id: null code: 404 error: content_type_not_found detail: Content type 'legal:nonexistent' not found for this company. doc_url: https://developers.lighton.ai/errors#content_type_not_found summary: Content type not found description: Parent or target content type not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/content-types/batch: post: operationId: api_v3_content_types_batch_create description: |- Execute multiple content-type actions in a single request. All actions are **validated upfront** before any execution begins. If any action has invalid fields, the entire batch is rejected with a 422 response and no actions are executed. On **domain errors** (e.g., content type not found, permission denied), the batch fails fast at the failing action. The error response includes an `"index"` field (0-based) indicating which action caused the failure. Actions before the failing index are committed; their results are not returned. All verbs are idempotent — it is safe to re-send the entire batch after fixing the error. **Request:** `{"actions": [, , ...]}` Each action object follows the same schema as the single-action `POST /api/v3/content-types` endpoint. Maximum 50 actions per batch. **Response:** `{"results": [{"status": , "data": }, ...]}` Results are in the same order as the input actions. The `data` key is `null` for 204 actions (deletes). See `POST /api/v3/content-types` for available actions and their fields. summary: Batch define content types and attributes tags: - Facets requestBody: content: application/json: schema: $ref: '#/components/schemas/ContentTypeBatchRequest' examples: AdoptAndDefineAttribute: value: actions: - action: adopt content_types: - legal - action: define_attribute content_type_path: legal name: owner attribute_type: text summary: Adopt and define attribute BuildATreeFromScratch: value: actions: - action: define_content_type code: compliance label: Compliance - action: define_content_type parent_path: compliance code: audit-report label: Audit Report - action: define_attribute content_type_path: compliance name: auditor attribute_type: text summary: Build a tree from scratch required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchResponse' examples: MixedStatuses: value: results: - status: 200 data: content_types: - path: legal code: legal label: Legal - status: 201 data: name: owner label: Owner type: text required: false description: '' choices: [] summary: Mixed statuses DeleteResult(nullData): value: results: - status: 204 data: null summary: Delete result (null data) description: All actions executed successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '400': content: application/json: schema: $ref: '#/components/schemas/APIV3BatchErrorResponse' examples: ContentTypeNotFound(withIndex): value: id: null code: 404 error: content_type_not_found detail: Content type 'nonexistent' not found for this company. doc_url: https://developers.lighton.ai/errors#content_type_not_found index: 1 summary: Content type not found (with index) description: Domain error with action index '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3BatchErrorResponse' examples: PermissionDenied(withIndex): value: id: null code: 403 error: insufficient_permissions detail: Permission denied for action 'undefine_content_type'. doc_url: https://developers.lighton.ai/errors#insufficient_permissions index: 1 summary: Permission denied (with index) description: Permission denied for action '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/content-types/scope: post: operationId: api_v3_content_types_scope_create description: "Resolves content type and attribute filters from a natural-language\ \ query.\nCall this **before** `/search`, `/ask`, or `/files` to narrow results\ \ by domain.\nPass the inferred `content_type` and `attribute` directly to\ \ those endpoints.\n\nReturns ranked content types grouped by root schema,\ \ each with a relevance score\nand the attribute definitions available for\ \ filtering.\n\n### Scores and decision signal\n\nEach content type in the\ \ response includes a `score` (relevance to your query).\nUse scores to decide\ \ how to scope your search — higher means stronger match.\n\n`has_signal`\ \ is a convenience shortcut: it's `true` when the top score meets a\ndefault\ \ confidence threshold. For custom logic, use `score` directly and apply\n\ your own threshold via the `threshold` request parameter.\n\n### Three modes\n\ \n**1. Prompt mode** (default) — returns `prompt_context`, a self-contained\ \ LLM-ready\ntext block. Feed it to any LLM alongside the user query to infer\ \ `content_type`\nand `attribute` filters. The prompt includes ranked content\ \ types, attribute\ndefinitions with filter syntax, inference rules, date\ \ ranges, and few-shot examples.\n\n**2. Completion mode** — pass `model`\ \ (technical name) and the API calls the LLM\nfor you. Returns `scope_completion`\ \ with parsed, normalized filters:\n- Label-to-name mapping (e.g. \"Filing\ \ Date\" → `filing_date`)\n- Syntax validation against the attribute schema\n\ - Structured JSON output via guided decoding\n- `warnings` for any normalization\ \ applied or issues detected\n- If the LLM call fails, `scope_completion`\ \ is still returned with `warnings`\n explaining the failure — the rest of\ \ the response remains usable.\n \n**3. Catalog + completion mode** — set\ \ `relevance_scoring: \"none\"` with a `query`\nand `model` to get the full\ \ content type catalog AND an LLM-inferred\n`scope_completion`. Useful when\ \ you want the LLM to choose from ALL content types\nwithout retrieval pre-filtering.\ \ `max_results` and `threshold` are ignored.\n\n### Response fields\n\n| Field\ \ | Description |\n|-------|-------------|\n| `score` | Relevance score. Higher\ \ = better match. Comparable across requests. |\n| `max_score` | Highest score\ \ in a root group. Compare roots without iterating. |\n| `chunk_count` | Retrieval\ \ chunks matching this CT. More chunks = broader evidence. |\n| `doc_count`\ \ | Total corpus documents classified under this CT. |\n| `prompt_context`\ \ | LLM-ready prompt text. Pass to your LLM as-is. |\n| `prompt_version` |\ \ Fingerprint (`t:.d:`) for eval reproducibility. |\n| `scope_completion`\ \ | Parsed LLM output (only when `model` is provided). |\n\n### Schema context\ \ mode\n\nOmit `query` to get the full content type catalog — useful for system\ \ prompts,\ntool descriptions, or schema exploration. `groups` contains all\ \ content types with\ntheir attributes (`score=0`, `chunk_count=0` since there\ \ is no query to rank against).\n`prompt_context` contains the same catalog\ \ as LLM-ready text.\n\n### Integration notes\n\n- Content type paths use\ \ `:` as separator (e.g. `patent:electricity:h04`).\n- Attribute filter syntax\ \ is documented in `prompt_context` per attribute type.\n Date ranges use\ \ `>=` / `<=` operators (e.g. `filing_date:>=2023-01-01`).\n- Writing meaningful\ \ attribute descriptions (especially for person-name and\n code/identifier\ \ fields) improves the quality of `prompt_context` hints." summary: Resolve search scope tags: - Facets requestBody: content: application/json: schema: $ref: '#/components/schemas/FacetScopeRequest' examples: BasicScopeQuery: value: query: rejected electronics patents summary: Basic scope query WithCustomMaxResults: value: query: mutual NDA expiring 2025 max_results: 5 summary: With custom max_results SchemaContext(noQuery): value: {} summary: Schema context (no query) description: Omit query to get the full CT catalog as prompt_context. WithLLMCompletion: value: query: patents from Q1 2023 model: mistral/mistral-large-latest summary: With LLM completion description: Pass model to get scope_completion with parsed filters. AllCTs+LLMCompletion(noScoring): value: query: employment contracts from last year model: mistral/mistral-large-latest relevance_scoring: none summary: All CTs + LLM completion (no scoring) description: relevance_scoring="none" returns all content types without retrieval ranking, with LLM completion over the full catalog. security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/FacetScopeResponse' examples: StrongMatch—SingleRoot: value: has_signal: true groups: - root: patent root_label: Patent Classification max_score: 1.72 content_types: - path: patent:electricity label: Electricity root: patent score: 1.72 chunk_count: 12 doc_count: 18000 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] prompt_context: |- Content types (by relevance): 1. Electricity (patent:electricity) — score: 1.72, 12 chunks * Relevant filters: - decision "Decision" (select: Accepted, Rejected) Other available attributes: - filing_date "Filing Date" (date: >=, <=) RULES: 1. Use null content_type when the query targets attributes without naming a topic area. ... OUTPUT FORMAT: {"content_type": "" or null, "attribute": [...]} prompt_version: t:a1b2c3d4.d:e5f6a7b8 summary: Strong match — single root Multi-root—Cross-schemaQuery: value: has_signal: true groups: - root: patent root_label: Patent Classification max_score: 1.72 content_types: - path: patent:electricity:h04 label: Electric Communication Technique root: patent score: 1.72 chunk_count: 8 doc_count: 12000 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] - path: patent:electricity:h01 label: Basic Electric Elements root: patent score: 0.91 chunk_count: 3 doc_count: 8500 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] - root: sic root_label: SIC Industry max_score: 0.45 content_types: - path: sic:manufacturing label: Manufacturing root: sic score: 0.45 chunk_count: 2 doc_count: 3200 attributes: - name: industry_code label: Industry Code type: text required: false description: SIC industry classification code choices: [] prompt_context: |- Content types (by relevance): 1. Electric Communication Technique (patent:electricity:h04) — score: 1.72, 8 chunks * 2. Manufacturing (sic:manufacturing) — score: 0.45, 2 chunks ... OUTPUT FORMAT: {"content_type": "" or null, "attribute": [...]} prompt_version: t:a1b2c3d4.d:e5f6a7b8 summary: Multi-root — cross-schema query LowConfidence—BelowThreshold: value: has_signal: false groups: - root: patent root_label: Patent Classification max_score: 0.42 content_types: - path: patent:electricity label: Electricity root: patent score: 0.42 chunk_count: 1 doc_count: 18000 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] prompt_context: |- No confident content type match — query may target metadata (dates, names, codes) rather than a specific domain. Content types (by relevance): 1. Electricity (patent:electricity) — score: 0.42, 1 chunks OUTPUT FORMAT: {"content_type": "" or null, "attribute": [...]} prompt_version: t:a1b2c3d4.d:e5f6a7b8 summary: Low confidence — below threshold description: has_signal is false when the top score is below the confidence threshold. Groups, attributes, and prompt_context are still returned — use scores to decide whether to apply filters. WithScopeCompletion(modelProvided): value: has_signal: true groups: - root: patent root_label: Patent Classification max_score: 1.85 content_types: - path: patent:electricity label: Electricity root: patent score: 1.85 chunk_count: 15 doc_count: 18000 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] prompt_context: |- Content types (by relevance): 1. Electricity (patent:electricity) — score: 1.85, 15 chunks * Relevant filters: - filing_date "Filing Date" (date: >=, <=) Other available attributes: - decision "Decision" (select: Accepted, Rejected) RULES: ... OUTPUT FORMAT: {"content_type": "" or null, "attribute": [...]} prompt_version: t:a1b2c3d4.d:e5f6a7b8 scope_completion: content_type: patent:electricity attribute: - filing_date:>=2023-01-01 - filing_date:<=2023-03-31 raw_output: '{"content_type":"patent:electricity","attribute":["filing_date:>=2023-01-01","filing_date:<=2023-03-31"]}' normalized: false warnings: [] summary: With scope_completion (model provided) description: When model is provided, scope_completion contains parsed filters. scope_completion.content_type and scope_completion.attribute map directly to the search API parameters. raw_output is the LLM's original response. prompt_context is always returned alongside for debugging or fallback. SchemaContext(noQuery): value: has_signal: false groups: - root: patent root_label: Patent Classification max_score: 0.0 content_types: - path: patent label: Patent root: patent score: 0.0 chunk_count: 0 doc_count: 20000 attributes: [] - path: patent:electricity label: Electricity root: patent score: 0.0 chunk_count: 0 doc_count: 18000 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] prompt_context: |- Available content type schemas: Patent Classification (patent): - Electricity (patent:electricity) Attributes: - Decision (select: Accepted, Rejected) on patent:electricity - Filing Date (date) on patent:electricity RULES: ... OUTPUT FORMAT: {"content_type": "" or null, "attribute": [...]} summary: Schema context (no query) description: No query → full CT catalog with attributes. groups contains all content types (score=0, chunk_count=0 since no query to rank). prompt_context contains the same catalog as LLM-ready text. description: Scored content types grouped by root. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' description: Invalid request body. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/content-types/templates: get: operationId: api_v3_content_types_templates_retrieve description: |- Browse the platform's **starter-kit templates** for content types. These are ready-made taxonomies (legal, finance, healthcare, tech, manufacturing) you can adopt to quickly organise your documents, no manual setup required. **Getting started:** 1. Browse templates here to see what's available 2. Adopt the ones you need: `POST /api/v3/content-types {"action": "adopt", "paths": ["legal", "finance"]}` 3. Once adopted, they become **your company's own** content types, fully editable 4. Customize: rename nodes, add children, define new attributes, or delete what you don't need 5. Create entirely new content types from scratch with `define_content_type` All write operations happen on `POST /api/v3/content-types`. This endpoint is read-only: it shows the catalog of available templates. **After adoption**, manage your company's content types (adopted + custom) via `GET /api/v3/content-types` and `POST /api/v3/content-types`. Classify files with `POST /api/v3/files/{id}/facets`. **Query modes:** - No params → full detail for all templates (children + attributes) - `?path=legal` → detail for one template - `?path=legal,finance` → detail for multiple (comma-separated) - `?path=legal:contract:nda` → detail for a nested node - `?depth=0` → root info only (code, label, description, no children/attributes) - `?depth=1` → roots + direct children only - `?include_attributes=false`: omit attribute definitions for a lighter response **Path separator:** `:` (colon). Example: `legal:contract:nda` **Attribute inheritance:** Attributes defined at a parent node are inherited by all its children. A document classified as `legal:contract:nda` gets attributes from `legal`, `legal:contract`, and `legal:contract:nda`. summary: List content type templates parameters: - in: query name: depth schema: type: integer description: Tree depth limit. Default (omitted) = full tree. `0` = root info only (no children, no attributes). `1` = roots + direct children. `N` = N levels of children. - in: query name: include_attributes schema: type: boolean description: 'Include attribute definitions per content type node. Default: true.' - in: query name: path schema: type: string description: 'Content type path(s), colon-separated hierarchy. Comma-separated for multiple (e.g., `?path=legal,finance`, `?path=tech,manufacturing`, or `?path=legal:contract:nda`). Root codes: finance, healthcare, legal, manufacturing, tech' examples: LegalRoot: value: legal summary: Legal root description: Get the full legal content type tree HealthcareRoot: value: healthcare summary: Healthcare root description: Get the full healthcare content type tree FinanceRoot: value: finance summary: Finance root description: Get the full finance content type tree TechRoot: value: tech summary: Tech root description: Get the full tech content type tree ManufacturingRoot: value: manufacturing summary: Manufacturing root description: Get the full manufacturing content type tree NestedNode: value: legal:contract:nda summary: Nested node description: Get detail for a specific leaf node tags: - Facets security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/TemplateListResponse' examples: FullDetail(default,NoParams): value: content_types: - path: legal code: legal label: Legal description: 'Legal documents: contracts, litigation, compliance, opinions, and filings.' children: - code: contract label: Contract description: 'Binding agreements between parties: NDAs, SLAs, MSAs, employment, and licensing.' path: legal:contract children: - code: nda label: Non-Disclosure Agreement description: '' path: legal:contract:nda - code: sla label: Service Level Agreement description: '' path: legal:contract:sla - code: litigation label: Litigation description: 'Court proceedings: briefs, motions, depositions, and court orders.' path: legal:litigation children: - code: brief label: Legal Brief description: '' path: legal:litigation:brief attributes: legal: - name: jurisdiction label: Jurisdiction type: multi-select required: false description: Legal jurisdiction(s) governing the document choices: - FR - US - UK - DE - CH - name: confidentiality_level label: Confidentiality Level type: select required: false choices: - Public - Internal - Confidential - Strictly Confidential legal:contract: - name: contract_value label: Contract Value type: number required: false description: Total monetary value of the contract - name: effective_date label: Effective Date type: date required: false legal:contract:nda: - name: counterparty label: Counterparty type: text required: true description: Name of the other party to the NDA - name: is_mutual label: Is Mutual type: boolean required: false description: Whether the NDA applies symmetrically to both parties summary: Full detail (default, no params) description: 'Default response: all root content types with children and attributes' RootsOnly(?depth=0): value: content_types: - path: legal code: legal label: Legal description: 'Legal documents: contracts, litigation, compliance, opinions, and filings.' - path: healthcare code: healthcare label: Healthcare description: 'Healthcare documents: clinical, administrative, billing, research, and operations.' - path: finance code: finance label: Finance description: 'Financial documents: reporting, audit, treasury, tax, and planning.' - path: tech code: tech label: Technology description: 'Technology documents: specifications, documentation, operations, security, and architecture.' - path: manufacturing code: manufacturing label: Manufacturing description: 'Manufacturing documents: production, quality, maintenance, and supply chain.' summary: Roots only (?depth=0) description: 'Minimal response: code, label, description only. No children or attributes.' description: Content types returned successfully '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: UnknownPath: value: id: null code: 404 error: not_found detail: 'Content type path(s) not found: unknown' doc_url: https://developers.lighton.ai/errors#not_found summary: Unknown path description: Content type path(s) not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/files/{file_id}/facets: get: operationId: api_v3_files_facets_retrieve description: |- See what content types a file is classified under and what attribute values have been set on it. A file can be classified under **multiple content types** (e.g., both `legal:contract:nda` and `compliance:audit-report`). Each classification comes with its own set of **attribute values**, the metadata fields defined in your content-type schema. **Response structure:** Each content type entry includes: - `path`: the content type (e.g., `legal:contract:nda`) - `label`: human-readable name - `labels`: breadcrumb from root to leaf (`["Legal", "Contract", "NDA"]`) Each attribute value includes: - `name` / `label`: identifier and display name - `value`: the current value (shape depends on type) - `type`: the attribute type (`text`, `number`, `date`, `boolean`, `select`, `multi-select`) - `choices`: available options for `select` / `multi-select` - `required`: whether the attribute is required by the schema The response includes `can_edit`, which indicates whether you have permission to modify this file's classifications and attribute values. **To modify:** use `POST /api/v3/files/{file_id}/facets` to classify, set attribute values, or remove classifications. **To set up content types first:** see `GET /api/v3/content-types/templates` (browse starter templates) and `POST /api/v3/content-types` (adopt or create). summary: List file classifications and attribute values parameters: - in: path name: file_id schema: type: integer required: true tags: - Facets security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/DocumentAttributesListResponse' description: '' '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: Document not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not found description: File not found or not accessible '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_files_facets_create description: |- Apply content-type classifications to a file and set attribute values (metadata) on it. This is how you tag a document with structured metadata from your content-type schema. **Typical workflow:** 1. **Classify** the file: `{"action": "classify", "content_type_path": "legal:contract:nda"}` 2. **Set attribute values**: `{"action": "set_value", "content_type_path": "legal:contract:nda", "attribute_name": "jurisdiction", "value": ["FR", "DE"]}` 3. **Read back** with `GET /api/v3/files/{file_id}/facets` A file can be classified under **multiple content types**. Just call `classify` for each one. Removing a classification (`unclassify`) cascades: all attribute values under that content type are removed too. **Actions:** - `classify`: assign a content type to the file (idempotent) - `unclassify`: remove a content type and all its attribute values - `set_value`: set or update an attribute value (the content type must be classified first) - `clear_value`: remove an attribute value **Value types for `set_value`:** - `text` / `rich-text` → string - `number` → number or numeric string - `date` → date string, normalized to `YYYY-MM-DD` - `boolean` → `true` / `false` - `select` → one string from `choices` - `multi-select` → array of strings from `choices` To clear a value, use `clear_value` (not `set_value` with `null`). **Prerequisites:** Content types must be set up first. See `GET /api/v3/content-types/templates` (browse templates) and `POST /api/v3/content-types` (adopt or create). Requires edit access to the file. summary: Classify file and set attribute values parameters: - in: path name: file_id schema: type: integer required: true tags: - Facets requestBody: content: application/json: schema: $ref: '#/components/schemas/FileFacetActionRequest' examples: ClassifyFile: value: action: classify content_type_path: legal:contract:nda summary: Classify file SetTextValue: value: action: set_value content_type_path: legal:contract:nda attribute_name: counterparty value: Nimbus Labs summary: Set text value SetNumberValue: value: action: set_value content_type_path: finance:report attribute_name: contract_value value: 50000 summary: Set number value SetDateValue: value: action: set_value content_type_path: legal:contract attribute_name: effective_date value: '2024-06-30' summary: Set date value SetBooleanValue: value: action: set_value content_type_path: legal:contract:nda attribute_name: is_mutual value: true summary: Set boolean value SetSelectValue: value: action: set_value content_type_path: tech:specification attribute_name: maturity value: Approved summary: Set select value SetMulti-selectValue: value: action: set_value content_type_path: legal:contract:nda attribute_name: jurisdiction value: - FR - DE summary: Set multi-select value ClearValue: value: action: clear_value content_type_path: legal:contract:nda attribute_name: jurisdiction summary: Clear value required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileFacetWriteResponse' description: Content type already classified, or attribute value updated '201': content: application/json: schema: $ref: '#/components/schemas/FileFacetWriteResponse' examples: ContentTypeClassified: value: content_type_path: legal:contract:nda label: Non-Disclosure Agreement summary: Content type classified AttributeValueCreated: value: name: jurisdiction value: - FR - DE content_type_path: legal:contract:nda summary: Attribute value created BooleanValueSet: value: name: is_mutual value: true content_type_path: legal:contract:nda summary: Boolean value set description: Content type classified or attribute value created '204': description: Content type unclassified or attribute value cleared '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: AttributeValueInvalid: value: id: null code: 400 error: attribute_value_invalid detail: 'jurisdiction: expected list, got str' doc_url: https://developers.lighton.ai/errors#attribute_value_invalid summary: Attribute value invalid UnknownContentType: value: id: null code: 400 error: content_type_unknown detail: 'Unknown content type path: ''fake:path''.' doc_url: https://developers.lighton.ai/errors#content_type_unknown summary: Unknown content type SiblingConflict: value: id: null code: 400 error: content_type_sibling_conflict detail: Document already has content type 'legal:contract' from the same tree. Unclassify it before assigning 'legal:compliance'. doc_url: https://developers.lighton.ai/errors#content_type_sibling_conflict summary: Sibling conflict description: Validation error or business rule violation '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to edit this file's facets. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: No edit permission '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: ContentTypeNotAssigned: value: id: null code: 404 error: content_type_not_assigned detail: Content type 'legal:contract' not assigned to document. doc_url: https://developers.lighton.ai/errors#content_type_not_assigned summary: Content type not assigned description: File or content type not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/files/{file_id}/facets/batch: post: operationId: api_v3_files_facets_batch_create description: |- Execute multiple file facet actions in a single request. All actions are **validated upfront** before any execution begins. If any action has invalid fields, the entire batch is rejected with a 422 response and no actions are executed. On **domain errors** (e.g., unknown content type, sibling conflict), the batch fails fast at the failing action. The error response includes an `"index"` field (0-based) indicating which action caused the failure. Actions before the failing index are committed; their results are not returned. All verbs are idempotent — it is safe to re-send the entire batch after fixing the error. **Request:** `{"actions": [, , ...]}` Each action object follows the same schema as the single-action `POST /api/v3/files/{file_id}/facets` endpoint. Maximum 50 actions per batch. **Response:** `{"results": [{"status": , "data": }, ...]}` Results are in the same order as the input actions. The `data` key is `null` for 204 actions (unclassify, clear_value). See `POST /api/v3/files/{file_id}/facets` for available actions and their fields. Requires edit access to the file. summary: Batch classify and set attribute values parameters: - in: path name: file_id schema: type: integer required: true tags: - Facets requestBody: content: application/json: schema: $ref: '#/components/schemas/FileFacetBatchRequest' examples: ClassifyAndSetAttributes: value: actions: - action: classify content_type_path: legal:contract:nda - action: set_value content_type_path: legal:contract:nda attribute_name: jurisdiction value: - FR - DE - action: set_value content_type_path: legal:contract:nda attribute_name: counterparty value: Nimbus Labs summary: Classify and set attributes required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchResponse' examples: Classify+SetValues: value: results: - status: 201 data: content_type_path: legal:contract:nda label: Non-Disclosure Agreement - status: 201 data: name: jurisdiction value: - FR - DE content_type_path: legal:contract:nda - status: 201 data: name: counterparty value: Nimbus Labs content_type_path: legal:contract:nda summary: Classify + set values description: All actions executed successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '400': content: application/json: schema: $ref: '#/components/schemas/APIV3BatchErrorResponse' examples: UnknownContentType(withIndex): value: id: null code: 400 error: content_type_unknown detail: 'Unknown content type path: ''fake:path''.' doc_url: https://developers.lighton.ai/errors#content_type_unknown index: 1 summary: Unknown content type (with index) description: Domain error with action index '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3BatchErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: Document not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not found description: File not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/files/{id}/tags: post: operationId: api_v3_files_tags_create description: | Add one or more tags to a file without affecting existing tags. **Behavior:** - Adds new tags to the document while preserving existing ones - New tags are marked as manually assigned (`auto_assigned=False`) - Duplicate tags are ignored (no error if tag already exists on document) **Validation:** - Returns 400 if tag IDs are invalid or don't belong to user's company - Returns 403 if user doesn't have permission to edit the document - Returns 404 if document doesn't exist summary: Add tags to a file parameters: - in: path name: id schema: type: integer required: true tags: - Tags requestBody: content: application/json: schema: $ref: '#/components/schemas/FileTaggingAddRequest' examples: AddSingleTag: value: tags: - 1 summary: Add single tag description: Add one tag to a file AddMultipleTags: value: tags: - 1 - 2 summary: Add multiple tags description: Add multiple tags to a file at once application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/FileTaggingAddRequest' examples: AddSingleTag: value: tags: - 1 summary: Add single tag description: Add one tag to a file AddMultipleTags: value: tags: - 1 - 2 summary: Add multiple tags description: Add multiple tags to a file at once multipart/form-data: schema: $ref: '#/components/schemas/FileTaggingAddRequest' examples: AddSingleTag: value: tags: - 1 summary: Add single tag description: Add one tag to a file AddMultipleTags: value: tags: - 1 - 2 summary: Add multiple tags description: Add multiple tags to a file at once required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileRetrieveResponseSerializerV3' examples: TagsAddedSuccessfully: value: id: 123 filename: project_proposal.pdf workspace: id: 1 name: Engineering Team summaries: - language: en summary: This document outlines Q4 initiatives... title: Q4 Project Proposal extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T11:45:00Z' total_pages: 25 size: 2458624 tags: - id: 1 name: Compliance auto_assigned: false - id: 2 name: Legal auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2 parser: v2.2.1 message: Added 2 tag(s) to file (duplicates ignored) summary: Tags added successfully description: Tags added successfully '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/files/{id}/tags/{tag_id}: delete: operationId: api_v3_files_tags_destroy description: | Remove a specific tag from a file. **Behavior:** - Removes the specified tag from the document - Works for both manually assigned and auto-assigned tags - Idempotent: returns 204 even if tag was not on the document **Validation:** - Returns 403 if user doesn't have permission to edit the document - Returns 404 if document doesn't exist - Returns 404 if tag doesn't exist or doesn't belong to user's company summary: Remove a tag from a file parameters: - in: path name: id schema: type: integer required: true - in: path name: tag_id schema: type: integer required: true tags: - Tags security: - bearerAuth: [] responses: '204': description: Tag removed successfully (or was already not on the file) '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/tags: get: operationId: api_v3_tags_list description: |- Retrieve a list of tags for the authenticated user's company. Results are ordered by creation date (newest first). summary: List all tags for the authenticated user's company parameters: - in: query name: auto_assign schema: type: boolean description: Filter by auto_assign flag. True if the tag can be automatically assigned by the system, False if it can only be assigned manually. - in: query name: name schema: type: string description: Filter by tag name (case-insensitive partial match) - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer tags: - Tags security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedTagListResponseSerializerV3List' examples: ListOfTags: value: count: 123 next: http://api.example.org/accounts/?page=4 previous: http://api.example.org/accounts/?page=2 results: - - id: 1 created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' name: Report description: Documents summarizing exchanges, meetings notes, transcripts. auto_assign: true document_count: 15 - id: 2 created_at: '2024-01-14T09:00:00Z' updated_at: '2024-01-14T09:00:00Z' name: Product description: Product management docs. Design, strategy, roadmaps, release notes. auto_assign: false document_count: 8 summary: List of tags description: List of tags for the authenticated user's company '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal Server Error description: An unexpected error occurred '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_tags_create description: |- Create a new tag for the authenticated user's company. The auto_assign flag determines if the tag can be automatically assigned by the system (True) or only manually (False). Requires tag creation permission. summary: Create a new tag for the company tags: - Tags requestBody: content: application/json: schema: $ref: '#/components/schemas/TagCreateRequestSerializerV3' examples: CreateTagRequest: value: name: Project Alpha description: Documents related to the development and release of Project Alpha auto_assign: true summary: Create tag request application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/TagCreateRequestSerializerV3' multipart/form-data: schema: $ref: '#/components/schemas/TagCreateRequestSerializerV3' required: true security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/TagListResponseSerializerV3' examples: CreatedTag: value: id: 3 created_at: '2024-01-16T11:00:00Z' updated_at: '2024-01-16T11:00:00Z' name: Project Alpha description: Documents related to the development and release of Project Alpha auto_assign: true document_count: 0 summary: Created tag description: Tag created successfully '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal Server Error description: An unexpected error occurred '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/tags/{id}: delete: operationId: api_v3_tags_destroy description: |- Delete a company tag. This will also remove all Document-Tag associations with this tag. Requires tag deletion permission. summary: Delete a company tag parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this Tag. required: true tags: - Tags security: - bearerAuth: [] responses: '204': description: Tag deleted successfully. All Document-Tag associations have been removed. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal Server Error description: An unexpected error occurred '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/workspaces: get: operationId: api_v3_workspaces_list description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Get the list of accessible workspaces for the authenticated user. Returns workspaces where the user is set as member (through any group: private, company, or custom). Please use instance or company level endpoints to access the workspaces as admin. **Filtering:** All users see only workspaces where they are members. Admin users should use `/api/v3/instance/workspaces` or `/api/v3/company/workspaces` for administrative access. Supported query filters: `workspace_type`, `document_upload_method`, `datasource_type` (`googledrive`, `sharepoint`, `servicenow`, `webscrapper`), `name` (case-insensitive contains), `group_id`, `group_name`, `user_role`. **API keys:** `scoped_api_keys` lists your own non-revoked keys that can access the workspace. Each entry has a `scope_type`: `workspace` for keys explicitly scoped to it (listed first, with their per-workspace role), or `global` for keys with no scope rows that implicitly reach every workspace (their `role` mirrors your own role on the workspace). **Taxonomy:** Each workspace includes a `taxonomy` field summarizing content type classification. `classified_files_rate` is the proportion of documents with at least one content type (0-to-1 ratio). `root_content_types` lists top-level content type families with document counts. A workspace holding documents that are all unclassified reports a rate of `0.0` with an empty `root_content_types`; the whole `taxonomy` object is `null` only when the workspace has no documents. Results ordered by `name` ascending by default — pass `ordering` to change it. Paginated with 20 elements per page by default. summary: List workspaces parameters: - in: query name: datasource_type schema: type: string enum: - googledrive - servicenow - sharepoint - webscrapper description: |- The type of data source. * `servicenow` - ServiceNow * `googledrive` - Google Drive * `sharepoint` - SharePoint * `webscrapper` - WebScrapper - in: query name: document_upload_method schema: type: string enum: - manual - synced description: |- Method for adding documents to this workspace: manual uploads or synced from datasources * `manual` - Manual * `synced` - Synced - in: query name: group_id schema: type: integer - in: query name: group_name schema: type: string - in: query name: name schema: type: string - in: query name: ordering schema: type: string enum: - -created_at - -name - -updated_at - created_at - name - updated_at description: Order the results by `name`, `created_at` or `updated_at`. Prefix the field with `-` for descending order (e.g. `-created_at`). Defaults to `name`; entries sharing a name are ordered newest-first. - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer - in: query name: user_role schema: type: string enum: - editor - owner - viewer description: |- * `owner` - Owner * `editor` - Editor * `viewer` - Viewer - in: query name: workspace_type schema: type: string enum: - personal - public - shared description: |- * `shared` - Shared * `personal` - Personal * `public` - Public tags: - Workspaces security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedStandardWorkspaceV3ListResponseList' description: List of workspaces where the user is a member '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': description: Unauthenticated - Missing or invalid API key/session cookie '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_workspaces_create description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Create a new custom workspace in the authenticated user's company. Requires the company to have `allow_user_workspace_creation` enabled, unless the caller is a company or instance administrator (who may always create workspaces). Returns **403** if workspace creation is disabled for the company and the caller is not an administrator. The creator is automatically added as OWNER. summary: Create a workspace tags: - Workspaces requestBody: content: application/json: schema: $ref: '#/components/schemas/StandardWorkspaceCreateV3Request' examples: CreateWorkspace: value: name: Engineering Team Workspace description: Workspace for the engineering team summary: Create workspace application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/StandardWorkspaceCreateV3Request' multipart/form-data: schema: $ref: '#/components/schemas/StandardWorkspaceCreateV3Request' required: true security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/StandardWorkspaceV3DetailsResponse' description: Workspace created successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': description: Unauthenticated - Missing or invalid API key/session cookie '403': description: Unauthorized - Standard users of this company are not allowed to create workspaces '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/workspaces/datasource/browse: post: operationId: api_v3_workspaces_datasource_browse_create description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Browse the remote folder hierarchy of a datasource without persisting anything. Connects to the external provider using the credentials in the payload and returns the immediate subfolders of ``parent_id`` (or the top-level entries when ``parent_id`` is ``null``). Use this to power a visual folder picker before submitting a datasource configuration via `PATCH /api/v3/workspaces/{id}` with a `datasource` payload. **Access:** any authenticated user. Supported providers and credentials: - **googledrive**: `service_account_file` (JSON string of the service account key file). When ``parent_id`` is omitted, returns the folders explicitly shared with the service account. - **sharepoint**: `client_id`, `client_secret`, `tenant_id`, `instance_url`, `site_name`. When both ``drive_id`` and ``parent_id`` are ``null``, returns the site's document libraries as ``kind="library"`` entries (each entry's ``id`` is the drive id). Pass that ``id`` back as ``drive_id`` (with ``parent_id=null``) to list the library root; pass it as ``drive_id`` together with a folder's ``id`` as ``parent_id`` to descend into a folder. summary: Browse datasource folders tags: - Workspaces requestBody: content: application/json: schema: $ref: '#/components/schemas/WorkspaceDatasourceBrowseV3Request' examples: SharePoint—ListDocumentLibraries(root): value: type: sharepoint credentials: tenant_id: tenant-uuid client_id: client-uuid client_secret: secret instance_url: https://contoso.sharepoint.com site_name: Engineering drive_id: null parent_id: null summary: SharePoint — list document libraries (root) SharePoint—ListFoldersInsideALibrary: value: type: sharepoint credentials: tenant_id: tenant-uuid client_id: client-uuid client_secret: secret instance_url: https://contoso.sharepoint.com site_name: Engineering drive_id: b!abc parent_id: null summary: SharePoint — list folders inside a library GoogleDrive—ChildrenOfAFolder: value: type: googledrive credentials: service_account_file: '{"type":"service_account", "...": "..."}' parent_id: 0AAbCdEfGhIjKlMn summary: Google Drive — children of a folder application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/WorkspaceDatasourceBrowseV3Request' multipart/form-data: schema: $ref: '#/components/schemas/WorkspaceDatasourceBrowseV3Request' required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/WorkspaceDatasourceBrowseV3Response' examples: Response—SharePointDocumentLibraries: value: folders: - id: b!abc name: Documents has_children: true path: Documents drive_id: null kind: library - id: b!def name: SyncedWithParadigm has_children: true path: SyncedWithParadigm drive_id: null kind: library summary: Response — SharePoint document libraries Response—SharePointFoldersInsideALibrary: value: folders: - id: 01ABC name: Engineering has_children: true path: /Engineering drive_id: b!abc kind: folder - id: 01DEF name: Templates has_children: false path: /Templates drive_id: b!abc kind: folder summary: Response — SharePoint folders inside a library description: Folder listing '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' description: Bad Request - Invalid credentials or connection failure to the external datasource '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/workspaces/datasource/test: post: operationId: api_v3_workspaces_datasource_test_create description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Test datasource credentials without persisting anything. Validates that the provided credentials can connect to the external source. Succeeds when the connection can be established; returns an error otherwise. No datasource or import is created. Use this before `PATCH /api/v3/workspaces/{id}` with a `datasource` payload to surface connection errors before committing the conversion. **Access:** any authenticated user. Credentials per type: - **googledrive**: `service_account_file` (JSON string of the service account key file) - **sharepoint**: `client_id`, `client_secret`, `tenant_id`, `site_id` (optional), `site_name` (optional) - **servicenow**: `instance_url`, `username`, `password` - **webscrapper**: no credentials required Filter criteria per type: - **googledrive**: `folder_id` (required), `recursive` (optional) - **sharepoint**: `folder_path` (required), `recursive` (optional) - **servicenow**: `doc_type` (required, e.g. `knowledge`) - **webscrapper**: `start_url` (required) summary: Test datasource credentials tags: - Workspaces requestBody: content: application/json: schema: $ref: '#/components/schemas/StandardWorkspaceDatasourceV3Request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/StandardWorkspaceDatasourceV3Request' multipart/form-data: schema: $ref: '#/components/schemas/StandardWorkspaceDatasourceV3Request' required: true security: - bearerAuth: [] responses: '200': description: Connection successful '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' description: Bad Request - Invalid credentials or connection failure to the external datasource '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/workspaces/{id}: get: operationId: api_v3_workspaces_retrieve description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Retrieve a workspace by ID. Returns workspace in V3 format. **Access:** Instance-level users (Sys Admin, Account Manager, Admin, DPO Admin) can retrieve any workspace. Company-level users (Company Admin, Company DPO) can retrieve workspaces in their company. Regular users can retrieve workspaces where they are members. **Member Visibility:** Instance-level users and company-level users see all members. Workspace OWNER sees members. EDITOR and VIEWER do not see members. **Sync status:** For synced workspaces, the response includes a `sync` block with `datasource_type`, `source_name`, `last_status`, `updated_at`, `failed_files_count`, and `next_import_date`. Use this field for polling the sync state. Non-existent and unauthorized workspaces are treated identically (existence is not disclosed). summary: Retrieve a workspace parameters: - in: path name: id schema: type: integer description: The unique identifier of the workspace. required: true tags: - Workspaces security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/StandardWorkspaceV3DetailsResponse' description: Workspace details retrieved successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_workspaces_partial_update description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Partially update a given workspace. **Standard update (workspace OWNER only):** - **name** (string, optional): Desired workspace name (max 100 characters, cannot be empty) - **description** (string, optional): Desired workspace description. Send empty string or null to clear. **Convert to a synced workspace** (workspace OWNER or a role granting workspace edit/delete): - **datasource** (object): Datasource configuration used to populate the workspace. Credentials are validated against the external source before persistence; use `POST /api/v3/workspaces/{id}/datasource/test` to validate them without committing. - The target workspace must be empty (no documents) and not already synced. **Edit an existing synced workspace's datasource:** - If the workspace is already synced and no successful sync has happened yet, sending a `datasource` payload edits the datasource in place (full credential re-entry required, name/filter_criteria updated, next sync re-triggered). - After the first successful sync, the field is rejected with **409 Conflict** — ingested data integrity is preserved by locking the config. Delete and recreate the workspace to change its configuration. - The datasource `type` is immutable on edit. - Edits are also rejected with 409 while a sync is currently in flight (WAITING/PROCESSING). - The current edit-availability is exposed in the response under `sync.editable` (boolean). **Restrictions:** - Only SHARED workspaces can be updated (PERSONAL workspaces cannot be modified) - Conversion is one-way: a synced workspace cannot be reverted to manual via the API summary: Update a workspace parameters: - in: path name: id schema: type: integer description: The unique identifier of the workspace. required: true tags: - Workspaces requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedUpdateWorkspaceV3Request' examples: RenameWorkspace: value: name: Updated Workspace Name description: Updated description summary: Rename workspace RestoreASoft-deletedWorkspace: value: deleted_at: null summary: Restore a soft-deleted workspace RestoreUnderANewName(resolvesANameCollision): value: deleted_at: null name: Project Apollo (restored) summary: Restore under a new name (resolves a name collision) RestoreAndUpdateTheDescription: value: deleted_at: null description: Reinstated after review summary: Restore and update the description ConvertToServiceNowSyncedWorkspace: value: datasource: type: servicenow name: My ServiceNow KB credentials: instance_url: https://acme.service-now.com username: admin password: s3cr3t filter_criteria: doc_type: knowledge summary: Convert to ServiceNow synced workspace ConvertToGoogleDriveSyncedWorkspace: value: datasource: type: googledrive name: Meet Recordings credentials: service_account_file: '{"type":"service_account","project_id":"my-project",...}' filter_criteria: folder_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs recursive: true summary: Convert to Google Drive synced workspace ConvertToSharePointSyncedWorkspace: value: datasource: type: sharepoint name: Engineering Docs credentials: client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx client_secret: s3cr3t tenant_id: yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy site_name: EngineeringSite filter_criteria: folder_path: /Shared Documents/Engineering recursive: true summary: Convert to SharePoint synced workspace ConvertToWebScrapperSyncedWorkspace: value: datasource: type: webscrapper name: Public Docs credentials: {} filter_criteria: start_url: https://docs.example.com summary: Convert to WebScrapper synced workspace application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedUpdateWorkspaceV3Request' multipart/form-data: schema: $ref: '#/components/schemas/PatchedUpdateWorkspaceV3Request' security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/StandardWorkspaceV3DetailsResponse' description: Workspace updated successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '409': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' description: Conflict - Datasource edit rejected because the workspace has already completed at least one successful sync (config locked), or a sync is currently in flight. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_workspaces_destroy description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Soft-delete a custom workspace you own. The workspace and its memberships are marked as deleted but retained for the configured recovery period; collection data (documents, chunks, embeddings) is preserved until the workspace is permanently deleted by the cleanup task. The workspace can be restored within the recovery period via `PATCH` with `deleted_at=null` (use `?include_deleted=true` to address it after deletion). **Restrictions:** - PERSONAL workspaces cannot be deleted (system-managed) - Caller must be an OWNER of the workspace (or hold instance/company workspace-delete permission) summary: Delete a workspace parameters: - in: path name: id schema: type: integer description: The unique identifier of the workspace. required: true tags: - Workspaces security: - bearerAuth: [] - {} responses: '204': description: Workspace soft-deleted '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/workspaces/{id}/members: get: operationId: api_v3_workspaces_members_retrieve description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Get the list of members for an owned workspace by the authenticated user. Please use instance or company level endpoints to access the workspaces as admin summary: List workspace members parameters: - in: path name: id schema: type: integer required: true tags: - Workspaces security: - bearerAuth: [] - {} responses: '201': content: application/json: schema: $ref: '#/components/schemas/WorkspaceMembersV3Response' description: Workspace members listed successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_workspaces_members_create description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Add a new member (user or group) to a custom workspace you own. summary: Add a member to a workspace parameters: - in: path name: id schema: type: integer required: true tags: - Workspaces requestBody: content: application/json: schema: $ref: '#/components/schemas/InstanceWorkspaceAddMemberV3Request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/InstanceWorkspaceAddMemberV3Request' multipart/form-data: schema: $ref: '#/components/schemas/InstanceWorkspaceAddMemberV3Request' required: true security: - bearerAuth: [] - {} responses: '201': content: application/json: schema: $ref: '#/components/schemas/WorkspaceMembersV3Response' description: Member added successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '409': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Conflict: value: id: null code: 409 error: conflict detail: A resource with this name already exists. doc_url: https://developers.lighton.ai/errors#conflict description: A resource with this name already exists '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' put: operationId: api_v3_workspaces_members_update description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Bulk replace the entire list of members for a custom workspace you own. The authenticated user must be an owner of the workspace and belong to the same company as the workspace. All given users and groups must belong to the same company as the workspace. summary: Replace all workspace members parameters: - in: path name: id schema: type: integer required: true tags: - Workspaces requestBody: content: application/json: schema: $ref: '#/components/schemas/InstanceWorkspaceSetMembersV3Request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/InstanceWorkspaceSetMembersV3Request' multipart/form-data: schema: $ref: '#/components/schemas/InstanceWorkspaceSetMembersV3Request' security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/WorkspaceMembersV3Response' description: Members replaced successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': description: Permission denied - only workspace owner can replace members '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/workspaces/{id}/members/groups/{group_id}: delete: operationId: api_v3_workspaces_members_groups_destroy description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Remove a group from a custom workspace you own. The authenticated user must be an owner of the workspace and belong to the same company as the workspace. Only CUSTOM workspaces allow group removal. Cannot remove the only remaining owner group from the workspace. summary: Remove a group from a custom workspace parameters: - in: path name: group_id schema: type: integer required: true - in: path name: id schema: type: integer required: true tags: - Workspaces security: - bearerAuth: [] responses: '204': description: Group removed from workspace successfully '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/workspaces/{id}/members/users/{user_id}: delete: operationId: api_v3_workspaces_members_users_destroy description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Remove a user from a custom workspace you own. The authenticated user must be an owner of the workspace and belong to the same company as the workspace. summary: Remove a user from a workspace parameters: - in: path name: id schema: type: integer description: The unique identifier of the workspace. required: true - in: path name: user_id schema: type: integer description: The unique identifier of the user to remove from the workspace. required: true tags: - Workspaces security: - bearerAuth: [] responses: '204': description: User removed from workspace successfully '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/ask: post: operationId: api_v3_ask_create description: |- Retrieval-augmented generation: searches your indexed corpus, then generates an LLM answer grounded in the retrieved passages. **Modes:** - `stream=false` (default): returns a single JSON response with `results` and `answer`. - `stream=true`: returns Server-Sent Events — `event: sources` (retrieved chunks), `event: token` (answer tokens), `event: done` (stream complete), or `event: error` (generation failure). **Model:** omit `model` to use the default model configured for your organization. Pass `model=alfred-ft5` for the lighter, faster LightOn fine-tune, or `model=mistral-large-latest` for the flagship general-purpose model. Company-specific custom models (`custom-{company_id}-{uuid}`) are also accepted. Any other value is rejected. **Structured output:** pass `response_format` with a JSON Schema object to constrain the LLM answer to valid JSON matching your schema. The schema must have `type: "object"` and `properties`. When set, the `answer` field contains a JSON string conforming to the schema. Works with both sync and streaming modes. Omit for free-text answers (default). **Relevance scoring:** relevance scoring always runs in `scoring_and_filtering` mode — candidates are scored for relevance and only those above the quality threshold are used as context. `score` equals the relevance score (`scores.relevance`, 0–1). Results are returned in descending order of `score`. If the scoring model is temporarily unavailable, `score` falls back to the combined retrieval score (higher is better, no fixed upper bound) and `scores.relevance` is null. **Scoping:** same rules as `/api/v3/search` — use `workspace_id` and/or `tag_id` to narrow results, or `file_id` to target specific files. `file_id` cannot be combined with `workspace_id` or `tag_id`. **Facet filtering:** use `content_type` and `attribute` to narrow results by facet metadata. Content type uses colon-separated paths (e.g. `legal:contract:nda`). **Repeated `attribute` entries are ANDed; values inside one entry are ORed with `|` (pipe, recommended).** Example: `attribute=fiscal_year:2024|2025&attribute=status:active` → (fiscal_year 2024 OR 2025) AND (status active). Supports operators (`>`, `>=`, `<`, `<=`), prefix (`name:prefix*`), smart dates, and content-type scoping. If the reranker is temporarily unavailable, results are returned in retrieval order and each result item includes a `warnings` array. Each warning has a `code` matching the degraded `scores` key (e.g. `relevance`) and a `reason` classifying the failure: `model_not_found`, `timeout`, `service_error`, or `unknown`. The `warnings` key is absent from result items when all pipeline steps succeed. Billing: 1 search-with-generation credit per request. summary: Ask a question over your documents tags: - Files Processing requestBody: content: application/json: schema: $ref: '#/components/schemas/AskRequest' examples: DefaultModel—ScopedToWorkspace: value: query: How are JWT tokens signed? max_results: 5 workspace_id: - 42 summary: Default model — scoped to workspace description: Ask a question within a specific workspace using the default model. AlternateModel—ScopedToFiles: value: query: What is the quarterly revenue forecast? max_results: 3 file_id: - 101 - 102 model: alfred-ft5 summary: Alternate model — scoped to files description: Ask using the lighter alfred-ft5 model, targeting specific files. StreamingMode: value: query: Summarize the onboarding process stream: true summary: Streaming mode description: Stream the answer as Server-Sent Events. StructuredOutput—JSONSchema: value: query: What are the key findings? max_results: 5 workspace_id: - 42 response_format: type: object properties: findings: type: array items: type: string confidence: type: number required: - findings - confidence summary: Structured output — JSON schema description: Constrain the answer to match a JSON schema. Facet—ContentTypeFilter: value: query: What are the indemnification terms? content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Ask only over documents classified as legal contracts. Facet—AttributeFilter: value: query: What are the compliance requirements? workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: Ask over documents with specific attribute values, combined with workspace scoping. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/AskRequest' examples: DefaultModel—ScopedToWorkspace: value: query: How are JWT tokens signed? max_results: 5 workspace_id: - 42 summary: Default model — scoped to workspace description: Ask a question within a specific workspace using the default model. AlternateModel—ScopedToFiles: value: query: What is the quarterly revenue forecast? max_results: 3 file_id: - 101 - 102 model: alfred-ft5 summary: Alternate model — scoped to files description: Ask using the lighter alfred-ft5 model, targeting specific files. StreamingMode: value: query: Summarize the onboarding process stream: true summary: Streaming mode description: Stream the answer as Server-Sent Events. StructuredOutput—JSONSchema: value: query: What are the key findings? max_results: 5 workspace_id: - 42 response_format: type: object properties: findings: type: array items: type: string confidence: type: number required: - findings - confidence summary: Structured output — JSON schema description: Constrain the answer to match a JSON schema. Facet—ContentTypeFilter: value: query: What are the indemnification terms? content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Ask only over documents classified as legal contracts. Facet—AttributeFilter: value: query: What are the compliance requirements? workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: Ask over documents with specific attribute values, combined with workspace scoping. multipart/form-data: schema: $ref: '#/components/schemas/AskRequest' examples: DefaultModel—ScopedToWorkspace: value: query: How are JWT tokens signed? max_results: 5 workspace_id: - 42 summary: Default model — scoped to workspace description: Ask a question within a specific workspace using the default model. AlternateModel—ScopedToFiles: value: query: What is the quarterly revenue forecast? max_results: 3 file_id: - 101 - 102 model: alfred-ft5 summary: Alternate model — scoped to files description: Ask using the lighter alfred-ft5 model, targeting specific files. StreamingMode: value: query: Summarize the onboarding process stream: true summary: Streaming mode description: Stream the answer as Server-Sent Events. StructuredOutput—JSONSchema: value: query: What are the key findings? max_results: 5 workspace_id: - 42 response_format: type: object properties: findings: type: array items: type: string confidence: type: number required: - findings - confidence summary: Structured output — JSON schema description: Constrain the answer to match a JSON schema. Facet—ContentTypeFilter: value: query: What are the indemnification terms? content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Ask only over documents classified as legal contracts. Facet—AttributeFilter: value: query: What are the compliance requirements? workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: Ask over documents with specific attribute values, combined with workspace scoping. required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/AskResponse' examples: SynchronousAnswer—WithFacetData: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: JWT tokens are signed using RS256 and expire after 1 hour. score: 0.95 scores: text: 0.91 vision: null keyword: 0.43 multivector: 0.78 relevance: 0.95 source: file_id: 512 filename: auth-system.pdf title: Authentication System Design mime_type: pdf size_bytes: 482113 page_start: 3 page_end: 4 total_pages: 12 tags: - id: 7 name: security content_types: - path: engineering:security label: Security attribute_values: topic: value: authentication type: text external_metadata: null workspace: id: 42 name: Engineering Docs answer: Based on the authentication system design document, JWT tokens are signed using RS256 and have a 1-hour expiration (auth-system.pdf, page 3). summary: Synchronous answer — with facet data description: Complete answer with source chunks. Source includes content_types with attribute values when documents have facet classifications. SynchronousAnswer—RerankerUnavailable: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: JWT tokens are signed using RS256 and expire after 1 hour. score: 1.65 scores: text: 0.91 vision: null keyword: 0.43 multivector: 0.78 relevance: null source: file_id: 512 filename: auth-system.pdf title: Authentication System Design mime_type: pdf size_bytes: 482113 page_start: 3 page_end: 4 total_pages: 12 tags: [] content_types: [] external_metadata: null workspace: id: 42 name: Engineering Docs warnings: - code: relevance reason: model_not_found answer: 'Based on the available documents, JWT tokens are signed using RS256 and have a 1-hour expiration. Note: relevance scoring was unavailable for this request.' summary: Synchronous answer — reranker unavailable description: Reranker degraded; each result item carries a warnings array. score falls back to the combined retrieval score (no fixed upper bound) and scores.relevance is null. The warnings key is absent when healthy. SynchronousAnswer—NoFacets: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: JWT tokens are signed using RS256 and expire after 1 hour. score: 0.95 scores: text: 0.91 vision: null keyword: 0.43 multivector: 0.78 relevance: 0.95 source: file_id: 512 filename: auth-system.pdf title: Authentication System Design mime_type: pdf size_bytes: 482113 page_start: 3 page_end: 4 total_pages: 12 tags: - id: 7 name: security content_types: [] external_metadata: null workspace: id: 42 name: Engineering Docs answer: Based on the authentication system design document, JWT tokens are signed using RS256 and have a 1-hour expiration (auth-system.pdf, page 3). summary: Synchronous answer — no facets description: Answer with source chunks without facet content type data. description: |- Synchronous mode (`stream=false`): complete answer with sources. Streaming mode (`stream=true`): Server-Sent Events with `event: sources`, `event: token`, and `event: done` (or `event: error`). '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: BadRequest: value: id: null code: 400 error: bad_request detail: The request body could not be parsed as valid JSON. doc_url: https://developers.lighton.ai/errors#bad_request summary: Bad Request description: Request body is not valid JSON '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InsufficientPermissions: value: id: null code: 403 error: insufficient_permissions detail: None of the provided filters resolve to authorized resources. doc_url: https://developers.lighton.ai/errors#insufficient_permissions summary: Insufficient permissions description: API key has no authorized resources matching the provided filters. '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: ModelUnavailableOnBackend: value: id: null code: 404 error: not_found detail: Model 'mistral-large-latest' not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Model unavailable on backend description: An explicitly requested model (`mistral-large-latest` or `alfred-ft5`) is not currently available on the backend. (An unsupported `model` value is rejected earlier with a 422.) '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError—ScopingConflict: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: file_id: - error: invalid_combination detail: file_id cannot be combined with workspace_id or tag_id. summary: Validation error — scoping conflict ValidationError—InvalidResponseFormat: value: code: 422 error: validation_error detail: One or more fields failed validation. fields: response_format: - error: invalid detail: response_format type must be 'object' summary: Validation error — invalid response_format ValidationError—UnsupportedModel: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: model: - error: invalid_choice detail: '"gpt-4" is not a valid choice.' summary: Validation error — unsupported model description: Field validation failure. '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: id: null code: 429 error: too_many_requests detail: Too many requests. Please try again later. doc_url: https://developers.lighton.ai/errors#too_many_requests summary: Too Many Requests description: Too many requests '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal Server Error description: An unexpected error occurred '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' '504': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: ModelTimeout: value: id: null code: 504 error: model_timeout detail: The model did not respond in time. Please try again later. doc_url: https://developers.lighton.ai/errors#model_timeout summary: Model timeout description: Model timeout. /api/v3/retrieve: post: operationId: api_v3_retrieve_create description: |- **Deprecated: Use the v3 search endpoint instead.** Invoke the document retrieval pipeline (embedding + hybrid vector search + reranking) and return matched document chunks. **Relevance scoring (`relevance_scoring`):** controls the relevance scoring stage. - `scoring_and_filtering` (default): Score candidates for relevance and only return those above the quality threshold. When no candidate clears the threshold, the few best-scoring candidates are returned instead of an empty result; their `scores.relevance` is then below the usual threshold. - `scoring_only`: Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. - `none`: Skip the relevance scoring step and return all candidates unfiltered. Fastest option, useful when you handle scoring yourself. Omit `relevance_scoring` for the default; send `none` to skip scoring. `skip_rerank` is **deprecated** — `true` maps to `relevance_scoring=none`, `false` to `scoring_and_filtering`. `relevance_scoring` wins if both are sent. **Result ordering:** results are returned in descending order of `score`. With `scoring_and_filtering` or `scoring_only`, `score` equals the relevance score (`scores.relevance`, 0–1). With `none`, `score` is the combined retrieval score (higher is better, no fixed upper bound). If the scoring model is temporarily unavailable, results are returned in retrieval order and a `warnings` array is included. Each warning has a `code` matching the degraded `scores` key (e.g. `relevance`) and a `reason` classifying the failure: `model_not_found`, `timeout`, `service_error`, or `unknown`. The `warnings` key is absent when all pipeline steps succeed. **Scoping:** use `workspace_id` and/or `tag_id` to narrow retrieval to specific workspaces or tags, or use `file_id` to target specific files. `file_id` cannot be combined with `workspace_id` or `tag_id`. A 403 is returned if any provided filter resolves to no authorized resources. When no filters are provided, retrieval runs across all authorized documents. **Public datasets:** a public dataset workspace must be the only workspace in the request — combining it with any other `workspace_id`, `file_id`, or `tag_id` returns 400. Public datasets are reachable only through a workspace-scoped API key whose scope includes the workspace, and only for companies allowed to access them; otherwise the result is empty. **Facet filtering:** use `content_type` and/or `attribute` to narrow retrieval by document metadata. These can be combined with workspace/tag scoping. Content type uses colon-separated paths (e.g. `legal:contract:nda`). Attributes support operators, OR, and content-type scoping. **Modes:** - `text` (default): hybrid text search - `vision`: image-based search **Explain mode:** set `explain=true` to receive a per-chunk scoring breakdown in the response (raw scores, normalized scores, fusion weights, filter stats, timing). Requires the `SEARCH_EXPLAIN_MODE` feature flag to be enabled. summary: Retrieve document chunks tags: - Files Processing requestBody: content: application/json: schema: $ref: '#/components/schemas/RetrieveRequest' examples: TextMode—ScopedToWorkspace: value: query: authentication system JWT tokens mode: text top_k: 20 workspace_id: - 42 summary: Text mode — scoped to workspace description: Retrieve chunks from a specific workspace using hybrid text search with reranking. TextMode—ScopedToFiles: value: query: quarterly revenue forecast mode: text top_k: 10 file_id: - 101 - 102 summary: Text mode — scoped to files description: Retrieve chunks from specific files only. TextMode—AcrossAllDocuments: value: query: onboarding process mode: text top_k: 20 summary: Text mode — across all documents description: Retrieve chunks across all documents the API key has access to. VisionModeWithImage: value: query: architecture diagram mode: vision top_k: 10 include_image: true summary: Vision mode with image description: Retrieve vision chunks (images/diagrams) using image-based search. SkipScoring(none)—RawRetrieval: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: none summary: Skip scoring (none) — raw retrieval description: Bypass the reranker to isolate raw vector + lexical retrieval quality. ScoringOnly—RerankWithoutFiltering: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: scoring_only summary: Scoring only — rerank without filtering description: Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract top_k: 20 summary: Facet — content type filter description: Retrieve only from documents classified as legal contracts. Facet—AttributeFilter: value: query: compliance requirements workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: Retrieve from documents with a specific attribute value, combined with workspace scoping. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/RetrieveRequest' examples: TextMode—ScopedToWorkspace: value: query: authentication system JWT tokens mode: text top_k: 20 workspace_id: - 42 summary: Text mode — scoped to workspace description: Retrieve chunks from a specific workspace using hybrid text search with reranking. TextMode—ScopedToFiles: value: query: quarterly revenue forecast mode: text top_k: 10 file_id: - 101 - 102 summary: Text mode — scoped to files description: Retrieve chunks from specific files only. TextMode—AcrossAllDocuments: value: query: onboarding process mode: text top_k: 20 summary: Text mode — across all documents description: Retrieve chunks across all documents the API key has access to. VisionModeWithImage: value: query: architecture diagram mode: vision top_k: 10 include_image: true summary: Vision mode with image description: Retrieve vision chunks (images/diagrams) using image-based search. SkipScoring(none)—RawRetrieval: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: none summary: Skip scoring (none) — raw retrieval description: Bypass the reranker to isolate raw vector + lexical retrieval quality. ScoringOnly—RerankWithoutFiltering: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: scoring_only summary: Scoring only — rerank without filtering description: Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract top_k: 20 summary: Facet — content type filter description: Retrieve only from documents classified as legal contracts. Facet—AttributeFilter: value: query: compliance requirements workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: Retrieve from documents with a specific attribute value, combined with workspace scoping. multipart/form-data: schema: $ref: '#/components/schemas/RetrieveRequest' examples: TextMode—ScopedToWorkspace: value: query: authentication system JWT tokens mode: text top_k: 20 workspace_id: - 42 summary: Text mode — scoped to workspace description: Retrieve chunks from a specific workspace using hybrid text search with reranking. TextMode—ScopedToFiles: value: query: quarterly revenue forecast mode: text top_k: 10 file_id: - 101 - 102 summary: Text mode — scoped to files description: Retrieve chunks from specific files only. TextMode—AcrossAllDocuments: value: query: onboarding process mode: text top_k: 20 summary: Text mode — across all documents description: Retrieve chunks across all documents the API key has access to. VisionModeWithImage: value: query: architecture diagram mode: vision top_k: 10 include_image: true summary: Vision mode with image description: Retrieve vision chunks (images/diagrams) using image-based search. SkipScoring(none)—RawRetrieval: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: none summary: Skip scoring (none) — raw retrieval description: Bypass the reranker to isolate raw vector + lexical retrieval quality. ScoringOnly—RerankWithoutFiltering: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: scoring_only summary: Scoring only — rerank without filtering description: Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract top_k: 20 summary: Facet — content type filter description: Retrieve only from documents classified as legal contracts. Facet—AttributeFilter: value: query: compliance requirements workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: Retrieve from documents with a specific attribute value, combined with workspace scoping. required: true security: - bearerAuth: [] deprecated: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/RetrieveV3Response' examples: TextModeResult—WithRerankingAndFacetScoping: value: query: indemnification clause retrieve_params: mode: text top_k: 20 relevance_scoring: scoring_and_filtering skip_rerank: false include_image: false explain: false scoping_params: file_id: [] tag_id: [] workspace_id: - 42 content_type: - legal:contract attribute: - jurisdiction:FR results: - chunk: id: 1024 uuid: 550e8400-e29b-41d4-a716-446655440000 content_id: content_id_550e8400-e29b-41d4-a716-446655440000 text: The indemnifying party shall hold harmless and indemnify the other party... chunk_type: text metadata: pages: 3-4 total_pages: 12 title: Customer NDA — Nimbus Labs source: customer-nda.pdf parser: v2.2.1 folder_name: legal/customers coords: 3,72.0,120.0,450.0,18.0;4,72.0,80.0,450.0,18.0 previous: 550e8400-e29b-41d4-a716-446655440002 next: 550e8400-e29b-41d4-a716-446655440004 overlapping: '' token_length: 412 created_at: '2025-11-01T09:00:00Z' updated_at: '2025-11-01T09:00:00Z' scoring: score: 0.95 scores: text: 0.92 vision: 0.12 keyword: 0.74 multivector: 0.81 relevance: 0.95 workspace: id: 42 name: Legal Team workspace_type: custom document: id: 512 name: customer-nda.pdf file_type: pdf status: embedded total_pages: 12 uploaded_at: '2025-10-30T08:00:00Z' title: Customer NDA — Nimbus Labs tags: - id: 7 name: confidential auto_assigned: true external_metadata: external_id: legal-doc-456789 doc_type: nda additional_metadata: external_url: https://contracts.example.com/legal/customer-nda content_types: - path: legal:contract:nda label: Non-Disclosure Agreement attribute_values: jurisdiction: value: - FR - US type: multi-select is_mutual: value: true type: boolean counterparty: value: Nimbus Labs type: text summary: Text mode result — with reranking and facet scoping description: Retrieval with reranking applied (relevance_scoring="scoring_and_filtering", default) and facet filters. score equals scores.relevance (relevance score). Document includes compact content_types with attribute values. TextModeResult—RawRetrieval: value: query: JWT authentication retrieve_params: mode: text top_k: 20 relevance_scoring: none skip_rerank: true include_image: false explain: false scoping_params: file_id: [] tag_id: [] workspace_id: [] content_type: [] attribute: [] results: - chunk: id: 1024 uuid: 550e8400-e29b-41d4-a716-446655440000 content_id: content_id_550e8400-e29b-41d4-a716-446655440000 text: JWT tokens are signed using RS256 and expire after 1 hour. chunk_type: text metadata: pages: '3' total_pages: 12 title: Authentication System Design source: auth-system.pdf parser: v2.2.1 folder_name: engineering/security coords: 3,72.0,120.0,450.0,18.0 previous: '' next: 550e8400-e29b-41d4-a716-446655440002 overlapping: '' token_length: 380 created_at: '2025-11-01T09:00:00Z' updated_at: '2025-11-01T09:00:00Z' scoring: score: 1.65 scores: text: 0.92 vision: 0.12 keyword: 0.74 multivector: 0.81 relevance: null workspace: id: 42 name: Engineering Docs workspace_type: custom document: id: 512 name: auth-system.pdf file_type: pdf status: embedded total_pages: 12 uploaded_at: '2025-10-30T08:00:00Z' title: Authentication System Design tags: - id: 7 name: security auto_assigned: false external_metadata: null content_types: [] summary: Text mode result — raw retrieval description: Raw retrieval without reranking (relevance_scoring="none"). score is the combined retrieval score (higher is better, no fixed upper bound). scores.relevance is null. VisionModeResult: value: query: architecture diagram retrieve_params: mode: vision top_k: 20 relevance_scoring: scoring_and_filtering skip_rerank: false include_image: true explain: false scoping_params: file_id: [] tag_id: [] workspace_id: [] content_type: [] attribute: [] results: - chunk: id: 2048 uuid: 661f9511-f3ac-52e5-b827-557766551111 metadata: pages: '4' total_pages: 20 title: Infrastructure Overview source: infra-overview.pdf parser: vision folder_name: '' coords: null previous: '' next: '' overlapping: '' token_length: null created_at: '2025-11-02T10:00:00Z' updated_at: '2025-11-02T10:00:00Z' scoring: score: 0.88 scores: text: null vision: 0.85 keyword: null multivector: null relevance: 0.88 workspace: id: 42 name: Engineering Docs workspace_type: custom document: id: 513 name: infra-overview.pdf file_type: pdf status: embedded total_pages: 20 uploaded_at: '2025-10-31T08:00:00Z' title: Infrastructure Overview tags: [] external_metadata: null content_types: [] corresponding_image: b64_content: iVBORw0KGgo... summary: Vision mode result description: Vision chunk result with base64-encoded image. TextModeResult—WithIncludeDetails: value: query: compliance requirements retrieve_params: mode: text top_k: 20 relevance_scoring: scoring_and_filtering skip_rerank: false include_image: false explain: false scoping_params: file_id: [] tag_id: [] workspace_id: [] content_type: - legal attribute: [] results: - chunk: id: 2050 uuid: 771fa622-g4bd-63f6-c938-668877662222 content_id: content_id_771fa622-g4bd-63f6-c938-668877662222 text: All data processing must comply with GDPR Article 28... chunk_type: text metadata: pages: '5' total_pages: 18 title: GDPR Compliance Policy source: gdpr-compliance-policy.pdf parser: v2.2.1 folder_name: legal/compliance coords: 5,72.0,420.0,450.0,18.0 previous: 771fa622-g4bd-63f6-c938-668877662221 next: 771fa622-g4bd-63f6-c938-668877662223 overlapping: '' token_length: 295 created_at: '2025-11-03T11:00:00Z' updated_at: '2025-11-03T11:00:00Z' scoring: score: 0.91 scores: text: 0.88 vision: null keyword: 0.69 multivector: null relevance: 0.91 workspace: id: 3 name: Legal Team workspace_type: custom document: id: 514 name: gdpr-compliance-policy.pdf file_type: pdf status: embedded total_pages: 18 uploaded_at: '2025-11-01T08:00:00Z' title: GDPR Compliance Policy tags: - id: 15 name: compliance auto_assigned: false external_metadata: null content_types: - code: compliance path: legal:compliance label: Compliance breadcrumb: - code: legal path: legal label: Legal - code: compliance path: legal:compliance label: Compliance attribute_values: regulation: value: - GDPR type: multi-select attribute: name: regulation label: Regulation type: multi-select required: false choices: - GDPR - SOX - HIPAA - AML - KYC jurisdiction: value: - FR - DE type: multi-select attribute: name: jurisdiction label: Jurisdiction type: multi-select required: false choices: - FR - US - UK - DE - CH summary: Text mode result — with include_details description: Response when include_details=true. Content types gain code, structured breadcrumb (ancestor chain), and expanded attribute_values with full attribute definitions (name, label, type, required, choices). TextModeResult—RerankerUnavailable: value: query: authentication system JWT tokens retrieve_params: mode: text top_k: 20 relevance_scoring: scoring_and_filtering skip_rerank: false include_image: false explain: false scoping_params: file_id: [] tag_id: [] workspace_id: - 42 content_type: [] attribute: [] results: - chunk: id: 1024 uuid: 550e8400-e29b-41d4-a716-446655440000 content_id: content_id_550e8400-e29b-41d4-a716-446655440000 text: JWT tokens are signed using RS256 and expire after 1 hour. chunk_type: text metadata: pages: '3' total_pages: 12 title: Authentication System Design source: auth-system.pdf parser: v2.2.1 folder_name: '' coords: 3,72.0,120.0,450.0,18.0 previous: '' next: '' overlapping: '' token_length: 380 created_at: '2025-11-01T09:00:00Z' updated_at: '2025-11-01T09:00:00Z' scoring: score: 1.65 scores: text: 0.92 vision: null keyword: 0.74 multivector: 0.81 relevance: null workspace: id: 42 name: Engineering Docs workspace_type: custom document: id: 512 name: auth-system.pdf file_type: pdf status: embedded total_pages: 12 uploaded_at: '2025-10-30T08:00:00Z' title: Authentication System Design tags: [] external_metadata: null content_types: [] warnings: - code: relevance reason: model_not_found summary: Text mode result — reranker unavailable description: Reranker failed; results returned in retrieval order. score falls back to the combined retrieval score (no fixed upper bound) and scores.relevance is null. The warnings array identifies the degraded signal and failure reason. NoMatchingDocuments: value: query: quantum computing patents retrieve_params: mode: text top_k: 20 relevance_scoring: scoring_and_filtering skip_rerank: false include_image: false explain: false scoping_params: file_id: [] tag_id: [] workspace_id: [] content_type: [] attribute: [] results: [] summary: No matching documents description: Query returned no results — empty array with HTTP 200. Full envelope is always present. description: Chunks retrieved successfully. Empty array if no documents match. '400': description: A public dataset workspace was combined with other scope filters. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': description: Authentication credentials were not provided or are invalid. '403': description: A provided filter (workspace_id, file_id, or tag_id) does not exist or the user is not authorized to access it. '429': description: Rate limit exceeded. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/search: post: operationId: api_v3_search_create description: |- Embedding → hybrid vector search → optional reranking, returning ranked chunks with provenance. No LLM generation is performed. Billing: 1 retrieval credit per request. **Relevance scoring (`relevance_scoring`):** controls the relevance scoring stage. - `scoring_and_filtering` (default): Score candidates for relevance and only return those above the quality threshold. - `scoring_only`: Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. - `none`: Skip the relevance scoring step and return all candidates unfiltered. Fastest option, useful when you handle scoring yourself. Omit `relevance_scoring` for the default; send `none` to skip scoring. `skip_rerank` is deprecated — `true` maps to `none`, `false` to `scoring_and_filtering`. **Result ordering:** results are returned in descending order of `score`. With `scoring_and_filtering` or `scoring_only`, `score` equals the relevance score (`scores.relevance`, 0–1). With `none`, `score` is the combined retrieval score (higher is better, no fixed upper bound). If the scoring model is temporarily unavailable, results are returned in retrieval order and a `warnings` array is included. Each warning has a `code` matching the degraded `scores` key (e.g. `relevance`) and a `reason` classifying the failure: `model_not_found`, `timeout`, `service_error`, or `unknown`. The `warnings` key is absent when all pipeline steps succeed. **Scoping:** use `workspace_id` and/or `tag_id` to narrow results, or `file_id` to target specific files. `file_id` cannot be combined with `workspace_id` or `tag_id`. Filters that resolve to no authorized resources are rejected. When no filters are provided, search runs across all documents authorized for the API key. **Facet filtering:** use `content_type` and `attribute` to narrow results by facet metadata. Content type uses colon-separated paths (e.g. `legal:contract:nda`). **Repeated `attribute` entries are ANDed; values inside one entry are ORed with `|` (pipe, recommended).** Example: `attribute=fiscal_year:2024|2025&attribute=status:active` → (fiscal_year 2024 OR 2025) AND (status active). Supports operators (`>`, `>=`, `<`, `<=`), prefix (`name:prefix*`), smart dates, and content-type scoping. **Modes:** - `text` (default): hybrid text search - `vision`: VLM-embedded page image search **Images:** set `include_image=true` to receive a base64-encoded page image with each result. In text mode the image is fetched from the VisionChunk covering the chunk's start page (empty string if no vision index exists for that page). **Bounding boxes (PDF only):** set `include_bboxes=true` to append a `bboxes` array to each result, giving the merged rectangles of the chunk's text on the source PDF (raw PDF points, top-left origin with y extending downward) so you can overlay highlights without re-locating the chunk. One rectangle per logical group; a chunk spanning two pages produces at least one rectangle per page. Available for PDF documents in text mode only — returns an empty list for non-PDF, vision-mode, or pre-v2.2.1 chunks. When `include_bboxes=false` (default) the `bboxes` key is omitted. summary: Search document chunks tags: - Files Processing requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequest' examples: TextSearch—ScopedToWorkspace: value: query: authentication system JWT tokens max_results: 5 workspace_id: - 42 summary: Text search — scoped to workspace description: Search within a specific workspace using hybrid text search with reranking. TextSearch—ScopedToFiles: value: query: quarterly revenue forecast max_results: 3 file_id: - 101 - 102 summary: Text search — scoped to files description: Search specific files only. TextSearch—AcrossAllDocuments: value: query: onboarding process max_results: 10 summary: Text search — across all documents description: Search across all documents the API key has access to. RawRetrieval—SkipScoring: value: query: incident response playbook max_results: 10 relevance_scoring: none summary: Raw retrieval — skip scoring description: Bypass relevance scoring for lower latency (relevance_scoring="none"). scores.relevance will be null. TextSearch—WithBoundingBoxes: value: query: authentication system JWT tokens max_results: 5 include_bboxes: true summary: Text search — with bounding boxes description: Append merged PDF bounding boxes to each result for overlaying chunk highlights. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Search only documents classified as legal contracts. Facet—AttributeFilter: value: query: compliance requirements workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: Search documents with specific attribute values, combined with workspace scoping. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SearchRequest' examples: TextSearch—ScopedToWorkspace: value: query: authentication system JWT tokens max_results: 5 workspace_id: - 42 summary: Text search — scoped to workspace description: Search within a specific workspace using hybrid text search with reranking. TextSearch—ScopedToFiles: value: query: quarterly revenue forecast max_results: 3 file_id: - 101 - 102 summary: Text search — scoped to files description: Search specific files only. TextSearch—AcrossAllDocuments: value: query: onboarding process max_results: 10 summary: Text search — across all documents description: Search across all documents the API key has access to. RawRetrieval—SkipScoring: value: query: incident response playbook max_results: 10 relevance_scoring: none summary: Raw retrieval — skip scoring description: Bypass relevance scoring for lower latency (relevance_scoring="none"). scores.relevance will be null. TextSearch—WithBoundingBoxes: value: query: authentication system JWT tokens max_results: 5 include_bboxes: true summary: Text search — with bounding boxes description: Append merged PDF bounding boxes to each result for overlaying chunk highlights. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Search only documents classified as legal contracts. Facet—AttributeFilter: value: query: compliance requirements workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: Search documents with specific attribute values, combined with workspace scoping. multipart/form-data: schema: $ref: '#/components/schemas/SearchRequest' examples: TextSearch—ScopedToWorkspace: value: query: authentication system JWT tokens max_results: 5 workspace_id: - 42 summary: Text search — scoped to workspace description: Search within a specific workspace using hybrid text search with reranking. TextSearch—ScopedToFiles: value: query: quarterly revenue forecast max_results: 3 file_id: - 101 - 102 summary: Text search — scoped to files description: Search specific files only. TextSearch—AcrossAllDocuments: value: query: onboarding process max_results: 10 summary: Text search — across all documents description: Search across all documents the API key has access to. RawRetrieval—SkipScoring: value: query: incident response playbook max_results: 10 relevance_scoring: none summary: Raw retrieval — skip scoring description: Bypass relevance scoring for lower latency (relevance_scoring="none"). scores.relevance will be null. TextSearch—WithBoundingBoxes: value: query: authentication system JWT tokens max_results: 5 include_bboxes: true summary: Text search — with bounding boxes description: Append merged PDF bounding boxes to each result for overlaying chunk highlights. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Search only documents classified as legal contracts. Facet—AttributeFilter: value: query: compliance requirements workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: Search documents with specific attribute values, combined with workspace scoping. required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/SearchResponse' examples: TextSearchResult—WithRerankingAndFacetData: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: The indemnifying party shall hold harmless and indemnify the other party... score: 0.95 scores: text: 0.91 vision: null keyword: 0.43 multivector: 0.78 relevance: 0.95 source: file_id: 512 filename: customer-nda.pdf title: Customer NDA — Nimbus Labs mime_type: pdf size_bytes: 482113 page_start: 3 page_end: 4 total_pages: 12 tags: - id: 7 name: confidential content_types: - path: legal:contract:nda label: Non-Disclosure Agreement attribute_values: jurisdiction: value: - FR - US type: multi-select is_mutual: value: true type: boolean counterparty: value: Nimbus Labs type: text external_metadata: null workspace: id: 42 name: Legal Team summary: Text search result — with reranking and facet data description: Search with reranking applied (relevance_scoring="scoring_and_filtering", default). score equals scores.relevance (relevance score). Source includes compact content_types with attribute values. TextSearchResult—RawRetrieval: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: JWT tokens are signed using RS256 and expire after 1 hour. score: 1.65 scores: text: 0.91 vision: null keyword: 0.43 multivector: 0.78 relevance: null source: file_id: 512 filename: auth-system.pdf title: Authentication System Design mime_type: pdf size_bytes: 482113 page_start: 3 page_end: 4 total_pages: 12 tags: - id: 7 name: security content_types: [] external_metadata: null workspace: id: 42 name: Engineering Docs summary: Text search result — raw retrieval description: Raw retrieval without reranking (relevance_scoring="none"). score is the combined retrieval score (higher is better, no fixed upper bound). scores.relevance is null. TextSearchResult—WithBoundingBoxes: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: JWT tokens are signed using RS256 and expire after 1 hour. score: 0.95 scores: text: 0.91 vision: null keyword: 0.43 multivector: 0.78 relevance: 0.95 source: file_id: 512 filename: auth-system.pdf title: Authentication System Design mime_type: pdf size_bytes: 482113 page_start: 3 page_end: 4 total_pages: 12 tags: - id: 7 name: security content_types: [] external_metadata: null workspace: id: 42 name: Engineering Docs bboxes: - page_number: 3 x: 47.37 y: 528.28 width: 280.13 height: 95.42 unit: pdf_point origin: top_left - page_number: 4 x: 41.86 y: 98.0 width: 285.99 height: 158.67 unit: pdf_point origin: top_left summary: Text search result — with bounding boxes description: Response when include_bboxes=true. Each result gains a bboxes array of merged rectangles in PDF points (top-left origin, y extending downward). A chunk spanning pages 3 and 4 yields at least one rectangle per page. Empty list for vision/non-PDF/pre-v2.2.1 chunks. TextSearchResult—RerankerUnavailable: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: JWT tokens are signed using RS256 and expire after 1 hour. score: 1.65 scores: text: 0.91 vision: null keyword: 0.43 multivector: 0.78 relevance: null source: file_id: 512 filename: auth-system.pdf title: Authentication System Design mime_type: pdf size_bytes: 482113 page_start: 3 page_end: 4 total_pages: 12 tags: [] content_types: [] external_metadata: null workspace: id: 42 name: Engineering Docs warnings: - code: relevance reason: timeout summary: Text search result — reranker unavailable description: Reranker failed; results returned in retrieval order. score falls back to the combined retrieval score (no fixed upper bound) and scores.relevance is null. The warnings array identifies the degraded signal and failure reason. NoMatchingDocuments: value: results: [] summary: No matching documents description: Query returned no results — empty array with HTTP 200. description: Ranked search results. Empty array if no documents match. '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: BadRequest: value: id: null code: 400 error: bad_request detail: The request body could not be parsed as valid JSON. doc_url: https://developers.lighton.ai/errors#bad_request summary: Bad Request description: Request body is not valid JSON '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InsufficientPermissions: value: id: null code: 403 error: insufficient_permissions detail: None of the provided filters resolve to authorized resources. doc_url: https://developers.lighton.ai/errors#insufficient_permissions summary: Insufficient permissions description: API key has no authorized resources matching the provided filters. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError—ScopingConflict: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: file_id: - error: invalid_combination detail: file_id cannot be combined with workspace_id or tag_id. summary: Validation error — scoping conflict ValidationError—MaxResultsOutOfRange: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: max_results: - error: too_large detail: Ensure this value is less than or equal to 100. summary: Validation error — max_results out of range description: Field validation failure. '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: id: null code: 429 error: too_many_requests detail: Too many requests. Please try again later. doc_url: https://developers.lighton.ai/errors#too_many_requests summary: Too Many Requests description: Too many requests '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal server error SearchBackendUnavailable: value: id: null code: 500 error: search_backend_unavailable detail: Search backend temporarily unavailable. doc_url: https://developers.lighton.ai/errors#search_backend_unavailable summary: Search backend unavailable description: Unexpected server error, or the search backend is unreachable. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/users: get: operationId: api_v3_users_list description: |- ⚠️ **ALPHA ENDPOINT** - This endpoint is in alpha and subject to breaking changes. Use with caution in production environments. Get the list of users in your company. summary: List company users parameters: - in: query name: group_id schema: type: integer - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer tags: - Users security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedCompanyUserV3ResponseList' description: Paginated list of active users in the authenticated user's company. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': description: Not Found - group does not exist or belongs to another company. '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_users_create description: |- This endpoint allows to create a new company member. **Permissions:** - Admin, SysAdmin, Account Manager: can create users for any company - Company Admin: can create users for their own company **Throttling:** 60 requests per minute It is API Key protected and restricted to users with appropriate permissions. summary: Create a new company member tags: - Users requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCompanyMemberRequestSerializerV3' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateCompanyMemberRequestSerializerV3' multipart/form-data: schema: $ref: '#/components/schemas/CreateCompanyMemberRequestSerializerV3' required: true security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/CompanyMemberResponse' description: Company member created successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': description: Permission denied - insufficient rights to create company members '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal Server Error description: An unexpected error occurred '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/users/me: get: operationId: api_v3_users_me_retrieve description: Returns information on the authenticated user. summary: Get current user profile tags: - Users security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserInfo' description: Current user profile '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_users_me_partial_update description: | Updates settings for the authenticated user. **Updatable fields:** - `language`: User's preferred language - `skip_help_step`: Whether to skip help steps in the UI - `agent_instructions`: Custom instructions for AI agents - `terms_accepted`: Accept the latest terms and conditions (can only be set to true) - `persona`: What the user is trying to achieve (captured at onboarding) - `channel`: How the user will mostly interact (captured at onboarding) **Note:** Setting `terms_accepted` to false will result in a 400 error. summary: Update current user profile tags: - Users requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedCurrentUserMeUpdateRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedCurrentUserMeUpdateRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedCurrentUserMeUpdateRequest' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserInfo' description: The updated current user profile. '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: BadRequest: value: id: null code: 400 error: bad_request detail: The request body could not be parsed as valid JSON. doc_url: https://developers.lighton.ai/errors#bad_request summary: Bad Request description: Request body is not valid JSON '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/users/{id}: get: operationId: api_v3_users_retrieve description: |- This endpoint allows to retrieve a specific company member by ID. **Permissions:** - Admin, SysAdmin, SysDPO, Account Manager: can retrieve any user - Company Admin, Company DPO: can retrieve users from their own company only **Throttling:** 100 requests per minute It is API Key protected and restricted to users with appropriate permissions. summary: Retrieve a company member parameters: - in: path name: id schema: type: integer required: true tags: - Users security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/CompanyMemberResponse' description: Company member details retrieved successfully '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': description: Permission denied - insufficient rights to access this company member '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal Server Error description: An unexpected error occurred '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' put: operationId: api_v3_users_update description: |- This endpoint allows to update a specific company member by ID. **PUT:** Requires all fields (first_name, last_name, account_expiration_date, language). **PATCH:** Allows partial updates - only provide the fields you want to change. **Permissions:** - Admin, SysAdmin, Account Manager: can update any user - Company Admin: can update users from their own company only **Throttling:** 60 requests per minute It is API Key protected and restricted to users with appropriate permissions. summary: Update a company member parameters: - in: path name: id schema: type: integer required: true tags: - Users requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateCompanyMemberRequestSerializerV3' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/UpdateCompanyMemberRequestSerializerV3' multipart/form-data: schema: $ref: '#/components/schemas/UpdateCompanyMemberRequestSerializerV3' required: true security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/CompanyMemberResponse' description: Company member updated successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': description: Permission denied - insufficient rights to update this company member '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal Server Error description: An unexpected error occurred '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_users_partial_update description: |- This endpoint allows to update a specific company member by ID. **PUT:** Requires all fields (first_name, last_name, account_expiration_date, language). **PATCH:** Allows partial updates - only provide the fields you want to change. **Permissions:** - Admin, SysAdmin, Account Manager: can update any user - Company Admin: can update users from their own company only **Throttling:** 60 requests per minute It is API Key protected and restricted to users with appropriate permissions. summary: Partially update a company member parameters: - in: path name: id schema: type: integer required: true tags: - Users requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedUpdateCompanyMemberRequestSerializerV3' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedUpdateCompanyMemberRequestSerializerV3' multipart/form-data: schema: $ref: '#/components/schemas/PatchedUpdateCompanyMemberRequestSerializerV3' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/CompanyMemberResponse' description: Company member updated successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': description: Permission denied - insufficient rights to update this company member '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal Server Error description: An unexpected error occurred '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_users_destroy description: |- This endpoint allows to soft-delete a specific company member by ID. **Soft Delete Behavior:** - The user is marked as deleted and their `is_active` status is set to False, preventing login - API keys are immediately revoked - The user can be restored within the recovery period (default: 7 days) via the admin interface - After the recovery period, the user will be anonymized and permanently deleted by a background task **Permissions:** - Admin, SysAdmin, Account Manager: can delete any user except themselves - Company Admin: can delete users from their own company except themselves **Throttling:** 60 requests per minute It is API Key protected and restricted to users with appropriate permissions. summary: Delete a company member parameters: - in: path name: id schema: type: integer required: true tags: - Users security: - bearerAuth: [] responses: '204': description: Company member deleted successfully '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': description: Permission denied - insufficient rights to delete this company member '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: id: null code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. doc_url: https://developers.lighton.ai/errors#internal_server_error summary: Internal Server Error description: An unexpected error occurred '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/users/{id}/roles: get: operationId: api_v3_users_roles_retrieve description: |- This endpoint allows you to list the roles of a company member. It is restricted to admin and company admin users. summary: List roles of a company member parameters: - in: path name: id schema: type: integer description: The unique identifier of the user. required: true tags: - Users security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserRoles' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' put: operationId: api_v3_users_roles_update description: |- This endpoint allows you to update the roles of a company member. Note that this will update all the roles of the member. It is restricted to admin and company admin users. summary: Update roles of a company member parameters: - in: path name: id schema: type: integer description: The unique identifier of the user. required: true tags: - Users requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateCompanyMemberRolesRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/UpdateCompanyMemberRolesRequest' multipart/form-data: schema: $ref: '#/components/schemas/UpdateCompanyMemberRolesRequest' security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/CompanyMemberResponse' description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/keys: get: operationId: api_v3_keys_list description: |- List all API keys belonging to the authenticated user. Each entry exposes its workspace scope via `scopes`. Every scope entry carries a `scope_type`: - `workspace` — the key is explicitly scoped to that workspace, with its own per-workspace permission (`viewer`, `editor`, or `owner`). - `global` — the key has no explicit scope rows and reaches every workspace you can access; `scopes` then lists those workspaces with your own current role on each (the effective access ceiling). A global key never mixes the two types. summary: List API keys parameters: - in: query name: is_expired schema: type: boolean - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer tags: - API Keys security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedAPIKeyV3ResponseList' description: Paginated list of API keys belonging to the authenticated user. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_keys_create description: |- Create a new API key for the authenticated user. **The full key value is returned only once** in the creation response and cannot be retrieved again afterwards. `expires_at` is required: - A future datetime expires the key at that time. - `null` creates a key that never expires. **Workspace scoping (optional):** include `scopes` — a list of `{workspace_id, permission}` entries — to restrict the key to those workspaces. Each entry's `permission` is one of `viewer`, `editor`, or `owner`, and cannot exceed the role you currently hold on that workspace. Different scopes on the same key can carry different permissions. summary: Create API key tags: - API Keys requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAPIKeyV3Request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateAPIKeyV3Request' multipart/form-data: schema: $ref: '#/components/schemas/CreateAPIKeyV3Request' required: true security: - bearerAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateAPIKeyV3Response' description: API key created. The `key` field contains the full key value — save it now, it will not be shown again. '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: QuotaExceeded: value: id: null code: 400 error: bad_request detail: You have reached the maximum allowed number of api keys. Think about deleting some to create new ones. doc_url: https://developers.lighton.ai/errors#bad_request summary: Quota exceeded description: Bad Request — API key quota exceeded (domain limit). '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/keys/{id}: get: operationId: api_v3_keys_retrieve description: Retrieve a single API key belonging to the authenticated user, including its workspace scope. summary: Retrieve API key parameters: - in: path name: id schema: type: string required: true tags: - API Keys security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/APIKeyV3Response' description: The requested API key. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_keys_partial_update description: |- Update an existing API key. Supports renaming and replacing the workspace scope: - Pass `scopes` with a non-empty list of `{workspace_id, permission}` entries to replace the full scope set. Existing scope rows not in the new list are dropped. - Pass `scopes: []` to unscope the key entirely. - The permission ceiling on each scoped workspace is re-validated against your current role there. summary: Update API key parameters: - in: path name: id schema: type: string required: true tags: - API Keys requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedUpdateAPIKeyV3Request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedUpdateAPIKeyV3Request' multipart/form-data: schema: $ref: '#/components/schemas/PatchedUpdateAPIKeyV3Request' security: - bearerAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/APIKeyV3Response' description: The updated API key. '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: BadRequest: value: id: null code: 400 error: bad_request detail: The request body could not be parsed as valid JSON. doc_url: https://developers.lighton.ai/errors#bad_request summary: Bad Request description: Request body is not valid JSON '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_keys_destroy description: Revoke an API key. Revoked keys can no longer be used to authenticate requests. summary: Revoke API key parameters: - in: path name: id schema: type: string required: true tags: - API Keys security: - bearerAuth: [] responses: '204': description: API key revoked successfully. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: AlreadyRevoked: value: id: null code: 403 error: insufficient_permissions detail: This API key has already been revoked. doc_url: https://developers.lighton.ai/errors#insufficient_permissions summary: Already revoked description: Forbidden — the API key has already been revoked. '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/groups: get: operationId: api_v3_groups_list description: |- Get the list of groups you are member of. Each group reports the user's `user_role` (their highest role in the group) and the `members_count` (number of members). Results are paginated with 20 elements per page by default. summary: List user groups parameters: - in: query name: category schema: type: string enum: - company - custom description: Filter by group category. - in: query name: name schema: type: string description: Filter by group name (case-insensitive contains). - in: query name: ordering schema: type: string enum: - -created_at - -name - -updated_at - created_at - name - updated_at description: Order the results by `name`, `created_at` or `updated_at`. Prefix the field with `-` for descending order (e.g. `-created_at`). Defaults to `name`; entries sharing a name are ordered newest-first. - in: query name: page schema: type: integer description: A page number within the paginated result set. - in: query name: page_size schema: type: integer description: 'The number of results to return per page (default: 20, max: 100).' - in: query name: user_role schema: type: string enum: - member - owner description: Filter by the role of the authenticated user in the group. tags: - User Groups security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedUserGroupV3ResponseList' description: '' '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/groups/{id}: get: operationId: api_v3_groups_retrieve description: |- Retrieve the details of a group you are member of. Members are not included in the response — use the dedicated `/groups/{id}/members` endpoint to retrieve them. Returns the user's `user_role` (their highest role in the group) and the `members_count` (number of members). summary: Get group details parameters: - in: path name: id schema: type: integer required: true tags: - User Groups security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserGroupV3Response' description: Group details '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' put: operationId: api_v3_groups_update description: |- Update the name and description of a custom group you own. Members are managed through the `/api/v3/groups/{id}/members` endpoints, not here. PUT requires all fields to be provided. Only an owner of the group may update it; admin roles are not considered (admins use the `/company/` or `/instance/` level endpoints). Only custom groups can be updated. Group name must be unique within the company. summary: Fully update a group (PUT) parameters: - in: path name: id schema: type: integer required: true tags: - User Groups requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateGroupRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/UpdateGroupRequest' multipart/form-data: schema: $ref: '#/components/schemas/UpdateGroupRequest' required: true security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserGroupV3Response' description: Group updated successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '409': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Conflict: value: id: null code: 409 error: conflict detail: A resource with this name already exists. doc_url: https://developers.lighton.ai/errors#conflict description: A resource with this name already exists '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' patch: operationId: api_v3_groups_partial_update description: |- Partially update a custom group you own (name or description). PATCH allows updating only the fields you want to change. Only an owner of the group may update it; admin roles are not considered (admins use the `/company/` or `/instance/` level endpoints). Only custom groups can be updated. Group name must be unique within the company. summary: Partially update a group (PATCH) parameters: - in: path name: id schema: type: integer required: true tags: - User Groups requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedPatchGroupRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedPatchGroupRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedPatchGroupRequest' security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/UserGroupV3Response' description: Group updated successfully '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '409': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Conflict: value: id: null code: 409 error: conflict detail: A resource with this name already exists. doc_url: https://developers.lighton.ai/errors#conflict description: A resource with this name already exists '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' delete: operationId: api_v3_groups_destroy description: |+ Delete a group of usersNote that if the users group could not be deleted because of protected dependencies, these dependencies will be list. summary: Delete group of users parameters: - in: path name: id schema: type: integer description: The unique identifier of the users group. required: true tags: - User Groups security: - bearerAuth: [] - {} responses: '200': description: No response body '409': content: application/json: schema: $ref: '#/components/schemas/DeleteUsersGroupProtectedDependencies' description: '' '403': content: application/json: schema: description: Users group not found or you don't have permission to delete it description: '' '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/groups/{id}/members: get: operationId: api_v3_groups_members_retrieve description: |- Get the list of members for a group you own. Only an owner of the group may list its members; admin roles are not considered. Only user members are returned (groups within groups are not supported yet). summary: List the members of a group you own parameters: - in: path name: id schema: type: integer required: true tags: - User Groups security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/GroupMembersResponse' description: List of group members with their roles '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' post: operationId: api_v3_groups_members_create description: |- Add a new member to a custom group you own. Only an owner of the group may add members; admin roles are not considered. The target user must belong to the same company as the group. Only custom groups can be modified. summary: Add a new member to a custom group you own parameters: - in: path name: id schema: type: integer required: true tags: - User Groups requestBody: content: application/json: schema: $ref: '#/components/schemas/AddGroupMemberRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/AddGroupMemberRequest' multipart/form-data: schema: $ref: '#/components/schemas/AddGroupMemberRequest' required: true security: - bearerAuth: [] - {} responses: '201': content: application/json: schema: $ref: '#/components/schemas/GroupMembersResponse' description: Member added successfully. Returns all group members with their roles. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '409': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Conflict: value: id: null code: 409 error: conflict detail: A resource with this name already exists. doc_url: https://developers.lighton.ai/errors#conflict description: A resource with this name already exists '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' put: operationId: api_v3_groups_members_update description: |- Bulk replace the entire member list of a custom group you own. Only an owner of the group may replace its members; admin roles are not considered. All users must belong to the group's company. You always remain an owner of your own group, so an empty `users` array removes every other member but keeps you as the owner. Only custom groups can be modified. summary: Bulk replace the members of a custom group you own parameters: - in: path name: id schema: type: integer required: true tags: - User Groups requestBody: content: application/json: schema: $ref: '#/components/schemas/ReplaceGroupMembersRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/ReplaceGroupMembersRequest' multipart/form-data: schema: $ref: '#/components/schemas/ReplaceGroupMembersRequest' required: true security: - bearerAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/GroupMembersResponse' description: Members replaced successfully. Returns all group members with their roles. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /api/v3/groups/{id}/members/users/{user_id}: delete: operationId: api_v3_groups_members_users_destroy description: |- Remove a user from a group you own. Only an owner of the group may remove members; admin roles are not considered. Only custom groups can be modified. summary: Remove a user from a group you own parameters: - in: path name: id schema: type: integer required: true - in: path name: user_id schema: type: integer required: true tags: - User Groups security: - bearerAuth: [] - {} responses: '204': description: User removed successfully from the group '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '404': description: Not Found - Group not found, user not found, or user not a member of the group '503': description: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' /scim/v2/Groups: get: operationId: scim_v2_Groups_retrieve description: |- Automatic filtering on company defined in get_extra_model_filter_kwargs_getter() We disable PUT as Microsoft does not need it summary: List or Retrieve a group tags: - SCIM security: - bearerAuth: [] responses: '200': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMGroupResponse' description: Groups list '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required post: operationId: scim_v2_Groups_create description: |- Automatic filtering on company defined in get_extra_model_filter_kwargs_getter() We disable PUT as Microsoft does not need it summary: Create a group tags: - SCIM requestBody: content: application/json: schema: $ref: '#/components/schemas/SCIMGroupRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SCIMGroupRequest' multipart/form-data: schema: $ref: '#/components/schemas/SCIMGroupRequest' required: true security: - bearerAuth: [] responses: '201': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMGroupCreateResponse' description: Groups creation '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required patch: operationId: scim_v2_Groups_partial_update description: |- Automatic filtering on company defined in get_extra_model_filter_kwargs_getter() We disable PUT as Microsoft does not need it summary: Update a group tags: - SCIM requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedSCIMGroupModifyRequest' examples: RenameTheGroup: value: schemas: - urn:ietf:params:scim:api:messages:2.0:PatchOp Operations: - op: replace path: displayName value: 1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName summary: Rename the group AddAMemberToTheGroup: value: schemas: - urn:ietf:params:scim:api:messages:2.0:PatchOp Operations: - op: add path: members value: - value: f648f8d5ea4e4cd38e9c summary: Add a member to the group RemoveAMemberFromTheGroup: value: schemas: - urn:ietf:params:scim:api:messages:2.0:PatchOp Operations: - op: remove path: members value: - value: f648f8d5ea4e4cd38e9c summary: Remove a member from the group application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedSCIMGroupModifyRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedSCIMGroupModifyRequest' security: - bearerAuth: [] responses: '200': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMGroupCreateResponse' description: Modified group '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required '404': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: GroupNotFound: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Resource 123 not found status: 404 summary: Group not found description: '' delete: operationId: scim_v2_Groups_destroy description: |- Automatic filtering on company defined in get_extra_model_filter_kwargs_getter() We disable PUT as Microsoft does not need it summary: Delete a group tags: - SCIM security: - bearerAuth: [] responses: '204': description: Group successfully deleted '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required '404': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: GroupNotFound: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Resource 123 not found status: 404 summary: Group not found description: '' /scim/v2/ResourceTypes: get: operationId: scim_v2_ResourceTypes_retrieve summary: List or Retrieve resource types tags: - SCIM security: - bearerAuth: [] responses: '200': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMResourceTypesResponse' description: Resource Types list '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required /scim/v2/Schemas: get: operationId: scim_v2_Schemas_retrieve summary: List or Retrieve schemas tags: - SCIM security: - bearerAuth: [] responses: '200': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMSchemasResponse' description: '' '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required /scim/v2/ServiceProviderConfig: get: operationId: scim_v2_ServiceProviderConfig_retrieve summary: Retrieve Service Provider Configuration tags: - SCIM security: - bearerAuth: [] responses: '200': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMServiceProviderConfigResponse' description: Service provider configuration response '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required /scim/v2/Users: get: operationId: scim_v2_Users_retrieve description: Automatic filtering on company defined in get_extra_model_filter_kwargs_getter() summary: List or Retrieve users tags: - SCIM security: - bearerAuth: [] responses: '200': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMPaginatedUsers' description: Users list '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required post: operationId: scim_v2_Users_create description: Automatic filtering on company defined in get_extra_model_filter_kwargs_getter() summary: Create a user tags: - SCIM requestBody: content: application/json: schema: $ref: '#/components/schemas/SCIMUserRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SCIMUserRequest' multipart/form-data: schema: $ref: '#/components/schemas/SCIMUserRequest' required: true security: - bearerAuth: [] responses: '200': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMUserResponse' description: Created user '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required put: operationId: scim_v2_Users_update description: Automatic filtering on company defined in get_extra_model_filter_kwargs_getter() summary: Replace a user tags: - SCIM requestBody: content: application/json: schema: $ref: '#/components/schemas/SCIMUserRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SCIMUserRequest' multipart/form-data: schema: $ref: '#/components/schemas/SCIMUserRequest' required: true security: - bearerAuth: [] responses: '200': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMUserResponse' description: Replaced user '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required '404': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: UserNotFound: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Resource 123 not found status: 404 summary: User not found description: '' patch: operationId: scim_v2_Users_partial_update description: Automatic filtering on company defined in get_extra_model_filter_kwargs_getter() summary: Update a user tags: - SCIM requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedSCIMUserModifyRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedSCIMUserModifyRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedSCIMUserModifyRequest' security: - bearerAuth: [] responses: '200': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMUserResponse' description: Modified user '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required '404': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: UserNotFound: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Resource 123 not found status: 404 summary: User not found description: '' delete: operationId: scim_v2_Users_destroy description: |- Override default SCIM delete to anonymize immediately without soft/hard delete. SCIM services (e.g., Microsoft Entra ID) handle soft-delete on their side, so we bypass our soft-delete mechanism entirely - we just anonymize the user in-place and leave them in the database. summary: Delete a user tags: - SCIM security: - bearerAuth: [] responses: '204': description: User successfully deleted '401': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: Unauthorized: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Unauthorized status: 401 description: Authentication required '404': content: application/scim+json: schema: $ref: '#/components/schemas/SCIMErrorResponse' examples: UserNotFound: value: schemas: - urn:ietf:params:scim:api:messages:2.0:Error detail: Resource 123 not found status: 404 summary: User not found description: '' components: schemas: APIKeyScope: type: object properties: workspace_id: type: integer workspace_name: type: string workspace_upload_method: type: string workspace_datasource_type: type: - string - 'null' readOnly: true role: type: string scope_type: allOf: - $ref: '#/components/schemas/ScopeTypeEnum' readOnly: true required: - role - scope_type - workspace_datasource_type - workspace_id - workspace_name - workspace_upload_method APIKeyScopeRequest: type: object description: One entry in the `scopes` list — a workspace + a role on it. properties: workspace_id: type: integer minimum: 1 role: $ref: '#/components/schemas/WorkspaceMemberRoleEnum' required: - role - workspace_id APIKeyV3Response: type: object properties: id: type: string name: type: string prefix: type: string created_at: type: string format: date-time expires_at: type: - string - 'null' format: date-time scopes: type: array items: $ref: '#/components/schemas/APIKeyScope' readOnly: true required: - created_at - expires_at - id - name - prefix - scopes APIV3BatchErrorResponse: type: object properties: id: type: - string - 'null' description: Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page index: type: integer description: 0-based position of the failing action in the batch. required: - code - detail - doc_url - error - id APIV3ErrorResponse: type: object properties: id: type: - string - 'null' description: Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page required: - code - detail - doc_url - error - id APIV3FieldError: type: object properties: error: type: string description: Error code / translation key detail: type: string description: Human-readable description of the field error required: - detail - error APIV3ValidationErrorResponse: type: object properties: id: type: - string - 'null' description: Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page fields: type: object additionalProperties: type: array items: $ref: '#/components/schemas/APIV3FieldError' description: Field-level validation errors keyed by field name required: - code - detail - doc_url - error - id AddGroupMemberRequest: type: object description: 'V3 API: Add a single member to a group' properties: user_id: type: integer description: ID of the user to add to the group role: allOf: - $ref: '#/components/schemas/GroupMemberRoleEnum' description: |- Role of the user in the group (owner or member) * `owner` - owner * `member` - member required: - role - user_id AddModelToAliasRequest: type: object properties: ml_model_uuid: type: string format: uuid description: UUID of the ML model to link. priority: type: integer default: 0 description: 'Fallback priority: 0 = primary, 1 = first fallback, etc.' required: - ml_model_uuid AgentFavoriteListResponseSchema: type: object properties: favorites: type: array items: $ref: '#/components/schemas/AgentFavoriteSchema' required: - favorites AgentFavoriteSchema: type: object properties: id: type: integer agent_name: type: string agent_description: type: - string - 'null' agent_id: type: integer user_id: type: integer required: - agent_description - agent_id - agent_name - id - user_id AgentListResponseSchema: type: object properties: count: type: integer next: type: - string - 'null' previous: type: - string - 'null' results: type: array items: $ref: '#/components/schemas/AgentSchema' required: - count - next - previous - results AgentSchema: type: object properties: id: type: integer name: type: string description: type: - string - 'null' instructions: type: - string - 'null' company: $ref: '#/components/schemas/CompanySchema' group: $ref: '#/components/schemas/GroupSchema' workspaces: type: array items: $ref: '#/components/schemas/WorkspaceSchema' tools: $ref: '#/components/schemas/AgentToolsSchema' is_default: type: boolean ownership: type: string scope_workspaces_by_group: type: boolean scoped_workspace_ids: type: array items: type: integer ml_model: type: - string - 'null' format: uuid ml_model_alias: type: - string - 'null' format: uuid is_current_user_favorite: type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time required: - company - created_at - description - group - id - instructions - is_current_user_favorite - is_default - ml_model - ml_model_alias - name - ownership - scope_workspaces_by_group - scoped_workspace_ids - tools - updated_at - workspaces AgentToolsSchema: type: object properties: native: type: array items: $ref: '#/components/schemas/NativeToolSchema' mcp_servers: type: array items: $ref: '#/components/schemas/MCPServerSchema' required: - mcp_servers - native Alias: type: object properties: id: type: string format: uuid description: Unique ID for this alias company_id: type: integer description: ID of the company which owns this alias. name: type: string description: Display name for this model alias technical_name: type: string description: Company-wide unique technical name for this model alias description: type: string description: Description of the alias. model_type: allOf: - $ref: '#/components/schemas/ModelTypeEnum' description: |- Type of models represented by this alias (eg. 'Large Language Model', 'Embedding Model','Vision Language Model', 'Multi-Vector Model) * `Large Language Model` - Large Language Model * `Embedding Model` - Embedding Model * `Vision Language Model` - Vision Language Model * `Multi-Vector Model` - Multi-Vector Model required: - company_id - description - id - model_type - name - technical_name AliasDetails: type: object properties: id: type: string format: uuid description: Unique ID for this alias company_id: type: integer description: ID of the company which owns this alias. name: type: string description: Display name for this model alias technical_name: type: string description: Company-wide unique technical name for this model alias description: type: string description: Description of the alias. model_type: allOf: - $ref: '#/components/schemas/ModelTypeEnum' description: |- Type of models represented by this alias (eg. 'Large Language Model', 'Embedding Model','Vision Language Model', 'Multi-Vector Model) * `Large Language Model` - Large Language Model * `Embedding Model` - Embedding Model * `Vision Language Model` - Vision Language Model * `Multi-Vector Model` - Multi-Vector Model linked_models: type: array items: $ref: '#/components/schemas/AliasToMLModelMapping' description: Models associated with this alias. required: - company_id - description - id - linked_models - model_type - name - technical_name AliasRoutingExcludedModel: type: object properties: id: type: string format: uuid description: Unique ID of the model name: type: string description: Display name of the model technical_name: type: string description: Technical name of the model reason: type: string description: Reason the model was excluded from routing (e.g. 'unhealthy') required: - id - name - reason - technical_name AliasRoutingModelRef: type: object properties: id: type: string format: uuid description: Unique ID of the model name: type: string description: Display name of the model technical_name: type: string description: Technical name of the model required: - id - name - technical_name AliasRoutingResult: type: object properties: primary: allOf: - $ref: '#/components/schemas/AliasRoutingModelRef' description: The model that would be selected as primary for inference fallbacks: type: array items: $ref: '#/components/schemas/AliasRoutingModelRef' default: [] description: Ordered fallback models, from highest to lowest priority excluded: type: array items: $ref: '#/components/schemas/AliasRoutingExcludedModel' default: [] description: Models excluded from routing (e.g. currently unhealthy) required: - primary AliasToMLModelMapping: type: object properties: priority: type: integer description: How priorized is this model if reffered by an alias assigned to multiple models,with highest priority being 0. model_id: type: string format: uuid description: ID of the model associated with the alias model_name: type: string description: Display name for the model associated with the alias model_technical_name: type: string description: Instance-wide unique technical name for this model such as it is set in the mode gateway configuration required: - model_id - model_name - model_technical_name - priority AnswerError: type: object properties: code: type: - string - 'null' message: type: - string - 'null' AnswerResponse: type: object properties: id: type: string object: type: string default: turn thread: type: string status: $ref: '#/components/schemas/AnswerResponseStatusEnum' error: oneOf: - $ref: '#/components/schemas/AnswerError' - type: 'null' messages: type: array items: $ref: '#/components/schemas/MessageResponse' created_at: type: string format: date-time liked: type: - boolean - 'null' required: - created_at - id - messages - status - thread AnswerResponseStatusEnum: enum: - running - completed - failed - cancelled - cancelling type: string description: |- * `running` - running * `completed` - completed * `failed` - failed * `cancelled` - cancelled * `cancelling` - cancelling AskRequest: type: object description: |- DRF serializer mixin providing ``content_type`` and ``attribute`` fields. Compose into any request serializer via multiple inheritance:: class SearchRequestSerializer(FacetFilterFieldsMixin, serializers.Serializer): query = serializers.CharField(...) # content_type and attribute inherited from the mixin properties: content_type: type: array items: type: string description: 'Filter by content type path. Multiple values are OR. Exact-or-subtree matching by default (e.g. `legal` matches legal, legal:contract). Wildcards: `*contract*` (contains), `legal:contract*` (prefix).' attribute: type: array items: type: string description: 'Filter by attribute value. **Repeated `attribute` entries are ANDed; values inside one entry are ORed with `|`** (pipe is the recommended OR delimiter — comma also works but can be ambiguous with multi-key values). Example: `attribute=fiscal_year:2024|2025&attribute=status:active` → (fiscal_year 2024 OR 2025) AND (status active). Formats: `name` (has any value), `name:value` (exact), `name:>value` / `name:>=value` (gt/gte), `name:``) and extract (``GET /api/v3/extract/``) polling envelopes: ``pages_processed`` is the count of pages done so far and ``percentage`` is the completion percentage [0, 100] derived from it. properties: percentage: title: Percentage type: integer pages_processed: title: Pages Processed type: integer required: - percentage - pages_processed title: JobProgress type: object KindEnum: enum: - library - folder type: string description: |- * `library` - library * `folder` - folder ListAnswerResponse: type: object properties: count: type: - integer - 'null' next: type: - string - 'null' previous: type: - string - 'null' results: type: array items: $ref: '#/components/schemas/AnswerResponse' required: - count - next - previous - results ListThreadsResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/ThreadResponse' readOnly: true count: type: - integer - 'null' readOnly: true next: type: - string - 'null' readOnly: true previous: type: - string - 'null' readOnly: true required: - count - next - previous - results LoginMethodEnum: enum: - password - sso - ldap type: string description: |- * `password` - password * `sso` - sso * `ldap` - ldap MCPServerListResponse: type: object properties: mcp_servers: type: array items: $ref: '#/components/schemas/MCPServerResponse' required: - mcp_servers MCPServerResponse: type: object properties: id: type: string format: uuid object: type: string default: mcp_server name: type: string url: type: - string - 'null' authentication_method: type: string has_credentials: type: boolean enabled: type: boolean availability_scope: type: string is_global: type: boolean company_id: type: - integer - 'null' group_id: type: - integer - 'null' required: - authentication_method - availability_scope - enabled - has_credentials - id - is_global - name MCPServerSchema: type: object properties: id: type: string name: type: string object: type: string default: mcp_server required: - id - name MaintenancePeriod: type: object properties: endpoint_category_names: description: Human-readable category names for the selected endpoint groups. E.g. ["Indexing & Parsing"] frontend_mode: $ref: '#/components/schemas/FrontendModeEnum' reason: type: string maxLength: 500 started_at: type: string format: date-time readOnly: true required: - started_at MessagePartResponse: type: object properties: type: $ref: '#/components/schemas/MessagePartResponseTypeEnum' text: type: - string - 'null' reasoning: type: - string - 'null' tool_call: oneOf: - $ref: '#/components/schemas/ToolCallResponse' - type: 'null' document: oneOf: - $ref: '#/components/schemas/DocumentPart' - type: 'null' workspace: oneOf: - $ref: '#/components/schemas/WorkspacePart' - type: 'null' tag: oneOf: - $ref: '#/components/schemas/Tag' - type: 'null' required: - type MessagePartResponseTypeEnum: enum: - text - reasoning - tool_call - document - workspace - tag type: string description: |- * `text` - text * `reasoning` - reasoning * `tool_call` - tool_call * `document` - document * `workspace` - workspace * `tag` - tag MessageResponse: type: object properties: id: type: string object: type: string default: message role: $ref: '#/components/schemas/MessageResponseRoleEnum' parts: type: array items: $ref: '#/components/schemas/MessagePartResponse' force_tool: oneOf: - $ref: '#/components/schemas/ToolResponse' - type: 'null' immediate_final_answer: type: - boolean - 'null' created_at: type: string format: date-time required: - created_at - id - parts - role MessageResponseRoleEnum: enum: - user - assistant type: string description: |- * `user` - user * `assistant` - assistant ModeEnum: enum: - text - vision type: string description: |- * `text` - text * `vision` - vision ModelTypeEnum: enum: - Large Language Model - Embedding Model - Vision Language Model - Multi-Vector Model type: string description: |- * `Large Language Model` - Large Language Model * `Embedding Model` - Embedding Model * `Vision Language Model` - Vision Language Model * `Multi-Vector Model` - Multi-Vector Model NativeToolListResponse: type: object properties: tools: type: array items: $ref: '#/components/schemas/NativeToolResponse' required: - tools NativeToolResponse: type: object properties: id: type: string object: type: string default: tool name: type: string type: $ref: '#/components/schemas/ToolTypeEnum' require_document: type: - boolean - 'null' accepted_file_types: type: - array - 'null' items: type: string required: - id - name - type NativeToolSchema: type: object properties: id: type: string name: type: string object: type: string default: tool required: - id - name NullEnum: type: 'null' OcrRequest: type: object properties: file: type: string format: uri description: The document to parse. model: type: - string - 'null' description: technical_name of an enabled parser model. Falls back to platform default. pages: type: string default: all description: 'Page range to parse. Accepted formats: "all" (default), a single page "3", a range "1-5", comma-separated pages "1,3,7", or mixed "2-4,8". Duplicates are ignored. Maximum 16 pages per request — using "all" on a document exceeding this limit returns 400. For larger documents, paginate with sequential range calls.' enable_antilooping: type: boolean default: true description: Detect repetitive generation loops and retry the page with progressively higher temperatures (above `temperature`) until the output is non-looping. Disable to get a single VLM call at the exact `temperature` requested. temperature: type: - number - 'null' format: double maximum: 2.0 minimum: 0.0 default: 0.2 description: 'Sampling temperature for the VLM. Lower values (e.g. 0.1) produce more deterministic results; higher values (e.g. 1.0) increase variety. Range: 0.0–2.0.' max_tokens: type: - integer - 'null' maximum: 16384 minimum: 1 default: 5000 description: 'Maximum number of tokens the model can generate per page. Higher values allow longer outputs but increase processing time. Range: 1–16384.' repetition_penalty: type: - number - 'null' format: double maximum: 2.0 minimum: 1.0 default: 1.0 description: 'Penalizes repeated tokens to reduce redundant output. A value of 1.0 applies no penalty; higher values (e.g. 1.2) discourage repetition more strongly. Range: 1.0–2.0.' required: - file OcrResponse: type: object properties: model: type: string total_pages: type: integer pages_parsed: type: array items: type: integer processing_time_ms: type: integer enable_antilooping: type: boolean sampling_params: $ref: '#/components/schemas/SamplingParams' pages: type: array items: $ref: '#/components/schemas/Page' required: - enable_antilooping - model - pages - pages_parsed - processing_time_ms - sampling_params - total_pages OpEnum: enum: - add - remove - replace type: string description: |- * `add` - add * `remove` - remove * `replace` - replace OwnershipEnum: enum: - personal - company - team type: string description: |- * `personal` - personal * `company` - company * `team` - team Page: type: object description: |- Canonical per-page document text object. Originates with /parse and is reused by /ocr and /files (the latter imports it from here) so a client can switch between live parsing and reading an already-ingested file without reshaping page data. Defined once and reused everywhere — never redefine this shape per app. Extensible: future per-page fields (tables, images, confidence, ...) can be added here without breaking callers that only consume ``index`` + ``markdown``. properties: index: type: integer description: Page number within the document (1-based). markdown: type: string description: Page text rendered as Markdown. required: - index - markdown PaginatedAPIKeyV3ResponseList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/APIKeyV3Response' PaginatedCompanyUserV3ResponseList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/CompanyUserV3Response' PaginatedExternalAPIKeyResponseList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/ExternalAPIKeyResponse' PaginatedFileListResponseSerializerV3List: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/FileListResponseSerializerV3' PaginatedStandardWorkspaceV3ListResponseList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/StandardWorkspaceV3ListResponse' PaginatedTagListResponseSerializerV3List: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/TagListResponseSerializerV3' PaginatedUserGroupV3ResponseList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/UserGroupV3Response' ParseAsyncResponse: type: object description: Returned by ``POST /api/v3/parse`` with ``options.async=true`` — caller polls ``GET /api/v3/parse/``. properties: id: type: string description: Parse job id (e.g. `parse_Kg`); poll via GET /api/v3/parse/. status: type: string description: Initial status — typically 'pending'. created_at: type: string format: date-time description: When the job was accepted. required: - created_at - id - status ParseDocument: type: object properties: filename: type: string page_count: type: - integer - 'null' file_size_bytes: type: integer mime_type: type: string required: - file_size_bytes - filename - mime_type - page_count ParseError: type: object description: Failure details surfaced on terminal-failed async parse jobs. properties: message: type: string required: - message ParseJobStatus: type: object description: |- Returned by ``GET /api/v3/parse/`` — async parse job status + (once terminal) result. Same shape as the sync ``ParseResponseSerializer`` but with completion fields (``result``, ``usage``, ``completed_at``, ``processing_time_ms``, ``document.page_count``) allowed to be null while the job is still in flight, plus an ``error`` block populated only on terminal failure. properties: id: type: string status: type: string created_at: type: string format: date-time completed_at: type: - string - 'null' format: date-time processing_time_ms: type: - integer - 'null' document: oneOf: - $ref: '#/components/schemas/ParseDocument' - type: 'null' result: oneOf: - $ref: '#/components/schemas/ParseResult' - type: 'null' usage: oneOf: - $ref: '#/components/schemas/ParseUsage' - type: 'null' progress: oneOf: - $ref: '#/components/schemas/ParseProgress' - type: 'null' error: oneOf: - $ref: '#/components/schemas/ParseError' - type: 'null' required: - completed_at - created_at - document - error - id - processing_time_ms - progress - result - status - usage ParseJsonRequest: type: object properties: document: type: string format: uri description: Publicly accessible URL of the document to parse. options: type: object properties: async: type: boolean default: false description: Queue the document for asynchronous parsing and return 202 with a job id. additionalProperties: true description: 'Parse options. Currently supports `{"async": true}` to queue the document.' required: - document ParseMultipartRequest: type: object properties: file: type: string format: binary description: The document to parse. options: type: object properties: async: type: boolean default: false description: Queue the document for asynchronous parsing and return 202 with a job id. additionalProperties: true description: 'Parse options as a JSON-encoded string. Currently supports `{"async": true}` to queue the document.' required: - file ParseProgress: type: object description: Live progress while a polled async job is in flight. properties: percentage: type: integer description: Completion percentage [0, 100]. pages_processed: type: integer description: Pages parsed so far. required: - pages_processed - percentage ParseResponse: type: object description: Synchronous ``POST /api/v3/parse`` response — the parse completed inline. properties: id: type: string status: type: string created_at: type: string format: date-time completed_at: type: string format: date-time processing_time_ms: type: integer document: $ref: '#/components/schemas/ParseDocument' result: $ref: '#/components/schemas/ParseResult' usage: $ref: '#/components/schemas/ParseUsage' required: - completed_at - created_at - document - id - processing_time_ms - result - status - usage ParseResult: type: object properties: pages: type: array items: $ref: '#/components/schemas/Page' required: - pages ParseUsage: type: object properties: pages_processed: type: integer required: - pages_processed PatchedAnswerFeedbackRequest: type: object properties: liked: type: - boolean - 'null' PatchedBudgetAlertBulkToggleRequest: properties: is_enabled: description: Enable or disable all alerts at once. title: Is Enabled type: boolean required: - is_enabled title: BudgetAlertBulkToggleRequest type: object PatchedBudgetAlertUpdateRequest: properties: is_enabled: anyOf: - type: boolean - type: 'null' default: null description: Whether this alert is active. title: Is Enabled threshold_type: anyOf: - enum: - percentage - absolute type: string - type: 'null' default: null description: '''percentage'' of budget or ''absolute'' EUR amount.' title: Threshold Type threshold_value: anyOf: - pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: string - type: 'null' default: null description: e.g. 75.00 for 75% or 500.00 for 500 EUR. title: Threshold Value title: BudgetAlertUpdateRequest type: object PatchedCreateAnswerFlagRequest: properties: comment: title: Comment type: string docs_shared: title: Docs Shared type: boolean include_previous_messages: default: false title: Include Previous Messages type: boolean required: - comment - docs_shared title: CreateAnswerFlagRequest type: object PatchedCurrentUserMeUpdateRequest: type: object properties: language: $ref: '#/components/schemas/PreferredLanguageEnum' agent_instructions: type: - string - 'null' skip_help_step: type: boolean terms_accepted: type: boolean persona: oneOf: - $ref: '#/components/schemas/PersonaEnum' - $ref: '#/components/schemas/NullEnum' channel: oneOf: - $ref: '#/components/schemas/ChannelEnum' - $ref: '#/components/schemas/NullEnum' PatchedFileUpdateRequestSerializerV3: type: object description: |- Request serializer for PATCH /api/v3/files/{id} endpoint. Allows partial updates to mutable document fields: - title: Update the document title - tags: Replace ALL tags for the document (both manual and auto-assigned) - external_metadata: Create or update external source metadata Immutable fields (if provided, will return 400): - file, filename, workspace_id, parser, etc. properties: title: type: string description: Updated title for the document. maxLength: 255 tags: type: array items: type: integer description: List of tag IDs to replace ALL existing tags (both manual and auto-assigned). To remove all tags when using multipart format, send [0] as the sentinel value. external_metadata: oneOf: - $ref: '#/components/schemas/ExternalMetadataRequest' - type: 'null' description: External source metadata to create or update. `external_id` is required when no external metadata record exists yet. Fields in `additional_metadata` are merged (not replaced) with existing values. PatchedPatchGroupRequest: type: object description: 'V3 API: Partially update an existing user group (PATCH) - all fields optional' properties: name: type: string description: Name of the group maxLength: 254 description: type: - string - 'null' description: Description of the group PatchedSCIMGroupModifyRequest: type: object properties: schemas: type: array items: type: string default: - urn:ietf:params:scim:api:messages:2.0:PatchOp Operations: type: array items: $ref: '#/components/schemas/SCIMGroupModifyOperationRequest' PatchedSCIMUserModifyRequest: type: object properties: schemas: type: array items: type: string default: - urn:ietf:params:scim:api:messages:2.0:PatchOp Operations: type: array items: $ref: '#/components/schemas/SCIMUserModifyOperationRequest' PatchedTurnActionRequest: oneOf: - $ref: '#/components/schemas/PatchedAnswerFeedbackRequest' - $ref: '#/components/schemas/PatchedCreateAnswerFlagRequest' PatchedUpdateAPIKeyV3Request: type: object description: Reject any request fields not declared on the serializer. properties: name: type: string maxLength: 250 scopes: type: array items: $ref: '#/components/schemas/APIKeyScopeRequest' description: Replace the key's full scope set. Pass an empty list to unscope the key. Each entry's role is re-validated against your current role on the workspace. PatchedUpdateAgentRequest: type: object properties: name: type: - string - 'null' description: type: - string - 'null' instructions: type: - string - 'null' scope_workspaces_by_group: type: - boolean - 'null' native_tool_ids: type: - array - 'null' items: type: string format: uuid mcp_server_ids: type: - array - 'null' items: type: string format: uuid scoped_workspace_ids: type: - array - 'null' items: type: integer ml_model: type: - string - 'null' format: uuid ml_model_alias: type: - string - 'null' format: uuid PatchedUpdateAliasRequest: type: object properties: name: type: - string - 'null' description: Display name for the alias. technical_name: type: - string - 'null' description: Company-wide unique technical identifier. description: type: - string - 'null' description: Optional description of the alias. PatchedUpdateCompanyMemberRequestSerializerV3: type: object properties: first_name: type: string description: The first name of the user. last_name: type: string description: The last name of the user. account_expiration_date: type: string format: date-time description: The account expiration date and time with timezone. language: allOf: - $ref: '#/components/schemas/PreferredLanguageEnum' description: |- The preferred language of the user. * `ar` - Arabic * `en` - English * `fr` - French * `de` - German PatchedUpdateMCPServerRequest: type: object properties: name: type: - string - 'null' url: type: - string - 'null' authentication_method: oneOf: - $ref: '#/components/schemas/AuthenticationMethodEnum' - $ref: '#/components/schemas/NullEnum' credentials: type: - string - 'null' enabled: type: - boolean - 'null' availability_scope: oneOf: - $ref: '#/components/schemas/AvailabilityScopeEnum' - $ref: '#/components/schemas/NullEnum' authorized_company_id: type: - integer - 'null' authorized_group_id: type: - string - 'null' format: uuid PatchedUpdateModelPriorityRequest: type: object properties: priority: type: integer description: New priority value for this mapping. PatchedUpdateThreadRequest: type: object properties: name: type: string maxLength: 255 is_archived: type: boolean PatchedUpdateWorkspaceV3Request: type: object properties: name: type: string description: 'Workspace name (max 100 characters, cannot be empty). When sent together with `deleted_at: null` (restore), the workspace is restored under this name — used to resolve a collision when the original name was re-taken by a live workspace during the grace period.' description: type: string description: 'Workspace description. Send empty string or null to clear. May be sent together with `deleted_at: null` (restore) to set the description as part of the restore request; a name collision rejects the whole request before the description is applied. `members` and `datasource` are not accepted on a restore request — restore first, then PATCH them.' members: description: 'Members with roles in format {"users": [{"id": , "role": "owner|editor|viewer"}, ...], "groups": [{"id": , "role": "owner|editor|viewer"}, ...]}. Role defaults to viewer if not specified. REPLACES all existing members.' datasource: allOf: - $ref: '#/components/schemas/_DatasourceConversionRequest' description: Datasource configuration to convert this workspace into a read-only synced workspace. Workspace OWNER (or a role granting workspace edit/delete) only. Cannot be undone. PersonaEnum: enum: - integrate - no_code - evaluate - exploring type: string description: |- * `integrate` - Integrate search into my product * `no_code` - Search my docs, no code * `evaluate` - Evaluate / compare RAG solutions * `exploring` - Just exploring PreferredLanguageEnum: enum: - ar - en - fr - de type: string description: |- * `ar` - Arabic * `en` - English * `fr` - French * `de` - German ProgressReportResponse: type: object properties: progress_percentage: type: - number - 'null' format: double current_progress_text: type: - string - 'null' time_remaining_estimate: type: - integer - 'null' metadata: type: - object - 'null' additionalProperties: {} RelevanceScoringEnum: enum: - none - scoring_only - scoring_and_filtering type: string description: |- * `none` - none * `scoring_only` - scoring_only * `scoring_and_filtering` - scoring_and_filtering RelevantChunkScoredV3: type: object description: |- Relevant chunk with the unified scoring shape, aligned with /api/v3/search. Exposes ``score`` + ``scores`` (text/vision/keyword/multivector/relevance) instead of the legacy final_score/lexical_score/distance. ``scores.relevance`` is always null on this path — no relevance scoring runs on file search. properties: text: type: string description: Chunk text content chunk_type: type: string description: Chunk type (e.g. text/table) score: type: number format: double readOnly: true description: Combined retrieval score (higher is better, no fixed upper bound). No relevance scoring runs on file search. scores: allOf: - $ref: '#/components/schemas/_ChunkScoresSchema' readOnly: true required: - score - scores - text ReplaceGroupMemberItem: type: object description: Serializer for a single member in replace group members request properties: id: type: integer description: ID of the user role: allOf: - $ref: '#/components/schemas/GroupMemberRoleEnum' description: |- Role of the member in the group (owner or member) * `owner` - owner * `member` - member required: - id - role ReplaceGroupMembersRequest: type: object description: 'V3 API: Bulk replace all group members' properties: users: type: array items: $ref: '#/components/schemas/ReplaceGroupMemberItem' description: List of users with their roles. An empty array removes all members from the group. required: - users RetrieveChunk: oneOf: - $ref: '#/components/schemas/RetrieveTextChunk' - $ref: '#/components/schemas/RetrieveVisionChunk' RetrieveCorrespondingImage: type: object properties: b64_content: type: string description: Base64-encoded page image. Empty string when the image is unavailable. required: - b64_content RetrieveDocument: type: object properties: id: type: integer readOnly: true name: type: string readOnly: true description: Document filename file_type: type: - string - 'null' maxLength: 30 status: $ref: '#/components/schemas/DocumentStatusEnum' total_pages: type: integer readOnly: true description: Total number of pages uploaded_at: type: string format: date-time readOnly: true title: type: - string - 'null' maxLength: 255 tags: type: array items: $ref: '#/components/schemas/TagItem' readOnly: true description: Tags associated with the document external_metadata: oneOf: - $ref: '#/components/schemas/RetrieveDocumentExternalMetadata' - type: 'null' readOnly: true description: External metadata, if any content_types: type: array items: $ref: '#/components/schemas/DocumentFacetCompactSchema' readOnly: true description: Content type classifications and attribute values required: - content_types - external_metadata - id - name - tags - total_pages - uploaded_at RetrieveDocumentExternalMetadata: type: object properties: external_id: type: string description: External document ID doc_type: type: string title: External document type maxLength: 255 additional_metadata: oneOf: - {} - type: 'null' required: - external_id RetrieveParams: type: object properties: mode: type: string description: 'Retrieval mode used: "text" or "vision".' top_k: type: integer description: Number of best candidates scored and returned. relevance_scoring: type: string description: 'Cross-encoder mode used: ''none'' (skip), ''scoring_only'', or ''scoring_and_filtering''.' skip_rerank: type: boolean description: Deprecated — derived from relevance_scoring (true when relevance_scoring is 'none'). include_image: type: boolean description: Whether page images are included. required: - include_image - mode - relevance_scoring - skip_rerank - top_k RetrieveRequest: type: object description: |- DRF serializer mixin providing ``content_type`` and ``attribute`` fields. Compose into any request serializer via multiple inheritance:: class SearchRequestSerializer(FacetFilterFieldsMixin, serializers.Serializer): query = serializers.CharField(...) # content_type and attribute inherited from the mixin properties: content_type: type: array items: type: string description: 'Filter by content type path. Multiple values are OR. Exact-or-subtree matching by default (e.g. `legal` matches legal, legal:contract). Wildcards: `*contract*` (contains), `legal:contract*` (prefix).' attribute: type: array items: type: string description: 'Filter by attribute value. **Repeated `attribute` entries are ANDed; values inside one entry are ORed with `|`** (pipe is the recommended OR delimiter — comma also works but can be ambiguous with multi-key values). Example: `attribute=fiscal_year:2024|2025&attribute=status:active` → (fiscal_year 2024 OR 2025) AND (status active). Formats: `name` (has any value), `name:value` (exact), `name:>value` / `name:>=value` (gt/gte), `name:value` / `name:>=value` (gt/gte), `name:`, where `` is your auth token. servers: - url: https://paradigm.lighton.ai tags: - name: Agents description: Operations about agents - name: Threads description: Operations about agents conversation threads - name: Tools description: Operations about native tools - name: Models description: Operations about AI models - name: MCP description: Operations about MCP servers - name: Sources description: Operations about sources used by agents conversation threads - name: Artifacts description: Operations about artifacts generated by agents conversation threads - name: Agent description: Operations about agents (deprecated). Please use the 'Agents' API component instead. - name: Files description: Operations about files - name: Facets description: Operations about facets - name: Tags description: Operations about tags - name: Workspaces description: Operations about workspaces - name: Files Processing description: Operations about files processing - name: Users description: Operations about users - name: API Keys description: Operations about API keys - name: User Groups description: Operations about user groups - name: SCIM description: Operations about SCIM