Skip to Content

Upload a file

POSThttps://api.respan.ai/api/files/

Upload a file to the upstream OpenAI Files API. Batch jobs use JSONL files with purpose=batch.

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Request body

A request body is required.

multipart/form-data

Field Type Requirement Description and constraints
$ object Required body
-
file string Required in parent
File to upload.
Format: binary
purpose string Required in parent
File purpose.
Example: "batch"
provider_id string Required in parent
Provider route with customer-owned credentials, for example openai or parasail.

OpenAPI request schema

{
  "type": "object",
  "required": [
    "file",
    "purpose",
    "provider_id"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "description": "File to upload."
    },
    "purpose": {
      "type": "string",
      "description": "File purpose.",
      "example": "batch"
    },
    "provider_id": {
      "type": "string",
      "description": "Provider route with customer-owned credentials, for example `openai` or `parasail`."
    }
  }
}
Upload a batch input file
JSON
{ "file": "batch_input.jsonl", "purpose": "batch", "provider_id": "openai" }

Examples

Upload a batch input file

Headers

JSON
{ "Authorization": "Bearer YOUR_RESPAN_API_KEY" }

Request

JSON
{ "purpose": "batch", "provider_id": "openai" }

Response

JSON
{ "body": { "id": "file-abc123", "object": "file", "bytes": 12345, "created_at": 1710000000, "filename": "batch_input.jsonl", "purpose": "batch", "status": "processed", "status_details": null } }

curl

Terminal
curl --request POST 'https://api.respan.ai/api/files/' \ --header 'Authorization: Bearer YOUR_RESPAN_API_KEY' \ --form 'file=@batch_input.jsonl' \ --form 'purpose=batch' \ --form 'provider_id=openai'

Responses

200

Uploaded file.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed
id string Required in parent
File ID.
Example: "file-abc123"
object string Required in parent
Example: "file"
bytes integer Optional
File size in bytes.
Example: 12345
created_at integer Optional
Unix timestamp.
Example: 1710000000
filename string Optional
Example: "batch_input.jsonl"
purpose string Optional
Example: "batch"
status string Optional
File status.
Example: "processed"
status_details any or null Optional
Provider status details, when available.

OpenAPI response schema

{
  "type": "object",
  "required": [
    "id",
    "object"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "File ID.",
      "example": "file-abc123"
    },
    "object": {
      "type": "string",
      "example": "file"
    },
    "bytes": {
      "type": "integer",
      "description": "File size in bytes.",
      "example": 12345
    },
    "created_at": {
      "type": "integer",
      "description": "Unix timestamp.",
      "example": 1710000000
    },
    "filename": {
      "type": "string",
      "example": "batch_input.jsonl"
    },
    "purpose": {
      "type": "string",
      "example": "batch"
    },
    "status": {
      "type": "string",
      "description": "File status.",
      "example": "processed"
    },
    "status_details": {
      "nullable": true,
      "description": "Provider status details, when available."
    }
  },
  "additionalProperties": true
}

400

provider_id is missing, or the upload is invalid.

application/json

Field Type Requirement Description and constraints
$ object Body
-
error object Required in parent
-
error.message string Required in parent
-
error.type string Required in parent
-
error.param any or null Optional
-
error.code any or null Optional
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "message",
        "type"
      ],
      "properties": {
        "message": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "param": {
          "nullable": true
        },
        "code": {
          "nullable": true
        }
      }
    }
  }
}
Example
JSON
{ "error": { "message": "The Files and Batch endpoints require a 'provider_id' field naming the provider to call (e.g. provider_id=openai, provider_id=parasail): a form field on upload, a JSON body field on batch create, a query parameter on every other call. It cannot be inferred: the model names inside a batch file are the provider's own, and follow-up calls carry only opaque IDs.", "type": "upstream_provider_error", "param": null, "code": null } }

401

You haven’t added your own key for the provider in Settings › Providers, or the provider rejected it. Files and batches always run on your own key; Respan credits can’t cover them.

application/json

Field Type Requirement Description and constraints
$ object Body
-
error object Required in parent
-
error.message string Required in parent
-
error.type string Required in parent
-
error.param any or null Optional
-
error.code any or null Optional
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "message",
        "type"
      ],
      "properties": {
        "message": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "param": {
          "nullable": true
        },
        "code": {
          "nullable": true
        }
      }
    }
  }
}
Example
JSON
{ "error": { "message": "Please add your OpenAI API key in Settings -> Providers. The Files and Batch endpoints always run on your own credentials. Respan credits cannot cover them, because a batch's usage is only known after it completes.", "type": "upstream_provider_error", "param": null, "code": null } }

