Files API in AI Gateway

The Files API lets you upload files to AI Gateway and reference them in requests to models. This is useful when a model needs to work with a document, spreadsheet, text file, or other material that you don't want to paste into the request body every time.

You upload a file once, and AI Gateway returns a file identifier. You can then reuse this identifier in subsequent requests to the model.

Setting Up Your Token

Copy link

To use the Files API, you'll need an AI Gateway API key. You can create one in the AI Agents section, under the AI Gateway → API Keys tab.

The examples below use an environment variable called HOSTMAN_AI_TOKEN so you don't have to paste your key into every request. On Linux and macOS, you can set it with:

export HOSTMAN_AI_TOKEN="your_API_key"

This makes the variable available for the current terminal session. If you want it to persist across terminal restarts, add the same line to your shell's configuration file — for example, ~/.zshrc for zsh or ~/.bashrc for bash.

API Methods

Copy link

Below are the available methods for working with files through the API. Requests targeting an already-uploaded file use its file_id, which is returned when the file is uploaded.

Uploading a File

Copy link

To upload a file, send a POST request to the /v1/files endpoint:

curl --request POST \
 --url https://ai-api.hostman.com/v1/files \
 --header "authorization: Bearer $HOSTMAN_AI_TOKEN" \
 --header "content-type: multipart/form-data" \
 --form purpose=user_data \
 --form "file=@<file_path>" \
 --form "target_model_names=openai/gpt-4.1"

Parameters:

• purpose: The purpose of the file. AI Gateway supports only user_data and messages. Use user_data for files used in model requests, and messages for files used with Claude models. Other values for purpose aren't supported.

• file: The path to your local file, prefixed with @. For example, file=@/Users/hostman/test.txt.

• target_model_names: The models the file should be available to. To make a file available to several models, list them separated by commas, for example, target_model_names=openai/gpt-4.1,openai/gpt-5. You can find the correct model names in the Connection tab under AI Gateway.

An uploaded file is only available to the model specified in the model parameter.

Example response:

{
 "id": "file-bGl0ZWxsbTpmaWxlLUdmMWRD1mDEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI",
 "bytes": 27,
 "created_at": 1782804439,
 "filename": "testfile.txt",
 "object": "file",
 "purpose": "user_data",
 "status": "processed",
 "expires_at": null,
 "status_details": null
}

Use the value of the id field for any further operations with this file.

Getting File Information

Copy link

This method retrieves the metadata of an uploaded file:

curl --request GET \
 --url https://ai-api.hostman.com/v1/files/<file_id> \
 --header "authorization: Bearer $HOSTMAN_AI_TOKEN"

Here, file_id is the file identifier returned when the file was uploaded.

Retrieving File Content

Copy link

The /content method exists for compatibility with the Files API and for future scenarios:

curl --request GET \
 --url https://ai-api.hostman.com/v1/files/<file_id>/content \
 --header "authorization: Bearer $HOSTMAN_AI_TOKEN"

Retrieving content is only available for certain purpose values, such as fine-tuning workflows. These scenarios aren't currently supported in AI Gateway. For files with purpose=user_data or purpose=messages, this method isn't used to read file content.

Deleting a File

Copy link

To delete a file, send a DELETE request:

curl --request DELETE \
 --url https://ai-api.hostman.com/v1/files/<file_id> \
 --header "authorization: Bearer $HOSTMAN_AI_TOKEN"

Once deleted, a file's identifier can no longer be used in requests to a model.

Example: Working with a File

Copy link

Let's walk through an example of uploading a text file, test.txt, located at /Users/hostman/test.txt.

curl --request POST \
 --url https://ai-api.hostman.com/v1/files \
 --header "authorization: Bearer $HOSTMAN_AI_TOKEN" \
 --header "content-type: multipart/form-data" \
 --form purpose=user_data \
 --form "file=@/Users/hostman/test.txt" \
 --form "target_model_names=openai/gpt-4.1"

The file parameter here specifies the full path to the file on your local machine. If the file is in your terminal's current directory, you can use a relative path instead, such as file=@test.txt.

Example response:

{
 "id": "file-bGl0ZWxsbTpmaWxlL87mMWRDV7NEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI",
 "bytes": 27,
 "created_at": 1782804439,
 "filename": "test.txt",
 "object": "file",
 "purpose": "user_data",
 "status": "processed",
 "expires_at": null,
 "status_details": null
}

Once uploaded, you can pass the file to a model through the Responses API. To do this, include an object with the type input_file in your request, with the file_id field set to the identifier from the upload response:

curl https://ai-api.hostman.com/v1/responses \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer $HOSTMAN_AI_TOKEN" \
 --data '{
   "model": "openai/gpt-4.1",
   "input": [
     {
       "role": "user",
       "content": [
         {
           "type": "input_text",
           "text": "Read the uploaded file and briefly summarize its contents."
         },
         {
           "type": "input_file",
           "file_id": "file-bGl0ZWxsbTpmaWxlL87mMWRDV7NEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI"
         }
       ]
     }
   ]
 }'

The model specified in this request must match the model the file was originally uploaded for.