# Sugestões (referência)

## GET `/v1/projects/{p}/suggestions`

Lista as sugestões de persistência abertas do projeto

As sugestões **abertas** (status `suggested`/`accepted`) dos serviços do projeto, da mais antiga para a mais nova. Cada item traz `kind` (`volume` ou `database`), o `engine` quando é banco, o `target_path` quando é volume, a origem do sinal (`source`) e um texto leigo pronto para a tela (`detail`). A plataforma **só sugere**: criar o recurso é um passo separado e exige autorização.

Escopo exigido: `projects:read`.

Escopo exigido: `projects:read` · operationId: `listSuggestions`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `cursor` | query | string | não | Cursor opaco devolvido em `next_cursor` da página anterior. |
| `limit` | query | integer | não | Itens por página (1 a 200). |

### Resposta 200

Página de sugestões abertas.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `next_cursor` | string\|null | sim | Passe em `cursor` para a próxima página; `null` ao fim. |
| `has_more` | boolean | sim | Há mais páginas. |
| `items` | array<object> | sim |  |
| `items[].id` | string | sim |  |
| `items[].service_id` | string | sim |  |
| `items[].service_name` | string | sim | Nome do serviço (resolvido do id; vazio se o serviço já não existe). |
| `items[].project_id` | string | sim |  |
| `items[].kind` | enum(volume, database) | sim | `volume` = precisa de disco persistente; `database` = precisa de um banco gerenciado. |
| `items[].engine` | enum(, sqlite, postgres, mysql, mongo) | sim | Motor do banco (só `kind=database`; vazio em `volume`). |
| `items[].target_path` | string | sim | Caminho do volume (só `kind=volume`; vazio em `database`). |
| `items[].source` | enum(build_detect, runtime_readonly, runtime_connrefused, unresolved_ref) | sim | Origem do sinal que gerou a sugestão. |
| `items[].status` | enum(suggested, dismissed, accepted, fulfilled) | sim |  |
| `items[].detail` | string | sim | Texto leigo pronto para a tela. |
| `items[].created_at` | string | sim |  |

```json
{
  "items": [
    {
      "id": "01jb7ksa5q8r7t2v4w6x8y0a7h",
      "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
      "service_name": "api",
      "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
      "kind": "volume",
      "engine": "",
      "target_path": "/app/data",
      "source": "runtime_readonly",
      "status": "suggested",
      "detail": "Este app guarda dados em /app/data, mas o disco do app é somente-leitura. Posso criar um volume persistente em /app/data para os dados sobreviverem aos deploys. Criar agora?",
      "created_at": "2026-10-12T14:03:11Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

### Erros comuns

Corpo `{"error", "message", "details"?}` (veja [Autenticação e visão geral](/referencia/autenticacao/) e a [tabela de erros](/erros/tabela/)): `400` Entrada inválida (nome de arquivo fora das regras, cursor malformado, formulário sem `file`, nome de galeria vazio ou longo); `401` Token ausente, inválido, expirado ou revogado. A resposta é genérica de propósito; `403` O token não tem o escopo exigido pela operação, ou uma condição da política do token negou a chamada (`token_ip_not_allowed`, `token_outside_schedule`, `token_action_not_allowed`, `token_destructive_scope_required`, `approval_invalid`; corpo `application/problem+json`, ver `Problem`). A resposta nunca revela a regra; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido (`rate_limited`) ou cota `deploys_per_hour` da política do token esgotada (`token_deploy_rate_exceeded`) ou aprovações pendentes demais (`approval_quota_exceeded`). 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`.

## POST `/v1/projects/{p}/suggestions/{sid}/dismiss`

Descarta uma sugestão

Marca a sugestão como `dismissed` e devolve-a atualizada. Descartada, ela não renasce pelo mesmo sinal na mesma janela (anti-spam). Uma sugestão de outro time ou de outro projeto é `404` (anti-IDOR).

Escopo exigido: `projects:write`.

Escopo exigido: `projects:write` · operationId: `dismissSuggestion`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `sid` | path | string | sim | Id da sugestão (do projeto da rota). Id de outro projeto/time ⇒ `404`. |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. Em upload `multipart/form-data` o pedido é comparado pelo conteúdo das partes (campo, nome do arquivo e bytes), não pelo tamanho. |

### Resposta 200

Sugestão descartada.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `id` | string | sim |  |
| `service_id` | string | sim |  |
| `service_name` | string | sim | Nome do serviço (resolvido do id; vazio se o serviço já não existe). |
| `project_id` | string | sim |  |
| `kind` | enum(volume, database) | sim | `volume` = precisa de disco persistente; `database` = precisa de um banco gerenciado. |
| `engine` | enum(, sqlite, postgres, mysql, mongo) | sim | Motor do banco (só `kind=database`; vazio em `volume`). |
| `target_path` | string | sim | Caminho do volume (só `kind=volume`; vazio em `database`). |
| `source` | enum(build_detect, runtime_readonly, runtime_connrefused, unresolved_ref) | sim | Origem do sinal que gerou a sugestão. |
| `status` | enum(suggested, dismissed, accepted, fulfilled) | sim |  |
| `detail` | string | sim | Texto leigo pronto para a tela. |
| `created_at` | string | sim |  |

