Files API

Use Cases

Reusing the same document across many API operations (datasource creation, batch jobs, downloads) without uploading it again.
Grounding agents and deployments with knowledge base datasources.
Storing JSONL datasets as files for batch jobs.
Giving code interpreter tools access to project documents.

Upload a file once with the Files API (/v2/files), then reuse it across Orq.ai: create a knowledge base datasource from it, feed a batch job, or download its content through a presigned URL. For sending inline image, PDF, or audio content directly in a request, see Multimodal inputs and generation.

Upload

Create a file with a JSON body or multipart form data.

Download

Get a presigned URL valid for one hour.

Knowledge base

Turn an uploaded file into a datasource for retrieval.

Manage

List, update metadata, and delete files.

Upload a file

POST /v2/files accepts a JSON body or multipart/form-data. JSON body fields:

Field	Type	Description
`filename`	string	Required. Name of the file, including the extension.
`content`	string	Required. Base64-encoded file contents.
`purpose`	string	Intended usage. Defaults to `retrieval`.
`content_type`	string	MIME type of the content, for example `application/pdf`.
`project_id`	string	Project the file is created in. Project-scoped API keys default to the key’s bound project.

The upload request uses filename; the response file object and the PATCH update use file_name. For multipart uploads, send the file in the file form field and set purpose and project_id as additional form fields. The MIME type is read from the file part’s Content-Type header.

curl --request POST \
     --url https://api.orq.ai/v2/files \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORQ_API_KEY' \
     --header 'content-type: multipart/form-data' \
     --form file='@contract.pdf' \
     --form purpose='retrieval'

curl --request POST \
     --url https://api.orq.ai/v2/files \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORQ_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "filename": "contract.pdf",
       "content": "<base64-encoded-content>",
       "content_type": "application/pdf",
       "purpose": "retrieval"
     }'

import { Orq } from "@orq-ai/node";
import fs from "node:fs";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.files.create({
    filename: "contract.pdf",
    content: fs.readFileSync("contract.pdf").toString("base64"),
    contentType: "application/pdf",
    purpose: "FILE_PURPOSE_RETRIEVAL",
  });

  console.log(result);
}

run();

from orq_ai_sdk import Orq
import base64
import os

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    with open("contract.pdf", "rb") as f:
        content = base64.b64encode(f.read()).decode("utf-8")

    res = orq.files.create(
        filename="contract.pdf",
        content=content,
        content_type="application/pdf",
        purpose="FILE_PURPOSE_RETRIEVAL",
    )

    print(res)

Purposes

Purpose	Description
`retrieval`	Default. General-purpose documents; usable as knowledge base datasources.
`knowledge_datasource`	Documents chunked and indexed into a knowledge base.
`batch`	JSONL datasets for batch inference jobs. Allows larger files.
`code_interpreter`	Documents available to code interpreter tools.

The REST API accepts lowercase purpose values on input (for example retrieval); the response object returns the prefixed form (for example FILE_PURPOSE_RETRIEVAL). The SDKs use the prefixed form for both input and output.

The file object

A successful upload returns the file object under a file key:

{
  "file": {
    "file_id": "file_01JA5D27ZVW2N702Z0D3B1G8EK",
    "purpose": "FILE_PURPOSE_RETRIEVAL",
    "file_name": "contract.pdf",
    "bytes": "245760",
    "created_at": "2026-08-10T12:00:00Z",
    "project_id": "project_01JA5D27ZVW2N702Z0D3B1G8EK"
  }
}

Field	Type	Description
`file_id`	string	Unique identifier, with a `file_` prefix.
`purpose`	string	Declared usage category.
`file_name`	string	Display name, including the extension.
`bytes`	string	Size of the uploaded file in bytes, returned as a decimal string.
`created_at`	string	Time when the file was created.
`project_id`	string	Project the file belongs to.

Keep the file_id for later operations: retrieval, metadata updates, downloads, and datasource creation.

Files and model calls

Model calls receive file content inline. Images and PDFs are passed as public URLs or base64 data URIs in the message content array. See Multimodal inputs and generation for the exact content parts. To use an uploaded file in a model call, index it into a knowledge base and attach the knowledge base to the deployment or agent. See From file to knowledge base and Run Agents: Attach Files.

Download file content

GET /v2/files/{file_id_or_path}/content returns a presigned URL for downloading the file content.

