The two API surfaces

What you will learn The two doors HyperTeams offers to the outside, what each one opens, and what you must understand before turning them on.

If APIs and endpoints are new, start with What an API is.

The character changes here

The previous twelve chapters were about using it from the screen. This part is about letting other programs call this machine.

That means opening a door, and before opening one you need to know what it opens.

There are exactly two doors

graph TD
  A["All of /api/*"] --> B["/api/v1<br/>HyperTeams' own REST"]
  A --> C["/api/ai<br/>models — OpenAI compatible"]
  A --> D["Every other /api/*<br/>dashboard only"]
  B --> B1["Bearer key"]
  C --> C1["Bearer key"]
  D --> D1["Browser cookie<br/>not callable from outside"]

Nothing outside these two is callable from outside. The routes the screens use open only for a logged-in browser's cookie.

Both default to off

The most important property.

On an install where you never turned them on, these paths do not exist — you get a 404.

That it is 404 (not there) rather than 401 (not authorised) is deliberate. A system that has not been turned on does not even advertise that an API exists.

The key is your dashboard password

This is the core of the chapter.

The API key is not a separately issued value — it is the dashboard password itself.

That design has consequences.

Consequence 1 — no password means you cannot turn it on

An install without a password stands on the premise that the dashboard itself runs without authentication (reachable only from your own machine). Add "an API that accepts any value" to that and the moment the premise breaks you are twice as open. So it simply will not turn on.

Consequence 2 — the key spreads

Once you use the password as a Bearer token, that value ends up in places like:

One leak opens the whole dashboard. Same story as the tunnel saying "anyone who knows the address can try," except here the value gets copied to several places.

So ask yourself before turning it on: can you count every place this key will live? If not, it is not time yet.

The model surface has three levels

REST is on or off, but the model side lets you choose how far to open.

What inference opens is a fixed list.

Anything outside that list is a 404 under inference. Management actions like downloading a model or restarting the server open only under full.

Start with inference. If the goal is lending your models to another program, inference is enough; full lets that program manage your model server. Least privilege applies here directly.

Two base addresses

The model side is advertised under two addresses, which is easy to confuse.

This happens because everything under /api/ai maps 1:1 onto the upstream model server's root. The upstream itself is "OpenAI surface at /v1 under the server root," so that nesting carries through.

⚠ Because it nests, the path does not enforce the scope. Being told …/api/ai/v1 does not mean you can only go below it — the scope is set by inference / full, not by the path.

The Settings tab. Turning the two API surfaces on and off happens here.

The order to turn it on

Step 4 matters. Once one call works, the rest is copying. Attach it in several places at once and you cannot tell which one is wrong.

Where the specification lives

This system publishes its own OpenAPI 3.1 specification. But that spec is not on the public surface — it sits behind the dashboard gate.

• You read it as a documentation screen from a logged-in browser
• If an external tool needs it, you download it and hand it over

The spec is not a secret, but there is also no reason to advertise what this system has left open. So it does not sit where it can be read without a key.

Common misconceptions

"Don't I get issued an API key separately?"

No. The dashboard password is the key. So changing the password means fixing every place you put that value.

"It's convenient — why not turn both on?"

Turn off surfaces you do not use. Being on means the same key opens that side too. If you only use models, leave REST off.

"Does this matter if I only use it locally?"

On localhost the risk is far smaller. But the moment you open a tunnel, the same key works from the internet. Turning on the tunnel and the API together is when password strength really starts to matter.

Check yourself

1. Why do you get a 404 rather than a 401 on a system that has not been turned on?

2. What is the API key, and what does that mean you must watch?

3. What is the difference between inference and full?

First, directing work from outside → Directing work over REST