```json
{
  "id": "01jb7ksa5q8r7t2v4w6x8y0a7h",
  "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
  "service_name": "api",
  "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
  "kind": "volume",
  "engine": "",
  "target_path": "/app/data",
  "source": "runtime_readonly",
  "status": "suggested",
  "detail": "Este app guarda dados em /app/data, mas o disco do app é somente-leitura. Posso criar um volume persistente em /app/data para os dados sobreviverem aos deploys. Criar agora?",
  "created_at": "2026-10-12T14:03:11Z"
}
```

### Resposta 422

`idempotency_conflict` (mesma `Idempotency-Key` com outro corpo).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, token_ip_not_allowed, token_outside_schedule, token_action_not_allowed, token_destructive_scope_required, approval_required, approval_invalid, approval_quota_exceeded, token_deploy_rate_exceeded, token_upload_too_large, token_ttl_invalid, policy_invalid, team_inactive, not_found, payload_too_large, quota_exceeded, technology_not_allowed, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_not_empty, project_trashed, service_trashed, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, hsts_too_early, wildcard_not_allowed, volume_exists, volume_in_use, volume_attached, backup_not_ready, backup_disabled, backup_not_done, backup_corrupt, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large, busy, stale_activation, idempotency_in_progress, activating, team_queue_full, suggestion_not_database, suggestion_dismissed, engine_unsupported) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### 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; `403` O token não tem o escopo exigido pela operação, ou uma condição da política do token negou a chamada (`token_ip_not_allowed`, `token_outside_schedule`, `token_action_not_allowed`, `token_destructive_scope_required`, `approval_invalid`; corpo `application/problem+json`, ver `Problem`). A resposta nunca revela a regra; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido (`rate_limited`) ou cota `deploys_per_hour` da política do token esgotada (`token_deploy_rate_exceeded`) ou aprovações pendentes demais (`approval_quota_exceeded`). 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`.

## POST `/v1/projects/{p}/suggestions/{sid}/accept`

Aceita uma sugestão de banco (provisiona + conecta)

Provisiona o **banco gerenciado** da sugestão (só `kind=database`) e injeta a referência `${{<db>.DATABASE_URL}}` (mais as variáveis por motor) no env do serviço do app, para o próximo deploy conectar. O motor detectado vira o gerenciado ofertado (`sqlite`→libSQL, `postgres`→Postgres, `mysql`→**MariaDB**). A resposta traz a sugestão já `fulfilled` e o banco criado (id/nome/motor) — **nunca** a credencial (fica selada).

**Idempotente:** aceitar de novo reusa o banco já criado, não cria outro. Uma sugestão de `kind=volume` responde `409 suggestion_not_database` (crie o volume na aba Volume); uma sugestão já descartada, `409 suggestion_dismissed`; um motor sem banco gerenciado (ex. Mongo), `409 engine_unsupported`. Em falha de provisionamento a sugestão volta a `suggested`. Uma sugestão de outro time/projeto é `404` (anti-IDOR).

Escopo exigido: `databases:write`.

Escopo exigido: `databases:write` · operationId: `acceptSuggestion`

| Parâmetro | Em | Tipo | Obrig. | Descrição |
|---|---|---|---|---|
| `p` | path | string | sim | Id (26 caracteres) ou slug do projeto. Projeto de outro time ou fora dos `project_ids` do token ⇒ `404`. |
| `sid` | path | string | sim | Id da sugestão (do projeto da rota). Id de outro projeto/time ⇒ `404`. |
| `Idempotency-Key` | header | string | não | Chave de idempotência (8 a 128 caracteres `[A-Za-z0-9._:-]`; use um UUID). Mesma chave + mesmo pedido em 24 h ⇒ a mesma resposta, com `Idempotent-Replay: true`; mesma chave + pedido diferente ⇒ `422 idempotency_conflict`. Falhas nunca são gravadas, então a repetição executa de verdade. Em upload `multipart/form-data` o pedido é comparado pelo conteúdo das partes (campo, nome do arquivo e bytes), não pelo tamanho. |

### Resposta 200

Sugestão aceita; banco provisionado e ligado ao app.

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `suggestion` | object | sim |  |
| `suggestion.id` | string | sim |  |
| `suggestion.service_id` | string | sim |  |
| `suggestion.service_name` | string | sim | Nome do serviço (resolvido do id; vazio se o serviço já não existe). |
| `suggestion.project_id` | string | sim |  |
| `suggestion.kind` | enum(volume, database) | sim | `volume` = precisa de disco persistente; `database` = precisa de um banco gerenciado. |
| `suggestion.engine` | enum(, sqlite, postgres, mysql, mongo) | sim | Motor do banco (só `kind=database`; vazio em `volume`). |
| `suggestion.target_path` | string | sim | Caminho do volume (só `kind=volume`; vazio em `database`). |
| `suggestion.source` | enum(build_detect, runtime_readonly, runtime_connrefused, unresolved_ref) | sim | Origem do sinal que gerou a sugestão. |
| `suggestion.status` | enum(suggested, dismissed, accepted, fulfilled) | sim |  |
| `suggestion.detail` | string | sim | Texto leigo pronto para a tela. |
| `suggestion.created_at` | string | sim |  |
| `database` | object | sim | Banco gerenciado criado/reusado. Carrega só id/nome/motor — nunca credencial. |
| `database.service_id` | string | sim |  |
| `database.name` | string | sim | Nome do serviço de banco (derivado do app, `<app>-db`). |
| `database.engine` | enum(sqlite, postgres, mariadb) | sim | Motor GERENCIADO ofertado (mysql é servido por MariaDB). |

