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 Type	Use Case	Header Format
JWT Token	User authentication for dashboard and management APIs	`Authorization: Bearer <jwt_token>`
Ingest Token	Sending telemetry data from SDKs	`Authorization: <ingest_token>`
Platform API Key	Programmatic access to agent and spotlight APIs	`x-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

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

Rate Limiting

API endpoints are rate-limited to ensure fair usage:

Endpoint Category	Rate Limit
All endpoints	1000 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 for MCP telemetry ingestion, we recommend using our official SDKs:

The SDKs handle authentication, batching, retries, and error handling automatically.

Getting Started

Create an account on the Shinzo Platform
Verify your email address
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": "your@email.com", "password": "your_password"}'

Overview

Authentication

AI Agents

Agent Messaging

Agent Schedules & Triggers

Agent Channels

Agent Filesystem

MCP Servers

Spotlight

Tokens

Provider Keys

Telemetry

API Reference Overview

API Reference

Base URL

API Categories

Authentication

AI Agents

Spotlight

Telemetry

Tokens

Provider Keys

Authentication Methods

Request Format

Response Format

Error Responses

HTTP Status Codes

Rate Limiting

SDKs and Libraries

Getting Started

​API Reference

​Base URL

​API Categories

Authentication

AI Agents

Spotlight

Telemetry

Tokens

Provider Keys

​Authentication Methods

​Request Format

​Response Format

​Error Responses

​HTTP Status Codes

​Rate Limiting

​SDKs and Libraries

​Getting Started

API Reference

Base URL

API Categories

Authentication Methods

Request Format

Response Format

Error Responses

HTTP Status Codes

Rate Limiting

SDKs and Libraries

Getting Started