OpenAI-compatible API

Fosnie speaks the OpenAI chat-completions protocol, so any client built for it – an SDK, a CLI, an editor extension, your own script – works by pointing at your instance and using a Fosnie key. The interesting part is that a key can address your agents, not just a raw model, so you can talk to your own libraries from wherever you work.

Get a key

Keys are self-service, under Profile → API keys. Give the key a name describing what it is for, and optionally an expiry in days. It appears once, at creation:

• Fosnie stores only a fingerprint of the key, never the key itself, so nobody can recover it afterwards – including an administrator. Lost it, mint a new one and revoke the old.
• Revoke from the same screen, and the key stops working immediately.
• An administrator can see that your keys exist and revoke one, but cannot read it.

A key acts as you: the same role, the same Projects, Libraries and agents, the same access checks as in the app. There are no per-key scopes, so treat a key as you would your password.

Call it

The base URL is {public_url}/v1, and your key is the API key. Everything else is the protocol your client already knows:

# What this key can address:
curl {public_url}/v1/models -H "Authorization: Bearer sk-fosnie-..."

# A completion (add "stream": true for token-by-token):
curl {public_url}/v1/chat/completions \
  -H "Authorization: Bearer sk-fosnie-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "GPT-5.4", "messages": [{"role": "user", "content": "Hello"}]}'

In an SDK, set the base URL to {public_url}/v1 and the API key to your Fosnie key. Streaming arrives as server-sent events and ends with the usual [DONE], so client libraries need no special handling.

Two kinds of model

GET /v1/models returns both, and either can be used verbatim as model:

• A provider name (whatever your instance calls it, e.g. GPT-5.4) is a passthrough. The messages go to that model as sent and nothing is kept. What Fosnie adds is the governance around it: who may call, which provider that name resolves to (including your own key for it), a per-key rate limit, and usage recorded in the admin dashboard alongside chat usage.
• agent/<id> runs the whole pipeline behind that agent: retrieval across the Libraries it can reach, its tools, its instructions, its citations. This is the one worth reaching for. It means asking your own knowledge base a question from a terminal or a script and getting the same answer, with the same sources, that you would get in the app.

Continuing a conversation

Agent replies carry an X-Fosnie-Chat-Id header. Send it back on the next request to continue that conversation; leave it out and each call starts a fresh one.

The history belongs to Fosnie rather than to the request, so the last user message is the question and any earlier messages in the array are ignored. Conversations created this way are kept, and stay out of your chat list because machine traffic would bury the conversations you are actually having. They remain openable by direct URL when you need to see what a client did.

Limits and settings

The API is on by default and inert until someone mints a key. An admin can switch it off with features.public_api, and both /v1 and key management then answer 404. Three super-admin knobs tune it: