API Reference

This reference covers the Tevis API endpoints for both Tevis Core (cloud) and Tevis Local (your machine).

Overview

Service	Base URL	Purpose
Tevis Core	https://api.tevis.ai/v1	Cloud intelligence, orchestration
Tevis Local	http://localhost:8082	Local execution, knowledge base

Authentication

Tevis Core

Core API requires JWT authentication:

# Login to get tokens
curl -X POST https://api.tevis.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'

# Response
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 900
}

# Use in requests
curl https://api.tevis.ai/v1/projects \
  -H "Authorization: Bearer eyJ..."

Tevis Local

Local API runs without authentication by default (localhost only).

For remote access, enable authentication:

# ~/.tevis/config.yaml
local:
  auth:
    enabled: true
    token: your-local-token

---

Tevis Core API

Authentication

POST /auth/login

Login with email and password.

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

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 900,
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John Doe"
  }
}

POST /auth/refresh

Refresh access token.

curl -X POST https://api.tevis.ai/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJ..."}'

POST /auth/signup

Create new account.

curl -X POST https://api.tevis.ai/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secret",
    "name": "John Doe"
  }'

---

Projects

GET /projects

List all projects.

curl https://api.tevis.ai/v1/projects \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "projects": [
    {
      "id": "proj_abc123",
      "name": "My SaaS App",
      "slug": "my-saas-app",
      "description": "A SaaS application",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

POST /projects

Create a new project.

curl -X POST https://api.tevis.ai/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Project",
    "slug": "my-new-project",
    "description": "Project description",
    "repo_url": "git@github.com:user/repo.git"
  }'

GET /projects/{id}

Get project details.

curl https://api.tevis.ai/v1/projects/proj_abc123 \
  -H "Authorization: Bearer $TOKEN"

PUT /projects/{id}

Update project.

curl -X PUT https://api.tevis.ai/v1/projects/proj_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "description": "Updated description"
  }'

DELETE /projects/{id}

Delete project (soft delete).

curl -X DELETE https://api.tevis.ai/v1/projects/proj_abc123 \
  -H "Authorization: Bearer $TOKEN"

---

Nanocycles

POST /nanocycles/plan

Generate a nanocycle plan.

curl -X POST https://api.tevis.ai/v1/nanocycles/plan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "description": "Add user authentication with OAuth"
  }'

Response:

{
  "plan": {
    "nanocycle_id": "NC-007",
    "title": "User Authentication with OAuth",
    "features": [
      {
        "name": "oauth-setup",
        "tasks": [
          {"id": "T001", "subject": "Configure OAuth providers"},
          {"id": "T002", "subject": "Implement Google OAuth"}
        ]
      }
    ],
    "estimated_tasks": 8
  }
}

POST /nanocycles/{id}/approve

Approve a nanocycle plan.

curl -X POST https://api.tevis.ai/v1/nanocycles/NC-007/approve \
  -H "Authorization: Bearer $TOKEN"

POST /nanocycles/{id}/execute

Start nanocycle execution.

curl -X POST https://api.tevis.ai/v1/nanocycles/NC-007/execute \
  -H "Authorization: Bearer $TOKEN"

GET /nanocycles/{id}/status

Get nanocycle status.

curl https://api.tevis.ai/v1/nanocycles/NC-007/status \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "nanocycle_id": "NC-007",
  "status": "in_progress",
  "progress": {
    "total_tasks": 8,
    "completed_tasks": 5,
    "percentage": 62.5
  },
  "features": [
    {"name": "oauth-setup", "status": "completed"},
    {"name": "auth-flow", "status": "in_progress"}
  ],
  "active_tpus": 2
}

---

LPU (Intelligence)

POST /lpu/generate

Generate content with LPU.

curl -X POST https://api.tevis.ai/v1/lpu/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "prompt": "Generate a plan for adding rate limiting",
    "context": {
      "include_memory": true,
      "include_planning": true
    }
  }'

POST /lpu/analyze

Analyze code or requirements.

curl -X POST https://api.tevis.ai/v1/lpu/analyze \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "query": "What are the security implications of our current auth?",
    "scope": ["src/auth/", "src/api/"]
  }'

---

Tevis Local API

Health

GET /health

Check service health.

curl http://localhost:8082/health

Response:

{
  "status": "healthy",
  "version": "2.1.3",
  "uptime_seconds": 3600
}

---

Sessions

GET /sessions

