Oracle Cloud Infrastructure Documentation

Files API

You can use the Files API to upload and manage documents and other data that agents can use while they run.

By attaching files to workflows such as retrieval and summarizing tasks, agents can work with large or complex source materials without requiring you to paste content into prompts. This approach helps you build more capable agents that can use knowledge bases, reports, logs, and datasets in a scalable, reusable way, while keeping data handling centralized and consistent.

Warning

This service is not intended to process personal information or any data (for example, certain regulated health or payment card information) that imposes specific data security, data protection or regulatory obligations on Oracle in addition to or different from those specified in your agreement with Oracle.

Note

The OCI Files API uses the same format as the OpenAI Files API with the OCI OpenAI-compatible endpoint. For syntax and request details, see the OpenAI Files API documentation.

Supported API Endpoint

Base URL Endpoint Path Authentication
https://inference.generativeai.${region}.oci.oraclecloud.com/openai/v1 /files API key or IAM session

Replace ${region} with a supported OCI region such as us-chicago-1.

Although the request format is OpenAI-compatible, authentication uses OCI credentials, requests are routed through OCI Generative AI inference endpoints, and resources and execution remain in OCI.

Tip

For setup steps before using this API, see QuickStart.

Uploading a File

POST /files

Body Parameters
  • file (required): file object to be uploaded
  • purpose (required): The intended purpose of the file. Supported values:
    • assistants
    • batch
    • fine-tune
    • vision
    • user_data
    • evals
  • expires_after (optional): Expiration policy for the file
File type restrictions (by purpose)
  • batch: .jsonl
  • fine-tune: .jsonl
  • evals: .jsonl
  • vision: .gif, .jpeg, .jpg, .png, .webp
Reference

Upload file

Python example:

# upload a file

file_path = "./example-file.pdf"
with open(file_path, "rb") as f:
    file = client.files.create(
        file=f,
        purpose="user_data"
    )
print(file.id)

Listing Files

GET /files

Input Parameters
  • after (optional): Cursor for use in pagination
  • limit (optional): Number of objects to be returned
  • order (optional): Sort order by created_at ("asc" or "desc")
  • purpose (optional): Filter files by purpose
Reference

List files

Python example:

# list files

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx",
)
files_list = client.files.list(order="asc")
print(files_list)

Retrieving File Information

GET /files/{file_id}

Input Parameter
  • file_id (required): Id of the file to be retrieved
Reference

Retrieve file

Python example:

# retrieve file
file = client.files.retrieve(file_id="xxx")
print(file)

Retrieving File Content

GET /files/{file_id}/content

Input Parameter
  • file_id (required): Id of the file whose content you want to retrieve
Reference

Retrieve file content

Python example:

# retrieve file content
file = client.files.content(file_id="xxx")
print(file.content)

Deleting a File

DELETE /files/{file_id}

Input Parameter
  • file_id (required): Id of the file to be deleted
Reference

Delete file

Python example:

# delete file
delete_result = client.files.delete(file_id="xxx")
print(delete_result)