Authentication

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

Galadri public APIs use organization-scoped API keys. Every request should send a Bearer token in the Authorization header. The API key determines the organization, available agents, rate limit bucket, and billing account for the request.

API Keys

Organization owners and admins can create API keys in the Galadri Console. Each key has a gld_ prefix followed by 32 random bytes encoded with base64url.

Key lifecycle

Field	Type	Description
`Create`	`console`	Create a named key from the API Keys page. Use separate keys for development, staging, production, and background jobs.
`Store`	`secret`	Put the full key in your server-side secret manager or environment variables. Never commit it to source control.
`Use`	`header`	Send the full key as a Bearer token in the Authorization header.
`Disable`	`console`	Disable a key to stop new requests while preserving its usage history.
`Delete`	`console`	Delete a key when it is no longer needed. Historical usage logs remain, but the plaintext key cannot be recovered.

Keys are shown once

API keys are displayed only at creation time. Galadri stores a SHA-256 hash and a masked key prefix, not the plaintext key. If you lose a key, disable or delete it and create a new one.

Keep keys secret

Never expose API keys in client-side code, public repositories, or browser network requests. Make API calls from your backend server or trusted server-side runtime.

Making Requests

Include your API key in the Authorization header as a Bearer token. Do not send the key as a query parameter or request body field.

curl

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

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",
  }),
});

if (!response.ok) {
  const errorBody = await response.text();
  throw new Error(`Galadri request failed (${response.status}): ${errorBody}`);
}

Server-side calls and CORS

Public API responses include non-credentialed CORS headers:Access-Control-Allow-Origin: * and Access-Control-Allow-Credentials: false. That does not make API keys browser-safe. A browser or mobile client would expose the Bearer key to users, extensions, logs, or reverse engineering.

Recommended pattern

Put Galadri calls behind your own backend route. Your frontend calls your backend with your normal user session, and your backend attaches the Galadri API key server-side.

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. The response also includes X-RateLimit-Remaining: 0.

429 Response

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Remaining: 0
Content-Type: application/json

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

Temporary limiter outage

If the distributed rate limiter is temporarily unavailable, Galadri fails closed and returns 503 with Retry-After. Treat it as a retryable platform dependency error.

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 or API key is not allowed to perform the requested operation.
`404`	Not Found	Agent not found, agent is inactive, or session ID does not exist.
`413`	Payload Too Large	The request body exceeds the public API size limit. Chat requests are also capped at 32,000 message characters.
`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, rate limiting is temporarily unavailable, or another 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": "agent_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"
}

Next steps

Quickstart - Make your first authenticated chat request
Chat endpoint - Request body, streaming events, sessions, and async callbacks
Data Model - Direct CRUD endpoints that use the same Bearer authentication

Chat APINext