403

The API key is missing, invalid or expired.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Upload a file",
  "operationId": "uploadFile",
  "tags": [
    "OpenAI Batch"
  ],
  "description": "Upload a file to the upstream OpenAI Files API. Batch jobs use JSONL files with `purpose=batch`.",
  "requestBody": {
    "required": true,
    "content": {
      "multipart/form-data": {
        "schema": {
          "type": "object",
          "required": [
            "file",
            "purpose",
            "provider_id"
          ],
          "properties": {
            "file": {
              "type": "string",
              "format": "binary",
              "description": "File to upload."
            },
            "purpose": {
              "type": "string",
              "description": "File purpose.",
              "example": "batch"
            },
            "provider_id": {
              "type": "string",
              "description": "Provider route with customer-owned credentials, for example `openai` or `parasail`."
            }
          }
        },
        "examples": {
          "uploadBatchFile": {
            "summary": "Upload a batch input file",
            "value": {
              "file": "batch_input.jsonl",
              "purpose": "batch",
              "provider_id": "openai"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Uploaded file.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "id",
              "object"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "File ID.",
                "example": "file-abc123"
              },
              "object": {
                "type": "string",
                "example": "file"
              },
              "bytes": {
                "type": "integer",
                "description": "File size in bytes.",
                "example": 12345
              },
              "created_at": {
                "type": "integer",
                "description": "Unix timestamp.",
                "example": 1710000000
              },
              "filename": {
                "type": "string",
                "example": "batch_input.jsonl"
              },
              "purpose": {
                "type": "string",
                "example": "batch"
              },
              "status": {
                "type": "string",
                "description": "File status.",
                "example": "processed"
              },
              "status_details": {
                "nullable": true,
                "description": "Provider status details, when available."
              }
            },
            "additionalProperties": true
          }
        }
      }
    },
    "400": {
      "description": "`provider_id` is missing, or the upload is invalid.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "object",
                "required": [
                  "message",
                  "type"
                ],
                "properties": {
                  "message": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "param": {
                    "nullable": true
                  },
                  "code": {
                    "nullable": true
                  }
                }
              }
            }
          },
          "example": {
            "error": {
              "message": "The Files and Batch endpoints require a 'provider_id' field naming the provider to call (e.g. provider_id=openai, provider_id=parasail): a form field on upload, a JSON body field on batch create, a query parameter on every other call. It cannot be inferred: the model names inside a batch file are the provider's own, and follow-up calls carry only opaque IDs.",
              "type": "upstream_provider_error",
              "param": null,
              "code": null
            }
          }
        }
      }
    },
    "401": {
      "description": "You haven't added your own key for the provider in Settings › Providers, or the provider rejected it. Files and batches always run on your own key; Respan credits can't cover them.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "object",
                "required": [
                  "message",
                  "type"
                ],
                "properties": {
                  "message": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "param": {
                    "nullable": true
                  },
                  "code": {
                    "nullable": true
                  }
                }
              }
            }
          },
          "example": {
            "error": {
              "message": "Please add your OpenAI API key in Settings -> Providers. The Files and Batch endpoints always run on your own credentials. Respan credits cannot cover them, because a batch's usage is only known after it completes.",
              "type": "upstream_provider_error",
              "param": null,
              "code": null
            }
          }
        }
      }
    },
    "403": {
      "$ref": "#/components/responses/InvalidApiKey"
    }
  },
  "security": [
    {
      "RespanApiKey": []
    }
  ],
  "x-fern-examples": [
    {
      "name": "Upload a batch input file",
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      },
      "request": {
        "purpose": "batch",
        "provider_id": "openai"
      },
      "response": {
        "body": {
          "id": "file-abc123",
          "object": "file",
          "bytes": 12345,
          "created_at": 1710000000,
          "filename": "batch_input.jsonl",
          "purpose": "batch",
          "status": "processed",
          "status_details": null
        }
      },
      "code-samples": [
        {
          "sdk": "curl",
          "code": "curl --request POST 'https://api.respan.ai/api/files/' \\\n  --header 'Authorization: Bearer YOUR_RESPAN_API_KEY' \\\n  --form 'file=@batch_input.jsonl' \\\n  --form 'purpose=batch' \\\n  --form 'provider_id=openai'"
        }
      ]
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "responses": {
    "InvalidApiKey": {
      "description": "The API key is missing, invalid or expired.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    }
  },
  "securitySchemes": {
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}