Skip to Content

List files

GEThttps://api.respan.ai/api/files/

List files from the upstream OpenAI Files API using the authenticated organization key’s OpenAI credentials.

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

Query parameters

Parameter Type Required Description and constraints
provider_id string Required
Provider route with customer-owned credentials, for example openai or parasail.

Responses

200

List of files.

application/json

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

OpenAPI response schema

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "object": {
      "type": "string",
      "example": "list"
    },
    "data": {
      "type": "array",
      "items": {
        "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
      }
    }
  },
  "additionalProperties": true
}

400

provider_id is missing.

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": "List files",
  "operationId": "listFiles",
  "tags": [
    "OpenAI Batch"
  ],
  "description": "List files from the upstream OpenAI Files API using the authenticated organization key's OpenAI credentials.",
  "responses": {
    "200": {
      "description": "List of files.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "object": {
                "type": "string",
                "example": "list"
              },
              "data": {
                "type": "array",
                "items": {
                  "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
                }
              }
            },
            "additionalProperties": true
          }
        }
      }
    },
    "400": {
      "description": "`provider_id` is missing.",
      "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": []
    }
  ],
  "parameters": [
    {
      "name": "provider_id",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider route with customer-owned credentials, for example `openai` or `parasail`."
    }
  ]
}

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"
      }
    }
  }
}