Authentication

The POST /api/ai endpoint accepts either of two auth methods:

• API key (recommended). Send Authorization: Bearer noct_… (or header X-API-Key: noct_…). Create + manage keys on the API keys tab. Keep keys server-side — never ship them in client code.
• Account credentials. Include account + password in the JSON body. Convenient for quick tests; prefer keys for anything real.

The account endpoints (/api/ai/usage, /credits, /config) are session-based — they read your signed-in cookie and power the Overview tab. For programmatic quota tracking, read the quota object returned by every /api/ai call.

Chat / completion — POST /api/ai

Send a prompt or a message list, get a completion. Every call counts against your account's daily token quota and is rate-limited to 60 requests/minute.

Request body

Example — API key

Copycurl -s https://nocturne.lol/api/ai \
  -H "Authorization: Bearer noct_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model-id>","prompt":"Explain CSS grid in 2 sentences."}'

Example — multi-turn + account auth

Copycurl -s https://nocturne.lol/api/ai \
  -H "Content-Type: application/json" \
  -d '{
    "model":"<model-id>",
    "account":"your-username","password":"YOUR_PASSWORD",
    "system":"You are concise.",
    "messages":[{"role":"user","content":"Name three primary colors."}],
    "temperature":0.5,"max_tokens":200
  }'

Response

{
  "ok": true,
  "model": "<model-id>",
  "response": "Red, green, and blue.",
  "usage": { "inputTokens": 18, "outputTokens": 7, "totalTokens": 25 },
  "quota": { "used": 25, "cap": 50000, "remaining": 49975 }
}

Reasoning models may also include a reasoning field. Owner accounts get "quota": { "unlimited": true }.

Streaming ("stream": true)

Responds with text/event-stream. Each event is a data: line of JSON:

# incremental text
data: {"type":"delta","text":"Red"}
data: {"type":"delta","text":", green"}
# final totals, then end
data: {"type":"done","usage":{...},"quota":{...}}
data: [DONE]

Images (vision)

Send images to a vision model (marked 👁 on the Models tab). Use an array content with image_url parts (OpenAI format); the URL can be a public https link or a base64 data: URL.

Copycurl -s https://nocturne.lol/api/ai \
  -H "Authorization: Bearer noct_your_api_key" -H "Content-Type: application/json" \
  -d '{
    "model":"<vision-model-id>",
    "messages":[{"role":"user","content":[
      {"type":"text","text":"What is in this image?"},
      {"type":"image_url","image_url":{"url":"https://example.com/cat.jpg"}}
    ]}]
  }'

Up to 8 images per request, ≤6 MB each. A data URL looks like data:image/png;base64,iVBORw0KGgo…. Non-vision models reject images with a 400.

Errors

SDK examples

No official client library yet — the API is plain JSON over HTTP, so any HTTP client works. Two common ones:

JavaScript (fetch)

Copy// non-streaming
const r = await fetch("https://nocturne.lol/api/ai", {
  method: "POST",
  headers: { Authorization: "Bearer noct_your_api_key", "Content-Type": "application/json" },
  body: JSON.stringify({ model: "<model-id>", prompt: "Say hi in 5 words." })
});
const data = await r.json();
console.log(data.response);

Copy// streaming
const r = await fetch("https://nocturne.lol/api/ai", {
  method: "POST",
  headers: { Authorization: "Bearer noct_your_api_key", "Content-Type": "application/json" },
  body: JSON.stringify({ model: "<model-id>", prompt: "Count to 5.", stream: true })
});
const reader = r.body.getReader();
const decoder = new TextDecoder();
let buf = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  for (const line of buf.split("\n")) {
    if (!line.startsWith("data:") || line.includes("[DONE]")) continue;
    const evt = JSON.parse(line.slice(5));
    if (evt.type === "delta") process.stdout.write(evt.text);
  }
  buf = "";
}

Python (requests)

Copyimport requests

r = requests.post(
    "https://nocturne.lol/api/ai",
    headers={"Authorization": "Bearer noct_your_api_key"},
    json={"model": "<model-id>", "prompt": "Say hi in 5 words."},
)
print(r.json()["response"])

