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 with the Files API (/v2/files), then reuse it across Orq.ai: reference it in a model request, 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 model request, see Image, PDF, and audio: 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://my.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://my.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.
`code_interpreter`	Documents available to code interpreter tools.

Both these aliases and the FILE_PURPOSE_* names work on JSON and multipart uploads. An omitted purpose resolves to retrieval. The two upload paths echo the value back in different forms:

Upload	Response `purpose`
JSON body	Prefixed form, for example `FILE_PURPOSE_RETRIEVAL`
`multipart/form-data`	Lowercase alias, for example `retrieval`

The SDKs take and return the prefixed form.

The file object

A successful JSON 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",
    "workspace_id": "workspace_01JA5D27ZVW2N702Z0D3B1G8EK",
    "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.
`workspace_id`	string	Workspace the file belongs to.
`project_id`	string	Project the file belongs to.

A multipart upload returns the record at the top level:

{
  "_id": "file_01JA5D27ZVW2N702Z0D3B1G8EK",
  "purpose": "retrieval",
  "file_name": "contract.pdf",
  "workspace_id": "workspace_01JA5D27ZVW2N702Z0D3B1G8EK",
  "project_id": "project_01JA5D27ZVW2N702Z0D3B1G8EK",
  "bytes": 245760,
  "created": "2026-08-10T12:00:00Z"
}

The multipart record carries the identifier as _id, the timestamp as created, and bytes as a number. Keep the file identifier (file_id from a JSON upload, _id from a multipart upload) for later operations, and pass that value wherever this page names file_id: model requests, retrieval, metadata updates, downloads, and datasource creation.

Files and model calls

Reference an uploaded file directly in a model request with file_id: set it on an input_file content part for the Responses API, or inside the file object of a file content part for Chat Completions. The AI Gateway checks workspace and project access, then reads the stored content before calling the provider. See Sending files to models for both request shapes. For uploaded images, use an input_image content part with file_id in the Responses API, or an image_url content part with the file ID as image_url.url in Chat Completions. Public URLs and base64 data URIs are also supported. The selected model must support image input. See Image, PDF, and audio: multimodal inputs and generation. For indexed retrieval, create a knowledge base datasource from the file and attach the knowledge base to a 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://my.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. Set order=desc to return the newest files first. 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://my.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`	100 MiB	TXT, PDF, DOC, DOCX, CSV, XLS, XLSX, PNG, JPG/JPEG, WebP, GIF
`batch`	100 MiB	JSONL (JSONL or NDJSON content)

The limit applies to the decoded file. Upload requests allow up to 150 MiB to accommodate base64 encoding. Stored files referenced in a model request have a combined 100 MiB limit; the selected provider may impose a lower limit. OpenAI PDF inputs must stay below 50 MB per file and 50 MB combined per request. Each workspace has a 1 TiB quota for original files, shared across its projects. Files used by knowledge bases count toward this quota; extracted chunks, vectors, and indexes do not. Existing files and pending upload reservations count toward the limit. A quota error rejects a new upload before its content is stored. Delete files to free capacity. For direct knowledge-base upload URLs, supply byte_size to reserve the exact file size; the upload must match it. Without byte_size, the URL reserves 100 MiB. These reservations remain allocated while the file exists because the URL can be reused. Deleted or abandoned uploads retain their reservation until the URL expires, a further 24-hour grace period passes, and a subsequent upload triggers cleanup. 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.

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

Overview

Managed Agents

Context Management

Test & Evaluate

Chat

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