API docs by Redocly

Convilyn Upload API (1.0.0)

Download OpenAPI specification:

Convilyn Support: support@convilyn.com URL: https://convilyn.com/support License: Proprietary

File upload API for Convilyn - AI-powered file conversion platform.

Overview

Provides endpoints for uploading files via two methods:

  1. Local Upload - Two-step presigned URL flow for direct S3 uploads
  2. Cloud Upload - Import files from Google Drive or Dropbox

Authentication

All endpoints support both authenticated and anonymous users:

  • Authenticated: Include Authorization: Bearer <access_token> header
  • Anonymous: Omit Authorization header; server creates session via cookie

Upload Flow (Local Files)

1. POST /upload/presign → Get presigned S3 URL
2. PUT {presigned_url} → Upload file directly to S3
3. POST /upload/confirm → Confirm upload and create file record

Upload Flow (Cloud Files)

1. User authorizes OAuth with cloud provider (client-side)
2. POST /upload/cloud → Server downloads from cloud and uploads to S3

File Size Limits

  • Maximum file size: 100MB (configurable)
  • Files exceeding limit return HTTP 413

Naming Convention

Following project-wide convention (same as auth/payment contracts):

  • Request body fields: camelCase (fileName, fileSize, contentType)
  • Response body fields: camelCase (fileId, uploadUrl, mimeType)
  • Query params: snake_case (not used in this API)
  • Path params: snake_case (not used in this API)

Cloud Upload

Import files from cloud storage providers

Upload file from cloud storage

Upload a file from Google Drive or Dropbox.

Flow:

  1. Client obtains OAuth access token from cloud provider
  2. Client sends cloud file metadata and access token
  3. Server downloads file from cloud provider
  4. Server uploads file to S3
  5. Server creates file record and returns result

Supported Providers:

  • google-drive - Google Drive (supports Workspace file export)
  • dropbox - Dropbox

Google Workspace Files: Google Docs/Sheets/Slides are automatically exported to:

  • Docs → PDF
  • Sheets → XLSX
  • Slides → PPTX

Authentication: Optional (supports anonymous users via session cookie)

Request Body schema: application/json
required
provider
required
string (CloudProvider)
Enum: "google-drive" "dropbox"

Supported cloud storage providers

fileId
required
string <= 500 characters

File ID in the cloud provider

accessToken
required
string

OAuth access token for the cloud provider

fileName
required
string <= 255 characters

Original filename

mimeType
required
string <= 100 characters

MIME type of the file

fileSize
required
integer >= 1

File size in bytes

Responses

Request samples

Content type
application/json
{
  • "provider": "google-drive",
  • "fileId": "1A2b3C4d5E6f7G8h9I0j",
  • "accessToken": "ya29.a0...",
  • "fileName": "document.pdf",
  • "mimeType": "application/pdf",
  • "fileSize": 1024000
}

Response samples

Content type
application/json
{
  • "success": true,
  • "fileId": "file_abc123xyz",
  • "fileName": "document.pdf",
  • "fileSize": 1024000,
  • "jobId": "job_xyz789",
  • "mimeType": "application/pdf",
  • "isInput": true,
  • "createdAt": "2026-01-15T10:30:00Z"
}

Upload from cloud with progress

Upload a file from cloud storage with real-time progress updates via SSE.

Response Type: Server-Sent Events (text/event-stream)

Event Types:

  • progress - Upload progress update
  • complete - Upload completed successfully
  • error - Upload failed

Progress Events:

event: progress
data: {"progress": 50, "status": "Downloading...", "bytesProcessed": 500000, "totalBytes": 1000000}

Complete Event:

event: complete
data: {"success": true, "fileId": "...", "fileName": "...", ...}

Error Event:

event: error
data: {"success": false, "error": "...", "code": "...", "status": 500}

Authentication: Optional (supports anonymous users via session cookie)

Request Body schema: application/json
required
provider
required
string (CloudProvider)
Enum: "google-drive" "dropbox"

Supported cloud storage providers

fileId
required
string <= 500 characters

File ID in the cloud provider

accessToken
required
string

OAuth access token for the cloud provider

fileName
required
string <= 255 characters

Original filename

mimeType
required
string <= 100 characters

MIME type of the file

fileSize
required
integer >= 1

File size in bytes

Responses

Request samples

Content type
application/json
{
  • "provider": "google-drive",
  • "fileId": "1A2b3C4d5E6f7G8h9I0j",
  • "accessToken": "ya29.a0...",
  • "fileName": "document.pdf",
  • "mimeType": "application/pdf",
  • "fileSize": 1024000
}

Response samples

Content type
text/event-stream
event: progress
data: {"progress": 25, "status": "Downloading from cloud...", "bytesProcessed": 250000, "totalBytes": 1000000}

event: progress
data: {"progress": 75, "status": "Uploading to S3...", "bytesProcessed": 750000, "totalBytes": 1000000}

event: complete
data: {"success": true, "fileId": "file_abc123", "fileName": "document.pdf", "fileSize": 1000000, "jobId": "job_xyz789", "mimeType": "application/pdf", "isInput": true, "createdAt": "2026-01-15T10:30:00Z"}

Local Upload

Upload files using presigned S3 URLs

Generate presigned upload URL

Generate a presigned S3 URL for direct file upload.

Flow:

  1. Client sends file metadata
  2. Server generates presigned URL valid for 1 hour
  3. Client uploads file directly to S3 using PUT request
  4. Client confirms upload via /upload/confirm

Authentication: Optional (supports anonymous users via session cookie)

Request Body schema: application/json
required
fileName
required
string <= 255 characters

Original filename

fileSize
required
integer >= 1

File size in bytes

contentType
required
string <= 100 characters

MIME type of the file

jobId
string or null

Job ID to associate with (optional).

  • Omit for standalone uploads (loose coupling with Job module)
  • Job can be associated later via turbo-lane API
  • Enables upload-first, create-job-later workflow
chatId
string or null

Chat ID for goal lane uploads

Responses

Request samples

Content type
application/json
{
  • "fileName": "example.png",
  • "fileSize": 1024000,
  • "contentType": "image/png",
  • "jobId": "job_abc123"
}

Response samples

Content type
application/json
{}

Confirm file upload

Confirm that a file has been uploaded to S3 and create the file record.

Prerequisites:

  • File must have been uploaded to S3 using the presigned URL
  • File must exist in S3 with matching size

Verification:

  • Server verifies file exists in S3
  • Server verifies file size matches expected value
  • Creates file record in database

Authentication: Optional (supports anonymous users via session cookie)

Request Body schema: application/json
required
fileId
required
string

File ID from presign response

fileName
required
string

Original filename

fileSize
required
integer >= 1

File size in bytes

contentType
required
string

MIME type of the file

s3Key
required
string

S3 key from presign response

jobId
string or null

Job ID (optional for standalone uploads)

Responses

Request samples

Content type
application/json
{
  • "fileId": "file_xyz789",
  • "fileName": "example.png",
  • "fileSize": 1024000,
  • "contentType": "image/png",
  • "s3Key": "input/job_abc123/file_xyz789/example.png",
  • "jobId": "job_abc123"
}

Response samples

Content type
application/json
{
  • "fileId": "file_xyz789",
  • "jobId": "job_abc123",
  • "fileName": "example.png",
  • "fileSize": 1024000,
  • "mimeType": "image/png",
  • "isInput": true,
  • "createdAt": "2026-01-15T10:30:00Z"
}