> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-ad5578da.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List Sources By ID

> Retrieve specific sources by their IDs.

Use this endpoint to fetch one or more sources by providing their
unique identifiers. This is useful when you need detailed information
about specific documents or content you've previously uploaded.

Provide the source IDs in the request body along with your tenant
information to get the exact sources you need.

export const TableOfContents = ({title = 'On this page', items, minHeadingLevel = 2, maxHeadingLevel = 3, className = '', activeClassName = 'text-primary dark:text-primary-light border-primary dark:border-primary-light hover:border-primary dark:hover:border-primary-light', inactiveClassName = 'hover:text-gray-900 dark:text-gray-400 dark:hover:text-gray-300'}) => {
  const [toc, setToc] = useState(items ?? []);
  const [activeId, setActiveId] = useState('');
  useEffect(() => {
    if (items && items.length) return;
    if (typeof document === 'undefined') return;
    const selectors = [];
    for (let lvl = minHeadingLevel; lvl <= maxHeadingLevel; lvl++) {
      selectors.push(`h${lvl}`);
    }
    const nodes = Array.from(document.querySelectorAll(selectors.join(','))).filter(el => el.id);
    const built = [];
    let currentTop = null;
    nodes.forEach(el => {
      const level = Number(el.tagName.slice(1));
      const node = {
        id: el.id,
        label: el.textContent.trim(),
        href: `#${el.id}`,
        children: []
      };
      if (level === minHeadingLevel) {
        built.push(node);
        currentTop = node;
      } else if (level > minHeadingLevel && currentTop) {
        currentTop.children.push(node);
      } else {
        built.push(node);
      }
    });
    setToc(built);
  }, [items, minHeadingLevel, maxHeadingLevel]);
  useEffect(() => {
    if (typeof document === 'undefined') return;
    const applyHash = () => {
      const h = window.location.hash.replace('#', '');
      if (h) setActiveId(h);
    };
    applyHash();
    const observer = new IntersectionObserver(entries => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          setActiveId(entry.target.id);
        }
      });
    }, {
      rootMargin: '0px 0px -70% 0px',
      threshold: 0.1
    });
    const ids = toc.flatMap(i => [i, ...i.children ?? []]).map(i => i.id);
    ids.forEach(id => {
      const el = document.getElementById(id);
      if (el) observer.observe(el);
    });
    window.addEventListener('hashchange', applyHash);
    return () => {
      window.removeEventListener('hashchange', applyHash);
      observer.disconnect();
    };
  }, [toc]);
  const Item = ({node, depth = 0}) => {
    const isActive = activeId === node.id;
    return <li className="toc-item relative ml-6" data-depth={depth}>
        <a href={node.href} className={`py-1 block font-medium ${isActive ? activeClassName : inactiveClassName}`} style={depth > 0 ? {
      marginLeft: `${depth}rem`
    } : {}} onClick={() => setActiveId(node.id)}>
          {node.label}
        </a>
        {node.children && node.children.length > 0 && <>
            {node.children.map(child => <Item node={child} depth={depth + 1} key={child.href} />)}
          </>}
      </li>;
  };
  const data = toc && toc.length ? toc : items || [];
  return <div className={`text-gray-600 text-sm leading-6 w-[18rem] pb-4 -mt-10 pt-10 hidden xl:block ${className}`} id="table-of-contents-custom">
      <ul id="table-of-contents-custom-content" className="toc">
        <li className="toc-item relative">
          <div className="text-gray-700 dark:text-gray-300 font-medium flex items-center space-x-2 py-1">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="2" xmlns="http://www.w3.org/2000/svg" className="h-3 w-3">
              <path d="M2.44434 12.6665H13.5554" strokeLinecap="round" strokeLinejoin="round"></path>
              <path d="M2.44434 3.3335H13.5554" strokeLinecap="round" strokeLinejoin="round"></path>
              <path d="M2.44434 8H7.33323" strokeLinecap="round" strokeLinejoin="round"></path>
            </svg>
            <span>{title}</span>
          </div>
        </li>
        {data.map(node => <Item node={node} key={node.href} />)}
      </ul>
    </div>;
};

<Panel>
  <TableOfContents />
</Panel>

<Tip> Hit the `Try it` button to try this API now in our playground. It's the best way to check the full request and response in one place, customize your parameters, and generate ready-to-use code snippets.</Tip>

### Examples

