Sugestões (referência)
GET /v1/projects/{p}/suggestions
Seção intitulada “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
Seção intitulada “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 | 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 |
{ "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
Seção intitulada “Erros comuns”Corpo {"error", "message", "details"?} (veja Autenticação e visão geral e a tabela de erros): 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
Seção intitulada “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
Seção intitulada “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 |
{ "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
Seção intitulada “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 |
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
Seção intitulada “Erros comuns”Corpo {"error", "message", "details"?} (veja Autenticação e visão geral e a tabela de erros): 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
Seção intitulada “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
Seção intitulada “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). |
{ "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
Seção intitulada “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 |
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
Seção intitulada “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 |
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
Seção intitulada “Erros comuns”Corpo {"error", "message", "details"?} (veja Autenticação e visão geral e a tabela de erros): 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.