```json
{
  "suggestion": {
    "id": "01jb7ksa5q8r7t2v4w6x8y0a7h",
    "service_id": "01jb7k4a5q8r7t2v4w6x8y0a2c",
    "service_name": "api",
    "project_id": "01jb7k3m5q8r7t2v4w6x8y0a1b",
    "kind": "database",
    "engine": "postgres",
    "target_path": "",
    "source": "build_detect",
    "status": "fulfilled",
    "detail": "Este app usa PostgreSQL, mas não há banco ligado a ele. Posso criar um banco gerenciado e conectá-lo automaticamente.",
    "created_at": "2026-10-12T14:03:11Z"
  },
  "database": {
    "service_id": "01jb7k9a5q8r7t2v4w6x8y0a3d",
    "name": "api-db",
    "engine": "postgres"
  }
}
```

### Resposta 409

`suggestion_not_database` (é de volume), `suggestion_dismissed` (já descartada) ou `engine_unsupported` (sem banco gerenciado para o motor).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, token_ip_not_allowed, token_outside_schedule, token_action_not_allowed, token_destructive_scope_required, approval_required, approval_invalid, approval_quota_exceeded, token_deploy_rate_exceeded, token_upload_too_large, token_ttl_invalid, policy_invalid, team_inactive, not_found, payload_too_large, quota_exceeded, technology_not_allowed, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_not_empty, project_trashed, service_trashed, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, hsts_too_early, wildcard_not_allowed, volume_exists, volume_in_use, volume_attached, backup_not_ready, backup_disabled, backup_not_done, backup_corrupt, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large, busy, stale_activation, idempotency_in_progress, activating, team_queue_full, suggestion_not_database, suggestion_dismissed, engine_unsupported) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### Resposta 422

`quota_exceeded` (limite de bancos do plano) ou `idempotency_conflict` (mesma `Idempotency-Key` com outro corpo).

| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
| `error` | enum(unauthorized, forbidden, token_ip_not_allowed, token_outside_schedule, token_action_not_allowed, token_destructive_scope_required, approval_required, approval_invalid, approval_quota_exceeded, token_deploy_rate_exceeded, token_upload_too_large, token_ttl_invalid, policy_invalid, team_inactive, not_found, payload_too_large, quota_exceeded, technology_not_allowed, unsupported_type, class_not_allowed, extension_mismatch, malware_detected, svg_unsafe, archive_encrypted, archive_bomb, archive_unsupported, rate_limited, unavailable, idempotency_conflict, invalid_request, unsupported_media_type, bad_json, too_large, authz_unavailable, database_unavailable, restore_not_removable, gallery_not_empty, bad_body, internal, name_taken, slug_taken, project_not_empty, project_trashed, service_trashed, deploy_in_progress, nothing_to_rollback, not_cancelable, sensitive_lowered, duplicate_variable, domain_taken, hsts_too_early, wildcard_not_allowed, volume_exists, volume_in_use, volume_attached, backup_not_ready, backup_disabled, backup_not_done, backup_corrupt, unresolved_reference, reference_cycle, invalid_reference, reference_too_deep, value_too_large, busy, stale_activation, idempotency_in_progress, activating, team_queue_full, suggestion_not_database, suggestion_dismissed, engine_unsupported) | sim | Código estável para tratamento programático. A tabela completa está na descrição geral. |
| `message` | string | sim | Mensagem legível em pt-BR. |
| `details` | object | não | Presente em alguns `422` (ex.: `unresolved_reference` e `reference_cycle` trazem `details.references`). |
| `details.references` | array<string> | não | Referências problemáticas (só nomes, nunca valores). |
| `details.retry_after_seconds` | integer | não | Em `422 rate_limited` (ex.: verificação manual de domínio): segundos até poder tentar de novo. |

### 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; `403` O token não tem o escopo exigido pela operação, ou uma condição da política do token negou a chamada (`token_ip_not_allowed`, `token_outside_schedule`, `token_action_not_allowed`, `token_destructive_scope_required`, `approval_invalid`; corpo `application/problem+json`, ver `Problem`). A resposta nunca revela a regra; `404` Recurso inexistente ou pertencente a outro time (indistinguíveis de propósito); `429` Limite de requisições excedido (`rate_limited`) ou cota `deploys_per_hour` da política do token esgotada (`token_deploy_rate_exceeded`) ou aprovações pendentes demais (`approval_quota_exceeded`). 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`.