<Tabs>
  <Tab title="API Request">
    ```bash theme={null}
    curl -X 'POST' \
    'https://api.usecortex.ai/list/list-sources-by-id' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
    "source_ids": [
    "string"
    ],
    "tenant_id": "string",
    "sub_tenant_id": "string"
    }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    const specificSources = await client.sources.getByIds({
      tenant_id: "tenant_1234",
      sub_tenant_id: "sub_tenant_4567",
      source_ids: ["doc_123", "doc_456"]
    });
    ```
  </Tab>

  <Tab title="Python (Sync)">
    ```python theme={null}
    # Async usage is similar, just use async_client and await
    specific_sources = client.sources.get_by_ids(
        tenant_id="tenant_1234",
        sub_tenant_id="sub_tenant_4567",
        source_ids=["doc_123", "doc_456"]
    )
    ```
  </Tab>
</Tabs>

## Overview

Retrieve specific sources by their IDs. Use this API to fetch one or more sources by providing their unique identifiers. This is useful when you need detailed information about specific documents or content you've previously uploaded.

## Example Request

```json theme={null}
{
  "tenant_id": "tenant_456",
  "sub_tenant_id": "subtenant_123",
  "source_ids": ["doc_123", "doc_456"]
}
```

## Example Response

````json theme={null}
{
  "sources": [
    {
      "id": "CortexDoccf0f1ccee4864c679bad5678bb1c515a1757402245",
      "title": "ai-2027.pdf",
      "type": "file",
      "timestamp": "1757402409.7277222",
      "description": "### **AI Futures** **Project** # **AI** **2027** ### **AI Futures** ### **Project** ## **`Daniel Kokotajlo`** **`Scott Alexander`** **`Thomas Larsen`** **`Eli Lifland`** **`Romeo Dean`** ``` Originally published on April 3rd 2025 on AI-2027.com ``` ``` Design by Lightcone Infrastructure ``` ## **AI 2027** We predict that the impact of superhuman AI",
      "document_metadata": {},
      "tenant_metadata": {}
    }
  ],
  "success": true,
  "message": "Successfully fetched sources"
}
````

## Error Responses

All endpoints return consistent error responses following the standard format. For detailed error information, see our [Error Responses](/api-reference/error-responses) documentation.


## OpenAPI

````yaml POST /list/list-sources-by-id
openapi: 3.1.0
info:
  title: Cortex SDK API
  description: REST APIs for Cortex AI retrieval engine
  version: 0.0.1
servers:
  - url: /
    description: Local
    x-fern-server-name: cortex-backend-local
  - url: https://api.usecortex.ai
    description: Production
    x-fern-server-name: cortex-prod
    x-fern-audiences:
      - public
  - url: https://preprod.usecortex.ai
    description: Staging
    x-fern-server-name: cortex-staging
security: []
paths:
  /list/list-sources-by-id:
    post:
      tags:
        - list
      summary: Get User Sources By Id
      description: |-
        Retrieve specific sources by their IDs.

        Use this endpoint to fetch one or more sources by providing their
        unique identifiers. This is useful when you need detailed information
        about specific documents or content you've previously uploaded.

        Provide the source IDs in the request body along with your tenant
        information to get the exact sources you need.
      operationId: get_user_sources_by_id_list_list_sources_by_id_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListSourcesByIdRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceListResponse'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '403':
          description: Forbidden - Access denied
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '422':
          description: Unprocessable Entity - Validation failed
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/cortex__models__response__commons__ActualErrorResponse
      security:
        - HTTPBearer: []
