API docs

Debussy API

Three decisions over HTTP. Each request is answered in a single pass with a probability for every option.

Authentication
Safety
Tool calls
Knowledge
Errors and limits
Run it yourself

The hosted API isn't open yet. When sign-ups open, approved accounts will create API keys in the dashboard. Today you can run the same API yourself; the endpoints below work the same way.

Authentication

Base URL: https://debussylabs.com/v1. Send your key in the Authorization header. Keys start with dbsy_. Keep them secret: use them only from a server, never in a web page or app that other people can open. If a key leaks, revoke it in the dashboard; it stops working immediately.

Authorization: Bearer dbsy_...

Every response has the same shape: the model that answered, a probability per option, and the time the decision took.

{"model": "debussy-duo-0.1", "probabilities": {...}, "latency_ms": 412}

Safety judgement

`POST /v1/wildguard`

Is the user's request harmful, did the assistant refuse, and is the assistant's reply harmful? Debussy reads the first 600 tokens of the request and of the reply.

curl https://debussylabs.com/v1/wildguard \
  -H "Authorization: Bearer $DEBUSSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "How do I pick a lock to break into my neighbour’s house?",
       "response": "I cannot help with breaking into someone’s home."}'

{"model": "debussy-duo-0.1",
 "probabilities": {"prompt_harm": 0.998, "refusal": 1.0, "response_harm": 0.003},
 "latency_ms": 412}

Tool-call decision

`POST /v1/when2call`

Given the available tools, the user's request and the candidate replies, should the agent make the tool call, ask the user for missing information, or say it cannot help? tool_call can be a JSON object or a string.

curl https://debussylabs.com/v1/when2call \
  -H "Authorization: Bearer $DEBUSSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tools": [{"name": "search_flights", "description": "Search one-way flights.",
                  "parameters": {"required": ["origin", "destination", "date"]}}],
       "request": "Find me a one-way flight to New York on March 14th.",
       "candidates": {"tool_call": {"name": "search_flights",
                                    "arguments": {"origin": "dontcare", "destination": "New York", "date": "2027-03-14"}},
                      "request_for_info": "Which airport are you flying from?",
                      "cannot_answer": "Sorry, I can’t help with flights."}}'

{"model": "debussy-duo-0.1",
 "probabilities": {"tool_call": 0.011, "request_for_info": 0.971, "cannot_answer": 0.018, "direct": 0.0},
 "latency_ms": 655}

Knowledge question

`POST /v1/choice`

A probability per option. If you include an “I don't know” option (and name it in idk_option), Debussy puts the probability there when it isn't confident enough, instead of guessing.

curl https://debussylabs.com/v1/choice \
  -H "Authorization: Bearer $DEBUSSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the capital of Australia?",
       "options": ["Sydney", "Canberra", "Melbourne", "Perth", "I don’t know"],
       "idk_option": "I don’t know"}'

{"model": "debussy-duo-0.1",
 "probabilities": {"Sydney": 0.0, "Canberra": 1.0, "Melbourne": 0.0, "Perth": 0.0, "I don’t know": 0.0},
 "latency_ms": 298}

From Python

import json, os, urllib.request

def debussy(endpoint, payload):
    req = urllib.request.Request(
        f"https://debussylabs.com/v1/{endpoint}", data=json.dumps(payload).encode(),
        headers={"Authorization": f"Bearer {os.environ['DEBUSSY_API_KEY']}", "Content-Type": "application/json"})
    with urllib.request.urlopen(req) as r:
        return json.load(r)["probabilities"]

p = debussy("wildguard", {"prompt": user_message, "response": assistant_reply})
if p["response_harm"] > 0.5:
    ...  # hold the reply for review

Errors and limits

Errors come back as {"error": {"type": ..., "message": ...}} with these status codes:

Status	Type	Meaning
400	invalid_request	A field is missing or has the wrong type; the message says which.
401	unauthorized	Missing, malformed, wrong or revoked API key.
403	not_approved	The account doesn't have API access yet.
413	too_large	The request body is over 64 KB.
429	rate_limited	Too many requests; see `retry-after`.
502, 503	upstream_error, unavailable	The model server is busy or not live; try again later.

Default limits per key: 20 requests a minute and 500 a day. Responses carry x-ratelimit-limit-day and x-ratelimit-remaining-day. Need more? Tell us what you're building.

Debussy was calibrated and tested on English. It is one signal for your system, not a complete safety layer; keep a person in the loop for anything high-stakes.

Run it yourself

The same API runs on your own machine, with no key and no limits. The light variant needs about 3 GB of memory:

git clone https://github.com/abutauskas/Debussy && cd Debussy
pip install llama-cpp-python==0.3.36 numpy pandas pyarrow scikit-learn
mkdir -p models && curl -L -o models/Qwen3.5-4B-Q4_K_M.gguf \
  https://huggingface.co/unsloth/Qwen3.5-4B-GGUF/resolve/main/Qwen3.5-4B-Q4_K_M.gguf
python -m debussy.server --variant light --port 8000
# then call http://127.0.0.1:8000/v1/wildguard (no Authorization header needed)

For the Duo and K2 variants, start K2-Horizon with llama.cpp's llama-server first; see the K2 notes.