Note: If you haven't downloaded or installed Zhiyu yet, please refer to Getting Started for installation instructions.

Zhiyu API Documentation

API Modules

Module Overview

Endpoints Reference

Auth Module (/api/auth/*, /api/remote-auth/*)

Login Example

curl -X POST https://app.openzhiyu.ai/api/remote-auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

Response:

{
  "user": { "id": "user_xxx", "email": "user@example.com", "name": "User" },
  "token": "eyJhbG..."
}

User Module (/api/user/*)

Messages Module (/api/messages/*)

Files Module (/api/files/*)

Storage Module (/api/storage/*)

Integrations Module (/api/integrations/*)

OAuth Callbacks (Various Platforms)

RAG Module (/api/rag/*)

Workspace Module (/api/workspace/*)

AI Module (/api/ai/*)

Chat Example

curl -X POST https://app.openzhiyu.ai/api/ai/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "stream": true
  }'

Insights Module (/api/insights/*, /api/chat-insights/*)

Billing Module (/api/billing/*)

Error Handling

Error Response Format

// API errors return standard HTTP status codes
{
  error: string;      // Error message
  code?: string;       // Error code for programmatic handling
  cause?: string;      // Additional context
}

Common Status Codes

AI/Agent Usage

Local API Access

When running Zhiyu desktop app, the local API server runs on port 3414 (fallback: 3515):

Authentication Token

The auth token is stored at ~/.openzhiyu/token (base64 encoded JWT). You must decode it before use:

# Decode base64 to get JWT token
TOKEN=$(cat ~/.openzhiyu/token | base64 -d)

# Verify token contents (decodes JWT payload)
echo "$TOKEN" | cut -d'.' -f2 | base64 -d 2>/dev/null | python3 -m json.tool

curl Examples

Important: All authenticated requests require the token to be base64 decoded first.

# Helper: Get decoded token
TOKEN=$(cat ~/.openzhiyu/token | base64 -d)

# 1. Check AI API status (no auth required)
curl http://localhost:3414/api/ai/chat

# 2. Get current user info
TOKEN=$(cat ~/.openzhiyu/token | base64 -d)
curl http://localhost:3414/api/remote-auth/user \
  -H "Authorization: Bearer $TOKEN"

# 3. Get subscription info
TOKEN=$(cat ~/.openzhiyu/token | base64 -d)
curl http://localhost:3414/api/remote-auth/subscription \
  -H "Authorization: Bearer $TOKEN"

# 4. Chat with AI (streaming)
TOKEN=$(cat ~/.openzhiyu/token | base64 -d)
curl -X POST http://localhost:3414/api/ai/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello!"}],"stream":true}'

# 5. Get chat insights (requires chatId)
TOKEN=$(cat ~/.openzhiyu/token | base64 -d)
curl "http://localhost:3414/api/chat-insights?chatId=xxx" \
  -H "Authorization: Bearer $TOKEN"

# 6. Search RAG documents
TOKEN=$(cat ~/.openzhiyu/token | base64 -d)
curl -X POST http://localhost:3414/api/rag/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"search term","limit":5}'

# 7. List workspace skills
TOKEN=$(cat ~/.openzhiyu/token | base64 -d)
curl http://localhost:3414/api/workspace/skills \
  -H "Authorization: Bearer $TOKEN"

# 8. Submit feedback
TOKEN=$(cat ~/.openzhiyu/token | base64 -d)
curl -X POST http://localhost:3414/api/remote-feedback \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Feedback message","email":"user@example.com"}'

Production API Access

# Using production API
export TOKEN="your_production_token"
curl https://app.openzhiyu.ai/api/remote-auth/user \
  -H "Authorization: Bearer $TOKEN"

Summary

• 129+ API endpoints across 20+ functional modules
• Dual authentication: Session cookies (web) and Bearer tokens (Tauri)
• RESTful JSON APIs with Zod validation
• CloudApiClient for desktop/Tauri integration
• SWR utilities for client-side data fetching
• OAuth support for Google, GitHub, Slack, Discord, X
• RAG for document retrieval and search
• AI endpoints for chat, embeddings, images, audio