List active sessions.

curl http://localhost:8082/sessions

Response:

{
  "sessions": [
    {
      "id": "sess_abc123",
      "project_id": "proj_xyz",
      "started_at": "2026-02-06T09:00:00Z",
      "status": "active"
    }
  ]
}

POST /sessions

Create a new session.

curl -X POST http://localhost:8082/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123"
  }'

GET /sessions/{id}

Get session details.

curl http://localhost:8082/sessions/sess_abc123

DELETE /sessions/{id}

End a session.

curl -X DELETE http://localhost:8082/sessions/sess_abc123

---

Execution

POST /execute/nanocycle

Execute a nanocycle locally.

curl -X POST http://localhost:8082/execute/nanocycle \
  -H "Content-Type: application/json" \
  -d '{
    "nanocycle_id": "NC-007",
    "session_id": "sess_abc123"
  }'

GET /execute/status/{id}

Get execution status.

curl http://localhost:8082/execute/status/exec_xyz

Response:

{
  "execution_id": "exec_xyz",
  "nanocycle_id": "NC-007",
  "status": "running",
  "progress": 0.65,
  "active_tpus": [
    {"id": "tpu-1", "feature": "oauth-setup", "task": "T003"},
    {"id": "tpu-2", "feature": "auth-flow", "task": "T005"}
  ],
  "pending_hold_points": []
}

POST /execute/hold-point/{id}/respond

Respond to a hold point.

curl -X POST http://localhost:8082/execute/hold-point/hp_abc/respond \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve",
    "feedback": "Proceed with bcrypt"
  }'

---

Knowledge Base

GET /kb/context

Get planning context.

curl http://localhost:8082/kb/context?project_id=proj_abc123

Response:

{
  "macrocycle": "# Macrocycle Q1 2026\n...",
  "mesocycle": "# Mesocycle January\n...",
  "microcycle": "# Microcycle Week 1\n..."
}

GET /kb/memory

Get memories.

curl "http://localhost:8082/kb/memory?project_id=proj_abc123&type=decision&limit=20"

Response:

{
  "memories": [
    {
      "id": "mem_abc123",
      "type": "decision",
      "content": "Use JWT for authentication",
      "confidence": 0.95,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

POST /kb/memory

Add a memory.

curl -X POST http://localhost:8082/kb/memory \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123",
    "type": "decision",
    "content": "Use PostgreSQL for production",
    "context": "Architecture review"
  }'

---

Workspaces

GET /workspaces

List workspaces.

curl http://localhost:8082/workspaces

POST /workspaces

Create a workspace.

curl -X POST http://localhost:8082/workspaces \
  -H "Content-Type: application/json" \
  -d '{
    "type": "session",
    "project_id": "proj_abc123",
    "branch": "main"
  }'

DELETE /workspaces/{id}

Delete a workspace.

curl -X DELETE http://localhost:8082/workspaces/ws_abc123

---

Streaming APIs

Consciousness Stream (SSE)

Real-time execution updates via Server-Sent Events.

curl -N http://localhost:8082/stream/consciousness?session_id=sess_abc123

Event format:

event: task_progress
data: {"tpu_id": "tpu-1", "task_id": "T003", "message": "Creating file..."}

event: task_complete
data: {"tpu_id": "tpu-1", "task_id": "T003", "duration_ms": 15000}

event: hold_point
data: {"id": "hp_abc", "type": "ambiguous_requirement", "question": "..."}

Execution Logs (SSE)

Stream execution logs.

curl -N http://localhost:8082/stream/logs?execution_id=exec_xyz

---

Error Responses

All APIs return consistent error format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid project_id format",
    "details": {
      "field": "project_id",
      "reason": "Must be a valid project ID"
    }
  }
}

Common Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid token
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	422	Invalid request data
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error

---

Rate Limits

Tevis Core

Endpoint	Limit
/auth/*	10/minute
/lpu/*	60/hour
Other	100/minute

Tevis Local

No rate limits (local service).

---

SDKs

Official SDKs for common languages:

# Python
pip install tevis-sdk

# Node.js
npm install @tevis/sdk

Example usage:

from tevis import TevisClient

client = TevisClient(api_key="your_key")

# Create nanocycle
plan = client.nanocycles.create_plan(
    project_id="proj_abc123",
    description="Add rate limiting"
)

# Approve and execute
client.nanocycles.approve(plan.id)
client.nanocycles.execute(plan.id)