# `ReqLLM.Providers.OpenAI.Files`
[🔗](https://github.com/agentjido/req_llm/blob/main/lib/req_llm/providers/openai/files.ex#L1)

OpenAI-scoped lifecycle operations for reusable provider files.

Uploaded and retrieved files are returned as explicitly owned
`ReqLLM.Message.ContentPart` values. They can be passed directly to an
OpenAI Responses request without changing ReqLLM's common provider
behaviour or legacy `ContentPart.file_id/1` contract.

## Upload and reuse

    alias ReqLLM.Message.ContentPart
    alias ReqLLM.Providers.OpenAI.Files

    {:ok, file} =
      Files.upload(
        ContentPart.file(pdf_bytes, "report.pdf", "application/pdf"),
        purpose: :user_data
      )

    context =
      ReqLLM.Context.new([
        ReqLLM.Context.user([
          ContentPart.text("Summarize this report."),
          file
        ])
      ])

    {:ok, response} = ReqLLM.generate_text("openai:gpt-5", context)
    {:ok, true} = Files.delete(file)

`upload/2` also accepts a local path or an explicit
`{:binary, data, filename, media_type}` tuple. The default purpose is
`:user_data`.

OpenAI retains most files until they are deleted. Pass `:expires_after` as
a number of seconds from creation when automatic expiry is appropriate, or
call `delete/2` when the file is no longer needed.

# `source`

```elixir
@type source() ::
  String.t()
  | ReqLLM.Message.ContentPart.t()
  | {:binary, binary(), String.t()}
  | {:binary, binary(), String.t(), String.t()}
```

# `delete`

```elixir
@spec delete(String.t() | ReqLLM.Message.ContentPart.t(), keyword()) ::
  {:ok, boolean()} | {:error, Exception.t()}
```

Deletes an OpenAI file.

Returns `{:ok, true}` when OpenAI confirms deletion. Explicitly owned
references are checked for OpenAI ownership before any HTTP request.

# `delete!`

```elixir
@spec delete!(String.t() | ReqLLM.Message.ContentPart.t(), keyword()) ::
  boolean() | no_return()
```

Same as `delete/2`, but raises on error.

# `list`

```elixir
@spec list(keyword()) ::
  {:ok, ReqLLM.Providers.OpenAI.Files.Page.t()} | {:error, Exception.t()}
```

Lists OpenAI files as canonical owned references.

Supports the OpenAI query options `:after`, `:limit`, `:order`, and
`:purpose`, alongside the shared request and authentication options accepted
by `upload/2`. `:after` accepts either a file ID or a returned file reference.

# `list!`

```elixir
@spec list!(keyword()) :: ReqLLM.Providers.OpenAI.Files.Page.t() | no_return()
```

Same as `list/1`, but raises on error.

# `retrieve`

```elixir
@spec retrieve(String.t() | ReqLLM.Message.ContentPart.t(), keyword()) ::
  {:ok, ReqLLM.Message.ContentPart.t()} | {:error, Exception.t()}
```

Retrieves current metadata for an OpenAI file.

Accepts either a file ID or a `ContentPart`. Explicitly owned references are
checked for OpenAI ownership and known expiry before any HTTP request.

# `retrieve!`

```elixir
@spec retrieve!(String.t() | ReqLLM.Message.ContentPart.t(), keyword()) ::
  ReqLLM.Message.ContentPart.t() | no_return()
```

Same as `retrieve/2`, but raises on error.

# `upload`

```elixir
@spec upload(source(), keyword()) ::
  {:ok, ReqLLM.Message.ContentPart.t()} | {:error, Exception.t()}
```

Uploads a file to OpenAI and returns its owned provider reference.

Sources may be a local path, an inline file `ContentPart`,
`{:binary, data, filename}`, or `{:binary, data, filename, media_type}`.

## Options

  * `:purpose` - OpenAI file purpose; defaults to `:user_data`
  * `:expires_after` - seconds after creation, from 3,600 through 2,592,000
  * `:media_type` - override the inferred media type
  * `:base_url` - override the OpenAI API base URL
  * `:api_key`, `:auth_mode`, `:access_token`, `:provider_options` - normal
    OpenAI authentication options
  * `:receive_timeout`, `:total_timeout`, `:max_retries` - request controls
  * `:req_http_options` - options merged into the Req request
  * `:telemetry` - ReqLLM telemetry options
  * `:fixture` - ReqLLM fixture name for tests

# `upload!`

```elixir
@spec upload!(source(), keyword()) :: ReqLLM.Message.ContentPart.t() | no_return()
```

Same as `upload/2`, but raises on error.

---

*Consult [api-reference.md](api-reference.md) for complete listing*