Skip to content
API Reference

API Reference

Complete API documentation for all ZIRI endpoints.

Endpoint Categories

User Endpoints

Endpoints your applications call to make LLM requests and manage their profile:

LLM endpoints require an X-API-Key header. Profile endpoints require a Bearer token from /api/auth/login.

Admin Endpoints

Endpoints for managing ZIRI:

Admin endpoints require a Bearer token from /api/auth/admin/login.

System Endpoints

System-level endpoints:

  • Health - Health checks
  • Events - Server-Sent Events for real-time updates

Base URL

All endpoints are relative to your ZIRI server URL:

  • Local development: http://localhost:3100
  • Production: Your server URL

Authentication

User Endpoints

Include the X-API-Key header:

curl -H "X-API-Key: ziri-user-123-a1b2c3d4e5f67890" \
  https://your-server.com/api/chat/completions

Admin Endpoints

Include the Authorization header with a Bearer token:

curl -H "Authorization: Bearer your-token-here" \
  https://your-server.com/api/users

Get a token from /api/auth/admin/login.

Request IDs

Many user-facing request errors include a requestId field. Use it for debugging and support requests when present.

Error Responses

Errors follow this format:

{
	"error": "Human-readable error message",
	"code": "ERROR_CODE",
	"requestId": "req-123"
}

Common HTTP status codes:

  • 400 - Bad request (missing fields, invalid format)
  • 401 - Unauthorized (invalid API key or token)
  • 403 - Forbidden (authorization denied, key revoked)
  • 404 - Not found (resource doesn’t exist)
  • 429 - Rate limit exceeded
  • 500 - Internal server error
  • 503 - Service unavailable (queue full)

Rate Limit Headers

User endpoints include rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

Pagination

List endpoints support pagination:

  • limit - Results per page (default: 10 for logs, 100 for others)
  • offset - Pagination offset

Responses include total for the total count.

Search

Many endpoints support search:

  • search - Search query (searches relevant fields)
  • Search is server-side
  • Search inputs are debounced (300ms) in the UI

Sorting

List endpoints support sorting:

  • sortBy - Column to sort by
  • sortOrder - “asc” or “desc”

Click column headers in the UI to sort.

Next Steps