--- title: "Upload and Use Files with AI Models | Hostman Docs" description: "Learn how to upload, retrieve, and delete files using the AI Gateway Files API. Step-by-step guide to preparing your API token and passing files to AI models in requests." --- > For the complete documentation index for AI agents, see [llms.txt](https://hostman.com/llms.txt). 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 To use the Files API, you'll need to [create an AI Gateway API key](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key).  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: ```shell 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 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 To upload a file, send a POST request to the `/v1/files` endpoint: ```shell 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=@" \ --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](https://hostman.com/docs/ai-agents/ai-gateway/connection/#getting-connection-details) in the **Connection** tab under **AI Gateway**. An uploaded file is only available to the model specified in the model parameter. Example response: ```shell { "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 This method retrieves the metadata of an uploaded file: ```shell curl --request GET \ --url https://ai-api.hostman.com/v1/files/ \ --header "authorization: Bearer $HOSTMAN_AI_TOKEN" ``` Here, `file_id` is the file identifier returned when the file was uploaded. ### Retrieving File Content The `/content` method exists for compatibility with the Files API and for future scenarios: ```shell curl --request GET \ --url https://ai-api.hostman.com/v1/files//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 To delete a file, send a `DELETE` request: ```shell curl --request DELETE \ --url https://ai-api.hostman.com/v1/files/ \ --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 Let's walk through an example of uploading a text file, `test.txt`, located at `/Users/hostman/test.txt`. ```shell 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: ```shell { "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: ```shell 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.