components:
  schemas:
    ListSourcesByIdRequest:
      properties:
        source_ids:
          items:
            type: string
          type: array
          minItems: 1
          title: Source Ids
          description: List of source IDs to fetch.
          example:
            - CortexDoc1234
            - CortexDoc4567
        tenant_id:
          type: string
          title: Tenant Id
          description: Tenant ID
          example: tenant_1234
        sub_tenant_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Sub Tenant Id
          description: Sub-tenant ID
          example: sub_tenant_4567
      type: object
      required:
        - source_ids
        - tenant_id
      title: ListSourcesByIdRequest
    SourceListResponse:
      properties:
        success:
          type: boolean
          title: Success
          default: true
          example: true
        message:
          type: string
          title: Message
          default: Sources retrieved successfully
        sources:
          items:
            $ref: '#/components/schemas/SourceModel-Output'
          type: array
          title: Sources
        total:
          type: integer
          title: Total
          description: Total number of sources matching the query.
          example: 1
      type: object
      required:
        - total
      title: SourceListResponse
    cortex__models__response__commons__ActualErrorResponse:
      properties:
        detail:
          $ref: >-
            #/components/schemas/cortex__models__response__commons__ErrorResponse
      type: object
      required:
        - detail
      title: ActualErrorResponse
    SourceModel-Output:
      properties:
        id:
          type: string
          title: Id
          description: >-
            Stable, unique identifier for the source. If omitted, one may be
            generated upstream.
          example: <id>
        tenant_id:
          type: string
          title: Tenant Id
          description: Unique identifier for the tenant/organization
          example: tenant_1234
        sub_tenant_id:
          type: string
          title: Sub Tenant Id
          description: >-
            Optional sub-tenant identifier used to organize data within a
            tenant. If omitted, the default sub-tenant created during tenant
            setup will be used.
          example: sub_tenant_4567
        title:
          type: string
          title: Title
          description: Short human-readable title for the source.
          default: ''
          example: <title>
        type:
          type: string
          title: Type
          description: High-level category of the source (e.g., document, email, ticket).
          default: ''
          example: <type>
        description:
          type: string
          title: Description
          description: Optional long-form description providing additional context.
          default: ''
          example: <description>
        note:
          type: string
          title: Note
          description: Free-form notes for internal use or ingestion hints.
          default: ''
          example: <note>
        url:
          type: string
          title: Url
          description: Canonical URL or reference link associated with the source.
          default: ''
          example: <url>
        timestamp:
          type: string
          title: Timestamp
          description: Creation or last-updated timestamp of the source in ISO-8601 format.
          default: ''
          example: <timestamp>
        content:
          $ref: '#/components/schemas/ContentModel'
          description: Primary content payload used for indexing and retrieval.
        tenant_metadata:
          additionalProperties: true
          type: object
          title: Tenant Metadata
          description: >+
            JSON string containing tenant-level document metadata (e.g.,
            department, compliance_tag)


            Example: > "{"department":"Finance","compliance_tag":"GDPR"}"

        document_metadata:
          additionalProperties: true
          type: object
          title: Document Metadata
          description: >+
            JSON string containing document-specific metadata (e.g., title,
            author, file_id). If file_id is not provided, the system will
            generate an ID automatically.


            Example: > "{"title":"Q1 Report.pdf","author":"Alice
            Smith","file_id":"custom_file_123"}"


        meta:
          additionalProperties: true
          type: object
          title: Meta
          description: >-
            System-provided attributes (e.g., app_name, local file size) not
            intended for search filtering.
        attachments:
          items:
            $ref: '#/components/schemas/AttachmentModel'
          type: array
          title: Attachments
          description: >-
            Attachments related to the source such as images, PDFs, or
            supplemental files.
          example: []
      type: object
      required:
        - id
        - tenant_id
        - sub_tenant_id
      title: SourceModel
    cortex__models__response__commons__ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          default: false
          example: true
        message:
          type: string
          title: Message
          default: Error occurred
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
      type: object
      title: ErrorResponse
    ContentModel:
      properties:
        text:
          type: string
          title: Text
          description: Plain text content extracted or provided for indexing.
          default: ''
          example: <text>
        html_base64:
          type: string
          title: Html Base64
          description: Base64-encoded HTML content preserving structure and formatting.
          default: ''
          example: <html_base64>
        csv_base64:
          type: string
          title: Csv Base64
          description: Base64-encoded CSV data for tabular content ingestion.
          default: ''
          example: <csv_base64>
        markdown:
          type: string
          title: Markdown
          description: Raw Markdown content to be indexed as rich text.
          default: ''
          example: <markdown>
        files:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Files
          description: >-
            List of file descriptors associated with the source (e.g.,
            filenames, sizes).
        layout:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Layout
          description: >-
            Optional layout metadata such as sections or blocks to guide
            chunking.
          example: []
      type: object
      title: ContentModel
    AttachmentModel:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the attachment.
          default: ''
          example: <id>
        url:
          type: string
          title: Url
          description: Public or internal URL referencing the attachment resource.
          default: ''
          example: <url>
        title:
          type: string
          title: Title
          description: Human-readable title or filename of the attachment.
          default: ''
          example: <title>
        content_type:
          type: string
          title: Content Type
          description: MIME type of the attachment (e.g., application/pdf).
          default: ''
          example: <content_type>
        content_url:
          type: string
          title: Content Url
          description: >-
            Direct URL for content retrieval when different from the reference
            URL.
          default: ''
          example: <content_url>
        misc:
          additionalProperties: true
          type: object
          title: Misc
          description: Additional attachment attributes defined by the tenant (free-form).
        content:
          $ref: '#/components/schemas/ContentModel'
          description: Structured content payload for the attachment when available.
      type: object
      title: AttachmentModel
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````