curl --request GET \
     --url https://api.orq.ai/v2/files/file_01JA5D27ZVW2N702Z0D3B1G8EK/content \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORQ_API_KEY'

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.files.getContent({
    fileIdOrPath: "file_01JA5D27ZVW2N702Z0D3B1G8EK",
  });

  console.log(result);
}

run();

from orq_ai_sdk import Orq
import os

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    res = orq.files.get_content(file_id_or_path="file_01JA5D27ZVW2N702Z0D3B1G8EK")

    print(res)

{
  "download_url": "https://storage.orq.ai/..."
}

Presigned URLs expire after one hour. Call the endpoint again to get a fresh URL.

List, update, and delete files

List files: GET /v2/files. Results are sorted by file_id in ascending order, so the most recently created files appear last. Page through with limit (default 10, maximum 200). Set starting_after to the file_id of the last item of the previous page, or ending_before to the first item. Filter by purpose or project_id. Retrieve a file: GET /v2/files/{file_id} returns the file object. Update metadata: PATCH /v2/files/{file_id} updates the file name. The body accepts file_name; content cannot be changed after upload. Delete a file: DELETE /v2/files/{file_id} permanently deletes the file record and its stored content. Deletion cannot be undone.

curl --request DELETE \
     --url https://api.orq.ai/v2/files/file_01JA5D27ZVW2N702Z0D3B1G8EK \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORQ_API_KEY'

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const fileId = "file_01JA5D27ZVW2N702Z0D3B1G8EK";

  const list = await orq.files.list({ limit: 10 });
  const file = await orq.files.get({ fileId });
  const updated = await orq.files.update({
    fileId,
    updateFileRequest: { fileName: "renamed.txt" },
  });
  await orq.files.delete({ fileId });

  console.log({ list, file, updated });
}

run();

from orq_ai_sdk import Orq
import os

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    file_id = "file_01JA5D27ZVW2N702Z0D3B1G8EK"

    listing = orq.files.list(limit=10)
    file = orq.files.get(file_id=file_id)
    updated = orq.files.update(file_id=file_id, file_name="renamed.txt")
    orq.files.delete(file_id=file_id)

    print(listing, file, updated)

Supported types and limits

Purpose	Maximum size	Supported types
`retrieval`, `knowledge_datasource`, `code_interpreter`	10 MB	TXT, PDF, DOC, DOCX, CSV, XLS, XLSX
`batch`	100 MB	JSONL (JSONL or NDJSON content)

Files with multiple filename extensions are rejected. The stored MIME type comes from the declared content_type or the filename extension.

Data handling and lifecycle

Project scope: files belong to the project they were created in. An API key can only access files in the projects it is authorized for.
Persistence: file content persists until explicitly deleted with DELETE /v2/files/{file_id}. There is no automatic expiry.
Presigned URLs: download links expire after one hour and can be regenerated at any time.
Cleanup: delete files that are no longer referenced. For long-running agents and deployments, delete superseded documents after the consuming run finishes to avoid unbounded storage.

For data handling, retention, and privacy practices, see Data compliance and privacy. For zero-data-retention deployments, see Sovereign AI & ZDR.

From file to knowledge base

The file-based knowledge base flow uploads a document, then points a datasource at the resulting file_id. Orq.ai chunks and indexes the file automatically.

Upload the document with POST /v2/files and save the file_id.
Create a datasource with POST /v2/knowledge/{knowledge_id}/datasources, passing file_id and display_name.
Attach the knowledge base to a deployment or agent to ground responses in the indexed content.

For the upload and datasource code samples, chunking options, and memory stores, see Knowledge Bases & Memory Stores.

Upload a file · List all files · Retrieve a file · Update a file · Delete a file · Download file content
Files SDK Reference

Overview

Routing

Security & Privacy

Model Capabilities

Analytics & Monitoring

Integrations

Upload

Download

Knowledge base

Manage

Upload a file

Purposes

The file object

Files and model calls

Download file content

List, update, and delete files

Supported types and limits

Data handling and lifecycle

From file to knowledge base

Upload

Download

Knowledge base

Manage

​Upload a file

​Purposes

​The file object

​Files and model calls

​Download file content

​List, update, and delete files

​Supported types and limits

​Data handling and lifecycle

​From file to knowledge base

​Related reference

Upload a file

Purposes

The file object

Files and model calls

Download file content

List, update, and delete files

Supported types and limits

Data handling and lifecycle

From file to knowledge base

Related reference