Skip to main content

Backend API Documentation

This section provides complete documentation for Ozwell's backend API, enabling server-side integration and custom workflows.

Overview​

Ozwell's API follows the OpenAI API specification, providing a familiar interface for developers. The API supports:

  • Chat Completions — Conversational AI interactions
  • File Management — Upload and manage files
  • Embeddings — Generate vector embeddings
  • Models — List and inspect available models
  • Responses — Extended response format with additional metadata
ResourceDescription
EndpointsComplete API endpoint documentation
AuthenticationAPI keys and authentication
ExamplesCode samples and recipes
OpenAI-compatible clientsConfigure OpenCode, VS Code, and similar tools

Getting Started​

1. Get Your API Key​

  1. Log in to Ozwell Manager with MIE auth (manager.os.mieweb.org credentials)
  2. Open agent management
  3. Ozwell creates your parent key automatically, or use Claim key to link an existing ozw_ key
  4. Use Show key if you need the ozw_ key for server-side API calls

2. Install the SDK​

npm install @ozwell/api

3. Make Your First Request​

import { OzwellClient } from '@ozwell/api';

const client = new OzwellClient({
  apiKey: process.env.OZWELL_API_KEY,
});

const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'user', content: 'Hello, Ozwell!' }
  ],
});

console.log(response.choices[0].message.content);

Base URL​

All API requests should be made to:

https://ozwellapi.os.mieweb.org/v1

For Ozwell Manager features, use https://ozwellapi.os.mieweb.org/v1. For self-hosted deployments, use your custom base URL.

Request Format​

All requests must include:

  • Authorization header with your API key
  • Content-Type: application/json for request bodies
curl https://ozwellapi.os.mieweb.org/v1/chat/completions \
  -H "Authorization: Bearer ozw_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hello!"}]}'

Response Format​

Successful responses return JSON:

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1699000000,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 12,
    "total_tokens": 22
  }
}

Error Handling​

Errors return a JSON object with error details:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

HTTP Status Codes​

CodeDescription
200Success
400Bad Request — Invalid parameters
401Unauthorized — Invalid or missing API key
403Forbidden — Insufficient permissions
404Not Found — Resource doesn't exist
429Rate Limited — Too many requests
500Server Error — Internal error

Rate Limits​

API requests are rate-limited based on your plan:

PlanRequests/minTokens/min
Free2010,000
Pro100100,000
EnterpriseCustomCustom

When rate limited, you'll receive a 429 response with retry information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1699000060
Retry-After: 30

Streaming​

For long responses, use streaming to receive chunks as they're generated:

const stream = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}

SDKs & Libraries​

Official SDKs​

LanguagePackageStatus
TypeScript/JS@ozwell/api✅ Available
Pythonozwell🚧 Coming Soon

OpenAI SDK Compatibility​

You can use the official OpenAI SDK with Ozwell:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OZWELL_API_KEY,
  baseURL: 'https://ozwellapi.os.mieweb.org/v1',
});

Next Steps​