Molly AI API Reference

Overview

Molly exposes a REST API for sovereign multi-agent inference orchestration. A single request to the molly orchestrator is routed across four tiers — T0 on-device, T1 LAN, T2 self-hosted, T3 external API — with local execution as the policy-gated default. The orchestrator dispatches work to the appropriate LoRA specialist and returns a standard chat-completion response.

• Drop-in compatible with OpenAI Chat Completions request/response shapes.
• Three endpoints: /chat/completions, /models, /usage.
• JSON over HTTPS. Streaming via Server-Sent Events.

Base URL

All API requests are made to the following base URL. Every path below is relative to it.

https://app.iamolly.ai/api/molly/v1

Authentication

Authenticate by supplying your secret API key as a Bearer token in the Authorization header. Keys are prefixed with mk- and are created in your dashboard. Keep them server-side; never expose keys in client code.

Authorization: Bearer mk-KEY

Rate Limits

The default rate limit is 60 requests per minute per API key. Exceeding it returns 429 Too Many Requests. Requests count toward the limit regardless of which tier ultimately serves them.

POST/chat/completions

Create a model response for a conversation. The molly orchestrator routes the request across the 4-tier stack and selects the appropriate specialist.

Request Parameters

Request Body

{
  "model": "molly",
  "messages": [
    { "role": "system", "content": "You are a concise assistant." },
    { "role": "user", "content": "Summarize our Q3 sales notes." }
  ],
  "mode": "standard",
  "temperature": 0.7,
  "stream": false
}

Response Body

{
  "id": "chatcmpl-8x2Kd9Qm",
  "object": "chat.completion",
  "created": 1717426800,
  "model": "molly",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Q3 sales grew 14% QoQ, led by enterprise renewals..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 96,
    "total_tokens": 138
  }
}

Examples

curl https://app.iamolly.ai/api/molly/v1/chat/completions \
  -H "Authorization: Bearer mk-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "molly",
    "messages": [
      { "role": "user", "content": "Summarize our Q3 sales notes." }
    ],
    "mode": "standard"
  }'

# pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="https://app.iamolly.ai/api/molly/v1",
    api_key="mk-KEY",
)

resp = client.chat.completions.create(
    model="molly",
    messages=[
        {"role": "user", "content": "Summarize our Q3 sales notes."},
    ],
    extra_body={"mode": "standard"},
)
print(resp.choices[0].message.content)

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://app.iamolly.ai/api/molly/v1",
  apiKey: "mk-KEY",
});

const resp = await client.chat.completions.create({
  model: "molly",
  messages: [
    { role: "user", content: "Summarize our Q3 sales notes." },
  ],
  mode: "standard",
});
console.log(resp.choices[0].message.content);

GET/models

List the models available to your key, including the molly orchestrator and any deployed specialists.

Response Body

{
  "object": "list",
  "data": [
    { "id": "molly", "object": "model", "owned_by": "core-labs" }
  ]
}

Examples

curl https://app.iamolly.ai/api/molly/v1/models \
  -H "Authorization: Bearer mk-KEY"

from openai import OpenAI

client = OpenAI(
    base_url="https://app.iamolly.ai/api/molly/v1",
    api_key="mk-KEY",
)

for m in client.models.list().data:
    print(m.id)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://app.iamolly.ai/api/molly/v1",
  apiKey: "mk-KEY",
});

const models = await client.models.list();
models.data.forEach((m) => console.log(m.id));

GET/usage

Return token and request usage for the authenticated key.

Response Body

{
  "object": "usage",
  "total_requests": 1842,
  "total_tokens": 2915430,
  "prompt_tokens": 1204880,
  "completion_tokens": 1710550
}

Examples

curl https://app.iamolly.ai/api/molly/v1/usage \
  -H "Authorization: Bearer mk-KEY"

import requests

r = requests.get(
    "https://app.iamolly.ai/api/molly/v1/usage",
    headers={"Authorization": "Bearer mk-KEY"},
)
print(r.json())

const res = await fetch(
  "https://app.iamolly.ai/api/molly/v1/usage",
  { headers: { Authorization: "Bearer mk-KEY" } }
);
console.log(await res.json());

Models

Set the model field to molly to use the orchestrator (the default and recommended choice). The orchestrator's CEO multi-agent layer selects and routes to the appropriate LoRA specialist derived from a single quantized base model.

Errors

The API uses standard HTTP status codes. Error responses include a JSON body with an error object describing what went wrong.

Error Response Shape

{
  "error": {
    "type": "rate_limit_error",
    "code": 429,
    "message": "Rate limit exceeded: 60 requests per minute."
  }
}