Skip to main content

​
Overview

Request a pre-signed upload URL for direct client-to-storage uploads. This endpoint generates a unique file_id and temporary upload URL that allows you to upload files directly to storage without going through the API server.

​
Authentication

All Files API endpoints require authentication via Bearer token in the Authorization header. 
Authorization: Bearer ik_your_api_key_here

​
Request

curl -X POST "https://api.incredible.one/v1/files/upload-url" \
  -H "Authorization: Bearer ik_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "data.csv"
  }'

​
Request Body

  • filename string (required) — Name of the file to upload, including extension (e.g., "report.pdf", "data.csv")

​
Response

​
Success Response

{
  "success": true,
  "file_id": "550e8400-e29b-41d4-a716-446655440000",
  "upload_url": "https://storage.supabase.co/object/upload/sign/files/550e8400-e29b-41d4-a716-446655440000.csv?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "storage_path": "files/550e8400-e29b-41d4-a716-446655440000.csv"
}

​
Field Reference

  • success boolean — Always true for successful requests
  • file_id string (UUID) — Unique identifier for this file. Save this to use in chat completions.
  • upload_url string — Pre-signed URL for uploading the file. Expires in ~60 seconds.
  • storage_path string — Internal storage path (for reference only)

​
Important Notes

  1. 💾 Save the file_id (CRITICAL): Store the file_id immediately in your database or application state. This is your permanent reference to the file—you’ll reuse it across unlimited chat requests. Upload once, use forever.
  2. 🔄 Reuse, don’t re-upload: The file_id is permanent. Once you have it:
    • Use it in unlimited chat completions
    • No need to ever upload the same file again
    • Store it alongside user data for easy reuse
    • Build a file library in your app showing previously uploaded files
  3. ⏰ URL Expiration: The upload_url expires after approximately 60 seconds. If your upload takes longer, request a new URL.
  4. 🔓 No Authentication Required for Upload: The upload URL itself is pre-signed, so you don’t need to include your API key when uploading to the URL.
  5. 📝 File Extension: The filename should include the proper file extension (e.g., .pdf, .csv, .png) to ensure correct processing.

​
Next Steps

After receiving the upload URL:
  1. Upload the file to the upload_url using a PUT request with raw file bytes → See Upload File to Storage
  2. Confirm the upload to trigger processing → See Confirm Upload
  3. Use the file_id in your chat completions → See Chat Completion API

​
Error Responses

​
Missing Filename

{
  "success": false,
  "error": "filename is required"
}
Status Code: 400 Bad Request

​
Authentication Required

{
  "error": "Authentication required",
  "message": "API key must be provided in Authorization header"
}
Status Code: 401 Unauthorized

​
Invalid API Key

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid, inactive, or expired"
}
Status Code: 403 Forbidden

​
Example: Complete Upload Flow

import requests

# 1. Get upload URL
response = requests.post(
    "https://api.incredible.one/v1/files/upload-url",
    headers={"Authorization": "Bearer ik_your_api_key"},
    json={"filename": "report.pdf"}
)

data = response.json()
file_id = data["file_id"]
upload_url = data["upload_url"]

# 2. Upload file
with open('report.pdf', 'rb') as f:
    requests.put(
        upload_url,
        data=f.read(),
        headers={"Content-Type": "application/pdf"}
    )

# 3. Confirm upload
requests.post(
    "https://api.incredible.one/v1/files/confirm-upload",
    headers={"Authorization": "Bearer ik_your_api_key"},
    json={"file_id": file_id, "filename": "report.pdf", "file_size": 45678}
)

# 4. Use in chat
requests.post(
    "https://api.incredible.one/v1/chat/completions",
    headers={"Authorization": "Bearer ik_your_api_key"},
    model= "small-2",
    json={
        "messages": [
            {"role": "user", "content": "Summarize this", "file_ids": [file_id]}
        ]
    }
)