# Generate upload URL

Generate a resumable upload URL for large file uploads (advanced).

Generate a resumable upload session URI for uploading large files directly to cloud storage. This endpoint is designed for files larger than 100MB or when you need resumable upload capabilities (e.g., unreliable network connections). The returned upload URL is valid for 7 days.

For simpler uploads under 100MB, use the [direct upload endpoint](/docs/api-reference/files/upload) instead.

#### Path Parameters

**`organization_id`** string required

The unique identifier of the organization.

#### Request Body

**`filename`** string required

Original filename (1-255 characters).

**`file_size`** integer required

File size in bytes. Must be greater than 0.

**`mime_type`** string required

MIME type of the file (e.g., `application/pdf`, `video/mp4`).

**`upload_type`** string optional

Upload type: `resumable` or `simple`. Default: `resumable`.

## Returns

Returns an upload session object containing:

- `upload_url` - Resumable upload session URI for uploading the file
- `gcs_path` - Destination path in cloud storage (use this when registering)
- `file_id` - Pre-generated file ID
- `expires_at` - Session expiry timestamp (7 days from now)
- `max_file_size` - Maximum allowed file size (5GB)
- `upload_type` - Upload type (always `resumable`)
- `chunk_size_recommended` - Recommended chunk size for uploads (5MB)


After uploading your file to the `upload_url`, call the [register file endpoint](/docs/api-reference/files/register) with the `gcs_path` to complete the process.

Request

```bash cURL
curl -X POST https://api.aitronos.com/v1/organizations/org_123/files/upload-url \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "large_video.mp4",
    "file_size": 524288000,
    "mime_type": "video/mp4"
  }'
```


```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-url"
headers = {"X-API-Key": api_key}

data = {
    "filename": "large_video.mp4",
    "file_size": 524288000,
    "mime_type": "video/mp4"
}

response = requests.post(url, headers=headers, json=data)
upload_session = response.json()

print(f"Upload URL: {upload_session['upload_url']}")
print(f"File ID: {upload_session['file_id']}")
print(f"GCS Path: {upload_session['gcs_path']}")
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;
const orgId = 'org_123';

const data = {
  filename: 'large_video.mp4',
  file_size: 524288000,
  mime_type: 'video/mp4'
};

fetch(`https://api.aitronos.com/v1/organizations/${orgId}/files/upload-url`, {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
  .then(res => res.json())
  .then(session => {
    console.log('Upload URL:', session.upload_url);
    console.log('File ID:', session.file_id);
  });
```

Response

```json 200 OK
{
  "upload_url": "https://storage.googleapis.com/upload/storage/v1/b/bucket/o?uploadType=resumable&upload_id=xyz789",
  "gcs_path": "files/org_123/file_abc123xyz789/large_video.mp4",
  "file_id": "file_abc123xyz789",
  "expires_at": "2025-12-29T15:30:00Z",
  "max_file_size": 5368709120,
  "upload_type": "resumable",
  "chunk_size_recommended": 5242880
}
```


```json 400 Bad Request - Invalid file size
{
  "success": false,
  "error": {
    "code": "INVALID_FIELD_VALUE",
    "message": "File size must be greater than 0",
    "type": "client_error",
    "status": 400,
    "details": {
      "field": "file_size",
      "value": 0
    },
    "trace_id": "abc-123-def",
    "timestamp": "2025-12-22T15:30:00Z"
  }
}
```


```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"
  }
}
```

## Resumable Upload Example

After receiving the upload URL, upload your file using the resumable protocol:


```python
import requests

# Step 1: Get upload URL (from above)
upload_url = upload_session['upload_url']
gcs_path = upload_session['gcs_path']
file_id = upload_session['file_id']

# Step 2: Upload file to GCS using resumable protocol
with open('/path/to/large_video.mp4', 'rb') as f:
    headers = {
        'Content-Type': 'video/mp4'
    }
    upload_response = requests.put(upload_url, headers=headers, data=f)

# Step 3: Register the completed upload (see Register File endpoint)
register_url = f"https://api.aitronos.com/v1/organizations/{org_id}/files"
register_data = {
    "filename": "large_video.mp4",
    "gcs_path": gcs_path,
    "file_size": 524288000,
    "mime_type": "video/mp4"
}
register_response = requests.post(
    register_url,
    headers={"X-API-Key": api_key},
    json=register_data
)
file_obj = register_response.json()
print(f"File registered: {file_obj['id']}")
```

## Upload Process

1. Call this endpoint to get an upload URL
2. Upload file to the returned `upload_url` using resumable upload protocol
3. Call [register file endpoint](/docs/api-reference/files/register) with the `gcs_path` and `file_id`


## Related Resources

- [Upload File](/docs/api-reference/files/upload) - Simple upload for files under 100MB
- [Register File](/docs/api-reference/files/register) - Complete the upload process
- [List Files](/docs/api-reference/files/list)
- [File Object](/docs/api-reference/objects/file-object)