Create a vault
⚠️
Preview — this feature is being built; the design below is the spec.
POST https://app.syntic.ai/v1/vaultsCreate 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
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Bearer <key>: a private inference key (sk_live_...). See Authentication. |
syntic-beta | Yes, while in preview | agents-2026-11-01. Without it the call fails with 400 beta_required. See Versioning. |
Content-Type | Yes | application/json |
Idempotency-Key | No | Up to 255 characters. Retrying with the same key within 24 hours returns the first result instead of creating a duplicate. See Idempotency. |
Body parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
name | string | Yes | Unique in the workspace. |
description | string | No | Up 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:
| Status | type | code | When |
|---|---|---|---|
| 400 | invalid_request_error | beta_required | The syntic-beta header is missing. |
| 403 | permission_error | role_required | The key’s creator is not an Administrator or Owner. |
| 409 | conflict_error | name_taken | Another vault uses this name. |
| 401 | authentication_error | invalid_api_key | The key is missing, unknown, revoked or expired. |
| 429 | rate_limit_error | rate_limited | Too 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.
Related
Was this page helpful?