> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Content

> Retrieve the original content of an ingested source.

## When to use it

* **Download original files** – PDFs, DOCX, etc. that you uploaded
* **Generate temporary share links** – presigned URLs for client-side access
* **Re-extract content** – rebuild downstream caches from the source of truth
* **Preview** – display original content alongside recall results

## Endpoint

* **Auth:** Bearer token
* **Idempotency:** Read-only
* **Async:** No

## Example

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST 'https://api.hydradb.com/fetch/content' \
    -H "Authorization: Bearer <your_api_key>" \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": "my_first_tenant",
      "source_id": "doc_12345",
      "mode": "url",
      "expiry_seconds": 3600
    }'
  ```

  ```typescript TypeScript SDK theme={"dark"}
  const result = await client.fetch.content({
    tenant_id: "my_first_tenant",
    source_id: "doc_12345",
    mode: "url",
    expiry_seconds: 3600
  });
  ```

  ```python Python SDK theme={"dark"}
  result = client.fetch.content(
      tenant_id="my_first_tenant",
      source_id="doc_12345",
      mode="url",
      expiry_seconds=3600,
  )
  ```
</CodeGroup>

## Request parameters

| Name             | Type    | Required | Default   | Description                                                                                           |
| ---------------- | ------- | -------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `tenant_id`      | string  | Yes      | –         | The tenant the source belongs to.                                                                     |
| `source_id`      | string  | Yes      | –         | The source to fetch.                                                                                  |
| `sub_tenant_id`  | string  | No       | default   | Sub-tenant scope.                                                                                     |
| `mode`           | enum    | No       | `content` | What to return. See [Modes](#modes).                                                                  |
| `expiry_seconds` | integer | No       | `3600`    | Presigned URL expiry (60–604800, i.e., 1 minute to 7 days). Only relevant when `mode` includes `url`. |

## Modes

| Mode                | Returns                                          |
| ------------------- | ------------------------------------------------ |
| `content` (default) | File content as text, or base64 for binary files |
| `url`               | Presigned URL only                               |
| `both`              | Content **and** presigned URL                    |

Use `url` for client-side downloads where you don't want to proxy bytes through your backend.

Use `content` when you need to process the file inline.

## Response

```json theme={"dark"}
{
  "success": true,
  "source_id": "doc_12345",
  "content": "Q4 Pricing Strategy\n\nThis document outlines...",
  "content_base64": null,
  "presigned_url": "https://storage.hydradb.com/presigned/...",
  "content_type": "application/pdf",
  "size_bytes": 245760,
  "message": "File fetched successfully"
}
```

| Field            | Description                                                             |
| ---------------- | ----------------------------------------------------------------------- |
| `success`        | `true` on a successful fetch.                                           |
| `source_id`      | The source that was fetched.                                            |
| `content`        | Text content (when `mode` is `content` or `both` and the file is text). |
| `content_base64` | Base64-encoded content for binary files.                                |
| `presigned_url`  | Time-limited download URL (when `mode` is `url` or `both`).             |
| `content_type`   | MIME type of the source.                                                |
| `size_bytes`     | Size of the original file.                                              |
| `error`          | Error message if fetch failed.                                          |

## Behavior notes

<Info>
  **Binary vs text.** For PDFs and other binaries, `content` is empty and the data is in `content_base64`. For markdown, plain text, or extracted text, `content` is populated directly.
</Info>

<Info>
  **Presigned URLs are time-limited.** Once `expiry_seconds` elapses, the URL stops working. Generate a fresh URL for each long-lived integration rather than caching them.
</Info>

## Related endpoints

* **Find sources first:** [List data](/api-reference/endpoint/list-data) – browse to find a `source_id`
* **Inspect relationships:** [Graph relations by source ID](/api-reference/endpoint/graph-relations) – see entities extracted from this source

## Errors

Common codes: `400 INVALID_PARAMETERS`, `404 SOURCE_NOT_FOUND`, `422 VALIDATION_ERROR`. See [Error Responses](/api-reference/error-responses) for the full list.


## OpenAPI

````yaml POST /fetch/content
openapi: 3.1.0
info:
  title: HydraDB API
  description: REST APIs for the HydraDB retrieval engine
  version: 0.0.1
servers:
  - url: https://api.hydradb.com
    description: Production
    x-fern-server-name: hydradb-prod
security: []
paths:
  /fetch/content:
    post:
      tags:
        - fetch
      summary: Fetch Source
      operationId: fetch_source_fetch_content_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceFetchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceFetchResponse'
        '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:
    SourceFetchRequest:
      properties:
        tenant_id:
          type: string
          title: Tenant Id
          description: Unique identifier for the tenant/organization
          example: tenant_1234
        sub_tenant_id:
          anyOf:
            - type: string
            - type: 'null'
          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
        source_id:
          type: string
          title: Source Id
          description: Source ID of the file to fetch
          example: <source_id>
        mode:
          $ref: '#/components/schemas/FetchMode'
          description: >-
            Fetch mode: 'content' returns file content, 'url' returns presigned
            URL, 'both' returns both
          default: content
        expiry_seconds:
          type: integer
          maximum: 604800
          minimum: 60
          title: Expiry Seconds
          description: 'Expiry time in seconds for presigned URL (60-604800, default: 3600)'
          default: 3600
          example: 1
      type: object
      required:
        - tenant_id
        - source_id
      title: SourceFetchRequest
      description: Request to fetch source file content.
    SourceFetchResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the fetch was successful
          default: true
          example: true
        source_id:
          type: string
          title: Source Id
          description: Source ID of the fetched file
          example: <source_id>
        content:
          anyOf:
            - type: string
            - type: 'null'
          title: Content
          description: File content as string (if mode includes 'content')
        content_base64:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Base64
          description: >-
            File content as base64 encoded string (for binary files, if mode
            includes 'content')
        presigned_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Presigned Url
          description: Presigned URL to access the file (if mode includes 'url')
        content_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Type
          description: Content type of the file
        size_bytes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Size Bytes
          description: Size of the file in bytes
        message:
          type: string
          title: Message
          description: Response message
          default: File fetched successfully
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if fetch failed
      type: object
      required:
        - source_id
      title: SourceFetchResponse
      description: Response for file fetch request.
    cortex__models__response__commons__ActualErrorResponse:
      properties:
        detail:
          $ref: >-
            #/components/schemas/cortex__models__response__commons__ErrorResponse
      type: object
      required:
        - detail
      title: ActualErrorResponse
    FetchMode:
      type: string
      enum:
        - content
        - url
        - both
      title: FetchMode
      description: Mode for fetching file content.
    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
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````