The Document Assistant API enables developers to integrate document-based assistant functionalities into their applications using AODocs.
The first step is to enable AIDA (AODocs Intelligent Document Assistant) in your tenant. The support team will provide you with the necessary information on how to get started.
The second step is to enable AIDA on libraries. You need to be an administrator of the
library to do this.
AIDA can answer questions only from those documents that are in an AIDA enabled
library.
We create a vector store index for these documents. This can take some time. The get
library API provides the status of the indexation and an estimate of the time
remaining.
The content of the index is automatically kept up-to-date near real time with the
content changes.
The third step is to ask questions based on the AODocs documents.
AIDA automatically filters the results based on the user's permissions.
Authentication: All API endpoints require a valid OAuth2 token in the Authorization header. Ensure the client ID of the OAuth2 token is whitelisted in AODocs.
version: 1.1.0 servers: - url: https://document-assistant.us.aodocs.app description: Production US - url: https://document-assistant.eu.aodocs.app description: Production EU security: [] paths: /assistant/api/v2/tenants/{tenant}/chat: post: tags: - chat-v2 summary: Chat V2 description: >- Answers a chat message with structured response preserving paragraph-level citations. **V2 Changes:** - Structured response with `items` array (paragraphs) - Per-paragraph citations and links - Removed deprecated fields (library_id, document_id) **Response Structure:** Each response item represents a paragraph with: - `text`: The paragraph content - `citations`: Sources cited in this specific paragraph - `links`: Search result links related to this paragraph **Example Response:** ```json { "metadata": { "conversation_id": "uuid", "message_id": "uuid", "response_id": "uuid" }, "items": [ { "text": "Alice is 32 years old.", "citations": [{"document_title": "Employee Records", ...}], "links": [] }, { "text": "She works at AODocs.", "citations": [{"document_title": "Team Directory", ...}], "links": [{"title": "View directory", "url": "..."}] } ] } ``` operationId: chat_v2_assistant_api_v2_tenants__tenant__chat_post parameters: - name: tenant in: path required: true schema: anyOf: - type: string - type: 'null' description: The domain of the customer examples: - example.com title: Tenant description: The domain of the customer requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SyncChatRequestV2' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ChatResponseV2' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: No answer was generated by the agent security: - HTTPBearer: [] components: schemas: SyncChatRequestV2: properties: message: type: string title: Message description: The message to be sent to the assistant agent_id: anyOf: - type: string - type: 'null' title: Agent Id description: The id of the agent to scope this chat request conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: >- The conversation ID of the chat message. If not provided, a new conversation will be created. library_ids: anyOf: - items: type: string type: array - type: 'null' title: Library Ids description: Answer the question in the context of these libraries document_ids: anyOf: - items: type: string type: array - type: 'null' title: Document Ids description: Answer the question in the context of these documents view_id: anyOf: - type: string - type: 'null' title: View Id description: Answer the question in the context of the view timezone: type: integer title: Timezone description: >- Timezone of the user. If not provided we use UTC timezone. Format: offset from UTC, in minutes (JavaScript getTimezoneOffset) default: 0 read_only: type: boolean title: Read Only description: Disable tools that can modify documents for this request default: false include_quotes: anyOf: - type: boolean - type: 'null' title: Include Quotes description: >- Include quoted text in citations. Set to false to reduce response size. default: false type: object required: - message title: SyncChatRequestV2 description: Synchronous chat request with option to exclude quoted text. ChatResponseV2: properties: metadata: $ref: '#/components/schemas/ChatResponseMetadataV2' description: Metadata including conversation, message, and response IDs items: items: $ref: '#/components/schemas/ChatResponseItemV2' type: array title: Items description: Structured response items, typically paragraphs with their sources type: object required: - metadata - items title: ChatResponseV2 description: >- Structured chat response preserving paragraph-level granularity. Each response item represents a logical unit (typically a paragraph) with its own citations, links, and search metadata. This allows clients to: - Display inline citations per paragraph - Show relevant search links contextually - Understand which searches contributed to each answer part Example: { "metadata": { "conversation_id": "uuid", "message_id": "uuid", "response_id": "uuid" }, "items": [ { "text": "Alice is 32 years old.", "citations": [{"document_title": "Employee Records", ...}], "links": [] }, { "text": "She works at AODocs as a software engineer.", "citations": [{"document_title": "Team Directory", ...}], "links": [{"title": "View team directory", "url": "..."}] } ] } HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ChatResponseMetadataV2: properties: conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The conversation ID of the chat message message_id: type: string title: Message Id description: The message ID of the chat message response_id: type: string title: Response Id description: The response ID of the chat message type: object required: - conversation_id - message_id - response_id title: ChatResponseMetadataV2 description: |- Metadata about the chat response. Simplified from V1 - sources and links moved to per-item level. ChatResponseItemV2: properties: text: type: string title: Text description: The text content of this response item (paragraph) citations: items: $ref: '#/components/schemas/Reference' type: array title: Citations description: >- Document sources cited in this specific paragraph. Each citation includes document info, quoted text, and location. links: items: $ref: '#/components/schemas/ChatLink' type: array title: Links description: >- Search result links related to this specific paragraph. These are typically AODocs view links showing the source documents. type: object required: - text title: ChatResponseItemV2 description: >- A single response item (typically a paragraph) with its own citations and links. This structure enables: - Inline citation display per paragraph - Contextual search links - Better transparency about source attribution ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError Reference: properties: id: type: string title: Id description: Unique identifier for the reference library_id: type: string title: Library Id description: The library ID of the node document_id: type: string title: Document Id description: The document ID of the node document_title: type: string title: Document Title description: Title of document document_link: type: string title: Document Link description: Link to the document quoted_text: anyOf: - type: string - type: 'null' title: Quoted Text description: >- Quoted text from the document. A short excerpt that verifies verbatim against the source where the answering flow narrowed it — the default for content-search answers — and the full retrieved source chunk otherwise. quote_narrowed tells the two apart. attachment_id: anyOf: - type: string - type: 'null' title: Attachment Id description: The attachment ID of the node attachment_name: anyOf: - type: string - type: 'null' title: Attachment Name description: The attachment name of the node attachment_mime_type: anyOf: - type: string - type: 'null' title: Attachment Mime Type description: The attachment mime type of the node attachment_link: anyOf: - type: string - type: 'null' title: Attachment Link description: The attachment link of the node location_info: anyOf: - type: string - type: 'null' title: Location Info description: Location of the quoted text on the document (optional location_type: anyOf: - type: string - type: 'null' title: Location Type description: Type of the location of the quoted text revision_id: anyOf: - type: string - type: 'null' title: Revision Id description: The revision ID of the attachment (optional) external_source_url: anyOf: - type: string - type: 'null' title: External Source Url description: URL of the external source external_source_title: anyOf: - type: string - type: 'null' title: External Source Title description: Display name of the external source quote_narrowed: type: boolean title: Quote Narrowed description: >- True when quoted_text has already been narrowed to a short, verified supporting quote (or nulled after failing verification) instead of holding the full raw retrieved chunk. Set only where that narrowing actually happens; callers deciding whether to strip quoted_text should check this field rather than the request's feature flags, since a flag being on doesn't mean the citation's own flow acted on it. default: false bounding_boxes_available: type: boolean title: Bounding Boxes Available description: >- Whether this citation can be submitted to the bounding-box lookup endpoint. readOnly: true type: object required: - id - library_id - document_id - document_title - document_link - bounding_boxes_available title: Reference ChatLink: properties: title: type: string title: Title url: type: string title: Url type: object required: - title - url title: ChatLink securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.