> ## Documentation Index > Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt > Use this file to discover all available pages before exploring further. # AI Search > AI-powered search that retrieves relevant knowledge from your teamspace, builds a merged context, and generates a natural language answer with numbered source citations. The response includes the generated answer, the sources cited (with links and metadata), and the full search tree results for reference. Use this when you want an AI-generated summary answer grounded in your team's data. ## OpenAPI ````yaml post /search/ai openapi: 3.0.3 info: version: 0.1.1 title: Datagrid API description: Datagrid API servers: - url: https://api.datagrid.com/v1 security: - BearerAuth: [] paths: /search/ai: post: tags: - Search summary: AI Search description: > AI-powered search that retrieves relevant knowledge from your teamspace, builds a merged context, and generates a natural language answer with numbered source citations. The response includes the generated answer, the sources cited (with links and metadata), and the full search tree results for reference. Use this when you want an AI-generated summary answer grounded in your team's data. operationId: searchAi requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchAiRequestBody' responses: '200': description: >- An AI-generated answer with source citations and the underlying search tree results. content: application/json: schema: $ref: '#/components/schemas/SearchAiResult' headers: X-Daily-Credit-Cap-Remaining: $ref: '#/components/headers/DailyCreditCapRemaining' X-Monthly-Credit-Cap-Remaining: $ref: '#/components/headers/MonthlyCreditCapRemaining' '402': description: >- Credit limit exceeded. Either the organization does not have enough credits to perform this search, or it has reached the monthly credit cap set in Control Tower. Check your billing status, or wait for the cap to reset. headers: X-Daily-Credit-Cap-Remaining: $ref: '#/components/headers/DailyCreditCapRemaining' X-Monthly-Credit-Cap-Remaining: $ref: '#/components/headers/MonthlyCreditCapRemaining' '429': description: >- Rate limit exceeded. The request has been throttled because the rate limit for this endpoint has been reached. Check the `Retry-After` response header and retry after the specified number of seconds. content: application/json: schema: $ref: '#/components/schemas/RateLimitError' components: schemas: SearchAiRequestBody: type: object description: Request body for AI-powered search. required: - query properties: query: type: string description: >- The natural language search query. The AI will search your indexed knowledge and generate an answer. record_types: type: array nullable: true items: $ref: '#/components/schemas/SearchRecordType' description: >- Optional filter to restrict search to specific record types (rows, tables, files, pages, cells). display_type: nullable: true description: >- Optional filter to restrict results to one display type (dataset, document, image, or channel). Applied before pagination, so pages cover the full filtered result pool. Honored when paginated search is enabled for the teamspace (Gen Search phase 3). allOf: - $ref: '#/components/schemas/SearchDisplayType' limit: type: integer nullable: true description: >- Maximum number of search results to consider when generating the answer. default: 10 offset: type: integer nullable: true description: >- Number of results to skip before the returned page, for paginating search results. Combine with `skip_ai_generation: true` to fetch subsequent pages without regenerating the AI answer. Honored when paginated search is enabled for the teamspace (Gen Search phase 3). default: 0 skip_ai_generation: type: boolean nullable: true description: >- When true, returns the requested page of search results without generating an AI answer (`answer` is null and `sources` is empty). Cannot be combined with streaming. Honored when paginated search is enabled for the teamspace (Gen Search phase 3). default: false SearchAiResult: type: object description: >- AI-generated answer with source citations and the underlying search results. required: - object - answer - sources - search_results - credits properties: object: type: string enum: - search_ai_result description: The object type, always `search_ai_result`. answer: type: string nullable: true description: >- AI-generated natural language answer based on the search results. Contains numbered citations like [1], [2] that reference entries in the `sources` array. Null when the request set `skip_ai_generation: true`. sources: type: array items: $ref: '#/components/schemas/AiSource' description: >- Sources cited in the answer, ordered by citation index. Each source links back to the original data in your teamspace. search_results: $ref: '#/components/schemas/SearchTreeResult' description: >- The full search tree results used to generate the answer. Useful for displaying raw results alongside the AI summary. credits: nullable: true description: >- Credit consumption for this search. When present, `consumed` reflects the actual variable cost of the retrieval work performed for this request. `null` when the billing write fails or the request is aborted before billing completes. allOf: - $ref: '#/components/schemas/OperationCredits' RateLimitError: type: object description: >- Returned when the rate limit is exceeded. Rate limits are enforced per teamspace, endpoint path, and HTTP method over a 60-second sliding window. Each endpoint may have its own limit — check the X-RateLimit-Limit response header for the effective value. required: - error - message - retryable - status_code properties: status_code: type: integer description: The HTTP status code (429). statusCode: type: integer deprecated: true description: Deprecated. Use status_code instead. error: type: string enum: - rate_limit_exceeded description: The error code identifying this as a rate limit error. message: type: string description: A human-readable error message. mitigation: type: string description: Suggested action to resolve the error. retryable: type: boolean description: Whether the request can be retried after a delay. details: type: object properties: reason: type: string description: A detailed explanation of why the rate limit was exceeded. SearchRecordType: type: string description: The record type in the vector database. enum: - rows - tables - files - pages - cells SearchDisplayType: type: string description: >- Product-facing grouping of one result card, aligned with the result tabs in the Datagrid web app. Derived from the card's structure and media type: tables and records are `dataset`, files with an `image/*` media type are `image`, other files and pages are `document`, and channels are `channel`. enum: - dataset - document - image - channel AiSource: type: object description: A source cited in an AI-generated search answer. required: - index - node_id - type - title properties: index: type: integer description: >- 1-based citation index corresponding to [N] references in the answer text. node_id: type: string description: Unique identifier of the source node in the search tree. type: type: string enum: - file - record - table description: >- The type of source: `file` (document/attachment), `record` (data row), or `table` (dataset). title: type: string description: Human-readable title of the source. dataset_name: type: string description: Name of the dataset this source belongs to, if applicable. table_name: type: string description: Name of the table this source belongs to, if applicable. emoji: type: string description: Emoji icon for the source type (e.g., 📄 for files, 📊 for tables). url: type: string description: URL to view the source in the Datagrid web app. thumbnail_uri: type: string description: URI for a thumbnail preview of the source, if available. page_numbers: type: array items: type: integer description: Page numbers within a document where the relevant content was found. SearchTreeResult: type: object description: >- Hierarchical search results grouped by source (datasets, files, pages) with navigation items. required: - object - query - data - nav_items - has_more - credits properties: object: type: string enum: - search_tree description: The object type, always `search_tree`. query: type: string description: The original search query. data: type: array items: type: object description: >- Tree nodes representing search results grouped by source. Each node contains the matched content, metadata, score, and child nodes for hierarchical display. nav_items: type: array items: type: object description: >- Navigation items providing quick links to the datasets, tables, and files that matched the query. Each item includes a name, emoji, URL, and type. has_more: type: boolean description: >- Whether more results are available beyond this page. Use the `next` cursor to fetch additional results. next: type: string nullable: true description: >- Pagination cursor (numeric offset as string). Pass this value as the `next` query parameter to `/search/tree` to fetch the next page. total_count: type: integer nullable: true description: >- Total number of grouped results in the ranked result pool across all pages (capped by the retrieval pool limit). Only present when paginated search is enabled for the teamspace (Gen Search phase 3). counts_by_display_type: nullable: true description: >- Number of results per display type across the entire result pool, independent of the current page or any filter. Only present when paginated search is enabled for the teamspace (Gen Search phase 3). allOf: - $ref: '#/components/schemas/SearchCountsByDisplayType' display_items: type: array nullable: true items: $ref: '#/components/schemas/SearchDisplayItem' description: >- Canonical ordered result cards for this page — one item per result, in ranked order with pinned dataset/channel supplements first. Render these directly instead of traversing `data`. Only present when paginated search is enabled for the teamspace (Gen Search phase 3). credits: nullable: true description: >- Credit consumption for this search. When present, `consumed` reflects the actual variable cost of the retrieval work performed for this request. `null` when the billing write fails or the request is aborted before billing completes. allOf: - $ref: '#/components/schemas/OperationCredits' OperationCredits: type: object required: - consumed properties: consumed: type: number description: The number of credits consumed by the operation. SearchCountsByDisplayType: type: object description: Result counts per display type across the entire result pool. required: - datasets - documents - images - channels properties: datasets: type: integer description: >- Number of dataset results: tables, data records, and name-matched datasets. documents: type: integer description: >- Number of document results: non-image files and standalone pages (multiple matched pages of one file count as a single file). images: type: integer description: 'Number of image results: files with an `image/*` media type.' channels: type: integer description: Number of name-matched channel results. SearchDisplayItem: type: object description: >- One search result card with no structural children. Items arrive in ranked page order; each corresponds to exactly one rendered result. required: - object - id - kind - display_type - table_id properties: object: type: string enum: - search_display_item description: The object type, always `search_display_item`. id: type: string description: >- Stable identifier of the result (document id for retrieval results, entity id for dataset/channel supplements). kind: type: string enum: - record - file - page - dataset - channel description: >- The kind of result card: a data record, a file, a single file page, a dataset, or a channel. display_type: description: >- Product-facing grouping of this card, aligned with the result tabs in the Datagrid web app. allOf: - $ref: '#/components/schemas/SearchDisplayType' title: type: string description: Card title. body: type: string description: Card body text (matched content snippet). score: type: number description: Relevance score of the result, between 0 and 1. created_at: type: string description: When the underlying item was created. updated_at: type: string description: When the underlying item was last updated. url: type: string description: >- Resolved navigation target: a trusted source deep link when available, otherwise the dataset URL in the Datagrid web app. dataset_name: type: string description: Name of the dataset this result belongs to. table_name: type: string description: Name of the table this result belongs to. table_id: type: string description: Identifier of the table this result belongs to. table_fingerprint: type: string description: Fingerprint of the table, used to build dataset URLs. navigation_item_id: type: string description: Identifier of the navigation item for the dataset or channel. emoji: type: string description: Emoji icon of the dataset or channel. file_uri: type: string description: >- Datagrid file URI for file/page media, used to resolve thumbnails and viewers. media_type: type: string description: Media type of the file (e.g. `application/pdf`, `image/png`). data_lake_item_id: type: string description: Identifier of the data-lake item backing the file. page_number: type: integer description: 1-based page number within the source document, for `page` items. page_url: type: string description: Datagrid file URI scoped to this page, for `page` items. total_pages: type: integer description: Total number of pages in the source document. parent_record: description: >- The record (row) this file or page is attached to, when it belongs to one — for example the RFI a photo was uploaded with. Present only for `file` and `page` items. allOf: - $ref: '#/components/schemas/SearchParentRecord' channel_data: description: Channel details. Present only for `channel` items. allOf: - $ref: '#/components/schemas/SearchDisplayItemChannelData' SearchParentRecord: type: object description: The record (row) a file or page search result is attached to. required: - id properties: id: type: string description: Document identifier of the record. title: type: string description: Record title. body: type: string description: Record summary text. SearchDisplayItemChannelData: type: object description: Channel membership and visibility details for channel search results. required: - channel_type - is_private - is_joined - participant_count - people_count - agent_count properties: channel_type: type: string description: One of `channel`, `directMessage`, or `chats`. is_private: type: boolean description: Whether the channel is private. is_joined: type: boolean description: Whether the requesting user is a member of this channel. participant_count: type: integer description: Total number of members (people + agents). people_count: type: integer description: Number of human members. agent_count: type: integer description: Number of AI/agent members. headers: DailyCreditCapRemaining: description: >- Credits left before the account's daily credit cap (set in Control Tower) is reached, rounded up. `0` means the cap has been reached; the daily cap does not block requests. Present only when a daily cap is configured. schema: type: integer example: 600 MonthlyCreditCapRemaining: description: >- Credits left before the account's monthly credit cap (set in Control Tower) is reached, rounded up. At `0`, credit-consuming requests return `402` until the next calendar month. Present only when a monthly cap is configured. schema: type: integer example: 15000 securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.