Authentication

Authenticate your API requests using API keys generated in the Galadri Console.

API Keys

API keys are generated in the Galadri Console. Each key has a gld_ prefix followed by 32 random bytes encoded in base64url.

Keys are shown once

API keys are displayed only at creation time. They are stored as a SHA-256 hash and cannot be retrieved later. If you lose a key, revoke it and create a new one.

Keep keys secret

Never expose API keys in client-side code, public repositories, or browser network requests. Always make API calls from your backend server or trusted server-side runtime. The public API is designed for non-credentialed cross-origin requests only and does not support browser cookies or credentialed CORS.

Making Requests

Include your API key in the Authorization header as a Bearer token.

curl

curl -X POST https://api.galadri.com/v1/chat \
  -H "Authorization: Bearer gld_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-agent",
    "message": "Hello",
    "end_user_id": "user-123"
  }'

JavaScript (server-side fetch)

const response = await fetch("https://api.galadri.com/v1/chat", {
  method: "POST",
  headers: {
    "Authorization": "Bearer gld_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent: "my-agent",
    message: "Hello",
    end_user_id: "user-123",
  }),
});

Rate Limits

Each API key is limited to 60 requests per minute using a token bucket algorithm. When the limit is exceeded, the API returns a 429 status with a Retry-After header indicating how many seconds to wait.

429 Response

{
  "error": "Too many requests. Please try again later."
}

Error Responses

All errors return a JSON object with an error field. Most CRUD and communications endpoints use a structured { code, message } object. Chat, auth, rate-limit, and a few compatibility paths may return a plain string.

HTTP Status Codes

Parameter	Type	Description
`400`	Bad Request	Invalid request body, missing required fields, or fields exceeding length limits.
`401`	Unauthorized	Missing or invalid API key. Ensure the Authorization header is set to "Bearer gld_...".
`402`	Payment Required	Insufficient credits. Add credits in the Galadri Console.
`403`	Forbidden	The selected agent does not have a required tool or permission.
`404`	Not Found	Agent not found, agent is inactive, or session ID does not exist.
`413`	Payload Too Large	The request body or uploaded content exceeds a configured limit.
`429`	Too Many Requests	Rate limit exceeded. Check the Retry-After header for wait time.
`500`	Server Error	Internal server error. Contact support if this persists.
`502`	Bad Gateway	The upstream AI model returned an error.
`503`	Service Unavailable	The model provider circuit is open or a dependency is temporarily unavailable.
`504`	Gateway Timeout	The upstream model timed out before completing the request.

String error format

{
  "error": "Missing or invalid Authorization header. Expected: Bearer gld_*"
}

Structured error format

{
  "error": {
    "code": "validation_error",
    "message": "user_id is required"
  }
}

Health Check

Use the health check endpoint to verify the API is online. No authentication required.

GET/v1/

Response

{
  "status": "ok",
  "version": "v1",
  "service": "galadri-api"
}

ToolsNext