Pular para o conteúdo

Sugestões (referência)

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).

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
}

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.

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.

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"
}

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.

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.

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.

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"
}
}

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.

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.

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.