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

# Visão geral

> Base URL, autenticação e formato das respostas da v0x API

A v0x API oferece upload de arquivos, links diretos via CDN e gerenciamento de chaves — tudo sob o prefixo `/api/v1`.

<Info>
  **Base URL**

  ```
  https://api.v0x.lol/api/v1
  ```

  Desenvolvimento local: `http://localhost:8080/api/v1`

  Health check (sem prefixo `/api/v1`): `GET https://api.v0x.lol/health`

  Chaves de produção usam o prefixo `v0x_live_`.
</Info>

## Endpoints disponíveis

| Método   | Rota             | Auth             | Descrição                             |
| -------- | ---------------- | ---------------- | ------------------------------------- |
| `GET`    | `/health`        | Pública          | Status da API (sem prefixo `/api/v1`) |
| `GET`    | `/auth/google`   | Pública          | Inicia login Google (browser)         |
| `GET`    | `/auth/me`       | Cookie           | Perfil do usuário logado              |
| `POST`   | `/auth/logout`   | Cookie           | Encerra sessão                        |
| `GET`    | `/files`         | Bearer ou cookie | Lista arquivos                        |
| `POST`   | `/files`         | Bearer ou cookie | Upload multipart                      |
| `GET`    | `/files/{id}`    | Bearer ou cookie | Detalhes de um arquivo                |
| `DELETE` | `/files/{id}`    | Bearer ou cookie | Exclui arquivo                        |
| `GET`    | `/api-keys`      | Cookie           | Lista chaves                          |
| `POST`   | `/api-keys`      | Cookie           | Cria chave                            |
| `DELETE` | `/api-keys/{id}` | Cookie           | Revoga chave                          |

## Autenticação (API key)

Crie a chave no dashboard: [API Keys](https://dash.v0x.lol/dashboard/api-keys).

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl https://api.v0x.lol/api/v1/files \
  -H "Authorization: Bearer $V0X_API_KEY"
```

<Danger>
  **API keys são credenciais secretas**

  Trate `v0x_live_...` como senha de banco de dados. Qualquer pessoa com a chave pode fazer upload e consumir sua quota de storage.

  **Nunca:**

  * commite no Git (`.env` no `.gitignore`)
  * coloque em código frontend (React, Vue, Svelte)
  * envie em apps mobile sem proxy backend
  * armazene em `localStorage`, `sessionStorage` ou cookies do browser
  * exponha em URLs, query strings ou repositórios públicos
</Danger>

## Arquitetura correta

```
Browser / App / ShareX
      ↓
Backend do cliente (seu servidor) — opcional para ShareX direto
      ↓  Authorization: Bearer v0x_live_...
v0x API
```

Para integrações web, o usuário final faz login via Google no dashboard. Scripts e ShareX usam API key server-side ou localmente no cliente desktop.

## Onde armazenar

| Ambiente                | Recomendação                                     |
| ----------------------- | ------------------------------------------------ |
| Servidor Node/Python/Go | `process.env.V0X_API_KEY` / `os.environ`         |
| Docker / K8s            | Secret do orchestrator                           |
| CI/CD                   | Secret do pipeline (GitHub Actions, etc.)        |
| ShareX                  | Campo `Authorization` no `.sxcu` (máquina local) |

Veja também: [Chaves de API](/pages/guides/authentication) · [Boas práticas](/pages/guides/boas-praticas)

## Formato de resposta

Sucesso — objeto JSON direto (sem envelope `data`):

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "screenshot.png",
  "mime_type": "image/png",
  "size_bytes": 248103,
  "url": "https://cdn.v0x.lol/uploads/...",
  "created_at": "2026-09-15T23:00:00Z"
}
```

Erro:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "error": "unauthorized"
}
```

## Limites padrão

| Recurso                    | Valor       |
| -------------------------- | ----------- |
| Tamanho máximo por arquivo | 100 MB      |
| Storage por conta          | 2 GB        |
| Upload                     | 60 req/min  |
| Listagem de arquivos       | 120 req/min |

Veja [Rate limiting](/api-reference/rate-limiting).

## Mapa rápido

<Columns cols={2}>
  <Card title="Primeira integração" icon="rocket" href="/pages/guides/primeira-integracao">
    Do zero ao primeiro upload
  </Card>

  <Card title="Chaves de API" icon="key" href="/pages/guides/authentication">
    Criar e proteger v0x\_live\_
  </Card>

  <Card title="ShareX" icon="upload" href="/pages/guides/sharex">
    Configuração .sxcu
  </Card>

  <Card title="Erros" icon="triangle-alert" href="/api-reference/guides/errors">
    Códigos e status HTTP
  </Card>
</Columns>