Skip to content
API Reference
API Reference

Create a File Upload

Upload one local file, remote HTTPS URL, or base64 source and receive a temporary URL.

View Markdown

Upload one local file, remote HTTPS URL, or base64 source and receive a temporary URL.

Endpoint

POST /api/v1/files
Base URL
https://runapi.ai
API version
v1
Authentication
Authorization: Bearer YOUR_API_KEY
02

Request

JSON body

Send values only in the listed request location.

application/json - Base64 source4 fields
file_namestring
Optional

Optional filename for the created File Upload.

sourceobject
Required

Base64-encoded source bytes.

source.datastring
Required

Base64 data

source.typestring
Required

Selects the base64 source representation.

application/json - URL source4 fields
file_namestring
Optional

Optional filename for the created File Upload.

sourceobject
Required

Remote HTTPS source to download.

source.typestring
Required

Selects the URL source representation.

source.urlstring
Required

Public HTTPS URL to download.

multipart/form-data2 fields
filestring
Required

Local file bytes to upload.

file_namestring
Optional

Optional filename for the created File Upload.

03

Success response

HTTP 201

POST /api/v1/files

JSON 
{
  "created_at": "2026-07-27T10:00:00.000Z",
  "expires_at": "2026-07-27T11:00:00.000Z",
  "file_name": "mask.png",
  "mime_type": "image/png",
  "size_bytes": 204800,
  "url": "https://file.runapi.ai/temp/user-uploads/mask.png"
}
04

Error response (401)

HTTP 401
Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "Authentication required"
}
05

Error response (403)

HTTP 403
Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "Standard API key required"
}
06

Error response (400)

HTTP 400
Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "Only HTTPS URLs are allowed"
}
07

Error response (408)

HTTP 408
Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "Download timeout"
}
08

Error response (413)

HTTP 413
Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "File size exceeds the maximum allowed size"
}
09

Error response (415)

HTTP 415
Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "This content type is not supported"
}
10

Error response (422)

HTTP 422
Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "File upload failed. Please try again."
}
11

Error response (429)

HTTP 429
Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "Too many file uploads for this account. Please retry later."
}
12

cURL example

CURL 
curl -X POST https://runapi.ai/api/v1/files \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"source":{"type":"url","url":"https://cdn.runapi.ai/public/samples/mask.png"},"file_name":"mask.png"}'