{ "openapi": "3.1.0", "info": { "title": "Endpoints", "version": "1.0" }, "servers": [ { "url": "https://api.contextual.ai/v1" } ], "paths": { "/datastores": { "post": { "tags": [ "/datastores" ], "summary": "Create Datastore", "description": "Create a new `Datastore`.\n\nA `Datastore` is a collection of documents. Documents can be ingested into and deleted from a `Datastore`.\n\nA `Datastore` can be linked to one or more `Agents`, and conversely, an `Agent` can be associated with one or more `Datastores` to ground its responses with relevant data. This flexible many-to-many relationship allows `Agents` to draw from multiple sources of information. This linkage of `Datastore` to `Agent` is done through the `Create Agent` or `Edit Agent` APIs.\n\n> Note that self-serve users are currently required to create datastores through our UI. Otherwise, they will receive the following message: \"This endpoint is disabled as you need to go through checkout. Please use the UI to make this request.\"", "operationId": "create_datastore_datastores_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatastoreOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "/datastores" ], "summary": "List Datastores", "description": "Retrieve a list of `Datastores`.\n\nPerforms `cursor`-based pagination if the number of `Datastores` exceeds the requested `limit`. The returned `cursor` can be passed to the next `GET /datastores` call to retrieve the next set of `Datastores`.", "operationId": "list_datastores_datastores_get", "parameters": [ { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "ID of the agent used to filter datastores. If provided, only datastores linked to this agent will be returned.", "title": "Agent Id" }, "description": "ID of the agent used to filter datastores. If provided, only datastores linked to this agent will be returned." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of datastores to return", "default": 1000, "title": "Limit" }, "description": "Maximum number of datastores to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor from the previous call to list datastores, used to retrieve the next set of results", "title": "Cursor" }, "description": "Cursor from the previous call to list datastores, used to retrieve the next set of results" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatastoreOutputList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/datastores/{datastore_id}/reset": { "put": { "tags": [ "/datastores" ], "summary": "Reset Datastore", "description": "Reset the give `Datastore`. This operation is irreversible and it deletes all the documents associated with the datastore.", "operationId": "reset_datastore_datastores__datastore_id__reset_put", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the datastore to edit", "title": "Datastore Id" }, "description": "ID of the datastore to edit" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/datastores/{datastore_id}": { "put": { "tags": [ "/datastores" ], "summary": "Edit Datastore Configuration", "operationId": "edit_datastore_configuration_datastores__datastore_id__put", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the datastore to edit", "title": "Datastore Id" }, "description": "ID of the datastore to edit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditDatastoreInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditDatastoreOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "/datastores" ], "summary": "Delete Datastore", "description": "Delete a given `Datastore`, including all the documents ingested into it. This operation is irreversible.\n\nThis operation will fail with status code 400 if there is an active `Agent` associated with the `Datastore`.", "operationId": "delete_datastore_datastores__datastore_id__delete", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the datastore to delete", "title": "Datastore Id" }, "description": "ID of the datastore to delete" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/datastores/{datastore_id}/metadata": { "get": { "tags": [ "/datastores" ], "summary": "Get Datastore Metadata", "description": "Get the details of a given `Datastore`, including its name, create time, and the list of `Agents` which are currently configured to use the `Datastore`.", "operationId": "get_datastore_metadata_datastores__datastore_id__metadata_get", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the datastore for which to get details", "title": "Datastore Id" }, "description": "ID of the datastore for which to get details" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDatastoreResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/datastores/{datastore_id}/documents": { "post": { "tags": [ "/datastores/{id}/documents" ], "summary": "Ingest Document", "description": "Ingest a document into a given `Datastore`.\n\nIngestion is an asynchronous task. Returns a document `id` which can be used to track the status of the ingestion job through calls to the `GET /datastores/{datastore_id}/documents/{document_id}/metadata` API.\n\nThis `id` can also be used to delete the document through the `DELETE /datastores/{datastore_id}/documents/{document_id}` API.\n\n`file` must be a PDF, HTML, DOC(X), PPT(X), PNG, JPG, or JPEG file. The filename must end with one of the following extensions: `.pdf`, `.html`, `.htm`, `.mhtml`, `.doc`, `.docx`, `.ppt`, `.pptx`, `.png`, `.jpg`, `.jpeg`.", "operationId": "ingest_document_datastores__datastore_id__documents_post", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Datastore ID of the datastore in which to ingest the document", "title": "Datastore Id" }, "description": "Datastore ID of the datastore in which to ingest the document" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_ingest_document_datastores__datastore_id__documents_post" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "/datastores/{id}/documents" ], "summary": "List Documents", "description": "Get list of documents in a given `Datastore`, including document `id`, `name`, and ingestion job `status`.\n\nPerforms `cursor`-based pagination if the number of documents exceeds the requested `limit`. The returned `cursor` can be passed to the next `GET /datastores/{datastore_id}/documents` call to retrieve the next set of documents.", "operationId": "list_documents_datastores__datastore_id__documents_get", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Datastore ID of the datastore to retrieve documents for", "title": "Datastore Id" }, "description": "Datastore ID of the datastore to retrieve documents for" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of documents to return", "default": 1000, "title": "Limit" }, "description": "Maximum number of documents to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor from the previous call to list documents, used to retrieve the next set of results", "title": "Cursor" }, "description": "Cursor from the previous call to list documents, used to retrieve the next set of results" }, { "name": "ingestion_job_status", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentStatusEnum" }, "description": "Filters documents whose ingestion job status matches (one of) the provided status(es).", "title": "Ingestion Job Status" }, "description": "Filters documents whose ingestion job status matches (one of) the provided status(es)." }, { "name": "uploaded_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Filters documents uploaded at or after specified timestamp.", "title": "Uploaded After" }, "description": "Filters documents uploaded at or after specified timestamp." }, { "name": "uploaded_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Filters documents uploaded at or before specified timestamp.", "title": "Uploaded Before" }, "description": "Filters documents uploaded at or before specified timestamp." }, { "name": "document_name_prefix", "in": "query", "required": false, "schema": { "type": "string", "description": "Filters documents with the given prefix.", "title": "Document Name Prefix" }, "description": "Filters documents with the given prefix." }, { "name": "document_name_search", "in": "query", "required": false, "schema": { "type": "string", "description": "Filters documents whose name contains the search term (case-insensitive substring match).", "title": "Document Name Search" }, "description": "Filters documents whose name contains the search term (case-insensitive substring match)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDocumentsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/datastores/{datastore_id}/documents/{document_id}/metadata": { "get": { "tags": [ "/datastores/{id}/documents" ], "summary": "Get Document Metadata", "description": "Get details of a given document, including its `name` and ingestion job `status`.", "operationId": "get_document_metadata_datastores__datastore_id__documents__document_id__metadata_get", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Datastore ID of the datastore from which to retrieve the document", "title": "Datastore Id" }, "description": "Datastore ID of the datastore from which to retrieve the document" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Document ID of the document to retrieve details for", "title": "Document Id" }, "description": "Document ID of the document to retrieve details for" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDescription" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "/datastores/{id}/documents" ], "summary": "Update Document Metadata", "description": "Post details of a given document that will enrich the chunk and be added to the context or just for filtering. If Just for filtering, start with \"_\" in the key.", "operationId": "update_document_metadata_datastores__datastore_id__documents__document_id__metadata_put", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Datastore ID of the datastore from which to retrieve the document", "title": "Datastore Id" }, "description": "Datastore ID of the datastore from which to retrieve the document" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Document ID of the document to retrieve details for", "title": "Document Id" }, "description": "Document ID of the document to retrieve details for" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataRequest", "description": "Metadata request in JSON format. `custom_metadata` is a flat dictionary containing one or more key-value pairs, where each value must be a primitive type (`str`, `bool`, `float`, or `int`). This function rewrites the metadata you are sending entirely. The strings with date format must stay in date format or be avoided if not in date format. The `custom_metadata.url` or `custom_metadata.link` field is automatically included in returned attributions during query time, if provided. The default maximum metadata fields that can be used is 15, contact support@contextual.ai if more is needed. The combined size of the metadata must not exceed **2 KB** when encoded as JSON. `metadata_config` is an optional dictionary that defines how each metadata field should be used — e.g., whether it's included in chunk reranking (`in_chunks`, default=False), included in the API response(`returned_in_response`, default=False), or enabled for filtering (`filterable`, default=True).\n\n**Example Request Body:**\n\n```json\n{\n\"custom_metadata\": {\n \"topic\": \"science\",\n \"difficulty\": 3\n},\n\"metadata_config\": {\n \"topic\": {\n \"in_chunks\": true,\n \"returned_in_response\": false,\n \"filterable\": true\n },\n \"difficulty\": {\n \"filterable\": true\n }\n}\n}\n```" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDescription" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/datastores/{datastore_id}/documents/{document_id}": { "delete": { "tags": [ "/datastores/{id}/documents" ], "summary": "Delete Document", "description": "Delete a given document from its `Datastore`. This operation is irreversible.", "operationId": "delete_document_datastores__datastore_id__documents__document_id__delete", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Datastore ID of the datastore from which to delete the document", "title": "Datastore Id" }, "description": "Datastore ID of the datastore from which to delete the document" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Document ID of the document to delete", "title": "Document Id" }, "description": "Document ID of the document to delete" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/datastores/{datastore_id}/documents/{document_id}/parse": { "get": { "tags": [ "/datastores/{id}/documents" ], "summary": "Get Parse Results", "description": "Get the parse results that are generated during ingestion for a given document. Retrieving parse results for existing documents ingested before the release of this endpoint is not supported and will return a 404 error.", "operationId": "get_parse_results_datastores__datastore_id__documents__document_id__parse_get", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Datastore ID of the datastore from which to retrieve the document", "title": "Datastore Id" }, "description": "Datastore ID of the datastore from which to retrieve the document" }, { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Document ID of the document to retrieve details for", "title": "Document Id" }, "description": "Document ID of the document to retrieve details for" }, { "name": "output_types", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ParseOutputFormat" }, "description": "The desired output format(s) of the parsed file. Must be `markdown-document`, `markdown-per-page`, and/or `blocks-per-page`. Specify multiple values to get multiple formats in the response. `markdown-document` parses the whole document into a single concatenated markdown output. `markdown-per-page` provides markdown output per page. `blocks-per-page` provides a structured JSON representation of the content blocks on each page, sorted by reading order.\n ", "default": [ "markdown-per-page" ], "title": "Output Types" }, "description": "The desired output format(s) of the parsed file. Must be `markdown-document`, `markdown-per-page`, and/or `blocks-per-page`. Specify multiple values to get multiple formats in the response. `markdown-document` parses the whole document into a single concatenated markdown output. `markdown-per-page` provides markdown output per page. `blocks-per-page` provides a structured JSON representation of the content blocks on each page, sorted by reading order.\n " } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResultsResponseV1" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/datastores/{datastore_id}/chunks/{content_id}/content": { "put": { "tags": [ "/datastores/{id}/documents" ], "summary": "Edit Chunk Content", "description": "Edit the content of a specific chunk in a datastore. This operation updates the chunk's text content and regenerates its embeddings.", "operationId": "edit_chunk_content_datastores__datastore_id__chunks__content_id__content_put", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Datastore ID of the datastore containing the chunk", "title": "Datastore Id" }, "description": "Datastore ID of the datastore containing the chunk" }, { "name": "content_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Content ID of the chunk to edit", "title": "Content Id" }, "description": "Content ID of the chunk to edit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditChunkContentRequest", "description": "Request body containing the new content text" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents": { "get": { "tags": [ "/agents" ], "summary": "List Agents", "description": "Retrieve a list of all `Agents`.", "operationId": "list_agents_agents_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of agents to return", "default": 1000, "title": "Limit" }, "description": "Maximum number of agents to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor from the previous call to list agents, used to retrieve the next set of results", "title": "Cursor" }, "description": "Cursor from the previous call to list agents, used to retrieve the next set of results" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "/agents" ], "summary": "Create Agent", "description": "Create a new `Agent` with a specific configuration.\n\nThis creates a specialized RAG `Agent` which queries over one or multiple `Datastores` to retrieve relevant data on which its generations are grounded.\n\nRetrieval and generation parameters are defined in the provided `Agent` configuration.\n\n> Note that self-serve users are currently required to create agents through our UI. Otherwise, they will receive the following message: \"This endpoint is disabled as you need to go through checkout. Please use the UI to make this request.\"", "operationId": "create_agent_agents_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}": { "delete": { "tags": [ "/agents" ], "summary": "Delete Agent", "description": "Delete a given `Agent`. This is an irreversible operation.\n\nNote: `Datastores` which are associated with the `Agent` will not be deleted, even if no other `Agent` is using them. To delete a `Datastore`, use the `DELETE /datastores/{datastore_id}` API.", "operationId": "delete_agent_agents__agent_id__delete", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the agent to delete", "title": "Agent Id" }, "description": "ID of the agent to delete" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "/agents" ], "summary": "Edit Agent", "description": "Modify a given `Agent` to utilize the provided configuration.\n\nFields not included in the request body will not be modified.", "operationId": "edit_agent_agents__agent_id__put", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the agent to edit", "title": "Agent Id" }, "description": "ID of the agent to edit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifyAgentRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}/metadata": { "get": { "tags": [ "/agents" ], "summary": "Get Agent Metadata", "description": "Get metadata and configuration of a given `Agent`.", "operationId": "get_agent_metadata_agents__agent_id__metadata_get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the agent for which to retrieve details", "title": "Agent Id" }, "description": "ID of the agent for which to retrieve details" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}/reset": { "put": { "tags": [ "/agents" ], "summary": "Reset Agent", "description": "Reset a given `Agent` to default configuration.", "operationId": "reset_agent_agents__agent_id__reset_put", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the agent to reset", "title": "Agent Id" }, "description": "ID of the agent to reset" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}/template": { "post": { "tags": [ "/agents" ], "summary": "Save Template", "operationId": "save_template_agents__agent_id__template_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the agent", "title": "Agent Id" }, "description": "ID of the agent" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveTemplateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/templates": { "get": { "tags": [ "/agents" ], "summary": "List Templates", "description": "Retrieve a list of all available Templates.", "operationId": "list_templates_agents_templates_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTemplatesResponse" } } } } } } }, "/agents/templates/acl": { "get": { "tags": [ "/agents" ], "summary": "List Agent Composer Templates", "description": "Retrieve a list of all available Agent Composer Templates.", "operationId": "list_acl_templates_agents_templates_acl_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListACLTemplatesResponse" } } } } } } }, "/agents/templates/{template}": { "get": { "tags": [ "/agents" ], "summary": "Get Template Configuration", "operationId": "get_template_configuration_agents_templates__template__get", "parameters": [ { "name": "template", "in": "path", "required": true, "schema": { "anyOf": [ { "$ref": "#/components/schemas/DefaultTemplateName" }, { "type": "string" } ], "description": "Template for which to get config, can be a built-in template (DefaultTemplateName) or a custom template name", "title": "Template" }, "description": "Template for which to get config, can be a built-in template (DefaultTemplateName) or a custom template name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}/copy": { "post": { "tags": [ "/agents" ], "summary": "Copy Agent", "description": "Copy an existing agent with all its configurations and datastore associations. The copied agent will have \"[COPY]\" appended to its name.", "operationId": "Copy_Agent_agents__agent_id__copy_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the agent to copy", "title": "Agent Id" }, "description": "ID of the agent to copy" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentOutput" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/datastores/{datastore_id}/contents": { "get": { "tags": [ "/contents" ], "summary": "Get Document Contents", "operationId": "get_document_contents_datastores__datastore_id__contents_get", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Datastore ID of the datastore from which to retrieve the document", "title": "Datastore Id" }, "description": "Datastore ID of the datastore from which to retrieve the document" }, { "name": "document_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Document ID of the document to retrieve details for", "title": "Document Id" }, "description": "Document ID of the document to retrieve details for" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "The query to search keywords for", "title": "Search" }, "description": "The query to search keywords for" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "The offset to start retrieving content ids", "default": 0, "title": "Offset" }, "description": "The offset to start retrieving content ids" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "The number of content ids to be returned", "default": 50, "title": "Limit" }, "description": "The number of content ids to be returned" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListContentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/datastores/{datastore_id}/contents/{content_id}/metadata": { "get": { "tags": [ "/contents" ], "summary": "Get Content Metadata", "operationId": "get_content_metadata_datastores__datastore_id__contents__content_id__metadata_get", "parameters": [ { "name": "datastore_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Datastore Id" } }, { "name": "content_id", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string" } ], "title": "Content Id" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UnstructuredContentMetadata" }, { "$ref": "#/components/schemas/StructuredContentMetadata" }, { "$ref": "#/components/schemas/FileAnalysisContentMetadata" }, { "$ref": "#/components/schemas/ContextualAgentContentMetadata" } ], "discriminator": { "propertyName": "content_type", "mapping": { "unstructured": "#/components/schemas/UnstructuredContentMetadata", "structured": "#/components/schemas/StructuredContentMetadata", "file_analysis": "#/components/schemas/FileAnalysisContentMetadata", "contextual_agent_response": "#/components/schemas/ContextualAgentContentMetadata" } }, "description": "Content type", "title": "Response Get Content Metadata Datastores Datastore Id Contents Content Id Metadata Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}/query/acl": { "post": { "tags": [ "/agents/{id}/query" ], "summary": "Query", "description": "Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions.", "operationId": "Query_agents__agent_id__query_acl_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Agent ID of the agent to query", "title": "Agent Id" }, "description": "Agent ID of the agent to query" }, { "name": "retrievals_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Set to `true` to fetch retrieval content and metadata, and then skip generation of the response.", "default": false, "title": "Retrievals Only" }, "description": "Set to `true` to fetch retrieval content and metadata, and then skip generation of the response." }, { "name": "include_retrieval_content_text", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Set to `true` to include the text of the retrieved contents in the response. If `false`, only metadata about the retrieved contents will be included, not content text. This parameter is ignored if `retrievals_only` is `true`, in which case `content_text` will always be returned. Content text and other metadata can also be fetched separately using the `/agents/{agent_id}/query/{message_id}/retrieval/info` endpoint.", "default": false, "title": "Include Retrieval Content Text" }, "description": "Set to `true` to include the text of the retrieved contents in the response. If `false`, only metadata about the retrieved contents will be included, not content text. This parameter is ignored if `retrievals_only` is `true`, in which case `content_text` will always be returned. Content text and other metadata can also be fetched separately using the `/agents/{agent_id}/query/{message_id}/retrieval/info` endpoint." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequestV1" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ACLQueryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}/query": { "post": { "tags": [ "/agents/{id}/query" ], "summary": "Query", "description": "Start a conversation with an `Agent` and receive its generated response, along with relevant retrieved data and attributions.", "operationId": "Query_agents__agent_id__query_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Agent ID of the agent to query", "title": "Agent Id" }, "description": "Agent ID of the agent to query" }, { "name": "retrievals_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Set to `true` to fetch retrieval content and metadata, and then skip generation of the response.", "default": false, "title": "Retrievals Only" }, "description": "Set to `true` to fetch retrieval content and metadata, and then skip generation of the response." }, { "name": "include_retrieval_content_text", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Set to `true` to include the text of the retrieved contents in the response. If `false`, only metadata about the retrieved contents will be included, not content text. This parameter is ignored if `retrievals_only` is `true`, in which case `content_text` will always be returned. Content text and other metadata can also be fetched separately using the `/agents/{agent_id}/query/{message_id}/retrieval/info` endpoint.", "default": false, "title": "Include Retrieval Content Text" }, "description": "Set to `true` to include the text of the retrieved contents in the response. If `false`, only metadata about the retrieved contents will be included, not content text. This parameter is ignored if `retrievals_only` is `true`, in which case `content_text` will always be returned. Content text and other metadata can also be fetched separately using the `/agents/{agent_id}/query/{message_id}/retrieval/info` endpoint." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequestV1" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}/query/{message_id}/retrieval/info": { "get": { "tags": [ "/agents/{id}/query" ], "summary": "Get Retrieval Info", "description": "Return metadata of the contents used to generate the response for a given message.", "operationId": "Get_Retrieval_Info_agents__agent_id__query__message_id__retrieval_info_get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the agent which sent the provided message.", "title": "Agent Id" }, "description": "ID of the agent which sent the provided message." }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the message for which the content metadata needs to be retrieved.", "title": "Message Id" }, "description": "ID of the message for which the content metadata needs to be retrieved." }, { "name": "content_ids", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of content ids for which to get the metadata.", "title": "Content Ids" }, "description": "List of content ids for which to get the metadata." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrievalInfoQueryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}/feedback": { "post": { "tags": [ "/agents/{id}/query" ], "summary": "Provide Feedback", "description": "Provide feedback for a generation or a retrieval. Feedback can be used to track overall `Agent` performance through the `Feedback` page in the Contextual UI, and as a basis for model fine-tuning.", "operationId": "provide_feedback_agents__agent_id__feedback_post", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "ID of the agent for which to provide feedback", "title": "Agent Id" }, "description": "ID of the agent for which to provide feedback" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequestV0_1" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackSubmitResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/agents/{agent_id}/metrics": { "get": { "tags": [ "/agents/{id}/query" ], "summary": "Get Metrics", "description": "Returns usage and user-provided feedback data. This information can be used for data-driven improvements and optimization.", "operationId": "Get_Metrics_agents__agent_id__metrics_get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Agent ID of the agent to get metrics for", "title": "Agent Id" }, "description": "Agent ID of the agent to get metrics for" }, { "name": "conversation_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Filter messages by conversation ids.", "title": "Conversation Ids" }, "description": "Filter messages by conversation ids." }, { "name": "user_emails", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter messages by users.", "title": "User Emails" }, "description": "Filter messages by users." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Filters messages that are created after the specified timestamp.", "title": "Created After" }, "description": "Filters messages that are created after the specified timestamp." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Filters messages that are created before specified timestamp. If both `created_after` and `created_before` are not provided, then `created_before` will be set to the current time and `created_after` will be set to the `created_before` - 2 days. If only `created_after` is provided, then `created_before` will be set to the `created_after` + 2 days. If only `created_before` is provided, then `created_after` will be set to the `created_before` - 2 days. If both `created_after` and `created_before` are provided, and the difference between them is more than 2 days, then `created_after` will be set to the `created_before` - 2 days.", "title": "Created Before" }, "description": "Filters messages that are created before specified timestamp. If both `created_after` and `created_before` are not provided, then `created_before` will be set to the current time and `created_after` will be set to the `created_before` - 2 days. If only `created_after` is provided, then `created_before` will be set to the `created_after` + 2 days. If only `created_before` is provided, then `created_after` will be set to the `created_before` - 2 days. If both `created_after` and `created_before` are provided, and the difference between them is more than 2 days, then `created_after` will be set to the `created_before` - 2 days." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "description": "Limits the number of messages to return.", "default": 100, "title": "Limit" }, "description": "Limits the number of messages to return." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Offset for pagination.", "default": 0, "title": "Offset" }, "description": "Offset for pagination." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/lmunit": { "post": { "tags": [ "/lmunit" ], "summary": "LMUnit", "description": "Given a `query`, `response`, and a `unit_test`, return the response's `score` on the unit test on a 5-point continuous scale. The total input cannot exceed 7000 tokens.\n\nSee a code example in [our blog post](https://contextual.ai/news/lmunit/). Email [lmunit-feedback@contextual.ai](mailto:lmunit-feedback@contextual.ai) with any feedback or questions.\n\n>🚀 Obtain an LMUnit API key by completing [this form](https://contextual.ai/request-lmunit-api/)", "operationId": "lmunit_lmunit_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LMUnitRequestV1" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LMUnitResponseV1" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/users": { "get": { "tags": [ "/users" ], "summary": "Get Users", "description": "Retrieve a list of `users`.", "operationId": "get_users_users_get", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Query to filter users by email", "title": "Search" }, "description": "Query to filter users by email" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor for the beginning of the current page", "title": "Cursor" }, "description": "Cursor for the beginning of the current page" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Number of users to return", "default": 50, "title": "Limit" }, "description": "Number of users to return" }, { "name": "deactivated", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When set to true, return deactivated users instead.", "default": false, "title": "Deactivated" }, "description": "When set to true, return deactivated users instead." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "/users" ], "summary": "Update User", "description": "Modify a given `User`.\n\nFields not included in the request body will not be modified.", "operationId": "update_user_users_put", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantNewUserInfo" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "/users" ], "summary": "Remove User", "description": "Delete a given `user`.", "operationId": "remove_user_users_delete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantRemoveUser" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "/users" ], "summary": "Invite Users", "description": "Invite users to the tenant. This checks if the user is already in the tenant and if not, creates the user. We will return a list of user emails that were successfully created (including existing users).", "operationId": "invite_users_users_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUsersRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUsersResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/generate": { "post": { "tags": [ "/generate" ], "summary": "Generate", "description": "Generate a response using Contextual's Grounded Language Model (GLM), an LLM engineered specifically to prioritize faithfulness to in-context retrievals over parametric knowledge to reduce hallucinations in Retrieval-Augmented Generation and agentic use cases.\n\nThe total request cannot exceed 32,000 tokens.\n\nSee our [blog post](https://contextual.ai/blog/introducing-grounded-language-model/) and [code examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/02-generate/generate.ipynb). Email [glm-feedback@contextual.ai](mailto:glm-feedback@contextual.ai) with any feedback or questions.", "operationId": "generate_generate_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateRequestV1" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateResponseV1" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/rerank": { "post": { "tags": [ "/rerank" ], "summary": "Rerank", "description": "Rank a list of documents according to their relevance to a query primarily and your custom instructions secondarily. We evaluated the model on instructions for recency, document type, source, and metadata, and it can generalize to other instructions as well. The reranker supports multilinguality.\n\nThe total request cannot exceed 400,000 tokens. The combined length of the query, instruction and any document with its metadata must not exceed 8,000 tokens.\n\nSee our [blog post](https://contextual.ai/blog/introducing-instruction-following-reranker/) and [code examples](https://colab.research.google.com/github/ContextualAI/examples/blob/main/03-standalone-api/03-rerank/rerank.ipynb). Email [rerank-feedback@contextual.ai](mailto:rerank-feedback@contextual.ai) with any feedback or questions.", "operationId": "rerank_rerank_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankRequestV1" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerankResponseV1" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/parse": { "post": { "tags": [ "/parse" ], "summary": "Parse File", "description": "Parse a file into a structured Markdown and/or JSON. Files must be less than 300MB and 2000 pages. We use LibreOffice to convert DOC(X) and PPT(X) files to PDF, which may affect page count.\n\nSee our [blog post](https://contextual.ai/blog/document-parser-for-rag) and [code examples](https://github.com/ContextualAI/examples/blob/main/03-standalone-api/04-parse/parse.ipynb). Email [parse-feedback@contextual.ai](mailto:parse-feedback@contextual.ai) with any feedback or questions.", "operationId": "parse_parse_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_parse_parse_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResponseV1" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/parse/jobs/{job_id}/status": { "get": { "tags": [ "/parse" ], "summary": "Parse Status", "description": "Get the status of a parse job.\n\nParse job results are retained for up to 30 days after job creation. Fetching a status for a parse job that is older than 30 days will return a 404 error.", "operationId": "parse_status_parse_jobs__job_id__status_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Unique ID of the parse job", "title": "Job Id" }, "description": "Unique ID of the parse job" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseStatusResponseV1" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/parse/jobs/{job_id}/results": { "get": { "tags": [ "/parse" ], "summary": "Parse Result", "description": "Get the results of a parse job.\n\nParse job results are retained for up to 30 days after job creation. Fetching results for a parse job that is older than 30 days will return a 404 error.", "operationId": "parse_results_parse_jobs__job_id__results_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Unique ID of the parse job", "title": "Job Id" }, "description": "Unique ID of the parse job" }, { "name": "output_types", "in": "query", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ParseOutputFormat" }, "description": "The desired output format(s) of the parsed file. Must be `markdown-document`, `markdown-per-page`, and/or `blocks-per-page`. Specify multiple values to get multiple formats in the response. `markdown-document` parses the whole document into a single concatenated markdown output. `markdown-per-page` provides markdown output per page. `blocks-per-page` provides a structured JSON representation of the content blocks on each page, sorted by reading order.\n ", "default": [ "markdown-per-page" ], "title": "Output Types" }, "description": "The desired output format(s) of the parsed file. Must be `markdown-document`, `markdown-per-page`, and/or `blocks-per-page`. Specify multiple values to get multiple formats in the response. `markdown-document` parses the whole document into a single concatenated markdown output. `markdown-per-page` provides markdown output per page. `blocks-per-page` provides a structured JSON representation of the content blocks on each page, sorted by reading order.\n " } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResultsResponseV1" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/parse/jobs": { "get": { "tags": [ "/parse" ], "summary": "Parse List Jobs", "description": "Get list of parse jobs, sorted from most recent to oldest.\n\nReturns all jobs from the last 30 days, or since the optional `uploaded_after` timestamp.", "operationId": "parse_list_jobs_parse_jobs_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of parse jobs to return", "default": 1000, "title": "Limit" }, "description": "Maximum number of parse jobs to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Cursor from the previous call to list parse jobs, used to retrieve the next set of results", "title": "Cursor" }, "description": "Cursor from the previous call to list parse jobs, used to retrieve the next set of results" }, { "name": "uploaded_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Filters to only documents uploaded to `/parse` at or after specified UTC timestamp. If not provided, or if the provided timestamp is before the maximum parse job retention period (30 days), the maximum retention period will be used instead.", "examples": [ "2026-05-10T00:00:00" ], "title": "Uploaded After" }, "description": "Filters to only documents uploaded to `/parse` at or after specified UTC timestamp. If not provided, or if the provided timestamp is before the maximum parse job retention period (30 days), the maximum retention period will be used instead." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseListJobsResponseV1" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/extract/schemas": { "get": { "tags": [ "/extract" ], "summary": "List Schemas", "description": "List schemas with optional search.", "operationId": "list_schemas_extract_schemas_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "/extract" ], "summary": "Create Schema", "description": "Create a new extraction schema.\n\nCreates a JSON Schema that defines the structure of data to extract from documents. The schema must conform to our supported subset of JSON Schema 2020-12 features.\n\nSupported Schema Features:\n\nBasic Types:\n\n1. `string`: Text data with optional constraints (`minLength`, `maxLength`, `pattern`, `enum`)\n2. `integer`: Whole numbers with optional constraints (`minimum`, `maximum`, `enum`)\n3. `number`: Decimal numbers with optional constraints (`minimum`, `maximum`, `enum`)\n4. `boolean`: True/false values\n5. `null`: Null values (often used with `anyOf` for optional fields)\n\nComplex Types:\n\n1. `object`: Key-value pairs with defined properties\n2. `array`: Lists of items with defined item schemas\n3. `anyOf`: Union types (e.g., string or null for optional fields)\n\nString Formats:\n\nSupported formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uuid`, `uri`\n\nSchema Structure:\n\n1. Root schema must be an `object` type\n2. Use `$defs` for reusable schema components\n3. Use `$ref` to reference definitions\n4. Arrays must have `items` schema defined\n\nConstraints:\n\n1. Maximum 10 leaf nodes per array (prevents overly complex schemas)\n2. No circular references in `$ref` definitions\n3. String formats must be from the supported list\n\nExample Schemas:\n\nSimple Company Schema:\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"company_name\": {\n \"type\": \"string\",\n \"description\": \"The name of the company exactly as it appears in the document\"\n },\n \"form_type\": {\n \"type\": \"string\",\n \"enum\": [\"10-K\", \"10-Q\", \"8-K\", \"S-1\"],\n \"description\": \"The type of SEC form\"\n },\n \"trading_symbol\": {\n \"type\": \"string\",\n \"description\": \"The trading symbol of the company\"\n },\n \"zip_code\": {\n \"type\": \"integer\",\n \"description\": \"The zip code of the company headquarters\"\n }\n },\n \"required\": [\"company_name\", \"form_type\", \"trading_symbol\", \"zip_code\"]\n}\n```\n\nComplex Resume Schema:\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"personalInfo\": {\n \"type\": \"object\",\n \"properties\": {\n \"fullName\": {\"type\": \"string\"},\n \"contact\": {\n \"type\": \"object\",\n \"properties\": {\n \"emails\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\", \"format\": \"email\"}\n },\n \"phones\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"}\n }\n }\n }\n },\n \"required\": [\"fullName\"]\n },\n \"workExperience\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"jobTitle\": {\"type\": \"string\"},\n \"company\": {\"type\": \"string\"},\n \"startDate\": {\"type\": \"string\"},\n \"endDate\": {\"type\": [\"string\", \"null\"]},\n \"isCurrent\": {\"type\": \"boolean\"}\n },\n \"required\": [\"jobTitle\", \"company\", \"startDate\"]\n }\n }\n },\n \"required\": [\"personalInfo\", \"workExperience\"]\n}\n```\n\nSchema with References:\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"algorithms\": {\n \"type\": \"array\",\n \"items\": {\"$ref\": \"#/$defs/algorithm\"}\n }\n },\n \"$defs\": {\n \"algorithm\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\"type\": \"string\"},\n \"description\": {\"type\": \"string\"}\n },\n \"required\": [\"name\"]\n }\n }\n}\n```\n\nBest Practices:\n\n1. Use descriptive field names that clearly indicate what data should be extracted\n2. Add detailed descriptions to help the AI understand what to extract\n3. Use `enum` for known values (e.g., form types, status values)\n4. Make fields optional by using `anyOf` with `null` or omitting from `required`\n5. Use arrays for lists of similar items (e.g., work experience, education)\n6. Keep schemas focused - avoid overly complex nested structures\n7. Test with sample documents to ensure the schema captures the expected data", "operationId": "create_schema_extract_schemas_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaCreateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/extract/schemas/{schema_id}": { "get": { "tags": [ "/extract" ], "summary": "Get Schema", "description": "Get schema information by ID.", "operationId": "get_schema_extract_schemas__schema_id__get", "parameters": [ { "name": "schema_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schema Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "/extract" ], "summary": "Update Schema", "description": "Update an existing schema.", "operationId": "update_schema_extract_schemas__schema_id__put", "parameters": [ { "name": "schema_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schema Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "/extract" ], "summary": "Delete Schema", "description": "Delete a schema.", "operationId": "delete_schema_extract_schemas__schema_id__delete", "parameters": [ { "name": "schema_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Schema Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Delete Schema Extract Schemas Schema Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/extract/documents": { "get": { "tags": [ "/extract" ], "summary": "List Documents", "description": "List documents for structured extraction.", "operationId": "list_documents_extract_documents_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/extract/documents/upload": { "post": { "tags": [ "/extract" ], "summary": "Upload Document", "description": "Upload a document for structured extraction.\n\nUploads a PDF document that can be used for structured data extraction. Only PDF files are supported.\n\nSupported File Types:\n\n1. PDF files only (`.pdf` extension)\n2. Maximum file size: 50MB (recommended)\n3. Documents are processed and validated upon upload\n\nDocument Processing:\n\n1. File size and page count are automatically calculated\n2. Document is validated for PDF format and readability\n3. Metadata is extracted and stored for future reference\n4. Document is stored securely and can be referenced by ID\n\nUsage:\n\nAfter uploading, you'll receive a `document_id` that can be used with:\n\n1. `POST /jobs` endpoint to start extraction jobs\n2. `GET /documents/{document_id}` to retrieve document information\n3. `DELETE /documents/{document_id}` to remove the document\n\nExample Response:\n```json\n{\n \"document_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"file_name\": \"financial_report.pdf\",\n \"file_size\": 2048576,\n \"page_count\": 45,\n \"uploaded_at\": \"2025-01-11T18:35:00Z\",\n \"status\": \"uploaded\"\n}\n```", "operationId": "upload_document_extract_documents_upload_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_document_extract_documents_upload_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUploadResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/extract/documents/{document_id}": { "get": { "tags": [ "/extract" ], "summary": "Get Document", "description": "Get document information by ID.", "operationId": "get_document_extract_documents__document_id__get", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentInfoResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "/extract" ], "summary": "Delete Document", "description": "Delete a document.", "operationId": "delete_document_extract_documents__document_id__delete", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "title": "Response Delete Document Extract Documents Document Id Delete" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/extract/jobs": { "get": { "tags": [ "/extract" ], "summary": "List Jobs", "description": "List extraction jobs.", "operationId": "list_jobs_extract_jobs_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, { "name": "job_status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Job Status" } }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "/extract" ], "summary": "Start Extraction Job", "description": "Start a new structured extraction job.\n\nExtracts structured data from a PDF document using AI models based on a JSON Schema. The `document_id` and `schema_id` must be valid UUIDs of previously uploaded documents and created schemas.\n\nHow It Works:\n\n1. Document Processing: The system analyzes the PDF document and splits it into manageable sections\n2. Schema Analysis: Your JSON schema is parsed and validated for supported features\n3. Extraction: The pipeline processes each section and extracts data according to your schema\n4. Validation: Extracted data is validated against your schema to ensure constraints and requirements are met\n5. Results: Structured data is returned in the format defined by your schema\n\nSupported Models:\n\n1. `gemini-2.5-flash`: Fast, cost-effective model for most use cases (default)\n2. `gemini-2.5-pro`: More powerful model for complex extractions\n\nConfiguration Options:\n\nBasic Settings:\n\n1. `model`: AI model to use for extraction\n2. `max_num_concurrent_requests`: Number of parallel processing requests (1-20)\n3. `validate_response_schema`: Whether to validate extracted data against schema\n\nAdvanced Settings:\n\n1. `per_key_attribution`: Enable detailed reasoning and confidence scores for each field\n2. `temperature`: Control randomness in AI responses (0.0-2.0)\n3. `seed`: Set random seed for reproducible results\n4. `enable_thinking`: Show AI reasoning process\n5. `n_max_retries`: Maximum retry attempts for failed requests\n\nStreaming Mode (`stream=true`):\n\nWhen `stream=true`, the endpoint returns an SSE stream instead of a job ID. Results are streamed as subtrees complete, enabling real-time progress visibility in the frontend.\n\n- Response: SSE stream (`text/event-stream`) with events: `start`, `subtree_result`, `subtree_error`, `agentic_array_progress`\n- Job records are still created and results persisted (retrievable via `GET /jobs/{job_id}`)\n- Always durable: Uses Temporal workflow—job continues running even if client disconnects\n- Automatic retries: Temporal handles activity failures and retries automatically\n- Use case: Interactive frontend UI where users want real-time extraction progress\n\nSSE Event Types:\n\n1. `start`: Emitted once with `job_id`, `total_subtrees`, and `start_time`\n2. `subtree_result`: Emitted per successful subtree with `extracted_result`, `attributions`, `usage_metadata`\n3. `subtree_error`: Emitted per failed subtree with `error_message` and `error_type`\n\nSee `STREAMING-DESIGN.md` for full protocol specification.\n\nJob Lifecycle:\n\n1. `pending`: Job is queued and waiting to start\n2. `processing`: AI is actively extracting data from the document\n3. `completed`: Extraction finished successfully with results\n4. `failed`: Extraction failed due to an error\n5. `cancelled`: Job was cancelled before completion\n\nMonitoring Progress:\n\nUse the `GET /jobs/{job_id}` endpoint to check job status and progress:\n\n1. `completion_percentage`: Overall progress (0-100)\n2. `current_step`: Current processing stage\n3. `fields_processed`: Number of schema fields completed\n4. `total_fields`: Total number of schema fields to process\n\nGetting Results:\n\nOnce a job is completed, use `GET /jobs/{job_id}/results` to retrieve:\n\n1. `results`: Extracted data conforming to your schema\n2. `metadata`: Processing information, costs, and performance metrics\n3. `attributions`: (if enabled) Reasoning and confidence scores for each field\n\nExample Request:\n```json\n{\n \"document_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"schema_id\": \"987fcdeb-51a2-43d1-b456-426614174000\",\n \"config\": {\n \"model\": \"gemini-2.5-flash\",\n \"per_key_attribution\": true,\n \"temperature\": 0.1,\n \"enable_thinking\": true\n \"additional_instructions\": \"Extract information only about company X. Do not include information about company Y.\"\n }\n}\n```\n\nExample Response:\n```json\n{\n \"job_id\": \"456e7890-e89b-12d3-a456-426614174000\",\n \"status\": \"pending\",\n \"created_at\": \"2025-01-11T18:35:00Z\",\n \"estimated_completion\": \"2025-01-11T18:40:00Z\"\n}\n```\n\nError Handling:\n\nDocument and schema validation occurs before job creation for both streaming and non-streaming paths:\n\n- `400`: Bad Request (invalid `document_id` or `schema_id` format)\n- `404`: Not Found (document or schema not found)\n- `422`: Unprocessable Entity (invalid schema definition)\n- `429`: Too Many Requests (user has exceeded concurrency limit of 5 active jobs)\n- `500`: Internal Server Error (processing error)", "operationId": "start_extraction_job_extract_jobs_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractJobRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractJobResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/extract/jobs/{job_id}/stream": { "get": { "tags": [ "/extract" ], "summary": "Resume Streaming Extraction", "description": "Resume streaming events for an existing extraction job.\n\nThis endpoint:\n1. Validates the job exists and is still processing\n2. Queries Temporal workflow for current state (accumulated_results)\n3. Sends current state as initial event\n4. Streams new events going forward", "operationId": "resume_streaming_extraction_extract_jobs__job_id__stream_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/extract/jobs/{job_id}": { "get": { "tags": [ "/extract" ], "summary": "Get Job Status", "description": "Get the status of an extraction job.\n\nFor running jobs with a Temporal workflow, returns accumulated results and failed subtrees from workflow queries. For completed/failed jobs or jobs without workflow, these fields are empty.", "operationId": "get_job_status_extract_jobs__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/extract/jobs/{job_id}/results": { "get": { "tags": [ "/extract" ], "summary": "Get Job Results", "description": "Get the results of a completed extraction job.", "operationId": "get_job_results_extract_jobs__job_id__results_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResultsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "/extract" ], "summary": "Update Job Results", "description": "Update the results of a completed extraction job.", "operationId": "update_job_results_extract_jobs__job_id__results_put", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResultsUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces/consent": { "get": { "tags": [ "/workspaces" ], "summary": "Get Consent", "description": "Retrieve the current consent status for the workspace.", "operationId": "get_consent_workspaces_consent_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConsentResponse" } } } } } }, "put": { "tags": [ "/workspaces" ], "summary": "Update Consent", "description": "Update the consent status for the workspace.", "operationId": "update_consent_workspaces_consent_put", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConsentRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/balance": { "get": { "tags": [ "/billing" ], "summary": "Get Balance", "description": "Get the remaining balance for a tenant", "operationId": "get_balance_billing_balance_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } } } } } }, "/billing/balance/top-ups": { "get": { "tags": [ "/billing" ], "summary": "Get Top Up History Endpoint", "description": "Get the top-up history for a tenant. Paginated.", "operationId": "get_top_up_history_endpoint_billing_balance_top_ups_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "default": 10, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTopUpHistoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/usages/monthly": { "get": { "tags": [ "/billing" ], "summary": "Get Monthly Usage Endpoint", "description": "Get monthly usage data for a tenant with validation for year and month parameters.\n\nArgs: request: Request object containing year and month with validation user_context: User context with tenant admin permissions resource_id: Optional[UUID]. If provided, get usage data for a specific resource. Otherwise, get aggregated usage data across all resources.\n\nReturns: Monthly usage records for the specified month and year", "operationId": "get_monthly_usage_endpoint_billing_usages_monthly_get", "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 2025, "title": "Year" } }, { "name": "month", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 12, "minimum": 1, "title": "Month" } }, { "name": "resource_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Resource Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonthlyUsageResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/usages/acl": { "get": { "tags": [ "/billing" ], "summary": "Get Agent Composer Step Usage", "description": "Get Agent Composer step-level usage data for a specific month.\n\nThis API returns daily usages of advance queries grouped by steps. The data is used for visualization purposes to show users which Agent Composer steps were executed and their associated costs and token consumption.\n\nNote: The costs returned here are already included in the ACL_COST entry from the daily_usages table and should not be double-counted in billing.\n\nArgs: request: Request object containing year, month, and optional resource_id user_context: User context with tenant admin permissions\n\nReturns: Agent Composer step usage data aggregated by step and date", "operationId": "get_acl_step_usage_endpoint_billing_usages_acl_get", "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 2025, "title": "Year" } }, { "name": "month", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 12, "minimum": 1, "title": "Month" } }, { "name": "resource_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Resource Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentComposerStepUsageResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/usages/earliest_date": { "get": { "tags": [ "/billing" ], "summary": "Get Earliest Usage Date Endpoint", "description": "Get the earliest usage date for a tenant", "operationId": "get_earliest_usage_date_endpoint_billing_usages_earliest_date_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EarliestUsageDateResponse" } } } } } } }, "/billing/billing_mode/history": { "get": { "tags": [ "/billing" ], "summary": "Get Billing Mode History", "description": "Get the billing mode history for a tenant for a specific month.\n\nArgs: request: Request object containing year and month with validation user_context: User context with tenant admin permissions\n\nReturns: Billing mode history records for the specified month and year Returns at least one entry which is the mode of the first date of the given month, with potential mode changes in the middle of the month. If no record found, defaults to LEGACY mode.", "operationId": "get_billing_mode_history_billing_billing_mode_history_get", "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 2025, "title": "Year" } }, { "name": "month", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 12, "minimum": 1, "title": "Month" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingModeHistoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/billing/metadata": { "get": { "tags": [ "/billing" ], "summary": "Get Billing Metadata", "description": "Non admin endpoint for getting the billing metadata for a tenant.", "operationId": "get_billing_metadata_billing_metadata_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingMetadataResponse" } } } } } } } }, "components": { "schemas": { "ACLConfig": { "properties": { "acl_active": { "type": "boolean", "title": "Acl Active", "description": "Deprecated field. To be removed in the future." }, "acl_yaml": { "type": "string", "title": "Acl Yaml", "description": "The YAML file to use for Agent Composer." } }, "type": "object", "title": "ACLConfig", "description": "Captures Agent Composer configurations for an Agent" }, "ACLConfigName": { "type": "string", "enum": [ "default_query", "datastore_search", "web_search", "meta_queries", "structured_unstructured_search", "default_query_fine_grained", "conditional", "instant_search_test", "root_cause_analysis" ], "title": "ACLConfigName" }, "ACLQueryResponse": { "properties": { "conversation_id": { "type": "string", "format": "uuid", "title": "Conversation Id", "description": "A unique identifier for the conversation. Can be passed to future `/query` calls to continue a conversation with the same message history." }, "message_id": { "type": "string", "format": "uuid", "title": "Message Id", "description": "A unique identifier for this specific message" }, "workflow_trace": { "items": { "$ref": "#/components/schemas/ACLWorkflowEvent" }, "type": "array", "title": "Workflow Trace", "description": "Workflow trace for the response" }, "dynamic_agent_trace": { "additionalProperties": { "items": { "$ref": "#/components/schemas/DynamicAgentEvent" }, "type": "array" }, "type": "object", "title": "Dynamic Agent Trace", "description": "Tool calls and thinking events for the response" }, "outputs": { "additionalProperties": true, "type": "object", "title": "Outputs", "description": "Outputs of the agent" }, "retrieval_contents": { "items": { "$ref": "#/components/schemas/RetrievalContentV0_1" }, "type": "array", "title": "Retrieval Contents", "description": "Relevant content retrieved to answer the query. Only included when include_retrieval_content_text is true." }, "message": { "$ref": "#/components/schemas/MessageAndRole", "title": "Message", "description": "Response to the query request. Extracted from outputs['response'] if available." }, "attributions": { "items": { "$ref": "#/components/schemas/AttributionV0_1" }, "type": "array", "title": "Attributions", "description": "Attributions for the response. Extracted from outputs['attribution_result'].attributions if available." }, "groundedness_scores": { "items": { "$ref": "#/components/schemas/GroundednessScore" }, "type": "array", "title": "Groundedness Scores", "description": "Groundedness scores for the response. Extracted from outputs['groundedness_scores'] if available." }, "rl_training_context": { "additionalProperties": true, "type": "object", "title": "Rl Training Context", "description": "RL training context for multi-turn training. Automatically included when policy_output is provided. Contains: full_message_history (complete conversation for next turn), message_history (original input), research_items (tool calls + results), tool_calls_summary (simplified), chunks_info (retrieved content)." } }, "type": "object", "required": [ "conversation_id" ], "title": "ACLQueryResponse", "description": "Response body for POST /query to Agent Composer" }, "ACLTemplateEntry": { "properties": { "id": { "type": "string", "title": "Id", "description": "Unique identifier for the Agent Composer template" }, "name": { "type": "string", "title": "Name", "description": "Display name of the template" }, "description": { "type": "string", "title": "Description", "description": "Description of what this template is for" }, "badges": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Badges", "description": "Optional badge identifiers for UI presentation (e.g., 'dynamic-agent')" }, "template_name": { "type": "string", "title": "Template Name", "description": "The DB template name to use (e.g., 'finance', 'default')" }, "acl_config_name": { "$ref": "#/components/schemas/ACLConfigName", "description": "The Agent Composer config name to use (e.g., 'default_query', 'datastore_search')" } }, "type": "object", "required": [ "id", "name", "description", "template_name", "acl_config_name" ], "title": "ACLTemplateEntry", "description": "An Agent Composer template entry with metadata" }, "ACLWorkflowEvent": { "properties": { "version": { "type": "string", "const": "v0", "title": "Version", "default": "v0" }, "duration": { "type": "number", "title": "Duration", "description": "Duration of the workflow event" }, "name": { "type": "string", "title": "Name", "description": "Name of the workflow event" }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Id", "description": "ID of the parent node in the workflow" } }, "type": "object", "required": [ "duration", "name", "parent_id" ], "title": "ACLWorkflowEvent" }, "AgentComposerStepUsage": { "properties": { "step_name": { "type": "string", "title": "Step Name", "description": "Name of the pipeline step" }, "date": { "type": "string", "title": "Date", "description": "Date in ISO format (YYYY-MM-DD)" }, "input_tokens": { "type": "integer", "title": "Input Tokens", "description": "Total input tokens for this step" }, "output_tokens": { "type": "integer", "title": "Output Tokens", "description": "Total output tokens for this step" }, "total_cost": { "type": "number", "title": "Total Cost", "description": "Total cost in USD for this step" } }, "type": "object", "required": [ "step_name", "date", "input_tokens", "output_tokens", "total_cost" ], "title": "AgentComposerStepUsage", "description": "Single day's Agent Composer usage for a specific step.\n\nRepresents aggregated usage data for a pipeline step on a specific date, summing across all models used by that step." }, "AgentComposerStepUsageResponse": { "properties": { "usages": { "items": { "$ref": "#/components/schemas/AgentComposerStepUsage" }, "type": "array", "title": "Usages", "description": "List of Agent Composer step usages aggregated by step and date" } }, "type": "object", "required": [ "usages" ], "title": "AgentComposerStepUsageResponse", "description": "Response containing daily usages of advance queries grouped by steps.\n\nThis API returns step-level breakdown of Agent Composer usage for visualization purposes. The costs in this response are already included in the ACL_COST entry from the daily_usages table and should not be double-counted." }, "AgentConfigs": { "properties": { "retrieval_config": { "$ref": "#/components/schemas/RetrievalConfig", "title": "Retrieval Config", "description": "Parameters that affect how the agent retrieves from datastore(s)" }, "filter_and_rerank_config": { "$ref": "#/components/schemas/FilterAndRerankConfig", "title": "Filter And Rerank Config", "description": "Parameters that affect filtering and reranking of retrieved knowledge" }, "generate_response_config": { "$ref": "#/components/schemas/GenerateResponseConfig", "title": "Generate Response Config", "description": "Parameters that affect response generation" }, "global_config": { "$ref": "#/components/schemas/GlobalConfig", "title": "Global Config", "description": "Parameters that affect the agent's overall RAG workflow" }, "reformulation_config": { "$ref": "#/components/schemas/ReformulationConfig", "title": "Reformulation Config", "description": "Parameters that affect the agent's query reformulation" }, "acl_config": { "$ref": "#/components/schemas/ACLConfig", "title": "Acl Config", "description": "Parameters that affect the agent's Agent Composer workflow" }, "translation_config": { "$ref": "#/components/schemas/TranslationConfig", "title": "Translation Config", "description": "Parameters that affect the agent's translation workflow" } }, "type": "object", "title": "AgentConfigs", "description": "Response to configs for different components" }, "AgentEntry": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "ID of the agent" }, "name": { "type": "string", "title": "Name", "description": "Name of the agent" }, "description": { "type": "string", "title": "Description", "description": "Description of the agent" } }, "type": "object", "required": [ "id", "name", "description" ], "title": "AgentEntry" }, "AgentEvaluationConfigOverride": { "properties": { "system_prompt": { "type": "string", "title": "System Prompt", "description": "Override the system prompt for the agent during evaluation." }, "filter_prompt": { "type": "string", "title": "Filter Prompt", "description": "Override the filter prompt for the agent during evaluation." }, "model": { "type": "string", "title": "Model", "description": "Override the model for the agent during evaluation." }, "max_new_tokens": { "type": "integer", "title": "Max New Tokens", "description": "Override the max new tokens for the agent during evaluation." }, "top_p": { "type": "number", "title": "Top P", "description": "Override the top_p for the query. This will override the top_p for the agent during evaluation." }, "temperature": { "type": "number", "title": "Temperature", "description": "Override the temperature for the query. This will override the temperature for the agent during evaluation." }, "top_k_retrieved_chunks": { "type": "integer", "title": "Top K Retrieved Chunks", "description": "Override the top_k for the query. This will override the top_k for the agent during evaluation." }, "top_k_reranked_chunks": { "type": "integer", "title": "Top K Reranked Chunks", "description": "Override the rerank_top_k for the query. This will override the rerank_top_k for the agent during evaluation." }, "enable_filter": { "type": "boolean", "title": "Enable Filter", "description": "Override the filter_retrievals for the query. This will override the filter_retrievals for the agent during evaluation." }, "filter_model": { "type": "string", "title": "Filter Model", "description": "Override the filter_model for the query. This will override the filter_model for the agent during evaluation." }, "enable_rerank": { "type": "boolean", "title": "Enable Rerank", "description": "Override the rerank_retrievals for the agent during evaluation." }, "reranker": { "type": "string", "title": "Reranker", "description": "Override the reranker for the agent during evaluation." }, "lexical_alpha": { "type": "number", "title": "Lexical Alpha", "description": "Override the lexical_alpha for the agent during evaluation." }, "semantic_alpha": { "type": "number", "title": "Semantic Alpha", "description": "Override the semantic_alpha for the agent during evaluation." }, "rerank_instructions": { "type": "string", "title": "Rerank Instructions", "description": "Override the rerank_instructions for the agent during evaluation." }, "reranker_score_filter_threshold": { "type": "number", "title": "Reranker Score Filter Threshold", "description": "Override the reranker_score_filter_threshold for the agent during evaluation." }, "use_optimized_context": { "type": "boolean", "title": "Use Optimized Context", "description": "Override whether to use optimized context for this request. When true, optimized context will be used if available. When false, optimized context is disabled. When null/omitted, uses the agent's configured setting." } }, "additionalProperties": false, "type": "object", "title": "AgentEvaluationConfigOverride" }, "AttributionV0_1": { "properties": { "start_idx": { "type": "integer", "title": "Start Idx", "description": "Start index of the attributed text in the generated message" }, "end_idx": { "type": "integer", "title": "End Idx", "description": "End index of the attributed text in the generated message" }, "content_ids": { "items": { "type": "string" }, "type": "array", "title": "Content Ids", "description": "Content IDs of the sources for the attributed text" } }, "type": "object", "required": [ "start_idx", "end_idx", "content_ids" ], "title": "AttributionV0_1", "description": "Attribution for some claim made in a generated message`." }, "BalanceResponse": { "properties": { "balance": { "type": "number", "title": "Balance", "description": "Balance of the user" } }, "type": "object", "required": [ "balance" ], "title": "BalanceResponse", "description": "Response to GET /billing/balance request" }, "BaseMetadataFilter": { "properties": { "field": { "type": "string", "title": "Field", "description": "Field name to search for in the metadata" }, "operator": { "$ref": "#/components/schemas/FilterMetadataOperator", "description": "Operator to be used for the filter." }, "value": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" }, { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "array" }, { "type": "null" } ], "title": "Value", "description": "The value to be searched for in the field. In case of exists operator, it is not needed." } }, "type": "object", "required": [ "field", "operator" ], "title": "BaseMetadataFilter", "description": "Defines a custom metadata filter. The expected input is a dict which can have different operators, fields and values. For example:\n\n {\"field\": \"title\", \"operator\": \"startswith\", \"value\": \"hr-\"}\n\nUse **lowercase** for `value` when not using `equals` operator. For document_id and date_created the query is built using direct query without nesting." }, "BillingMetadataResponse": { "properties": { "is_low_balance": { "type": "boolean", "title": "Is Low Balance", "description": "Whether the user is low on balance" }, "is_auto_top_up_enabled": { "type": "boolean", "title": "Is Auto Top Up Enabled", "description": "Whether auto top-up is enabled" } }, "type": "object", "required": [ "is_low_balance", "is_auto_top_up_enabled" ], "title": "BillingMetadataResponse", "description": "Response to GET /billing/metadata request" }, "BillingMode": { "type": "string", "enum": [ "ON_DEMAND_PREPAID", "ON_DEMAND_PAY_ARREARS", "PROVISION_THROUGHPUT", "LEGACY" ], "title": "BillingMode" }, "BillingModeHistoryEntry": { "properties": { "date": { "type": "string", "format": "date", "title": "Date", "description": "Date (yyyy-mm-dd) when the billing mode became effective" }, "billing_mode": { "$ref": "#/components/schemas/BillingMode", "description": "Billing mode" } }, "type": "object", "required": [ "date", "billing_mode" ], "title": "BillingModeHistoryEntry", "description": "Individual billing mode entry" }, "BillingModeHistoryResponse": { "properties": { "billing_modes": { "items": { "$ref": "#/components/schemas/BillingModeHistoryEntry" }, "type": "array", "title": "Billing Modes", "description": "List of billing mode entries for the specified month" } }, "type": "object", "required": [ "billing_modes" ], "title": "BillingModeHistoryResponse", "description": "Response to GET /billing/billing_mode/history request" }, "BlockBoundingBox": { "properties": { "x0": { "type": "number", "maximum": 1, "minimum": 0, "title": "X0", "description": "The x-coordinate of the top-left corner of the bounding box" }, "y0": { "type": "number", "maximum": 1, "minimum": 0, "title": "Y0", "description": "The y-coordinate of the top-left corner of the bounding box" }, "x1": { "type": "number", "maximum": 1, "minimum": 0, "title": "X1", "description": "The x-coordinate of the bottom-right corner of the bounding box" }, "y1": { "type": "number", "maximum": 1, "minimum": 0, "title": "Y1", "description": "The y-coordinate of the bottom-right corner of the bounding box" } }, "type": "object", "required": [ "x0", "y0", "x1", "y1" ], "title": "BlockBoundingBox", "description": "Normalized bounding box of a block, as relative percentages of the page width and height." }, "Body_ingest_document_datastores__datastore_id__documents_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File", "description": "File to ingest." }, "metadata": { "type": "string", "title": "Metadata", "description": "Metadata request in stringified JSON format. `custom_metadata` is a flat dictionary containing one or more key-value pairs, where each value must be a primitive type (`str`, `bool`, `float`, or `int`). The default maximum metadata fields that can be used is 15, contact support@contextual.ai if more is needed. The combined size of the metadata must not exceed **2 KB** when encoded as JSON. The strings with date format must stay in date format or be avoided if not in date format. The `custom_metadata.url` or `link` field is automatically included in returned attributions during query time, if provided.\n\n **Example Request Body (as returned by `json.dumps`):**\n\n ```json\n \"{{\n \\\"custom_metadata\\\": {{\n \\\"topic\\\": \\\"science\\\",\n \\\"difficulty\\\": 3\n }}\n }}\"\n ```", "examples": [ { "custom_metadata": { "field1": "value1", "field2": "value2" } } ] }, "configuration": { "type": "string", "title": "Configuration", "description": "Overrides the datastore's default configuration for this specific document. This allows applying optimized settings tailored to the document's characteristics without changing the global datastore configuration.", "examples": [ { "parsing": { "figure_caption_mode": "custom", "figure_captioning_prompt": "Generate a detailed caption for each figure." } } ] } }, "type": "object", "required": [ "file" ], "title": "Body_ingest_document_datastores__datastore_id__documents_post" }, "Body_parse_parse_post": { "properties": { "raw_file": { "type": "string", "format": "binary", "title": "Raw File", "description": "The file to be parsed. The file type must be PDF, DOC / DOCX, PPT / PPTX, PNG, JPG / JPEG." }, "parse_mode": { "$ref": "#/components/schemas/ParseMode", "description": "The settings to use for parsing. `basic` is for simple, text-only documents. `standard` is for complex documents with images, complex hierarchy, and/or no natively encoded textual data (e.g. for scanned documents).", "default": "standard", "examples": [ "standard" ] }, "enable_document_hierarchy": { "type": "boolean", "title": "Enable Document Hierarchy", "description": "Adds a table of contents to the output with the structure of the entire parsed document. This feature is in beta. Controls parsing heading levels (e.g. H1, H2, H3) at higher quality. Not permitted in `basic` parsing_mode, or if page_range is not continuous and/or does not start from page zero.", "examples": [ true ] }, "enable_split_tables": { "type": "boolean", "title": "Enable Split Tables", "description": "Controls whether tables are split into multiple tables by row with the headers propagated. Use for improving LLM comprehension of very large tables. Not permitted in `basic` parsing_mode.", "examples": [ false ] }, "max_split_table_cells": { "type": "integer", "title": "Max Split Table Cells", "description": "Threshold number of table cells beyond which large tables are split if `enable_split_tables` is True. Must be null if `enable_split_tables` is False.", "examples": [ null ], "gt": 0 }, "page_range": { "type": "string", "title": "Page Range", "description": "Optional string representing page range to be parsed. Format: comma-separated indexes (0-based, e.g. `0,1,2,5,6`), or ranges inclusive of both ends (e.g. `0-2,5,6`)", "examples": [ null ] } }, "type": "object", "required": [ "raw_file" ], "title": "Body_parse_parse_post" }, "Body_upload_document_extract_documents_upload_post": { "properties": { "file": { "type": "string", "format": "binary", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_document_extract_documents_upload_post" }, "ChunkingConfiguration": { "properties": { "chunking_mode": { "$ref": "#/components/schemas/ChunkingMode", "title": "Chunking Mode", "description": "Chunking mode to use. Options are: `hierarchy_depth`, `hierarchy_heading`, `static_length`, `page_level`. `hierarchy_depth` groups chunks of the same hierarchy level or below, additionally merging or splitting based on length constraints. `hierarchy_heading` splits chunks at every heading in the document hierarchy, additionally merging or splitting based on length constraints. `static_length` creates chunks of a fixed length. `page_level` creates chunks that cannot run over page boundaries.", "default": "hierarchy_depth" }, "max_chunk_length_tokens": { "type": "integer", "maximum": 4096, "minimum": 512, "title": "Max Chunk Length Tokens", "description": "Target maximum length of text tokens chunks for chunking. Chunk length may exceed this value in some edge cases.", "default": 768 }, "min_chunk_length_tokens": { "type": "integer", "maximum": 3712, "minimum": 128, "title": "Min Chunk Length Tokens", "description": "Target minimum length of chunks in tokens. Must be at least 384 tokens less than `max_chunk_length_tokens`. Chunk length may be shorter than this value in some edge cases. Ignored if `chunking_mode` is `page_level`.", "default": 384 }, "enable_hierarchy_based_contextualization": { "type": "boolean", "title": "Enable Hierarchy Based Contextualization", "description": "Whether to enable section-based contextualization for chunking", "default": true } }, "type": "object", "title": "ChunkingConfiguration", "description": "Configuration for document chunking settings." }, "ChunkingMode": { "type": "string", "enum": [ "hierarchy_depth", "hierarchy_heading", "static_length", "page_level" ], "title": "ChunkingMode", "description": "Defines available chunking strategies.\n\n- `hierarchy_depth`: Creates a new chunk whenever a higher-level section heading is encountered.\n\n- `hierarchy_heading`: Creates a new chunk whenever any section heading is encountered.\n\n- `static_length`: Creates chunks of a fixed length.\n- `page_level`: Creates chunks that cannot run over page boundaries." }, "CompositeMetadataFilter": { "properties": { "filters": { "items": { "anyOf": [ { "$ref": "#/components/schemas/BaseMetadataFilter" }, { "$ref": "#/components/schemas/CompositeMetadataFilter" } ] }, "type": "array", "title": "Filters", "description": "Filters added to the query for filtering docs " }, "operator": { "anyOf": [ { "$ref": "#/components/schemas/CompositeOperator" }, { "type": "null" } ], "description": "Composite operator to be used to combine filters" } }, "type": "object", "required": [ "filters" ], "title": "CompositeMetadataFilter", "description": "\"Defines a custom metadata filter as a Composite MetadataFilter. Which can be be a list of filters or nested filters." }, "CompositeOperator": { "type": "string", "enum": [ "AND", "OR", "AND_NOT" ], "title": "CompositeOperator" }, "ConsentType": { "type": "string", "enum": [ "CONSENT_FULL", "CONSENT_SUPPORT", "REVOKE", "UNKNOWN" ], "title": "ConsentType" }, "ContextualAgentContentMetadata": { "properties": { "content_id": { "type": "string", "format": "uuid", "title": "Content Id", "description": "Id of the content." }, "content_type": { "type": "string", "const": "contextual_agent_response", "title": "Content Type", "default": "contextual_agent_response" }, "agent_id": { "type": "string", "title": "Agent Id", "description": "Id of the agent that generated the response." }, "content_text": { "type": "string", "title": "Content Text", "description": "The text content of the agent response." } }, "type": "object", "required": [ "content_id", "agent_id", "content_text" ], "title": "ContextualAgentContentMetadata" }, "CreateAgentOutput": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "ID of the agent" }, "datastore_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Datastore Ids", "description": "IDs of the datastores associated with the agent. If no datastore was provided as part of the request, this is a singleton list containing the ID of the automatically created datastore." } }, "type": "object", "required": [ "id", "datastore_ids" ], "title": "CreateAgentOutput", "description": "Response to POST /agents request" }, "CreateAgentRequest": { "properties": { "system_prompt": { "type": "string", "maxLength": 8000, "title": "System Prompt", "description": "Instructions that your agent references when generating responses. Note that we do not guarantee that the system will follow these instructions exactly." }, "no_retrieval_system_prompt": { "type": "string", "maxLength": 8000, "title": "No Retrieval System Prompt", "description": "Instructions on how the agent should respond when there are no relevant retrievals that can be used to answer a query." }, "multiturn_system_prompt": { "type": "string", "maxLength": 8000, "title": "Multiturn System Prompt", "description": "Instructions on how the agent should handle multi-turn conversations." }, "filter_prompt": { "type": "string", "maxLength": 8000, "title": "Filter Prompt", "description": "The prompt to an LLM which determines whether retrieved chunks are relevant to a given query and filters out irrelevant chunks." }, "suggested_queries": { "items": { "type": "string" }, "type": "array", "title": "Suggested Queries", "description": "These queries will show up as suggestions in the Contextual UI when users load the agent. We recommend including common queries that users will ask, as well as complex queries so users understand the types of complex queries the system can handle. The max length of all the suggested queries is 1000." }, "agent_configs": { "$ref": "#/components/schemas/AgentConfigs", "title": "Agent Configs", "description": "The following advanced parameters are experimental and subject to change." }, "name": { "type": "string", "maxLength": 200, "minLength": 3, "title": "Name", "description": "Name of the agent" }, "description": { "type": "string", "maxLength": 500, "title": "Description", "description": "Description of the agent", "default": "" }, "template_name": { "anyOf": [ { "$ref": "#/components/schemas/DefaultTemplateName" }, { "type": "string" } ], "title": "Template Name", "description": "The template defining the base configuration for the agent. This can be a built-in template (DefaultTemplateName) or a custom template name", "default": "default" }, "datastore_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Datastore Ids", "description": "The IDs of the datastore to associate with this agent." } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "CreateAgentRequest", "description": "Input to Create Agent request" }, "CreateDatastoreOutput": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "ID of the datastore" } }, "type": "object", "required": [ "id" ], "title": "CreateDatastoreOutput" }, "DailyUsage": { "properties": { "date": { "type": "string", "format": "date", "title": "Date", "description": "Date of the usage" }, "usage_type": { "$ref": "#/components/schemas/UsageType", "description": "Type of usage" }, "quantity": { "type": "integer", "title": "Quantity", "description": "Usage quantity" }, "price": { "type": "number", "title": "Price", "description": "Price per unit" } }, "type": "object", "required": [ "date", "usage_type", "quantity", "price" ], "title": "DailyUsage", "description": "" }, "DatastoreFigureCaptionMode": { "type": "string", "enum": [ "default", "custom", "ignore" ], "title": "DatastoreFigureCaptionMode", "description": "Mode for figure captioning.\n\n- `default`: Use the default figure prompt, which generates a detailed caption for each figure.\n\n- `custom`: Use a custom prompt.\n\n- `ignore`: Disable figure captioning." }, "DatastoreInput": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the datastore" }, "configuration": { "$ref": "#/components/schemas/UnstructuredDatastoreConfigModel", "title": "Configuration", "description": "Configuration of the datastore. If not provided, default configuration is used.", "default": {} } }, "type": "object", "required": [ "name" ], "title": "DatastoreInput", "description": "DatastoreInput for creating a new datastore. If no type is provided, we default to unstructured." }, "DatastoreOutputEntry": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "ID of the datastore" }, "name": { "type": "string", "title": "Name", "description": "Name of the datastore" }, "datastore_type": { "type": "string", "const": "UNSTRUCTURED", "title": "Datastore Type", "description": "Type of the datastore" }, "configuration": { "$ref": "#/components/schemas/UnstructuredDatastoreConfigModel", "title": "Configuration", "description": "Configuration of the datastore", "default": {} }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp of when the datastore was created, in ISO format" } }, "type": "object", "required": [ "id", "name", "datastore_type", "created_at" ], "title": "DatastoreOutputEntry", "description": "Datastore output entry with additional fields for public API." }, "DatastoreOutputList": { "properties": { "next_cursor": { "type": "string", "title": "Next Cursor", "description": "Next cursor to continue pagination. Omitted if there are no more datastores to retrieve." }, "datastores": { "items": { "$ref": "#/components/schemas/DatastoreOutputEntry" }, "type": "array", "title": "Datastores", "description": "List of all datastores" } }, "type": "object", "required": [ "datastores" ], "title": "DatastoreOutputList" }, "DatastoreParseConfiguration": { "properties": { "figure_captioning_prompt": { "type": "string", "title": "Figure Captioning Prompt", "description": "Prompt to use for generating image captions. Must be non-empty if `figure_caption_mode` is `custom`. Otherwise, must be null." }, "figure_caption_mode": { "$ref": "#/components/schemas/DatastoreFigureCaptionMode", "title": "Figure Caption Mode", "description": "Mode for figure captioning. Options are `default`, `custom`, or `ignore`. Set to `ignore` to disable figure captioning. Set to `default` to use the default figure prompt, which generates a detailed caption for each figure. Set to `custom` to use a custom prompt.\n ", "default": "default" }, "enable_split_tables": { "type": "boolean", "title": "Enable Split Tables", "description": "Whether to enable table splitting, which splits large tables into smaller tables with at most `max_split_table_cells` cells each. In each split table, the table headers are reproduced as the first row(s). This is useful for preserving context when tables are too large to fit into one chunk.\n ", "default": false }, "max_split_table_cells": { "type": "integer", "title": "Max Split Table Cells", "description": "Maximum number of cells for split tables. Ignored if `enable_split_tables` is False.", "default": 100 }, "ingestion_tier": { "anyOf": [ { "$ref": "#/components/schemas/IngestionTier" }, { "type": "null" } ], "description": "Ingestion tier for preset extraction configurations. Options: STANDARD, ADVANCED, PREMIUM, or None. When None (default), uses explicit config values or system defaults. When set, applies tier-based presets that can be overridden by explicit config." } }, "type": "object", "title": "DatastoreParseConfiguration", "description": "Configuration for data extraction settings from documents at datastore level. Controls settings for document parsing. Includes those from `/parse` API along with some extra ingestion-only ones." }, "DatastoreUsages": { "properties": { "size_gb": { "type": "number", "title": "Size Gb", "description": "Actual size of the datastore in GB" } }, "type": "object", "required": [ "size_gb" ], "title": "DatastoreUsages" }, "DefaultTemplateName": { "type": "string", "enum": [ "default", "finance", "customer_support", "company_policy_q_and_a" ], "title": "DefaultTemplateName" }, "DocumentContentEntry": { "properties": { "content_id": { "type": "string", "format": "uuid", "title": "Content Id", "description": "ID of the content" }, "content_type": { "type": "string", "const": "unstructured", "title": "Content Type", "default": "unstructured" }, "page_number": { "type": "integer", "title": "Page Number", "description": "Page number of the content" } }, "type": "object", "required": [ "content_id", "page_number" ], "title": "DocumentContentEntry" }, "DocumentDescription": { "properties": { "custom_metadata": { "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "string" }, { "items": { "type": "number" }, "type": "array" } ] }, "type": "object", "title": "Custom Metadata", "description": "Custom metadata for the document, provided by the user at ingestion time.Must be a JSON-serializable dictionary with string keys and simple primitive values (str, int, float, bool). The total size must not exceed 2 KB.The strings with date format must stay in date format or be avodied if not in date format.The 'custom_metadata.url' field is automatically included in returned attributions during query time, if provided.The default maximum metadata fields that can be used is 15, contact support if more is needed." }, "custom_metadata_config": { "additionalProperties": { "$ref": "#/components/schemas/MetadataFieldConfig" }, "type": "object", "title": "Custom Metadata Config", "description": "A dictionary mapping metadata field names to the configuration to use for each field. If a metadata field is not present in the dictionary, the default configuration will be used. If the dictionary is not provided, metadata will be added in context for rerank and generation but will not be returned back to the user in retrievals in query API. Limits:\n- Maximum characters per metadata field (for prompt or rerank): **400**\n- Maximum number of metadata fields (for prompt or retrieval): **10** Contact support@contextual.ai to request quota increases." }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "ID of the document that was ingested" }, "name": { "type": "string", "title": "Name", "description": "User specified name of the document" }, "status": { "$ref": "#/components/schemas/DocumentStatusEnum", "description": "Status of this document's ingestion job" }, "created_at": { "type": "string", "title": "Created At", "description": "Timestamp of when the document was created in ISO format." }, "updated_at": { "type": "string", "title": "Updated At", "description": "Timestamp of when the document was modified in ISO format." }, "ingestion_config": { "title": "Ingestion Config", "description": "Ingestion configuration for the document when the document was ingested. It may be different from the current datastore configuration." }, "has_access": { "type": "boolean", "title": "Has Access", "description": "Whether the user has access to this document.", "default": true } }, "type": "object", "required": [ "id", "name", "status", "created_at" ], "title": "DocumentDescription", "description": "Document description" }, "DocumentHierarchy": { "properties": { "blocks": { "items": { "$ref": "#/components/schemas/ParsedBlock" }, "type": "array", "title": "Heading Blocks", "description": "Heading blocks which define the hierarchy of the document" }, "table_of_contents": { "type": "string", "title": "Markdown Table of Contents", "description": "Markdown representation of the table of contents for this document" } }, "additionalProperties": false, "type": "object", "title": "DocumentHierarchy", "description": "Document hierarchy within the parsed document" }, "DocumentInfoResponse": { "properties": { "document_id": { "type": "string", "title": "Document Id", "description": "Unique ID of the document" }, "file_name": { "type": "string", "title": "File Name", "description": "Original filename" }, "file_size": { "type": "integer", "title": "File Size", "description": "File size in bytes" }, "page_count": { "type": "integer", "title": "Page Count", "description": "Number of pages in the document" }, "uploaded_at": { "type": "string", "title": "Uploaded At", "description": "Timestamp when the document was uploaded" }, "status": { "type": "string", "title": "Status", "description": "Document status" }, "signed_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signed Url", "description": "Presigned download URL for the document (valid for 1 hour). Only available for GCS and S3 storage backends." } }, "type": "object", "required": [ "document_id", "file_name", "file_size", "page_count", "uploaded_at", "status" ], "title": "DocumentInfoResponse", "description": "Response model for document information." }, "DocumentListResponse": { "properties": { "documents": { "items": { "$ref": "#/components/schemas/DocumentInfoResponse" }, "type": "array", "title": "Documents", "description": "List of documents" }, "total_count": { "type": "integer", "title": "Total Count", "description": "Total number of documents" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Next cursor to continue pagination. Omitted if there are no more documents to retrieve." }, "prev_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prev Cursor", "description": "Previous cursor to go back in pagination. Omitted if this is the first page." } }, "type": "object", "required": [ "documents", "total_count" ], "title": "DocumentListResponse", "description": "Response model for document listing." }, "DocumentMetadata": { "properties": { "hierarchy": { "$ref": "#/components/schemas/DocumentHierarchy", "title": "Hierarchy", "description": "Hierarchy of the document, as both heading blocks and a markdown table of contents" } }, "type": "object", "title": "DocumentMetadata", "description": "Metadata about the document that was parsed." }, "DocumentStatusEnum": { "type": "string", "enum": [ "pending", "processing", "retrying", "completed", "failed", "cancelled" ], "title": "DocumentStatusEnum" }, "DocumentUploadResponse": { "properties": { "document_id": { "type": "string", "title": "Document Id", "description": "Unique ID of the uploaded document" }, "file_name": { "type": "string", "title": "File Name", "description": "Original filename of the uploaded document" }, "file_size": { "type": "integer", "title": "File Size", "description": "File size in bytes" }, "page_count": { "type": "integer", "title": "Page Count", "description": "Number of pages in the document" }, "uploaded_at": { "type": "string", "title": "Uploaded At", "description": "Timestamp when the document was uploaded" }, "status": { "type": "string", "title": "Status", "description": "Upload status" } }, "type": "object", "required": [ "document_id", "file_name", "file_size", "page_count", "uploaded_at", "status" ], "title": "DocumentUploadResponse", "description": "Response model for document upload." }, "DynamicAgentEvent": { "properties": { "version": { "type": "string", "const": "v0", "title": "Version", "default": "v0" }, "event": { "oneOf": [ { "$ref": "#/components/schemas/ToolCall" }, { "$ref": "#/components/schemas/ThinkingEvent" } ], "title": "Event", "discriminator": { "propertyName": "type", "mapping": { "thinking_event": "#/components/schemas/ThinkingEvent", "tool_call": "#/components/schemas/ToolCall" } } } }, "type": "object", "required": [ "event" ], "title": "DynamicAgentEvent" }, "EarliestUsageDateResponse": { "properties": { "date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Date", "description": "Earliest usage date" } }, "type": "object", "required": [ "date" ], "title": "EarliestUsageDateResponse", "description": "Response to GET /billing/usage/earliest_date request" }, "EditChunkContentRequest": { "properties": { "content": { "type": "string", "title": "Content", "description": "The new content text for the chunk" } }, "additionalProperties": false, "type": "object", "required": [ "content" ], "title": "EditChunkContentRequest", "description": "This class contains all editable content associated with an update to a chunk." }, "EditDatastoreInput": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the datastore" }, "configuration": { "$ref": "#/components/schemas/UnstructuredDatastoreConfigModel", "title": "Configuration", "description": "Configuration of the datastore. If not provided, current configuration is retained.", "default": {} } }, "type": "object", "title": "EditDatastoreInput", "description": "Input model for editing a datastore." }, "EditDatastoreOutput": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "ID of the datastore" } }, "type": "object", "required": [ "id" ], "title": "EditDatastoreOutput" }, "EmptyResponse": { "properties": {}, "type": "object", "title": "EmptyResponse" }, "ExtractConfig": { "properties": { "model": { "type": "string", "enum": [ "gemini-2.5-flash", "gemini-2.5-pro", "gemini-3-pro-preview", "gemini-3-flash-preview" ], "title": "Model", "description": "Base model for extraction. 'gemini-2.5-flash' is faster and cheaper, while 'gemini-2.5-pro' is more accurate and expensive.", "default": "gemini-2.5-flash", "examples": [ "gemini-2.5-flash", "gemini-2.5-pro", "gemini-3-pro-preview", "gemini-3-flash-preview" ] }, "per_key_attribution": { "type": "boolean", "title": "Per Key Attribution", "description": "Set to include attributions for each extracted field including reasoning, confidence scores, and page numbers. This option increases processing time and cost.", "default": false, "examples": [ false, true ] }, "temperature": { "anyOf": [ { "type": "number", "maximum": 2, "minimum": 0 }, { "type": "null" } ], "title": "Temperature", "description": "Sampling temperature (0.0-2.0). Lower values make output more deterministic and consistent, higher values vary more. Leave as None for model defaults.", "examples": [ 0, 0.1, 0.5, 1, 2 ] }, "enable_thinking": { "type": "boolean", "title": "Enable Thinking", "description": "Enable reasoning which can improve accuracy but increases processing time and cost.", "default": true, "examples": [ true, false ] }, "additional_instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Additional Instructions", "description": "Additional instructions to the model. This is a string that will be appended to the prompt. It is useful for providing additional context or instructions to the model." }, "enable_agentic_array_extraction": { "type": "boolean", "title": "Enable Agentic Array Extraction", "description": "If True, will use agentic array extraction to extract the array of objects when possible. Requires isolate_arrays=True in splitter_config. One can also enable agentic array extraction for specific arrays by setting agenticArrayExtractionMaxItemsPerTurn > 0 for the array in the JSON schema.", "default": false } }, "additionalProperties": false, "type": "object", "title": "ExtractConfig", "description": "Configuration for structured extraction. Most settings have sensible defaults, but you can customize them for your specific use case." }, "ExtractJobRequest": { "properties": { "document_id": { "type": "string", "title": "Document Id", "description": "ID of the document to extract from" }, "schema_id": { "type": "string", "title": "Schema Id", "description": "ID of the schema to use for extraction" }, "config": { "anyOf": [ { "$ref": "#/components/schemas/ExtractConfig" }, { "type": "null" } ], "description": "Configuration options for the extraction process" }, "stream": { "type": "boolean", "title": "Stream", "description": "Whether to stream the results as they become available. If true, the response will be a stream of JSON objects.", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "document_id", "schema_id" ], "title": "ExtractJobRequest", "description": "Request model for starting a structured extraction job." }, "ExtractJobResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "Unique ID of the extraction job" }, "status": { "$ref": "#/components/schemas/DocumentStatusEnum", "description": "Current status of the job" }, "created_at": { "type": "string", "title": "Created At", "description": "Timestamp when the job was created" }, "estimated_completion": { "type": "string", "title": "Estimated Completion", "description": "Estimated completion time" } }, "type": "object", "required": [ "job_id", "status", "created_at", "estimated_completion" ], "title": "ExtractJobResponse", "description": "Response model for extraction job creation." }, "FeedbackRequestV0_1": { "properties": { "message_id": { "type": "string", "format": "uuid", "title": "Message ID", "description": "ID of the message on which to provide feedback." }, "feedback": { "$ref": "#/components/schemas/FeedbackStatus", "title": "Feedback", "description": "Feedback to provide on the message. Set to \"removed\" to undo previously provided feedback." }, "explanation": { "type": "string", "title": "Explanation", "description": "Optional explanation for the feedback." }, "content_id": { "type": "string", "format": "uuid", "title": "Content ID", "description": "ID of the content on which to provide feedback, if feedback is on retrieval. Do not set (or set to null) while providing generation feedback." }, "query_category": { "type": "string", "title": "Query Category", "description": "The query category for the feedback." } }, "additionalProperties": false, "type": "object", "required": [ "message_id", "feedback" ], "title": "FeedbackRequestV0_1", "description": "Input to POST feedback endpoint" }, "FeedbackStatus": { "type": "string", "enum": [ "thumbs_up", "thumbs_down", "flagged", "removed" ], "title": "FeedbackStatus" }, "FeedbackSubmitResponse": { "properties": { "feedback_id": { "type": "string", "format": "uuid", "title": "Feedback ID", "description": "ID of the submitted or updated feedback." } }, "type": "object", "required": [ "feedback_id" ], "title": "FeedbackSubmitResponse", "description": "Response schema for feedback submission endpoint." }, "FileAnalysisContentMetadata": { "properties": { "gcp_location": { "type": "string", "title": "Gcp Location", "description": "GCP location of the file." }, "file_format": { "type": "string", "title": "File Format", "description": "Format of the file." }, "content_id": { "type": "string", "format": "uuid", "title": "Content Id", "description": "Id of the content." }, "content_type": { "type": "string", "const": "file_analysis", "title": "Content Type", "default": "file_analysis" } }, "type": "object", "required": [ "gcp_location", "file_format", "content_id" ], "title": "FileAnalysisContentMetadata" }, "FilterAndRerankConfig": { "properties": { "top_k_reranked_chunks": { "type": "integer", "title": "Top K Reranked Chunks", "description": "The number of highest ranked chunks after reranking to be used" }, "reranker_score_filter_threshold": { "type": "number", "maximum": 1, "minimum": 0, "title": "Reranker Score Filter Threshold", "description": "If the reranker relevance score associated with a chunk is below this threshold, then the chunk will be filtered out and not used for generation. Scores are between 0 and 1, with scores closer to 1 being more relevant. Set the value to 0 to disable the reranker score filtering. ", "default": 0 }, "rerank_instructions": { "type": "string", "title": "Rerank Instruction", "description": "Instructions that the reranker references when ranking retrievals. Note that we do not guarantee that the reranker will follow these instructions exactly. Examples: \"Prioritize internal sales documents over market analysis reports. More recent documents should be weighted higher. Enterprise portal content supersedes distributor communications.\" and \"Emphasize forecasts from top-tier investment banks. Recent analysis should take precedence. Disregard aggregator sites and favor detailed research notes over news summaries.\"" }, "default_metadata_filters": { "anyOf": [ { "$ref": "#/components/schemas/BaseMetadataFilter" }, { "$ref": "#/components/schemas/CompositeMetadataFilter" } ], "title": "Default Metadata Filters", "description": "Optional metadata filter which is applied while retrieving from every datastore linked to this agent.", "examples": [ { "filters": [ { "field": "field1", "operator": "equals", "value": "value1" } ], "operator": "AND" } ] }, "per_datastore_metadata_filters": { "additionalProperties": { "$ref": "#/components/schemas/CompositeMetadataFilter" }, "type": "object", "title": "Per Datastore Metadata Filters", "description": "Defines an optional custom metadata filter per datastore ID. Each entry in the dictionary should have a datastore UUID as the key, and the value should be a metadata filter definition. The filter will be applied in addition to filter(s) specified in `default_metadata_filters` and in the `documents_filters` field in the `/query` request during retrieval.", "examples": [ { "d49609d9-61c3-4a67-b3bd-5196b10da560": { "filters": [ { "field": "field1", "operator": "equals", "value": "value1" } ], "operator": "AND" } } ] } }, "type": "object", "title": "FilterAndRerankConfig", "description": "Captures Filter and Rerank configurations for an Agent" }, "FilterMetadataOperator": { "type": "string", "enum": [ "equals", "containsany", "exists", "startswith", "gt", "gte", "lt", "lte", "notequals", "between", "wildcard" ], "title": "FilterMetadataOperator" }, "GenerateRequestV1": { "properties": { "model": { "type": "string", "title": "Model", "description": "The version of the Contextual's GLM to use. Currently, we have `v1` and `v2`." }, "messages": { "items": { "$ref": "#/components/schemas/MessageAndRoleGenerateAPI" }, "type": "array", "minItems": 1, "title": "Messages", "description": "List of messages in the conversation so far. The last message must be from the user." }, "knowledge": { "items": { "type": "string" }, "type": "array", "title": "Knowledge", "description": "The knowledge sources the model can use when generating a response." }, "system_prompt": { "type": "string", "title": "System Prompt", "description": "Instructions that the model follows when generating responses. Note that we do not guarantee that the model follows these instructions exactly." }, "avoid_commentary": { "type": "boolean", "title": "Avoid Commentary", "description": "Flag to indicate whether the model should avoid providing additional commentary in responses. Commentary is conversational in nature and does not contain verifiable claims; therefore, commentary is not strictly grounded in available context. However, commentary may provide useful context which improves the helpfulness of responses.", "default": false }, "temperature": { "type": "number", "maximum": 1, "minimum": 0, "title": "Temperature", "description": "The sampling temperature, which affects the randomness in the response. Note that higher temperature values can reduce groundedness.", "default": 0 }, "top_p": { "type": "number", "maximum": 1, "exclusiveMinimum": 0, "title": "Top_p", "description": "A parameter for nucleus sampling, an alternative to temperature which also affects the randomness of the response. Note that higher top_p values can reduce groundedness.", "default": 0.9 }, "max_new_tokens": { "type": "integer", "maximum": 2048, "minimum": 1, "title": "Max New Tokens", "description": "The maximum number of tokens that the model can generate in the response.", "default": 1024 } }, "additionalProperties": false, "type": "object", "required": [ "model", "messages", "knowledge" ], "title": "GenerateRequestV1", "description": "/generate input request object." }, "GenerateResponseConfig": { "properties": { "model": { "$ref": "#/components/schemas/GenerationModelName", "title": "Model", "description": "The model to use for response generation." }, "max_new_tokens": { "type": "integer", "title": "Max New Tokens", "description": "The maximum number of tokens the model can generate in a response." }, "temperature": { "type": "number", "title": "Temperature", "description": "The sampling temperature, which affects the randomness in the response.", "ge": 0, "le": 1 }, "top_p": { "type": "number", "title": "Top P", "description": "A parameter for nucleus sampling, an alternative to `temperature` which also affects the randomness of the response.", "ge": 0, "le": 1 }, "frequency_penalty": { "type": "number", "title": "Frequency Penalty", "description": "This parameter adjusts how the model treats repeated tokens during text generation." }, "seed": { "type": "integer", "title": "Seed", "description": "This parameter controls the randomness of how the model selects the next tokens during text generation." }, "calculate_groundedness": { "type": "boolean", "title": "Calculate Groundedness", "description": "This parameter controls generation of groundedness scores." }, "avoid_commentary": { "type": "boolean", "title": "Avoid Commentary", "description": "Flag to indicate whether the model should avoid providing additional commentary in responses. Commentary is conversational in nature and does not contain verifiable claims; therefore, commentary is not strictly grounded in available context. However, commentary may provide useful context which improves the helpfulness of responses.", "default": false } }, "additionalProperties": false, "type": "object", "title": "GenerateResponseConfig", "description": "Captures advance LLM configurations for an Agent" }, "GenerateResponseV1": { "properties": { "response": { "type": "string", "title": "Response", "description": "The model's response to the last user message." } }, "type": "object", "required": [ "response" ], "title": "GenerateResponseV1", "description": "/generate result object." }, "GenerationModelName": { "type": "string", "enum": [ "Contextual GLM", "Gemini 2.5 Pro", "Gemini 2.5 Flash", "Gemini 2.0 Flash", "Gemini 2.0 Flash Lite", "Gemini 3 Flash", "Gemini 3 Pro", "Claude Opus 4", "Claude Sonnet 4", "GPT-5", "Default" ], "title": "GenerationModelName", "description": "User-facing model names for API requests." }, "GetAgentResponse": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the agent" }, "description": { "type": "string", "title": "Description", "description": "Description of the agent" }, "datastore_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Datastore Ids", "description": "The IDs of the datastore(s) associated with the agent" }, "template_name": { "type": "string", "title": "Template Name", "description": "The template used to create this agent." }, "system_prompt": { "type": "string", "title": "System Prompt", "description": "Instructions that your agent references when generating responses. Note that we do not guarantee that the system will follow these instructions exactly." }, "filter_prompt": { "type": "string", "title": "Filter Prompt", "description": "The prompt to an LLM which determines whether retrieved chunks are relevant to a given query and filters out irrelevant chunks. This prompt is applied per chunk." }, "no_retrieval_system_prompt": { "type": "string", "title": "No Retrieval System Prompt", "description": "Instructions on how the agent should respond when there are no relevant retrievals that can be used to answer a query." }, "multiturn_system_prompt": { "type": "string", "title": "Multiturn System Prompt", "description": "Instructions on how the agent should handle multi-turn conversations." }, "suggested_queries": { "items": { "type": "string" }, "type": "array", "title": "Suggested Queries", "description": "These queries will show up as suggestions in the Contextual UI when users load the agent. We recommend including common queries that users will ask, as well as complex queries so users understand the types of complex queries the system can handle. The max length of all the suggested queries is 1000." }, "agent_configs": { "$ref": "#/components/schemas/AgentConfigs", "title": "Agent Configs", "description": "The following advanced parameters are experimental and subject to change." } }, "type": "object", "required": [ "name", "datastore_ids", "template_name" ], "title": "GetAgentResponse", "description": "Response to GET Agent request" }, "GetConsentResponse": { "properties": { "status": { "type": "string", "title": "Status", "description": "The current consent status in `ConsentType`." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "The email of the user who granted or revoked the consent" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "The timestamp when the consent was granted or revoked" } }, "type": "object", "required": [ "status", "email", "created_at" ], "title": "GetConsentResponse", "description": "Response for the endpoint that retrieves the consent status for the workspace." }, "GetDatastoreResponse": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the datastore" }, "configuration": { "anyOf": [ { "$ref": "#/components/schemas/UnstructuredDatastoreConfigModel" }, { "type": "null" } ], "title": "Configuration", "description": "Configuration of the datastore. Not set if default configuration is in use." }, "datastore_type": { "type": "string", "const": "UNSTRUCTURED", "title": "Datastore Type", "description": "Type of the datastore", "default": "UNSTRUCTURED" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp of when the datastore was created" }, "agent_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Agent Ids", "description": "List of agents using this datastore" }, "datastore_usages": { "$ref": "#/components/schemas/DatastoreUsages", "title": "Datastore Usages", "description": "Datastore usage" } }, "type": "object", "required": [ "name", "created_at", "agent_ids" ], "title": "GetDatastoreResponse" }, "GetDocumentsResponse": { "properties": { "total_count": { "type": "integer", "title": "Total Count", "description": "Total number of available documents which would be returned by the request if no limit were specified. Ommitted if job_id was set in the request." }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "Next cursor to continue pagination. Ommitted if there are no more documents after these ones, or if job_id was set in the request." }, "documents": { "items": { "$ref": "#/components/schemas/DocumentDescription" }, "type": "array", "title": "Documents", "description": "List of documents retrieved based on the user's GET request" } }, "type": "object", "required": [ "documents" ], "title": "GetDocumentsResponse", "description": "Response body from GET /data/documents" }, "GetTopUpHistoryResponse": { "properties": { "top_ups": { "items": { "$ref": "#/components/schemas/TopUpHistoryResponse" }, "type": "array", "title": "Top Ups", "description": "List of top-ups" }, "has_more": { "type": "boolean", "title": "Has More", "description": "Whether there are more top-ups to fetch" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor", "description": "Cursor for next page" } }, "type": "object", "required": [ "top_ups", "has_more" ], "title": "GetTopUpHistoryResponse", "description": "Response to GET /billing/free-credit request" }, "GlobalConfig": { "properties": { "enable_rerank": { "type": "boolean", "title": "Enable Rerank", "description": "Enables reranking of retrieved chunks" }, "enable_filter": { "type": "boolean", "title": "Enable Filter", "description": "Enables filtering of retrieved chunks with a separate LLM" }, "enable_multi_turn": { "type": "boolean", "title": "Enable Multi Turn", "description": "Enables multi-turn conversations. This feature is currently experimental and will be improved." }, "should_check_retrieval_need": { "type": "boolean", "title": "Should Check Retrieval Need", "description": "Enables checking if retrieval is needed for the query. This feature is currently experimental and will be improved." } }, "additionalProperties": false, "type": "object", "title": "GlobalConfig", "description": "Captures global configs" }, "GroundednessScore": { "properties": { "start_idx": { "type": "integer", "title": "Start Index", "description": "Start index of the span in the generated message" }, "end_idx": { "type": "integer", "title": "End Index", "description": "End index of the span in the generated message" }, "score": { "type": "integer", "title": "Score", "description": "Groundedness score for the span" } }, "type": "object", "required": [ "start_idx", "end_idx", "score" ], "title": "GroundednessScore", "description": "Groundedness scores in a generated message`." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HtmlConfiguration": { "properties": { "max_chunk_length_tokens": { "type": "integer", "maximum": 4096, "minimum": 512, "title": "Max Chunk Length Tokens", "description": "Target maximum length of text tokens chunks for chunking. Chunk length may exceed this value in some edge cases.", "default": 768 } }, "type": "object", "title": "HtmlConfiguration", "description": "Configuration for HTML document ingestion settings." }, "IngestionResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "ID of the document being ingested" } }, "type": "object", "required": [ "id" ], "title": "IngestionResponse", "description": "Response body from POST /data/documents" }, "IngestionTier": { "type": "string", "enum": [ "STANDARD", "ADVANCED", "PREMIUM" ], "title": "IngestionTier", "description": "Ingestion tier levels that determine extraction quality and cost." }, "InnerRetrievableCtxlMetadata": { "properties": { "document_title": { "type": "string", "title": "Document Title", "description": "Title of the document." }, "section_title": { "type": "string", "title": "Section Title", "description": "Title of the section." }, "is_figure": { "type": "boolean", "title": "Is Figure", "description": "Whether this chunk represents a figure." }, "file_name": { "type": "string", "title": "File Name", "description": "Name of the source file." }, "chunk_size": { "type": "integer", "title": "Chunk Size", "description": "Size of the chunk in tokens or characters." }, "file_format": { "type": "string", "title": "File Format", "description": "Format of the file (e.g., PDF, DOCX)." }, "page": { "type": "integer", "title": "Page", "description": "Page number in the source document." }, "chunk_id": { "type": "string", "title": "Chunk Id", "description": "Unique identifier for the chunk." }, "date_created": { "type": "string", "title": "Date Created", "description": "Date when the document or chunk was created." }, "section_id": { "type": "string", "title": "Section Id", "description": "The HTML id of the nearest element of the chunk" } }, "additionalProperties": true, "type": "object", "title": "InnerRetrievableCtxlMetadata" }, "InviteUsersRequest": { "properties": { "tenant_short_name": { "type": "string", "title": "Tenant Short Name", "description": "The short name of the tenant" }, "new_users": { "items": { "$ref": "#/components/schemas/TenantNewUserInfo" }, "type": "array", "title": "New Users", "description": "List of new users to be invited" } }, "type": "object", "required": [ "tenant_short_name", "new_users" ], "title": "InviteUsersRequest" }, "InviteUsersResponse": { "properties": { "invited_user_emails": { "items": { "type": "string" }, "type": "array", "title": "Invited User Emails", "description": "List of emails of the invited users" }, "error_details": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Error Details", "description": "Details of the errors occurred while inviting users, where keys are the emails and values are the error messages" } }, "type": "object", "required": [ "invited_user_emails", "error_details" ], "title": "InviteUsersResponse" }, "JobListResponse": { "properties": { "jobs": { "items": { "$ref": "#/components/schemas/JobStatusResponse" }, "type": "array", "title": "Jobs", "description": "List of jobs" }, "total_count": { "type": "integer", "title": "Total Count", "description": "Total number of jobs" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Next cursor to continue pagination. Omitted if there are no more jobs to retrieve." }, "prev_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prev Cursor", "description": "Previous cursor to go back in pagination. Omitted if this is the first page." } }, "type": "object", "required": [ "jobs", "total_count" ], "title": "JobListResponse", "description": "Response model for job listing." }, "JobResultsResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "Unique ID of the extraction job" }, "status": { "$ref": "#/components/schemas/DocumentStatusEnum", "description": "Current status of the job" }, "results": { "additionalProperties": true, "type": "object", "title": "Results", "description": "Extracted results conforming to the provided JSON Schema. When per_key_attribution is enabled, primitive values are wrapped with AttributionInfo containing extracted_value, reasoning, confidence, and location fields." }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Metadata about the extraction process. May include has_attributions boolean flag indicating if attribution data is present in results." }, "config": { "anyOf": [ { "$ref": "#/components/schemas/ExtractConfig" }, { "type": "null" } ], "description": "Configuration used for the extraction job (model, temperature, etc.)" } }, "type": "object", "required": [ "job_id", "status", "results", "metadata" ], "title": "JobResultsResponse", "description": "Response model for job results.\n\nThe results field contains extracted data conforming to the provided JSON Schema. When per_key_attribution is enabled in ExtractConfig, primitive fields in results will be wrapped with AttributionInfo structures containing the extracted_value along with reasoning, confidence, and page location metadata." }, "JobResultsUpdateRequest": { "properties": { "results": { "additionalProperties": true, "type": "object", "title": "Results", "description": "Extracted results conforming to the provided JSON Schema." } }, "additionalProperties": false, "type": "object", "required": [ "results" ], "title": "JobResultsUpdateRequest", "description": "Request model for updating the results of a completed extraction job." }, "JobStatusResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "Unique ID of the extraction job" }, "status": { "$ref": "#/components/schemas/DocumentStatusEnum", "description": "Current status of the job" }, "created_at": { "type": "string", "title": "Created At", "description": "Timestamp when the job was created" }, "progress": { "$ref": "#/components/schemas/ProgressInfo", "description": "Progress information" }, "current_activity": { "type": "string", "title": "Current Activity", "description": "Current activity being performed" }, "schema_id": { "type": "string", "title": "Schema Id", "description": "ID of the schema used for the extraction" }, "document_id": { "type": "string", "title": "Document Id", "description": "ID of the document used for the extraction" }, "config": { "anyOf": [ { "$ref": "#/components/schemas/ExtractConfig" }, { "type": "null" } ], "description": "Configuration used for the extraction job (model, temperature, etc.)" } }, "type": "object", "required": [ "job_id", "status", "created_at", "progress", "current_activity", "schema_id", "document_id" ], "title": "JobStatusResponse", "description": "Response model for job status.\n\nReturns basic job status and progress." }, "LMUnitRequestV1": { "properties": { "query": { "type": "string", "title": "Query", "description": "The prompt to which the model responds" }, "response": { "type": "string", "title": "Response", "description": "The model response to evaluate" }, "unit_test": { "type": "string", "title": "Unit Test", "description": "A natural language statement or question against which to evaluate the response" } }, "additionalProperties": false, "type": "object", "required": [ "query", "response", "unit_test" ], "title": "LMUnitRequestV1", "description": "LMUnit input request object." }, "LMUnitResponseV1": { "properties": { "score": { "type": "number", "title": "Score", "description": "The response is scored on a continuous scale from 1 to 5 on the unit test. The discrete scores 1, 2, 3, 4, and 5 roughly correspond to \"Strongly fails,\" \"Fails,\" \"Neutral,\" \"Passes,\" and \"Strongly passes,\" respectively." } }, "type": "object", "required": [ "score" ], "title": "LMUnitResponseV1", "description": "LMUnit result object." }, "ListACLTemplatesResponse": { "properties": { "templates": { "items": { "$ref": "#/components/schemas/ACLTemplateEntry" }, "type": "array", "title": "Templates", "description": "List of available Agent Composer templates.", "default": [] } }, "type": "object", "title": "ListACLTemplatesResponse" }, "ListAgentsResponse": { "properties": { "next_cursor": { "type": "string", "title": "Next Cursor", "description": "Next cursor to continue pagination. Omitted if there are no more agents to retrieve." }, "agents": { "items": { "$ref": "#/components/schemas/AgentEntry" }, "type": "array", "title": "Agents", "description": "List of active agents", "default": [] } }, "type": "object", "title": "ListAgentsResponse" }, "ListContentResponse": { "properties": { "data": { "items": { "oneOf": [ { "$ref": "#/components/schemas/DocumentContentEntry" }, { "$ref": "#/components/schemas/StructuredContentEntry" } ], "description": "Content entry type", "discriminator": { "propertyName": "content_type", "mapping": { "structured": "#/components/schemas/StructuredContentEntry", "unstructured": "#/components/schemas/DocumentContentEntry" } } }, "type": "array", "title": "Data", "description": "List of content entries" }, "has_more": { "type": "boolean", "title": "Has More", "description": "Whether there are more content entries to retrieve" } }, "type": "object", "required": [ "data", "has_more" ], "title": "ListContentResponse" }, "ListTemplatesResponse": { "properties": { "templates": { "items": { "type": "string" }, "type": "array", "title": "Templates", "description": "List of available templates.", "default": [] } }, "type": "object", "title": "ListTemplatesResponse" }, "MessageAndRole": { "properties": { "content": { "type": "string", "title": "Content", "description": "Content of the message" }, "role": { "$ref": "#/components/schemas/SenderType", "description": "Role of the sender" }, "custom_tags": { "items": { "type": "string" }, "type": "array", "title": "Custom Tags", "description": "Custom tags for the message" } }, "type": "object", "required": [ "content", "role" ], "title": "MessageAndRole", "description": "Message object for a message sent or received in a conversation" }, "MessageAndRoleGenerateAPI": { "properties": { "content": { "type": "string", "title": "Content", "description": "Content of the message" }, "role": { "$ref": "#/components/schemas/SenderTypeGenerateAPI", "description": "Role of the sender" } }, "type": "object", "required": [ "content", "role" ], "title": "MessageAndRoleGenerateAPI", "description": "Message object for a message received in the /generate request" }, "MetadataFieldConfig": { "properties": { "in_chunks": { "type": "boolean", "title": "In Chunks", "description": "Whether to add in chunks. Defaults to True. The maximum amount of characters per metadata field that can be added to the prompt or rerank is 400. The maximum amount of metadata fields that can be added for prompt or retrieval is 10. Contact support@contextual.ai to request quota increases.", "default": true }, "returned_in_response": { "type": "boolean", "title": "Returned In Response", "description": "Whether to add in response. Defaults to False", "default": false }, "filterable": { "type": "boolean", "title": "Filterable", "description": "Whether to use in filtering. Defaults to True", "default": true } }, "type": "object", "title": "MetadataFieldConfig" }, "MetadataRequest": { "properties": { "custom_metadata": { "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "string" }, { "items": { "type": "number" }, "type": "array" } ] }, "type": "object", "title": "Custom Metadata", "description": "Custom metadata for the document, provided by the user at ingestion time.Must be a JSON-serializable dictionary with string keys and simple primitive values (str, int, float, bool). The total size must not exceed 2 KB.The strings with date format must stay in date format or be avodied if not in date format.The 'custom_metadata.url' field is automatically included in returned attributions during query time, if provided.The default maximum metadata fields that can be used is 15, contact support if more is needed." }, "custom_metadata_config": { "additionalProperties": { "$ref": "#/components/schemas/MetadataFieldConfig" }, "type": "object", "title": "Custom Metadata Config", "description": "A dictionary mapping metadata field names to the configuration to use for each field. If a metadata field is not present in the dictionary, the default configuration will be used. If the dictionary is not provided, metadata will be added in context for rerank and generation but will not be returned back to the user in retrievals in query API. Limits:\n- Maximum characters per metadata field (for prompt or rerank): **400**\n- Maximum number of metadata fields (for prompt or retrieval): **10** Contact support@contextual.ai to request quota increases." } }, "additionalProperties": false, "type": "object", "title": "MetadataRequest", "description": "This class contains all queries associated with metadata request for a doc." }, "MetricsResponse": { "properties": { "messages": { "items": {}, "type": "array", "title": "Messages", "description": "List of messages.", "default": [] }, "total_count": { "type": "integer", "title": "Total Count", "description": "Total number of messages." }, "next_offset": { "type": "integer", "title": "Next Offset", "description": "Offset for the next page. If there are no more messages to get, then this is not set." } }, "type": "object", "required": [ "total_count" ], "title": "MetricsResponse" }, "ModifyAgentRequest": { "properties": { "system_prompt": { "type": "string", "maxLength": 8000, "title": "System Prompt", "description": "Instructions that your agent references when generating responses. Note that we do not guarantee that the system will follow these instructions exactly." }, "no_retrieval_system_prompt": { "type": "string", "maxLength": 8000, "title": "No Retrieval System Prompt", "description": "Instructions on how the agent should respond when there are no relevant retrievals that can be used to answer a query." }, "multiturn_system_prompt": { "type": "string", "maxLength": 8000, "title": "Multiturn System Prompt", "description": "Instructions on how the agent should handle multi-turn conversations." }, "filter_prompt": { "type": "string", "maxLength": 8000, "title": "Filter Prompt", "description": "The prompt to an LLM which determines whether retrieved chunks are relevant to a given query and filters out irrelevant chunks." }, "suggested_queries": { "items": { "type": "string" }, "type": "array", "title": "Suggested Queries", "description": "These queries will show up as suggestions in the Contextual UI when users load the agent. We recommend including common queries that users will ask, as well as complex queries so users understand the types of complex queries the system can handle. The max length of all the suggested queries is 1000." }, "agent_configs": { "$ref": "#/components/schemas/AgentConfigs", "title": "Agent Configs", "description": "The following advanced parameters are experimental and subject to change." }, "name": { "type": "string", "maxLength": 200, "minLength": 3, "title": "Name", "description": "Name of the agent" }, "description": { "type": "string", "maxLength": 500, "title": "Description", "description": "Description of the agent" }, "datastore_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Datastore Ids", "description": "IDs of the datastore to associate with the agent." } }, "additionalProperties": false, "type": "object", "title": "ModifyAgentRequest" }, "MonthlyUsageResponse": { "properties": { "usages": { "items": { "$ref": "#/components/schemas/DailyUsage" }, "type": "array", "title": "Usages", "description": "List of daily usages" } }, "type": "object", "required": [ "usages" ], "title": "MonthlyUsageResponse", "description": "Response to GET /billing/usage/monthly request" }, "ParseListJobsItem": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Job ID", "description": "Unique ID of the parse job" }, "status": { "$ref": "#/components/schemas/DocumentStatusEnum", "title": "Job Status", "description": "The current status of the parse job", "examples": [ "completed" ] }, "file_name": { "type": "string", "title": "File Name", "description": "The name of the file that was uploaded for parsing" } }, "type": "object", "required": [ "id", "status", "file_name" ], "title": "ParseListJobsItem" }, "ParseListJobsResponseV1": { "properties": { "total_jobs": { "type": "integer", "title": "Total Jobs", "description": "Total number of parse jobs", "examples": [ 10 ] }, "next_cursor": { "type": "string", "title": "Next Cursor", "description": "Next cursor to continue pagination. Omitted if there are no more parse jobs after these ones." }, "jobs": { "items": { "$ref": "#/components/schemas/ParseListJobsItem" }, "type": "array", "title": "Jobs", "description": "List of parse jobs" } }, "type": "object", "required": [ "total_jobs", "jobs" ], "title": "ParseListJobsResponseV1", "description": "/parse list jobs object." }, "ParseMode": { "type": "string", "enum": [ "basic", "standard" ], "title": "ParseMode" }, "ParseOutputFormat": { "type": "string", "enum": [ "markdown-document", "markdown-per-page", "blocks-per-page" ], "title": "ParseOutputFormat", "description": "The format of the output to be returned by the /parse endpoint." }, "ParseResponseV1": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job ID", "description": "Unique ID of the parse job" } }, "type": "object", "required": [ "job_id" ], "title": "ParseResponseV1", "description": "/parse response object." }, "ParseResultsResponseV1": { "properties": { "file_name": { "type": "string", "title": "File Name", "description": "The name of the file that was uploaded for parsing" }, "status": { "$ref": "#/components/schemas/DocumentStatusEnum", "title": "Job Status", "description": "The current status of the parse job", "examples": [ "completed" ] }, "pages": { "items": { "$ref": "#/components/schemas/ParsedPage" }, "type": "array", "title": "Parsed Pages", "description": "Per-page parse results, containing per-page Markdown (if `markdown-per-page` was requested) and/or per-page `ParsedBlock`s (if `blocks-per-page` was requested)." }, "markdown_document": { "type": "string", "title": "Parsed Markdown File", "description": "The parsed, structured Markdown of the input file. Only present if `markdown-document` was among the requested output types." }, "document_metadata": { "$ref": "#/components/schemas/DocumentMetadata", "title": "Document Metadata", "description": "Document-level metadata parsed from the document" } }, "type": "object", "required": [ "file_name", "status" ], "title": "ParseResultsResponseV1", "description": "/parse results reponse object." }, "ParseStatusResponseV1": { "properties": { "status": { "$ref": "#/components/schemas/DocumentStatusEnum", "title": "Job Status", "description": "The current status of the parse job", "examples": [ "completed" ] }, "file_name": { "type": "string", "title": "File Name", "description": "The name of the file that was uploaded for parsing" } }, "type": "object", "required": [ "status", "file_name" ], "title": "ParseStatusResponseV1", "description": "/parse status reponse object." }, "ParsedBlock": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Block ID", "description": "Unique ID of the block" }, "type": { "$ref": "#/components/schemas/ParsedBlockType", "title": "Block Type", "description": "The type of the block" }, "bounding_box": { "$ref": "#/components/schemas/BlockBoundingBox", "title": "Bounding Box", "description": "The normalized bounding box of the block, as relative percentages of the page width and height" }, "markdown": { "type": "string", "title": "Block Markdown", "description": "The Markdown representation of the block" }, "confidence_level": { "$ref": "#/components/schemas/ParsedBlockConfidenceLevel", "title": "Table Confidence Level", "description": "The confidence level of this block categorized as 'low', 'medium', or 'high'. Only available for blocks of type 'table' currently.", "examples": [ "high" ] }, "page_index": { "type": "integer", "title": "Page Index", "description": "The page (0-indexed) that this block belongs to. Only set for heading blocks that are returned in the table of contents." }, "parent_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Parent Block IDs", "description": "The IDs of the parent in the document hierarchy, sorted from root-level to bottom. For root-level heading blocks, this will be an empty list. Only present if `enable_document_hierarchy` was set to true in the request." }, "hierarchy_level": { "type": "integer", "title": "Block Hierarchy Level", "description": "The level of the block in the document hierarchy, starting at 0 for the root-level title block. Only present if `enable_document_hierarchy` was set to true in the request." } }, "type": "object", "required": [ "id", "type", "bounding_box", "markdown" ], "title": "ParsedBlock", "description": "One logical block of content from a parsed page." }, "ParsedBlockConfidenceLevel": { "type": "string", "enum": [ "low", "medium", "high" ], "title": "ParsedBlockConfidenceLevel", "description": "The confidence level of a parsed block." }, "ParsedBlockType": { "type": "string", "enum": [ "heading", "text", "table", "figure" ], "title": "ParsedBlockType", "description": "The type of a parsed block." }, "ParsedPage": { "properties": { "index": { "type": "integer", "title": "Page Index", "description": "The index of the parsed page (zero-indexed)", "examples": [ 0 ] }, "markdown": { "type": "string", "title": "Markdown", "description": "The parsed, structured Markdown of this page. Present if `markdown-per-page` was among the requested output types." }, "blocks": { "items": { "$ref": "#/components/schemas/ParsedBlock" }, "type": "array", "title": "Blocks", "description": "The parsed, structured blocks of this page. Present if `blocks-per-page` was among the requested output types." } }, "type": "object", "required": [ "index" ], "title": "ParsedPage", "description": "Per-page parse results." }, "ProgressInfo": { "properties": { "completion_percentage": { "type": "integer", "maximum": 100, "minimum": 0, "title": "Completion Percentage", "description": "Overall progress percentage (0-100)" }, "current_step": { "type": "string", "title": "Current Step", "description": "Current processing stage or step description" }, "fields_processed": { "type": "integer", "minimum": 0, "title": "Fields Processed", "description": "Number of schema fields that have been processed", "default": 0 }, "total_fields": { "type": "integer", "minimum": 0, "title": "Total Fields", "description": "Total number of schema fields to process", "default": 0 } }, "type": "object", "required": [ "completion_percentage", "current_step" ], "title": "ProgressInfo", "description": "Progress information for an extraction job." }, "QueryRequestV1": { "properties": { "messages": { "items": { "$ref": "#/components/schemas/MessageAndRole" }, "type": "array", "title": "Messages", "description": "Messages sent so far in the conversation, ending in the latest user message. Add multiple objects to provide conversation history. Last message in the list must be a `user`-sent message (i.e. `role` equals `\"user\"`)." }, "stream": { "type": "boolean", "title": "Stream", "description": "Set to `true` to receive a streamed response", "default": false }, "conversation_id": { "type": "string", "format": "uuid", "title": "Conversation Id", "description": "An optional alternative to providing message history in the `messages` field. If provided, all messages in the `messages` list prior to the latest user-sent query will be ignored." }, "llm_model_id": { "type": "string", "title": "Llm Model Id", "description": "Model ID of the specific fine-tuned or aligned LLM model to use. Defaults to base model if not specified." }, "structured_output": { "$ref": "#/components/schemas/StructuredOutput", "title": "Structured Output", "description": "Custom output structure format." }, "documents_filters": { "anyOf": [ { "$ref": "#/components/schemas/BaseMetadataFilter" }, { "$ref": "#/components/schemas/CompositeMetadataFilter" } ], "title": "Documents Filters", "description": "Defines an Optional custom metadata filter, which can be a list of filters or nested filters. Use **lowercase** for `value` and/or **field.keyword** for `field` when not using `equals` operator.The expected input is a nested JSON object that can represent a single filter or a composite (logical) combination of filters.\n\n Unnested Example:\n\n```json\n \t{\n \t\t\"operator\": \"AND\",\n \t\t\"filters\": [\n \t\t\t{\"field\": \"status\", \"operator\": \"equals\", \"value\": \"active\"},\n \t\t]\n \t}\n\n```\n\nNested example:\n\n```json\n \t{\n \t\t\"operator\": \"AND\",\n \t\t\"filters\": [\n \t\t\t{\"field\": \"status\", \"operator\": \"equals\", \"value\": \"active\"},\n \t\t\t{\n \t\t\t\t\"operator\": \"OR\",\n \t\t\t\t\"filters\": [\n \t\t\t\t\t{\"field\": \"category\", \"operator\": \"containsany\", \"value\": [\"policy\", \"HR\"]},\n \t\t\t\t\t{\"field\": \"tags\", \"operator\": \"exists\"}\n \t\t\t\t]\n \t\t\t}\n \t\t]\n \t}\n\n```", "examples": [ { "filters": [ { "field": "field1", "operator": "equals", "value": "value1" } ], "operator": "AND" }, { "filters": [ { "field": "field1", "operator": "equals", "value": "value1" }, { "filters": [ { "field": "filed1", "operator": "containsany", "value": [ "value1", "value2" ] }, { "field": "field2", "operator": "exists" } ], "operator": "OR" } ], "operator": "AND" } ] }, "override_configuration": { "$ref": "#/components/schemas/AgentEvaluationConfigOverride", "title": "Override Configuration", "description": "This will modify select configuration parameters for the agent during the response generation." } }, "additionalProperties": false, "type": "object", "required": [ "messages" ], "title": "QueryRequestV1", "description": "Request body for a POST `/agents/{agent_id}/query` request" }, "QueryResponse": { "properties": { "conversation_id": { "type": "string", "format": "uuid", "title": "Conversation Id", "description": "A unique identifier for the conversation. Can be passed to future `/query` calls to continue a conversation with the same message history." }, "message_id": { "type": "string", "format": "uuid", "title": "Message Id", "description": "A unique identifier for this specific message" }, "message": { "$ref": "#/components/schemas/MessageAndRole", "title": "Message", "description": "Response to the query request" }, "retrieval_contents": { "items": { "$ref": "#/components/schemas/RetrievalContentV0_1" }, "type": "array", "title": "Retrieval Contents", "description": "Relevant content retrieved to answer the query" }, "attributions": { "items": { "$ref": "#/components/schemas/AttributionV0_1" }, "type": "array", "title": "Attributions", "description": "Attributions for the response" }, "groundedness_scores": { "items": { "$ref": "#/components/schemas/GroundednessScore" }, "type": "array", "title": "Groundedness Scores", "description": "Groundedness scores for the response" } }, "type": "object", "required": [ "conversation_id", "retrieval_contents" ], "title": "QueryResponse", "description": "Response body for POST /query" }, "ReformulationConfig": { "properties": { "enable_query_expansion": { "type": "boolean", "title": "Enable Query Expansion", "description": "Whether to enable query expansion." }, "query_expansion_prompt": { "type": "string", "title": "Query Expansion Prompt", "description": "The prompt to use for query expansion." }, "enable_query_decomposition": { "type": "boolean", "title": "Enable Query Decomposition", "description": "Whether to enable query decomposition." }, "query_decomposition_prompt": { "type": "string", "title": "Query Decomposition Prompt", "description": "The prompt to use for query decomposition." } }, "type": "object", "title": "ReformulationConfig", "description": "Captures Query Reformulation configurations for an Agent" }, "RerankRequestV1": { "properties": { "query": { "type": "string", "title": "Query", "description": "The string against which documents will be ranked for relevance" }, "documents": { "items": { "type": "string" }, "type": "array", "minItems": 1, "title": "Documents", "description": "The texts to be reranked according to their relevance to the query and the optional instruction" }, "model": { "type": "string", "title": "Model", "description": "The version of the reranker to use. Currently, we have: \"ctxl-rerank-v2-instruct-multilingual\", \"ctxl-rerank-v2-instruct-multilingual-mini\", \"ctxl-rerank-v1-instruct\"." }, "top_n": { "type": "integer", "title": "Top N", "description": "The number of top-ranked results to return" }, "instruction": { "type": "string", "title": "Instruction", "description": "Instructions that the reranker references when ranking documents, after considering relevance. We evaluated the model on instructions for recency, document type, source, and metadata, and it can generalize to other instructions as well. For instructions related to recency and timeframe, specify the timeframe (e.g., instead of saying \"this year\") because the reranker doesn't know the current date. Example: \"Prioritize internal sales documents over market analysis reports. More recent documents should be weighted higher. Enterprise portal content supersedes distributor communications.\"" }, "metadata": { "items": { "type": "string" }, "type": "array", "minLength": 1, "title": "Metadata", "description": "Metadata for documents being passed to the reranker. Must be the same length as the documents list. If a document does not have metadata, add an empty string." } }, "additionalProperties": false, "type": "object", "required": [ "query", "documents", "model" ], "title": "RerankRequestV1", "description": "Rerank input request object." }, "RerankResponseV1": { "properties": { "results": { "items": { "$ref": "#/components/schemas/RerankedResultItem" }, "type": "array", "title": "Reranked Results", "description": "The ranked list of documents containing the index of the document and the relevance score, sorted by relevance score." } }, "type": "object", "required": [ "results" ], "title": "RerankResponseV1", "description": "Rerank output response." }, "RerankedResultItem": { "properties": { "index": { "type": "integer", "title": "Index", "description": "Index of the document in the input list, starting with 0" }, "relevance_score": { "type": "number", "title": "Relevance Score", "description": "Relevance scores assess how likely a document is to have information that is helpful to answer the query. Our model outputs the scores in a wide range, and we normalize scores to a 0-1 scale and truncate the response to 8 decimal places. Our reranker is designed for RAG, so its purpose is to check whether a document has information that is helpful to answer the query. A reranker that is designed for direct Q&A (Question & Answer) would behave differently." } }, "type": "object", "required": [ "index", "relevance_score" ], "title": "RerankedResultItem", "description": "Reranked result object." }, "RetrievalConfig": { "properties": { "top_k_retrieved_chunks": { "type": "integer", "title": "Top K Retrieved Chunks", "description": "The maximum number of retrieved chunks from the datastore.", "ge": 1, "le": 200 }, "lexical_alpha": { "type": "number", "title": "Lexical Alpha", "description": "The weight of lexical search during retrieval. Must sum to 1 with semantic_alpha.", "le": 1 }, "semantic_alpha": { "type": "number", "title": "Semantic Alpha", "description": "The weight of semantic search during retrieval. Must sum to 1 with lexical_alpha.", "le": 1 } }, "type": "object", "title": "RetrievalConfig", "description": "Captures Retrieval configurations for an Agent" }, "RetrievalContentV0_1": { "properties": { "custom_metadata": { "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "string" }, { "items": { "type": "number" }, "type": "array" } ] }, "type": "object", "title": "Custom Metadata", "description": "Custom metadata for the document, provided by the user at ingestion time.Must be a JSON-serializable dictionary with string keys and simple primitive values (str, int, float, bool). The total size must not exceed 2 KB.The strings with date format must stay in date format or be avodied if not in date format.The 'custom_metadata.url' field is automatically included in returned attributions during query time, if provided.The default maximum metadata fields that can be used is 15, contact support if more is needed." }, "custom_metadata_config": { "additionalProperties": { "$ref": "#/components/schemas/MetadataFieldConfig" }, "type": "object", "title": "Custom Metadata Config", "description": "A dictionary mapping metadata field names to the configuration to use for each field. If a metadata field is not present in the dictionary, the default configuration will be used. If the dictionary is not provided, metadata will be added in context for rerank and generation but will not be returned back to the user in retrievals in query API. Limits:\n- Maximum characters per metadata field (for prompt or rerank): **400**\n- Maximum number of metadata fields (for prompt or retrieval): **10** Contact support@contextual.ai to request quota increases." }, "number": { "type": "integer", "title": "Number", "description": "Index of the retrieved item in the retrieval_contents list (starting from 1)", "default": 1 }, "type": { "type": "string", "title": "Source", "description": "Source type of the content. Will be `file` for any docs ingested through ingestion API." }, "format": { "type": "string", "enum": [ "pdf", "html", "htm", "mhtml", "doc", "docx", "ppt", "pptx" ], "title": "Format", "description": "Format of the content, such as `pdf` or `html`" }, "content_id": { "type": "string", "title": "Content Id", "description": "Unique identifier of the retrieved content" }, "datastore_id": { "type": "string", "title": "Datastore Id", "description": "Unique identifier of the datastore" }, "doc_id": { "type": "string", "title": "Doc Id", "description": "Unique identifier of the document" }, "doc_name": { "type": "string", "title": "Doc Name", "description": "Name of the document" }, "page": { "type": "integer", "title": "Page", "description": "Page number of the content in the document" }, "content_text": { "type": "string", "title": "Content Text", "description": "Text of the retrieved content. Included in response to a query if `include_retrieval_content_text` is True" }, "url": { "type": "string", "title": "Url", "description": "URL of the source content, if applicable" }, "ctxl_metadata": { "$ref": "#/components/schemas/InnerRetrievableCtxlMetadata", "title": "Ctxl Metadata", "description": "Default metadata from the retrieval" }, "score": { "type": "number", "title": "Score", "description": "Score of the retrieval, if applicable" } }, "type": "object", "required": [ "type", "format", "content_id", "doc_id", "doc_name" ], "title": "RetrievalContentV0_1", "description": "Retrieval content object typing for v0.1 API." }, "RetrievalInfoQueryResponse": { "properties": { "content_metadatas": { "items": { "oneOf": [ { "$ref": "#/components/schemas/UnstructuredContentMetadata" }, { "$ref": "#/components/schemas/StructuredContentMetadata" }, { "$ref": "#/components/schemas/FileAnalysisContentMetadata" }, { "$ref": "#/components/schemas/ContextualAgentContentMetadata" } ], "description": "Content type", "discriminator": { "propertyName": "content_type", "mapping": { "contextual_agent_response": "#/components/schemas/ContextualAgentContentMetadata", "file_analysis": "#/components/schemas/FileAnalysisContentMetadata", "structured": "#/components/schemas/StructuredContentMetadata", "unstructured": "#/components/schemas/UnstructuredContentMetadata" } } }, "type": "array", "title": "Content Metadatas", "description": "List of content metadatas.", "default": [] } }, "type": "object", "title": "RetrievalInfoQueryResponse" }, "SaveTemplateRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "The name of the template" } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "SaveTemplateRequest" }, "SchemaCreateRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the schema" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the schema" }, "schema_definition": { "additionalProperties": true, "type": "object", "title": "Schema Definition", "description": "JSON Schema definition. Must be a valid JSON Schema that defines the structure of data to extract from documents. See the comprehensive schema guide in the API documentation for detailed examples and supported features.", "examples": [ { "properties": { "company_name": { "description": "The name of the company exactly as it appears in the document", "type": "string" }, "form_type": { "description": "The type of SEC form", "enum": [ "10-K", "10-Q", "8-K", "S-1" ], "type": "string" }, "trading_symbol": { "description": "The trading symbol of the company", "type": "string" }, "zip_code": { "description": "The zip code of the company headquarters", "type": "integer" } }, "required": [ "company_name", "form_type", "trading_symbol", "zip_code" ], "type": "object" } ] }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata for the schema" } }, "additionalProperties": false, "type": "object", "required": [ "name", "schema_definition" ], "title": "SchemaCreateRequest", "description": "Request model for creating a new extraction schema.\n\nThe schema_definition must be a valid JSON Schema that defines the structure of data to extract from documents. The system supports a subset of JSON Schema 2020-12 features optimized for document extraction." }, "SchemaListResponse": { "properties": { "schemas": { "items": { "$ref": "#/components/schemas/SchemaResponse" }, "type": "array", "title": "Schemas", "description": "List of schemas" }, "total_count": { "type": "integer", "title": "Total Count", "description": "Total number of schemas" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Next cursor to continue pagination. Omitted if there are no more schemas to retrieve." }, "prev_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prev Cursor", "description": "Previous cursor to go back in pagination. Omitted if this is the first page." } }, "type": "object", "required": [ "schemas", "total_count" ], "title": "SchemaListResponse", "description": "Response model for schema listing." }, "SchemaResponse": { "properties": { "schema_id": { "type": "string", "title": "Schema Id", "description": "Unique ID of the schema" }, "name": { "type": "string", "title": "Name", "description": "Name of the schema" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the schema" }, "schema_definition": { "additionalProperties": true, "type": "object", "title": "Schema Definition", "description": "JSON schema definition" }, "metadata": { "additionalProperties": true, "type": "object", "title": "Metadata", "description": "Schema metadata" }, "created_at": { "type": "string", "title": "Created At", "description": "Timestamp when the schema was created" }, "updated_at": { "type": "string", "title": "Updated At", "description": "Timestamp when the schema was last updated" } }, "type": "object", "required": [ "schema_id", "name", "schema_definition", "metadata", "created_at", "updated_at" ], "title": "SchemaResponse", "description": "Response model for schema information." }, "SchemaUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Name of the schema" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the schema" }, "schema_definition": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Schema Definition", "description": "JSON schema definition" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Additional metadata" } }, "additionalProperties": false, "type": "object", "title": "SchemaUpdateRequest", "description": "Request model for updating a schema." }, "SenderType": { "type": "string", "enum": [ "user", "system", "assistant", "knowledge" ], "title": "SenderType" }, "SenderTypeGenerateAPI": { "type": "string", "enum": [ "user", "assistant" ], "title": "SenderTypeGenerateAPI" }, "StructuredContentEntry": { "properties": { "content_id": { "type": "string", "title": "Content Id", "description": "ID of the content" }, "content_type": { "type": "string", "const": "structured", "title": "Content Type", "default": "structured" }, "table_name": { "type": "string", "title": "Table Name", "description": "Name of the table" }, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Schema", "description": "Name of the schema of the table" } }, "type": "object", "required": [ "content_id", "table_name" ], "title": "StructuredContentEntry", "description": "Tabular content entry used in query retrieval." }, "StructuredContentMetadata": { "properties": { "content_id": { "type": "string", "title": "Content Id", "description": "Id of the content." }, "content_type": { "type": "string", "const": "structured", "title": "Content Type", "default": "structured" }, "content_text": { "title": "Content Text", "description": "Text of the content." } }, "type": "object", "required": [ "content_id", "content_text" ], "title": "StructuredContentMetadata" }, "StructuredOutput": { "properties": { "type": { "$ref": "#/components/schemas/StructuredOutputType", "description": "Type of the structured output. The default is JSON", "default": "JSON" }, "json_schema": { "additionalProperties": true, "type": "object", "title": "Json Schema", "description": "The output json structure." } }, "additionalProperties": false, "type": "object", "required": [ "json_schema" ], "title": "StructuredOutput" }, "StructuredOutputType": { "type": "string", "enum": [ "JSON" ], "title": "StructuredOutputType", "description": "This captures type of the structured data." }, "TenantNewUserInfo": { "properties": { "email": { "type": "string", "title": "Email", "description": "The email of the user" }, "is_tenant_admin": { "type": "boolean", "title": "Is Tenant Admin", "description": "Flag indicating if the user is a tenant admin", "default": false }, "roles": { "items": { "$ref": "#/components/schemas/UserRolesEnum" }, "type": "array", "title": "Roles", "description": "The user level roles of the user." } }, "type": "object", "required": [ "email" ], "title": "TenantNewUserInfo", "description": "The schema used for creating new users or updating existing users." }, "TenantRemoveUser": { "properties": { "email": { "type": "string", "title": "Email", "description": "The email of the user" } }, "type": "object", "required": [ "email" ], "title": "TenantRemoveUser", "description": "The schema used for removing a user" }, "TenantUserInfo": { "properties": { "email": { "type": "string", "title": "Email", "description": "The email of the user" }, "is_tenant_admin": { "type": "boolean", "title": "Is Tenant Admin", "description": "Flag indicating if the user is a tenant admin", "default": false }, "roles": { "items": { "$ref": "#/components/schemas/UserRolesEnum" }, "type": "array", "title": "Roles", "description": "The user level roles of the user." }, "id": { "type": "string", "title": "Id" }, "effective_roles": { "items": { "$ref": "#/components/schemas/UserRolesEnum" }, "type": "array", "title": "Effective Roles", "description": "The effective roles of the user." } }, "type": "object", "required": [ "email", "id" ], "title": "TenantUserInfo", "description": "The schema used for listing existing (activated / deactivated) users." }, "ThinkingEvent": { "properties": { "type": { "type": "string", "const": "thinking_event", "title": "Type", "default": "thinking_event" }, "thinking_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Thinking Summary", "description": "Thinking summary" }, "duration": { "type": "number", "title": "Duration", "description": "Duration of the thinking" } }, "type": "object", "required": [ "thinking_summary", "duration" ], "title": "ThinkingEvent", "description": "Thinking event for dynamic agents" }, "ToolCall": { "properties": { "type": { "type": "string", "const": "tool_call", "title": "Type", "default": "tool_call" }, "tool_name": { "type": "string", "title": "Tool Name", "description": "Name of the tool called" }, "tool_args": { "type": "string", "title": "Tool Args", "description": "Arguments of the tool called" }, "tool_output": { "type": "string", "title": "Tool Output", "description": "Output of the tool called" }, "successful": { "type": "boolean", "title": "Successful", "description": "Whether the tool call was successful" }, "error": { "type": "string", "title": "Error", "description": "Error message if the tool call was not successful" }, "duration": { "type": "number", "title": "Duration", "description": "Duration of the tool call" } }, "type": "object", "required": [ "tool_name", "tool_args", "successful", "duration" ], "title": "ToolCall", "description": "Tool call for the response" }, "TopUpHistoryResponse": { "properties": { "amount": { "type": "number", "title": "Amount", "description": "Amount of the top-up" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Date when the top-up was created" }, "description": { "type": "string", "title": "Description", "description": "Description of the top-up" }, "starting_balance": { "type": "number", "title": "Starting Balance", "description": "Starting balance before the top-up" }, "ending_balance": { "type": "number", "title": "Ending Balance", "description": "Ending balance after the top-up" } }, "type": "object", "required": [ "amount", "created_at", "description", "starting_balance", "ending_balance" ], "title": "TopUpHistoryResponse", "description": "Individual top-up entry" }, "TranslationConfig": { "properties": { "translate_needed": { "type": "boolean", "title": "Translate Needed", "description": "Whether to enable translation for the agent's responses." }, "translate_confidence": { "type": "number", "title": "Translate Confidence", "description": "The confidence threshold for translation." } }, "type": "object", "title": "TranslationConfig", "description": "Captures Translation configurations for an Agent" }, "UnstructuredContentMetadata": { "properties": { "x0": { "type": "number", "title": "X0", "description": "X coordinate of the top left corner on the bounding box." }, "y0": { "type": "number", "title": "Y0", "description": "Y coordinate of the top left corner on the bounding box." }, "x1": { "type": "number", "title": "X1", "description": "X coordinate of the bottom right corner on the bounding box." }, "y1": { "type": "number", "title": "Y1", "description": "Y coordinate of the bottom right corner on the bounding box." }, "page": { "type": "integer", "title": "Page", "description": "Page number of the content." }, "page_img": { "type": "string", "title": "Page Img", "description": "Image of the page on which the content occurs." }, "width": { "type": "number", "title": "Width", "description": "Width of the image." }, "height": { "type": "number", "title": "Height", "description": "Height of the image." }, "content_id": { "type": "string", "format": "uuid", "title": "Content Id", "description": "Id of the content." }, "document_id": { "type": "string", "format": "uuid", "title": "Document Id", "description": "Id of the document which the content belongs to." }, "content_type": { "type": "string", "const": "unstructured", "title": "Content Type", "default": "unstructured" }, "content_text": { "type": "string", "title": "Content Text", "description": "Text of the content." } }, "type": "object", "required": [ "x0", "y0", "x1", "y1", "page", "page_img", "width", "height", "content_id", "document_id", "content_text" ], "title": "UnstructuredContentMetadata" }, "UnstructuredDatastoreConfigModel": { "properties": { "parsing": { "$ref": "#/components/schemas/DatastoreParseConfiguration", "description": "Configuration for document parsing" }, "chunking": { "$ref": "#/components/schemas/ChunkingConfiguration", "description": "Configuration for document chunking" }, "html_config": { "$ref": "#/components/schemas/HtmlConfiguration", "description": "Configuration for HTML Extraction" } }, "additionalProperties": false, "type": "object", "title": "UnstructuredDatastoreConfigModel", "description": "Configuration for unstructured datastores." }, "UpdateConsentRequest": { "properties": { "type": { "$ref": "#/components/schemas/ConsentType", "description": "The new consent status" } }, "type": "object", "required": [ "type" ], "title": "UpdateConsentRequest", "description": "Request to update the consent status for the workspace." }, "UsageType": { "type": "string", "enum": [ "QUERY_REFORMULATION_INPUT_TOKEN", "QUERY_REFORMULATION_OUTPUT_TOKEN", "QUERY_EXPANSION_INPUT_TOKEN", "QUERY_EXPANSION_OUTPUT_TOKEN", "QUERY_FILTER_TOKEN", "QUERY_RETRIEVAL_TOKEN", "QUERY_RERANK_TOKEN", "QUERY_GENERATION_INPUT_TOKEN", "QUERY_GENERATION_OUTPUT_TOKEN", "QUERY_CONTEXTUALIZATION_TOKEN", "QUERY_GROUNDEDNESS_TOKEN", "QUERY_PLANNING_INPUT_TOKEN", "QUERY_PLANNING_OUTPUT_TOKEN", "QUERY_TRANSLATION_INPUT_TOKEN", "QUERY_TRANSLATION_OUTPUT_TOKEN", "QUERY_REQUEST", "TUNE_REQUEST", "EVAL_REQUEST", "INGEST_BASIC_PAGE", "INGEST_STANDARD_PAGE", "INGEST_V3_STANDARD_PAGE", "INGEST_V3_ADVANCED_PAGE", "INGEST_V3_PREMIUM_PAGE", "PARSE_BASIC_PAGE", "PARSE_STANDARD_PAGE", "RERANK_TOKEN", "RERANK_V2_MINI_TOKEN", "RERANK_V2_TOKEN", "GENERATE_INPUT_TOKEN", "GENERATE_OUTPUT_TOKEN", "LMUNIT_TOKEN", "ACL_COST", "STRUCTURED_EXTRACTION_COST", "STRUCTURED_EXTRACTION_INPUT_TOKENS", "STRUCTURED_EXTRACTION_OUTPUT_TOKENS", "STRUCTURED_EXTRACTION_CACHED_TOKENS", "STRUCTURED_EXTRACTION_REASONING_TOKENS" ], "title": "UsageType" }, "UserRolesEnum": { "type": "string", "enum": [ "VISITOR", "AGENT_USER", "CUSTOMER_USER", "CUSTOMER_INTERNAL_USER", "CONTEXTUAL_STAFF_USER", "CONTEXTUAL_EXTERNAL_STAFF_USER", "CONTEXTUAL_INTERNAL_STAFF_USER", "TENANT_ADMIN", "CUSTOMER_ADMIN", "CONTEXTUAL_ADMIN", "SUPER_ADMIN", "SERVICE_ACCOUNT" ], "title": "UserRolesEnum" }, "UsersListResponse": { "properties": { "users": { "items": { "$ref": "#/components/schemas/TenantUserInfo" }, "type": "array", "title": "Users", "description": "List of users" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Cursor for the beginning of the next page" } }, "type": "object", "required": [ "users" ], "title": "UsersListResponse" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } } }, "security": [ { "BearerAuth": [] } ] }