> ## Documentation Index > Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Add File > Add a file to a knowledge base by upload or URL. File names must be unique within a directory. Uploading `report.pdf` to `docs/` when it already exists returns `409`. Folders and files share the same namespace: you cannot upload a file whose name matches an existing folder in the same directory. ## OpenAPI ````yaml POST /orgs/{org_id}/k2/{kb_id}/files openapi: 3.1.0 info: title: Timbal Platform API description: Public API documentation for the Timbal platform license: name: '' version: 2.0.0 servers: - url: https://api.timbal.ai description: Production - url: https://api.dev.timbal.ai description: Development security: [] tags: - name: ace description: Action Control Engine (ACE) operations - name: alarms description: Metric series and threshold alarms - name: analytics description: Org and project analytics - name: billing description: Subscriptions, usage, and payment-related operations - name: channels description: Delivery channels alarms notify through - name: content description: Re-sign stored content URLs - name: files description: File operations - name: iam description: IAM — actions, roles, users, and authorization introspection - name: k2 description: Knowledge Bases v2 operations - name: orgs description: Organization operations - name: projects description: Project operations - name: runs description: Execution operations - name: templates description: Public project template catalog - name: users description: Authenticated user profile paths: /orgs/{org_id}/k2/{kb_id}/files: post: tags: - k2 description: Add a file to a knowledge base by upload or URL. operationId: add parameters: - name: org_id in: path required: true schema: type: string - name: kb_id in: path required: true schema: type: string requestBody: content: multipart/form-data: schema: type: object description: >- Request body for adding a file to a knowledge base. Provide either `file` (multipart bytes) or `url` (http/https). Exactly one is required. required: - metadata properties: directory: type: - string - 'null' description: Optional subdirectory path within the knowledge base. file: type: - array - 'null' items: type: integer format: int32 minimum: 0 description: >- File bytes (multipart `file` field). Mutually exclusive with `url`. contentMediaType: application/octet-stream metadata: type: object description: Optional JSON metadata to attach to the file. parse: type: - boolean - 'null' description: >- When set, overrides whether the file is parsed and embedded on upload. url: type: - string - 'null' description: >- Public http/https URL for the server to fetch and ingest. Mutually exclusive with `file`. required: true responses: '201': description: File uploaded headers: RateLimit-Limit: schema: type: integer description: Max requests per window for this user. RateLimit-Remaining: schema: type: integer description: Requests left in the current window. RateLimit-Reset: schema: type: integer description: Seconds until the current window resets. X-RateLimit-Limit: schema: type: integer description: Legacy alias of `RateLimit-Limit`. X-RateLimit-Remaining: schema: type: integer description: Legacy alias of `RateLimit-Remaining`. X-RateLimit-Reset: schema: type: integer description: Legacy alias of `RateLimit-Reset`. content: application/json: schema: $ref: '#/components/schemas/K2File' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '429': description: Rate limit exceeded headers: RateLimit-Limit: schema: type: integer description: Max requests per window for this user. RateLimit-Remaining: schema: type: integer description: Requests left in the current window. RateLimit-Reset: schema: type: integer description: Seconds until the current window resets. Retry-After: schema: type: integer description: Seconds the client should wait before retrying. X-RateLimit-Limit: schema: type: integer description: Legacy alias of `RateLimit-Limit`. X-RateLimit-Remaining: schema: type: integer description: Legacy alias of `RateLimit-Remaining`. X-RateLimit-Reset: schema: type: integer description: Legacy alias of `RateLimit-Reset`. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' security: - bearer_auth: [] components: schemas: K2File: type: object required: - id - uid - kb_id - name - content_type - content_length - metadata - parse_state - url - created_at - updated_at properties: content_length: type: integer format: int64 content_type: type: string created_at: type: string format: date-time directory: type: - string - 'null' id: type: integer format: int64 kb_id: type: integer format: int64 metadata: {} name: type: string parse_state: type: string description: >- Pipeline state for parsing + embedding. One of `pending` (pipeline in flight), `success` (parse + embed both completed), `failed` (latest attempt failed), or `skipped` (format unsupported, never parsed). Unsupported files are stored as-is; the indicator lets clients flag them in listings rather than rejecting the upload. signed_url: type: - string - 'null' description: >- CloudFront signed URL on the new CDN for private content. Omitted when signing is unavailable or the object is public. uid: type: string updated_at: type: string format: date-time url: type: string description: >- **Deprecated:** prefer `signed_url` when present. Kept for old clients. deprecated: true ErrorMessage: type: object required: - code - message properties: code: type: string description: Machine-readable error code (e.g. `ALREADY_EXISTS`, `BAD_REQUEST`). message: type: string description: Human-readable description. securitySchemes: bearer_auth: type: http scheme: bearer description: >- Timbal API key. Obtain your API key from the Timbal platform settings. See [Authentication](/api-reference/authentication) for more information. ````