Skip to main content

​
Overview

After uploading a file to storage, call this endpoint to confirm the upload and trigger automatic file processing. The system will download the file, analyze it, extract metadata, and prepare it for use in chat completions.

​
Authentication

Authorization: Bearer ik_your_api_key_here

​
Request

curl -X POST "https://api.incredible.one/v1/files/confirm-upload" \
  -H "Authorization: Bearer ik_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "data.csv",
    "file_size": 2048
  }'

​
Request Body

  • file_id string (required) — UUID of the file from the /upload-url response
  • filename string (required) — Original filename with extension
  • file_size number (required) — File size in bytes

​
Response

The response varies based on file type. Here are examples for different file types:

​
CSV File Response

{
  "success": true,
  "file_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "data.csv",
  "file_size": 2048,
  "processed_at": "2024-01-01T12:00:00Z",
  "metadata": {
    "columns": ["name", "age", "city"],
    "row_count": 150,
    "data_types": {
      "name": "string",
      "age": "integer",
      "city": "string"
    },
    "preview": [
      {"name": "Alice", "age": 30, "city": "New York"},
      {"name": "Bob", "age": 25, "city": "San Francisco"}
    ]
  },
  "processing_summary": "CSV with 3 columns (name, age, city), 150 rows"
}

​
PDF File Response

{
  "success": true,
  "file_id": "660e8400-e29b-41d4-a716-446655440000",
  "filename": "report.pdf",
  "file_size": 45678,
  "processed_at": "2024-01-01T12:05:00Z",
  "metadata": {
    "page_count": 12,
    "text_length": 8432,
    "extracted_text": "This is the beginning of the document...",
    "text_preview": "First 500 characters..."
  },
  "processing_summary": "PDF with 12 pages, 8432 characters extracted via OCR"
}

​
Excel File Response

{
  "success": true,
  "file_id": "770e8400-e29b-41d4-a716-446655440000",
  "filename": "sales.xlsx",
  "file_size": 15234,
  "processed_at": "2024-01-01T12:10:00Z",
  "metadata": {
    "sheet_names": ["Q1 Sales", "Q2 Sales", "Summary"],
    "sheets": {
      "Q1 Sales": {
        "columns": ["date", "product", "revenue"],
        "row_count": 90
      },
      "Q2 Sales": {
        "columns": ["date", "product", "revenue"],
        "row_count": 91
      },
      "Summary": {
        "columns": ["quarter", "total_revenue"],
        "row_count": 4
      }
    }
  },
  "processing_summary": "Excel file with 3 sheets (Q1 Sales, Q2 Sales, Summary)"
}

​
Image File Response

{
  "success": true,
  "file_id": "880e8400-e29b-41d4-a716-446655440000",
  "filename": "diagram.png",
  "file_size": 125678,
  "processed_at": "2024-01-01T12:15:00Z",
  "metadata": {
    "width": 1920,
    "height": 1080,
    "format": "PNG",
    "mode": "RGBA"
  },
  "processing_summary": "PNG image, 1920x1080 pixels"
}

​
JSON File Response

{
  "success": true,
  "file_id": "990e8400-e29b-41d4-a716-446655440000",
  "filename": "config.json",
  "file_size": 1024,
  "processed_at": "2024-01-01T12:20:00Z",
  "metadata": {
    "top_level_keys": ["settings", "database", "api"],
    "structure_depth": 3,
    "total_keys": 47,
    "preview": {
      "settings": {
        "timeout": 30,
        "retries": 3
      }
    }
  },
  "processing_summary": "JSON with 3 top-level keys, 47 total keys"
}

​
Field Reference

  • success boolean — Whether file processing succeeded
  • file_id string — UUID of the file
  • filename string — Original filename
  • file_size number — File size in bytes
  • processed_at string — ISO 8601 timestamp of processing
  • metadata object — File-specific metadata (varies by type)
  • processing_summary string — Human-readable summary of file contents

​
File Processing Details

File TypeProcessing TimeWhat’s Analyzed
CSV< 1 secondColumn names, data types, row count, preview
Excel1-2 secondsSheet names, columns per sheet, row counts
PDF2-10 secondsOCR text extraction, page count
Images< 1 secondDimensions, format, color mode
JSON< 1 secondStructure, keys, depth
Text< 1 secondCharacter count, line count
Note: PDF processing time depends on page count and image complexity.

​
Error Responses

​
File Not Found in Storage

{
  "success": false,
  "error": "File not found in storage",
  "details": "Verify the file was uploaded successfully"
}
Status Code: 404 Not Found Solution: Ensure the file was uploaded to the pre-signed URL before confirming.

​
Invalid File Type

{
  "success": false,
  "error": "Unsupported file type: .exe"
}
Status Code: 400 Bad Request Solution: Use a supported file type (CSV, PDF, Excel, images, JSON, text).

​
File Too Large

{
  "success": false,
  "error": "File size exceeds 50 MB limit",
  "file_size": 52428800,
  "max_size": 52428800
}
Status Code: 400 Bad Request

​
Processing Failed

{
  "success": false,
  "error": "Failed to process file",
  "details": "Invalid CSV format: missing header row"
}
Status Code: 500 Internal Server Error

​
Authentication Required

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

​
Complete Upload Flow Example

import requests

def upload_and_confirm_file(api_key, file_path, filename):
    """
    Complete file upload flow: get URL, upload, confirm.
    """
    # Step 1: Get upload URL
    response = requests.post(
        "https://api.incredible.one/v1/files/upload-url",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"filename": filename}
    )
    data = response.json()
    file_id = data["file_id"]
    upload_url = data["upload_url"]
    
    # Step 2: Upload file
    with open(file_path, 'rb') as f:
        file_bytes = f.read()
    
    response = requests.put(
        upload_url,
        data=file_bytes,
        headers={"Content-Type": "application/pdf"}
    )
    
    if response.status_code not in [200, 201]:
        return {"success": False, "error": "Upload failed"}
    
    # Step 3: Confirm upload
    response = requests.post(
        "https://api.incredible.one/v1/files/confirm-upload",
        headers={"Authorization": f"Bearer {api_key}"},
        json={
            "file_id": file_id,
            "filename": filename,
            "file_size": len(file_bytes)
        }
    )
    
    return response.json()

# Usage
result = upload_and_confirm_file(
    api_key="ik_your_api_key",
    file_path="report.pdf",
    filename="report.pdf"
)

if result["success"]:
    print(f"✓ File uploaded and processed!")
    print(f"  File ID: {result['file_id']}")
    print(f"  Summary: {result['processing_summary']}")
else:
    print(f"✗ Error: {result['error']}")

​
Next Steps

After confirming the upload:
  1. Use the file in chat completions by including the file_id → See Chat Completion API
  2. Retrieve file metadata anytime → See Get Files Metadata
  3. Upload more files to use together in a single chat → See Generate Upload URL

​
Best Practices

  1. Wait for confirmation response: Don’t use the file in chat until confirmation succeeds
  2. Handle processing errors: Check success field before proceeding
  3. Store metadata: Save the processing summary and metadata for reference
  4. Validate file types: Check file extension client-side before uploading
  5. Timeout handling: Set appropriate timeouts (PDFs may take 5-10 seconds to process)