Skip to main content

​
API Reference

The Shinzo Platform provides a RESTful API for programmatic access to authentication, telemetry ingestion, AI agent management, and analytics. This reference documents all available endpoints and their usage.

​
Base URL

All API requests are made to the following base URL: 
https://api.app.shinzo.ai

​
API Categories

Authentication

User registration, login, OAuth, and token management.

AI Agents

Deploy, manage, and interact with AI agents.

Spotlight

AI model proxy, session analytics, and token tracking.

Telemetry

Send OpenTelemetry data from your MCP servers.

Tokens

Manage ingest tokens and platform API keys.

Provider Keys

Configure AI provider credentials (Anthropic, etc.).

​
Authentication Methods

The Shinzo Platform supports multiple authentication methods depending on the endpoint:
Auth TypeUse CaseHeader Format
JWT TokenUser authentication for dashboard and management APIsAuthorization: Bearer <jwt_token>
Ingest TokenSending telemetry data from SDKsAuthorization: <ingest_token>
Platform API KeyProgrammatic access to agent and spotlight APIsx-shinzo-api-key: <api_key> or Authorization: Bearer <api_key>
JWT tokens are obtained by logging in via /auth/login or OAuth. Ingest tokens and platform API keys are generated from the dashboard or via API.

​
Request Format

All API requests should include: 
Content-Type: application/json
Authorization: Bearer <your_token>

​
Response Format

All responses are JSON-formatted and include standard fields: 
{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

​
Error Responses

Error responses include an error object with details: 
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is missing required field 'server_name'",
    "details": {
      "field": "server_name",
      "reason": "required"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

​
HTTP Status Codes

CodeDescription
200Success
201Resource created
400Bad request (invalid parameters)
401Unauthorized (invalid or missing token)
403Forbidden (insufficient permissions)
404Resource not found
429Rate limit exceeded
500Internal server error

​
Rate Limiting

API endpoints are rate-limited to ensure fair usage:
Endpoint CategoryRate Limit
All endpoints1000 requests/minute
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1705315800

​
SDKs and Libraries

While you can use the API directly, we recommend using our official SDKs for telemetry ingestion: The SDKs handle authentication, batching, retries, and error handling automatically.

​
Getting Started

  1. Create an account on the Shinzo Platform
  2. Verify your email address
  3. Make your first API call to verify connectivity
curl -X GET https://api.app.shinzo.ai/health
Expected response: 
{
  "status": "healthy",
  "database": "healthy"
}
For authenticated endpoints, first log in to get a JWT token: 
curl -X POST https://api.app.shinzo.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your_password"}'