Api
B Y O K
List BYOK keys for a project
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
project_id*string
Project UUID
Response Body
application/json
application/problem+json
curl -X GET "https://loading/api/v1/projects/string/byok-keys"{
"$schema": "/api/v1/schemas/ListBYOKKeysOutputBody.json",
"keys": [
{
"$schema": "/api/v1/schemas/BYOKKeyResponse.json",
"api_key_prefix": "string",
"health_status": "string",
"is_active": true,
"last_health_check_at": "2019-08-24T14:15:22Z",
"last_health_error": "string",
"last_used_at": "2019-08-24T14:15:22Z",
"provider": "string",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}{
"$schema": "/api/v1/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Enable or disable a BYOK key without rotating it
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
project_id*string
provider*string
Value in
"openai" | "gemini" | "xai" | "openrouter"Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
is_active*boolean
Response Body
application/json
application/problem+json
curl -X PATCH "https://loading/api/v1/projects/string/byok-keys/openai" \ -H "Content-Type: application/json" \ -d '{ "is_active": true }'{
"$schema": "/api/v1/schemas/BYOKKeyResponse.json",
"api_key_prefix": "string",
"health_status": "string",
"is_active": true,
"last_health_check_at": "2019-08-24T14:15:22Z",
"last_health_error": "string",
"last_used_at": "2019-08-24T14:15:22Z",
"provider": "string",
"updated_at": "2019-08-24T14:15:22Z"
}{
"$schema": "/api/v1/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Delete a BYOK key
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
project_id*string
provider*string
Value in
"openai" | "gemini" | "xai" | "openrouter"Response Body
application/problem+json
curl -X DELETE "https://loading/api/v1/projects/string/byok-keys/openai"Empty
{
"$schema": "/api/v1/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Create or replace a BYOK key
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
project_id*string
provider*string
Provider name
Value in
"openai" | "gemini" | "xai" | "openrouter"Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
api_key*string
Plaintext API key from the provider. Stored encrypted; never returned.
Response Body
application/json
application/problem+json
curl -X PUT "https://loading/api/v1/projects/string/byok-keys/openai" \ -H "Content-Type: application/json" \ -d '{ "api_key": "string" }'{
"$schema": "/api/v1/schemas/BYOKKeyResponse.json",
"api_key_prefix": "string",
"health_status": "string",
"is_active": true,
"last_health_check_at": "2019-08-24T14:15:22Z",
"last_health_error": "string",
"last_used_at": "2019-08-24T14:15:22Z",
"provider": "string",
"updated_at": "2019-08-24T14:15:22Z"
}{
"$schema": "/api/v1/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Re-test a stored BYOK key against the provider
AuthorizationBearer <token>
API key issued to a Sonzai project. Format: Bearer sk_....
In: header
Path Parameters
project_id*string
provider*string
Value in
"openai" | "gemini" | "xai" | "openrouter"Response Body
application/json
application/problem+json
curl -X POST "https://loading/api/v1/projects/string/byok-keys/openai/test"{
"$schema": "/api/v1/schemas/BYOKKeyResponse.json",
"api_key_prefix": "string",
"health_status": "string",
"is_active": true,
"last_health_check_at": "2019-08-24T14:15:22Z",
"last_health_error": "string",
"last_used_at": "2019-08-24T14:15:22Z",
"provider": "string",
"updated_at": "2019-08-24T14:15:22Z"
}{
"$schema": "/api/v1/schemas/ErrorModel.json",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "string",
"message": "string",
"value": null
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}