API referenceAgents APIVaultsCreate a vault

Create a vault

⚠️
Preview — this feature is being built; the design below is the spec.
POST https://app.syntic.ai/v1/vaults

Create an empty vault. Add secrets to it with Set a secret, then list the vault in an agent’s vault_ids.

For how this fits into a full workflow, see Credential vaults.

Headers

HeaderRequiredValue
AuthorizationYesBearer <key>: a private inference key (sk_live_...). See Authentication.
syntic-betaYes, while in previewagents-2026-11-01. Without it the call fails with 400 beta_required. See Versioning.
Content-TypeYesapplication/json
Idempotency-KeyNoUp to 255 characters. Retrying with the same key within 24 hours returns the first result instead of creating a duplicate. See Idempotency.

Body parameters

ParameterTypeRequiredNotes
namestringYesUnique in the workspace.
descriptionstringNoUp to 500 characters.

Response

201 Created, Content-Type: application/json

{
  "id": "vlt_01JC2B4D6F8H0K2M4P6R",
  "type": "vault",
  "name": "acme-prod",
  "description": "Production credentials for the Acme integration.",
  "secrets": [],
  "created_at": "2026-11-03T09:00:00Z"
}

Examples

curl -sS https://app.syntic.ai/v1/vaults \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "syntic-beta: agents-2026-11-01" \
  -H "Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "acme-prod",
      "description": "Production credentials for the Acme integration."
    }'

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

StatustypecodeWhen
400invalid_request_errorbeta_requiredThe syntic-beta header is missing.
403permission_errorrole_requiredThe key’s creator is not an Administrator or Owner.
409conflict_errorname_takenAnother vault uses this name.
401authentication_errorinvalid_api_keyThe key is missing, unknown, revoked or expired.
429rate_limit_errorrate_limitedToo many requests; wait for Retry-After. See Rate-limit headers.

Who may call this

Creating vaults and writing or deleting secrets needs a key created by an Administrator or Owner. Any key in the workspace may list vaults and read secret names, so developers can wire up agents without ever handling values.

Was this page helpful?