> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Files

> Lista arquivos.

Lista arquivos vinculados à organização que está atuando, ordenados por
`created_at` decrescente. Use `starting_after`/`ending_before` para paginar.
Cada item vem no mesmo shape de
[`GET /v1/files/:id`](/api-reference/files/get#resposta).

## Autenticação

A API key da própria organização atua diretamente. A API key de plataforma exige o
header `Organization: <organization_id>` apontando para uma organização
conectada ativa.

## Parâmetros de query

<ParamField query="limit" type="integer" default="10">
  Quantidade de itens por página. Entre `1` e `100`.
</ParamField>

<ParamField query="starting_after" type="string">
  ID do arquivo que delimita o início da próxima página (exclusivo).
</ParamField>

<ParamField query="ending_before" type="string">
  ID do arquivo que delimita o fim da página anterior (exclusivo).
</ParamField>

<ParamField query="purpose" type="string">
  Filtra por `purpose`: `organization_avatar`, `product_image` ou
  `dispute_evidence`.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X GET "https://api.chargefy.io/v1/files?purpose=product_image&limit=20" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```
</RequestExample>

## Resposta

`200 OK` com o envelope canônico de listagem.

| Campo      | Tipo      | Observação                            |
| ---------- | --------- | ------------------------------------- |
| `object`   | `string`  | Sempre `"list"`                       |
| `data`     | `array`   | Cada item é um objeto `file` completo |
| `has_more` | `boolean` | `true` quando há próxima página       |
| `url`      | `string`  | Path relativo (`/v1/files`)           |

<ResponseExample>
  ```json Response 200 theme={}
  {
    "object": "list",
    "data": [
      {
        "id": "file_123",
        "object": "file",
        "created_at": "2026-05-24T10:14:50Z",
        "filename": "foto.webp",
        "livemode": true,
        "metadata": {},
        "mime_type": "image/webp",
        "purpose": "product_image",
        "size": 184320,
        "updated_at": null,
        "url": "https://storage.chargefy.io/file_123"
      }
    ],
    "has_more": false,
    "url": "/v1/files"
  }
  ```
</ResponseExample>

## Erros comuns

| Status | `code`            | Quando ocorre                                |
| ------ | ----------------- | -------------------------------------------- |
| `400`  | `invalid_request` | `purpose` enviado fora do conjunto suportado |