API Documentation

Quick Start

Make your first API call in seconds. Replace sk_simplio_YOUR_KEY with your Master Key from the dashboard.

curl https://simpliodev.vercel.app/api/v1/chat/completions \
  -H "Authorization: Bearer sk_simplio_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello, world!"}
    ]
  }'

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer sk_simplio_YOUR_MASTER_KEY

Generate your Master Key in the Dashboard. Your key is shown once — store it securely. We only store a SHA-256 hash.

Endpoint

Fully compatible with the OpenAI Chat Completions API. Use any OpenAI SDK — just change the base URL.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk_simplio_YOUR_KEY",
  baseURL: "https://simpliodev.vercel.app/api/v1",
});

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

Request Format

Standard OpenAI Chat Completions request body:

{
  "model": "gpt-4o",        // optional — defaults to gpt-4o
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "What is 2+2?"
    }
  ],
  "temperature": 0.7,        // optional, 0-2
  "max_tokens": 1000,        // optional
  "stream": true             // always true (SSE)
}

Response Format

Responses are Server-Sent Events (SSE) in OpenAI format, regardless of the underlying provider:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1700000000,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1700000000,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Streaming

All responses are streamed as SSE. Anthropic responses are automatically transformed into OpenAI-compatible format.

const response = await fetch(
  "https://simpliodev.vercel.app/api/v1/chat/completions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_simplio_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hi!" }],
    }),
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  // Parse SSE lines: "data: {...}"
  console.log(chunk);
}

Embeddings

Generate vector embeddings for text. OpenAI-compatible — use the same SDK methods you already know. Embeddings require an OpenAI API key configured in the dashboard.

Supported Embedding Models

Request Format

{
  "model": "text-embedding-3-small",
  "input": "Hello world"          // string or string[]
  "encoding_format": "float",     // optional
  "dimensions": 256               // optional
}

Response Format

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0094, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 2, "total_tokens": 2 }
}

Examples

curl https://simplio.dev/api/v1/embeddings \
  -H "Authorization: Bearer sk_simplio_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": "Hello world"}'

from openai import OpenAI

client = OpenAI(
    api_key="sk_simplio_YOUR_KEY",
    base_url="https://simplio.dev/api/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Hello world",
)

print(response.data[0].embedding[:5])

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk_simplio_YOUR_KEY",
  baseURL: "https://simplio.dev/api/v1",
});

const response = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: "Hello world",
});

console.log(response.data[0].embedding.slice(0, 5));

Models

List all models available to your account. Returns models based on which provider API keys you have configured in the dashboard.

Response Format

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 1715367049,
      "owned_by": "openai"
    },
    ...
  ]
}

Example

curl https://simplio.dev/api/v1/models \
  -H "Authorization: Bearer sk_simplio_YOUR_KEY"

Code Examples

Simplio is OpenAI-compatible — use any language or SDK. Just swap the base URL and API key.

import requests

response = requests.post(
    "https://simplio.dev/api/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk_simplio_YOUR_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-4o",
        "messages": [{"role": "user", "content": "Hello!"}],
    },
    stream=True,
)

for line in response.iter_lines():
    if line:
        text = line.decode("utf-8")
        if text.startswith("data: ") and text != "data: [DONE]":
            print(text[6:])

from openai import OpenAI

client = OpenAI(
    api_key="sk_simplio_YOUR_KEY",
    base_url="https://simplio.dev/api/v1",
)

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk_simplio_YOUR_KEY",
  baseURL: "https://simplio.dev/api/v1",
});

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
});

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

API Reference

Request body parameters for POST /api/v1/chat/completions

Maximum request body size: 100 KB. Requests exceeding this limit receive a 413 response.

Headers

Optional Request Headers

Response Headers

Error Codes

All errors return JSON with a trace_id for debugging:

{
  "error": {
    "message": "Invalid API key",
    "type": "simplio_error",
    "code": 401,
    "trace_id": "abc123-def456"
  }
}

Rate Limits

Features

curl ... -H "X-Simplio-No-Eco: true"

curl ... -H "Idempotency-Key: my-unique-key-123"

Troubleshooting

OpenAPI Specification

The complete API specification is available as an OpenAPI 3.1 document. Use it to generate client SDKs, import into Postman, or integrate with any OpenAPI-compatible tool.