Copy# streaming
import json, requests

with requests.post(
    "https://nocturne.lol/api/ai",
    headers={"Authorization": "Bearer noct_your_api_key"},
    json={"model": "<model-id>", "prompt": "Count to 5.", "stream": True},
    stream=True,
) as r:
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data:") or "[DONE]" in line:
            continue
        evt = json.loads(line[5:])
        if evt.get("type") == "delta":
            print(evt["text"], end="", flush=True)

Best practices

Account & usage endpoints

Session-authenticated (your signed-in cookie). These power the Overview and Logs tabs.

GET /api/ai/usage

{ "authenticated": true, "weekTokens": 12840, "weekCost": 0.04, "allTokens": 91120, "allCost": 0.31 }

GET /api/ai/credits

{ "authenticated": true, "dollars": 2.84,
  "daily": { "used": 1320, "cap": 50000, "resetAt": 1750000000000 } }

GET /api/ai/config

Lists the models your account can use (id, label, pricing, flags) plus your credit balance — the source for the Models tab.

GET /api/ai/logs · /api/ai/usage/by-model

/logs returns your last 50 requests plus today's rollup (the Logs tab). /usage/by-model returns a 30-day per-model breakdown (tokens, requests, avg latency — the hover stats on Overview).

POST /api/ai/apikeys · GET /api/ai/apikeys · DELETE /api/ai/apikeys/:id

Create, list, and revoke your own keys programmatically — the same calls the API keys tab makes. POST accepts { "label": "my-app" } and returns the raw key. Unlike most providers, you can also re-fetch it later with GET /api/ai/apikeys/:id/reveal — useful if you lose it, though a fresh key is just as easy to create.

Link Checker API

Check whether a URL is blocked by common school/content filters (GoGuardian, Securly, Lightspeed, and more). This has its own dedicated docs now — see the Link Checker tab for the full reference (auth, rate limits, all 16 filters, examples, error codes). Note: the AI assistant can't help with Link Checker questions — the docs there are self-contained.

FAQ

Authentication & rate limits

No account or sign-in required. Every request is rate-limited per IP address:

Check a URL — GET / POST /api/v1/linkcheck

Runs the URL against every vendor's own public classification check. Your URL is only ever sent to each vendor as data — Nocturne never fetches, loads, or renders it. There's no SSRF surface on this endpoint.

Parameters

Example — GET

Copycurl -s "https://nocturne.lol/api/v1/linkcheck?url=discord.com&filters=all"

Example — POST

Copycurl -s https://nocturne.lol/api/v1/linkcheck \
  -H "Content-Type: application/json" \
  -d '{"url":"discord.com","filters":["securly","goguardian"]}'

Example — with a key (higher limit)

Copycurl -s "https://nocturne.lol/api/v1/linkcheck?url=discord.com" \
  -H "X-API-Key: your-linkcheck-key"

Response

{
  "url": "http://discord.com/",
  "checkedAt": "2026-07-20T12:00:00.000Z",
  "summary": { "total": 16, "blocked": 3, "allowed": 12, "errors": 1 },
  "results": [
    { "id": "securly", "label": "Securly", "category": "Social Media", "blocked": true, "ms": 240 },
    { "id": "fortiguard", "label": "FortiGuard", "category": "Technology", "blocked": false, "ms": 180 }
  ]
}

Each result has blocked: true/false/null (null = the vendor's check errored or timed out — see error), category as reported by that vendor, and ms = how long that single check took. Each vendor is checked concurrently with a 12s timeout, so one slow vendor never blocks the rest.

Available filters — GET /api/v1/filters

Errors

JavaScript example

Copyconst r = await fetch("https://nocturne.lol/api/v1/linkcheck?url=discord.com&filters=all");
const data = await r.json();
console.log(data.summary);   // { total: 16, blocked: 3, allowed: 12, errors: 1 }

Python example

Copyimport requests

r = requests.get("https://nocturne.lol/api/v1/linkcheck", params={"url": "discord.com", "filters": "all"})
print(r.json()["summary"])