# Conta (referência)

## GET `/v1/limits`

Plano e consumo

Plano do time e o uso de serviços, memória, volumes, bancos e deploys por hora. `used` > `max` nunca acontece: ao atingir, a criação responde `422 quota_exceeded` e um novo deploy responde `429 rate_limited` com `Retry-After`.

Qualquer token válido (nenhum escopo específico).

Escopo exigido: - · operationId: `getLimits`

### Resposta 200

Limites.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `plan` | string | sim |  |
| `services` | object | sim |  |
| `services.used` | integer | sim |  |
| `services.max` | integer | sim |  |
| `memory_mb` | object | sim |  |
| `memory_mb.used` | integer | sim |  |
| `memory_mb.max` | integer | sim |  |
| `volumes_gb` | object | sim |  |
| `volumes_gb.used` | integer | sim |  |
| `volumes_gb.max` | integer | sim |  |
| `databases` | object | sim |  |
| `databases.used` | integer | sim |  |
| `databases.max` | integer | sim |  |
| `deploys_per_hour` | object | sim |  |
| `deploys_per_hour.used` | integer | sim |  |
| `deploys_per_hour.max` | integer | sim |  |

```json
{
  "plan": "pro",
  "services": {
    "used": 3,
    "max": 20
  },
  "memory_mb": {
    "used": 1536,
    "max": 8192
  },
  "volumes_gb": {
    "used": 5,
    "max": 50
  },
  "databases": {
    "used": 1,
    "max": 5
  },
  "deploys_per_hour": {
    "used": 2,
    "max": 60
  }
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/me`

Quem é o token

Devolve o token (id, nome, escopos, projetos permitidos, validade) e o time. Use para descobrir o que o token pode fazer antes de agir.

Qualquer token válido (nenhum escopo específico).

Escopo exigido: - · operationId: `getMe`

### Resposta 200

Token e time.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `token` | object | sim |  |
| `token.id` | string | sim |  |
| `token.name` | string | sim |  |
| `token.scopes` | array<string> | sim |  |
| `token.project_ids` | array\|null | sim | `null` = token com acesso a todos os projetos do time. |
| `token.expires_at` | string | não |  |
| `team` | object | sim |  |
| `team.id` | string | sim |  |
| `team.name` | string | sim |  |
| `team.plan` | string | sim |  |

```json
{
  "token": {
    "id": "01jb7kd15q8r7t2v4w6x8y0a3m",
    "name": "agente-deploy",
    "scopes": [
      "projects:read",
      "projects:write",
      "deploy"
    ],
    "project_ids": null,
    "expires_at": "2027-01-08T14:03:11Z"
  },
  "team": {
    "id": "01jb7h0000000000000000team",
    "name": "Acme",
    "plan": "pro"
  }
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `429` Limite de requisições excedido. Espere `Retry-After` segundos; `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.

## GET `/v1/openapi.json`

Esta especificação (OpenAPI 3.1 em JSON)

Serve esta própria especificação. Cache curto (5 minutos) e `ETag`. A versão YAML legível está no repositório (`docs/openapi.yaml`).

Endpoint **público**: não exige token.

Escopo exigido: - · operationId: `getOpenAPI`

### Resposta 200

Documento OpenAPI 3.1.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `openapi` | string | sim |  |
| `info` | object | sim |  |
| `paths` | object | sim |  |

### Resposta 304

`If-None-Match` igual ao `ETag` atual: sem corpo.

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `500` Falha interna (`internal`). O detalhe fica só no log do servidor; repita depois, e informe o `Idempotency-Key` ao suporte se persistir; `503` Serviço (ex.: scanner ou borda) temporariamente indisponível. Tente de novo após `Retry-After`.