---
title: "Secrets · API reference · Promigence"
description: "The Promigence API's secrets routes: 3 in all, with parameters, request bodies and answers."
url: "https://www.promigence.ai/docs/reference/api/secrets"
site: "Promigence"
---

[API reference](https://www.promigence.ai/docs/reference/api)

# Secrets

3 routes of the published API contract, generated from it.

### GET/v1/secrets

Auth: API key

The calling key's project's secret names and shapes, and for a bound secret its `urls` and `env` as `POST /v1/secrets` answers them. Never values.

#### Answer 200 · SecretList · application/json

secretsrequiredSecretSummary[]

### POST/v1/secrets

Auth: API key

Store a secret in the calling key's project (the same name may hold a different value in another project). Write-only: no route ever returns a value, and only that project's sandboxes are given it. With `hosts` the secret is bound to those hosts: requests a sandbox sends to the address in the answer's `urls` (with the request's path added) are authenticated with it, a request sent straight to the host is not, and the value stays out of the sandbox unless a run asks for it with `mode: "raw"`. `raw: "refused"` means the value itself can never be given to a sandbox; `allowed` is the default. A sandbox given a secret bound to `api.openai.com` or `api.anthropic.com` also gets `OPENAI_BASE_URL` or `ANTHROPIC_BASE_URL` set to that address (the answer's `env` names each variable and its value), so those SDKs need no change. Setting a secret again keeps every binding field the request leaves out; `hosts: []` removes the binding.

#### Request body SecretSet · application/json

bodyboolean | null

Let the secret be used in request bodies to its hosts. Not available yet: `true` is refused, `false` (the default) is accepted.

headersstring[] | null

Request headers the value may be sent in.

hostsstring[] | null

Host names the value may be sent to (never addresses).

namerequiredstring

A valid environment variable name.

queryboolean | null

Let the secret be used in query strings to its hosts. Not available yet: `true` is refused, `false` (the default) is accepted.

rawSecretRaw | null

Whether a command may ask for the value itself.

scan_responsesboolean | null

Mask the value in responses from its hosts.

valuerequiredstring

#### Answer 200 · SecretStored · application/json

bytesrequiredinteger

The length of the value that was stored, in bytes.

createdrequiredboolean

False when an existing secret of that name was overwritten in place.

envmap of string

The variables a sandbox that names this secret is also given, each set to the address in `urls` for a provider whose SDKs read their base URL from a variable (with the path those SDKs expect), such as `OPENAI_BASE_URL` for `api.openai.com` and `ANTHROPIC_BASE_URL` for `api.anthropic.com`. A variable the caller sets itself wins. Absent when there is none.

hostsstring[]

The hosts the secret is bound to. Absent when it is not bound, and a sandbox that names it is given the value itself.

namerequiredstring

nextrequiredstring[]

What to do next, ready to run.

placeholderstring | null

What the variable holds, in place of the value, in a sandbox that names this secret. Present when `hosts` is.

rawstring | null

`refused` when the value itself can never be given to a sandbox, `allowed` (the default) otherwise. Present when `hosts` is.

scan_responsesboolean | null

Whether the value is masked out of responses from the bound hosts. Present when `hosts` is.

updated_atrequiredstring

RFC 3339.

urlsstring[]

For each of `hosts`, in the same order, the address a sandbox sends that host's requests to, with the request's path added after it. Requests sent there are authenticated with the secret; a request sent straight to the host is not. For a `*.` host, put the name in place of the `*`. Present when `hosts` is.

### DELETE/v1/secrets/{name}

Auth: API key

Remove a secret.

#### Parameters

namerequiredpath · string

#### Answer 200 · SecretDeleted · application/json

deletedrequiredboolean

namerequiredstring

[Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors)