Referência da API

Secrets

Lista, cria, atualiza e elimina secrets de projeto através da API. Os valores são write-only — nunca são devolvidos em texto simples.

Última atualização:

API de Segredos

Gere segredos de projeto — chaves de API, tokens e outras credenciais que o teu projeto publicado lê a partir deprocess.env em tempo de execução. Os valores sãosó de escrita: entram através destes endpoints e saem através do runtime do projeto publicado, e nunca são devolvidos em nenhuma resposta da API.

Para contextualização sobre como os segredos funcionam e como são armazenados, consulta o guia de Segredos & Variáveis de Ambiente.

Listar Segredos

GET /api/v1/projects/{projectId}/secrets

Devolve o conjunto de segredos definidos num projeto. São devolvidos apenas o nome da chave, os últimos quatro caracteres do valor e os timestamps.

Resposta:

{
  "data": {
    "secrets": [
      {
        "key": "STRIPE_SECRET_KEY",
        "lastFour": "aB3x",
        "createdAt": "2026-04-18T09:12:44.000Z",
        "updatedAt": "2026-04-21T15:03:10.000Z"
      }
    ]
  }
}

Criar ou Atualizar um Segredo

POST /api/v1/projects/{projectId}/secrets
{ "key": "STRIPE_SECRET_KEY", "value": "sk_live_..." }

Idempotente por (projectId, key) — reenviar a mesma chave substitui o valor armazenado. As atualizações nunca contam para o limite por projeto; apenas a adição de uma nova chave conta.

Formato da chave: UPPER_SNAKE_CASE, 1–64 caracteres, deve começar com uma letra. Comprimento do valor: 1–4096 caracteres.

Resposta:

{
  "data": {
    "secret": {
      "key": "STRIPE_SECRET_KEY",
      "lastFour": "aB3x",
      "createdAt": "2026-04-18T09:12:44.000Z",
      "updatedAt": "2026-04-21T15:03:10.000Z"
    }
  }
}

Eliminar um Segredo

DELETE /api/v1/projects/{projectId}/secrets/{key}

Remove um segredo. Idempotente — eliminar uma chave que não existe continua a devolver success: true, comexisted a indicar se uma linha foi realmente removida.

Resposta:

{ "data": { "success": true, "existed": true } }

Erros

  • 400 VALIDATION_ERROR — O formato do corpo está incorreto, a chave não passa na verificação de formato, ou o valor está vazio ou tem mais de 4096 caracteres.
  • 404 NOT_FOUND — O projeto não existe ou a chave de API do chamador não tem âmbito para ele. Para escritas/eliminações, o chamador deve também ter o papel de admin na equipa proprietária.
  • 409 SECRET_LIMIT_EXCEEDED — O projeto já tem 25 segredos. Elimina um ou atualiza uma chave existente em vez de adicionar uma nova.
  • 429 RATE_LIMITED — Limite de taxa da API excedido. Consulta Tratamento de Erros para mais detalhes.
AnteriorDomínios PersonalizadosSeguinteConselheiro IA (streaming)