API Reference

Build with Wispy API

Integrate autonomous AI into your product. Chat, stream, run multi-day tasks, generate images, and search memory — all via REST API.

Quickstart API Reference

Quickstart

Get up and running in under 2 minutes.

1Install Wispy

npm install -g wispy-ai

2Create API Key

wispy api create --name "My App" --scopes "chat,marathon"

3Start the Gateway

wispy gateway

Authentication

Pass your API key via the Authorization header orX-Api-Key header.

Authorization: Bearer wsk_your_api_key_here

# or

X-Api-Key: wsk_your_api_key_here

Code Examples

Copy-paste examples in your language of choice.

const response = await fetch(
  "https://your-wispy.example.com/api/v1/chat",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer wsk_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "Summarize the latest AI trends",
      session: "my-session-1",
    }),
  }
);

const data = await response.json();
console.log(data.message.content);

API Endpoints

All endpoints are prefixed with /api/v1

Method	Endpoint	Scope	Description
POST	/api/v1/chat	chat	Send a message and get a response
POST	/api/v1/chat/stream	chat:stream	Stream a response via SSE
GET	/api/v1/sessions	sessions	List all sessions
GET	/api/v1/sessions/:key	sessions	Get session message history
DELETE	/api/v1/sessions/:key	sessions	Clear a session
POST	/api/v1/memory/search	memory	Search agent memory
POST	/api/v1/marathon	marathon	Start an autonomous marathon task
GET	/api/v1/marathon	marathon:read	List all marathons
GET	/api/v1/marathon/:id	marathon:read	Get marathon status
POST	/api/v1/marathon/:id/pause	marathon	Pause a marathon
POST	/api/v1/marathon/:id/abort	marathon	Abort a marathon
POST	/api/v1/generate/image	generate	Generate an image from text
GET	/api/v1/skills	skills	List available skills
GET	/api/v1/tools	tools	List available tools
GET	/api/v1/usage	chat	View API key usage stats
GET	/api/v1/health	-	Health check (no auth)

Response Format

All responses follow a consistent JSON structure.

Success

{
  "id": "req_m1k2j3h",
  "object": "chat.completion",
  "created": 1738857600,
  "message": {
    "role": "assistant",
    "content": "Here are the latest AI trends..."
  },
  "thinking": "Let me analyze...",
  "tool_calls": []
}

Error

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 45s.",
    "retryAfter": 45
  }
}

// Error codes:
// unauthorized     - Missing/invalid API key
// forbidden        - Key lacks required scope
// bad_request      - Invalid request body
// rate_limit_exceeded - Too many requests
// not_found        - Resource not found
// internal_error   - Server error

API Key Scopes

Control what each API key can access with fine-grained scopes.

chatSend messages

chat:streamSSE streaming

sessionsRead/manage sessions

memorySearch agent memory

marathonStart/manage marathons

marathon:readRead marathon status

skillsList available skills

generateImage generation

toolsList/use tools

adminFull access + webhooks

*All scopes

Rate Limits

Rate limit info is returned in response headers.

X-RateLimit-Limit: 60        # Max requests per minute
X-RateLimit-Remaining: 58    # Remaining requests
X-RateLimit-Reset: 1738857660 # Unix timestamp when limit resets

Default: 60 requests/minute. Configurable per API key via wispy api create --rate-limit 120.

What You Can Build

Examples of products powered by Wispy API.

AI-powered SaaS

Add autonomous AI to your product. Let users ask questions, generate content, or automate workflows.

Custom Chatbots

Build chatbots with memory, tool use, and multi-day task execution — far beyond simple Q&A.

Internal Copilots

Deploy Wispy as a team copilot that searches docs, writes code, and manages tasks autonomously.

Content Pipelines

Automate content creation with Marathon mode — research, write, edit, and publish in one task.

DevOps Automation

Trigger autonomous coding tasks, deployments, and monitoring via API from your CI/CD pipeline.

Mobile Apps

Connect your iOS/Android app to Wispy for AI features with streaming and real-time responses.

Watch DemoDemo GitHub