# Upload a file

Upload a file to an organization for use in vector stores, file search, or AI conversations.

Upload files directly through the API using multipart/form-data. This is the simplest upload method and works for files up to 100MB. The file is automatically uploaded to cloud storage, validated, and registered in the database. For larger files (>100MB) or when you need resumable uploads, use the [resumable upload flow](/docs/api-reference/files/upload-url).

#### Path Parameters

**`organization_id`** string required

The unique identifier of the organization.

#### Request Body (multipart/form-data)

**`files`** file[] required

The file(s) to upload. Maximum file size: 100MB per file. File type and content are automatically validated using MIME type detection and magic byte verification.

## Returns

Returns a [File object](/docs/api-reference/objects/file-object) with complete metadata including:

- Generated file ID
- Storage path in cloud storage
- File size and MIME type
- Upload timestamp and user information


Request

```bash cURL
curl -X POST https://api.aitronos.com/v1/organizations/org_123/files/upload \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -F "files=@/path/to/document.pdf"
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

with open("/path/to/document.pdf", "rb") as f:
    result = client.files.upload_file(
        "org_abc123",
        files=[f],
    )

print(result.files[0].id)
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]
org_id = "org_123"

url = f"https://api.aitronos.com/v1/organizations/{org_id}/files/upload"
headers = {"X-API-Key": api_key}

with open("/path/to/document.pdf", "rb") as file:
    files = {"files": file}
    response = requests.post(url, headers=headers, files=files)
    file_obj = response.json()
    print(f"Uploaded file: {file_obj['id']}")
```


```javascript JavaScript
const fs = require('fs');
const FormData = require('form-data');

const apiKey = process.env.FREDDY_API_KEY;
const orgId = 'org_123';

const form = new FormData();
form.append('files', fs.createReadStream('/path/to/document.pdf'));

fetch(`https://api.aitronos.com/v1/organizations/${orgId}/files/upload`, {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    ...form.getHeaders()
  },
  body: form
})
  .then(res => res.json())
  .then(file => console.log('Uploaded file:', file.id));
```

Response

```json 200 OK
{
  "success": true,
  "message": "Files uploaded successfully",
  "files": [
    {
      "id": "file_abc123xyz789",
      "original_filename": "document.pdf",
      "file_size": 2457600,
      "mime_type": "application/pdf",
      "storage_path": "files/org_123/file_abc123xyz789/document.pdf",
      "organization_id": "org_123",
      "uploaded_by": "usr_user123",
      "uploaded_by_api_key_id": null,
      "uploaded_at": "2025-12-22T15:30:00Z"
    }
  ],
  "total_uploaded": 1,
  "total_failed": 0,
  "errors": []
}
```


```json 400 Bad Request - Invalid file type
{
  "success": false,
  "error": {
    "code": "INVALID_FILE_TYPE",
    "message": "File type not supported",
    "type": "client_error",
    "status": 400,
    "details": {
      "mime_type": "application/x-executable",
      "supported_types": [
        "application/pdf",
        "text/plain",
        "image/png"
      ]
    },
    "trace_id": "abc-123-def",
    "timestamp": "2025-12-22T15:30:00Z",
    "system_message": "File type not supported"
  }
}
```


```json 400 Bad Request - File too large
{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds maximum limit of 100MB",
    "type": "client_error",
    "status": 400,
    "details": {
      "file_size": 125829120,
      "max_size": 104857600
    },
    "trace_id": "abc-123-def",
    "timestamp": "2025-12-22T15:30:00Z",
    "system_message": "File size exceeds maximum limit of 100MB"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "ORGANIZATION_ACCESS_DENIED",
    "message": "You do not have access to this organization",
    "type": "client_error",
    "status": 403,
    "details": {
      "organization_id": "org_123"
    },
    "trace_id": "abc-123-def",
    "timestamp": "2025-12-22T15:30:00Z",
    "system_message": "You do not have access to this organization"
  }
}
```

## Supported File Types

- **Documents**: PDF, TXT, DOCX, DOC, RTF, MD
- **Spreadsheets**: CSV, XLSX, XLS
- **Data**: JSON, XML, YAML
- **Code**: PY, JS, TS, JAVA, CPP, and more
- **Images**: PNG, JPG, JPEG, WEBP (for vision models)


## Related Resources

- [Get File Content URL](/docs/api-reference/files/content)
- [Download File](/docs/api-reference/files/download)
- [List Files](/docs/api-reference/files/list)
- [Retrieve File](/docs/api-reference/files/retrieve)
- [Delete File](/docs/api-reference/files/delete)
- [File Object](/docs/api-reference/objects/file-object)