> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Upload a file > Files are used to upload documents that can be used with features like Deployments. ## OpenAPI ````yaml post /v2/files openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - description: List models available through the AI Router. name: Models - name: Guardrail Rules - name: Policies - name: Routing Rules - name: API keys description: >- API keys authenticate programmatic access to the workspace. The unified key model exposes opaque tokens, per-domain access grants, and budget / rate-limit constraints (see ADR 0001 and ADR 0002). - name: Budgets description: >- Budgets govern spend, token usage, and request rate across six scopes: workspace, project, identity, api-key, provider, and model. A budget is hierarchical and defense-in-depth — every applicable budget is a hard gate, and the most restrictive one wins per dimension (see ADR 0007). - name: Documentation description: >- Search the orq.ai documentation. Proxies the workspace's query to the hosted docs search index. - name: Files description: File upload and retrieval operations. - name: Identities description: >- Identities represent end users from your system for usage and engagement tracking. - name: Projects description: Projects organize resources within a workspace - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Embeddings - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/files: post: tags: - Files summary: Upload a file description: >- Files are used to upload documents that can be used with features like Deployments. operationId: FileUpload requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateFileRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateFileResponse' x-code-samples: - lang: curl label: Core - Upload retrieval file source: | curl --request POST \ --url 'https://api.orq.ai/v2/files' \ --header 'Authorization: Bearer $ORQ_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "filename": "support-faq.md", "content": "IyBTdXBwb3J0IEZBUQoKQ29tbW9uIHJlc29sdXRpb25zIGFuZCBlc2NhbGF0aW9uIHBhdGhzLg==", "content_type": "text/markdown", "purpose": "FILE_PURPOSE_RETRIEVAL", "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V" }' - lang: python label: Python - Upload retrieval file source: | import base64 import os from orq_ai_sdk import Orq client = Orq(api_key=os.environ["ORQ_API_KEY"]) content = base64.b64encode( b"# Support FAQ\n\nCommon resolutions and escalation paths." ).decode("utf-8") result = client.files.create( filename="support-faq.md", content=content, content_type="text/markdown", purpose="FILE_PURPOSE_RETRIEVAL", project_id="proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V", ) print(result.file.file_id) - lang: typescript label: Node.js - Upload retrieval file source: | import { Orq } from '@orq-ai/node'; const client = new Orq({ apiKey: process.env.ORQ_API_KEY, }); const content = Buffer.from( '# Support FAQ\n\nCommon resolutions and escalation paths.', ).toString('base64'); const result = await client.files.create({ filename: 'support-faq.md', content, contentType: 'text/markdown', purpose: 'FILE_PURPOSE_RETRIEVAL', projectId: 'proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V', }); console.log(result.file.fileId); components: schemas: CreateFileRequest: required: - filename - content type: object properties: filename: type: string description: >- Name to store for the uploaded file, including extension when available. content: type: string description: Base64-encoded file contents. format: bytes purpose: $ref: '#/components/schemas/FilePurpose' description: |- Intended usage category for the uploaded file. Defaults to retrieval when omitted. content_type: type: string description: MIME type of the uploaded content, for example `application/pdf`. project_id: type: string description: >- Project the file is created in. Optional for project-scoped API keys (defaults to the key's bound project); required for workspace-scoped callers. CreateFileResponse: required: - file type: object properties: file: allOf: - $ref: '#/components/schemas/File' description: Newly created file. FilePurpose: type: string enum: - FILE_PURPOSE_UNSPECIFIED - FILE_PURPOSE_RETRIEVAL - FILE_PURPOSE_KNOWLEDGE_DATASOURCE - FILE_PURPOSE_BATCH File: required: - file_id - purpose - file_name - bytes - created_at - project_id type: object properties: file_id: type: string description: Unique file identifier assigned by ORQ. purpose: $ref: '#/components/schemas/FilePurpose' description: Declared usage category for the file. file_name: type: string description: Display file name, including extension when available. bytes: type: string description: Size of the uploaded file in bytes. created_at: type: string description: Time when the file was created. format: date-time project_id: type: string description: >- Identifier of the project the file belongs to. Files are project-scoped; an API key may only access files in projects it is authorized for. securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````