Control Plane API¶

The control plane is how you create and manage Organizations, Applications, policy, cost configuration, and API keys in G-1 Studio. It is the management counterpart to the chat data plane: the control plane decides what an Application is, the data plane runs requests through it.

Every control-plane route is mounted under /v1/glad — right next to the compliance API — on the same single-origin server as the gateway and the web UI. The routes operate on the shared Studio database (Organizations, Applications, API keys, the usage ledger).

Call it — create an Application end to end¶

What it does. Creates an Organization, an Application bound to your upstream, sets its policy, and mints the key your application will authenticate with. Four calls; after them the Application is live on the data plane.

BASE=http://localhost:8080
JSON='-H Content-Type:application/json'

ORG=$(curl -s $BASE/v1/glad/orgs $JSON \
  -d '{"name":"Acme Legal","max_applications":5}' | jq -r .org_id)

APP=$(curl -s $BASE/v1/glad/apps $JSON -d "{
  \"name\": \"Contract Reviewer\",
  \"org_id\": \"$ORG\",
  \"config\": {\"binding\": {\"upstream_type\":\"ollama\",
                             \"base_url\":\"http://localhost:11434\",
                             \"model\":\"llama3.1:8b\"}}
}" | jq -r .app_id)

curl -s -X PUT $BASE/v1/glad/apps/$APP/policy $JSON \
  -d '{"policy":{"thresholds":{"prompt_safety":0.75},"scope":"Reviews commercial contracts."}}'

KEY=$(curl -s $BASE/v1/glad/apps/$APP/keys $JSON -d '{"role":"invoke"}' | jq -r .api_key)
echo "$KEY"   # shown once — store it now

import httpx

c = httpx.Client(base_url="http://localhost:8080", timeout=30)
# If a platform token is configured:
# c.headers["X-Geodesia-Admin-Key"] = os.environ["GEODESIA_ADMIN_TOKEN"]

org = c.post("/v1/glad/orgs", json={"name": "Acme Legal", "max_applications": 5}).json()

app = c.post("/v1/glad/apps", json={
    "name": "Contract Reviewer",
    "org_id": org["org_id"],
    "config": {"binding": {"upstream_type": "ollama",
                           "base_url": "http://localhost:11434",
                           "model": "llama3.1:8b"}},
}).json()
app_id = app["app_id"]

# Ask the server which axes this checkpoint actually has before writing a policy.
meta = c.get("/v1/glad/apps/meta").json()
print("axes:", meta["axes"])

c.put(f"/v1/glad/apps/{app_id}/policy", json={"policy": {
    "thresholds": {"prompt_safety": 0.75},
    "scope": "Reviews commercial contracts.",   # required for the out_of_scope axis
}})

key = c.post(f"/v1/glad/apps/{app_id}/keys", json={"role": "invoke"}).json()
print(key["api_key"])          # returned ONCE — store it now

const BASE = "http://localhost:8080"
const H = { "Content-Type": "application/json" }
const post = (p: string, b: unknown) =>
  fetch(BASE + p, { method: "POST", headers: H, body: JSON.stringify(b) }).then(r => r.json())

const org = await post("/v1/glad/orgs", { name: "Acme Legal", max_applications: 5 })

const app = await post("/v1/glad/apps", {
  name: "Contract Reviewer",
  org_id: org.org_id,
  config: { binding: { upstream_type: "ollama", base_url: "http://localhost:11434", model: "llama3.1:8b" } },
})

await fetch(`${BASE}/v1/glad/apps/${app.app_id}/policy`, {
  method: "PUT", headers: H,
  body: JSON.stringify({ policy: { thresholds: { prompt_safety: 0.75 },
                                   scope: "Reviews commercial contracts." } }),
})

const key = await post(`/v1/glad/apps/${app.app_id}/keys`, { role: "invoke" })
console.log(key.api_key)       // returned ONCE — store it now

What comes back — the Application record, and from the last call a key you can immediately use on the data plane:

curl -s http://localhost:8080/gw/v1/chat/completions \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"llama3.1:8b","stream":false,
       "messages":[{"role":"user","content":"Is this NDA mutual?"}]}'

Authentication & RBAC¶

The control plane has four roles, in ascending privilege:

viewer  <  app_editor  <  org_admin  <  platform_admin

A caller's role is resolved from the request headers:

Role required per write¶

Reads are always permitted. Writes require at least the role shown:

An org_admin resolved from an app key may only act on its own Organization — a cross-org write returns 403 org scope mismatch. A platform_admin has no such restriction.

When a write is denied, the API returns:

{ "detail": "requires role >= org_admin (you are viewer)" }

Route reference¶

Every route, grouped by resource. The Role column is the minimum role for that route (reads are open; the gate only applies once auth is configured).

Meta¶

Organizations¶

Applications¶

Policy & cost configuration¶

Metrics & cost¶

API keys¶

Worked examples¶

The examples below assume the server is on http://localhost:8080 and the control plane is open (local install). If you have configured a platform token, add -H "X-Geodesia-Admin-Key: $GEODESIA_ADMIN_TOKEN" to each write.

1. Create an Organization¶

curl -s http://localhost:8080/v1/glad/orgs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Legal",
    "country": "IT",
    "license_type": "evaluation",
    "max_applications": 5
  }'

{
  "org_id": "acme_legal",
  "name": "Acme Legal",
  "country": "IT",
  "license_type": "evaluation",
  "max_applications": 5,
  "created_at": "2026-06-18T09:00:00.000000Z",
  "updated_at": "2026-06-18T09:00:00.000000Z"
}

org_id is slugged from name if you omit it. Returns 201 Created. Calling it again with the same org_id upserts the name/country.

2. Create an Application¶

curl -s http://localhost:8080/v1/glad/apps \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract Reviewer",
    "org_id": "acme_legal",
    "config": {
      "binding": {"upstream_type": "ollama", "base_url": "http://localhost:11434", "model": "llama3.1:8b"},
      "calibration_profile": "llama3.1:8b"
    }
  }'

{
  "app_id": "contract_reviewer_4f2a9c",
  "config_version": 1,
  "status": "active",
  "app": {
    "app_id": "contract_reviewer_4f2a9c",
    "org_id": "acme_legal",
    "name": "Contract Reviewer",
    "status": "active",
    "config_version": 1,
    "config": { "schema_version": 1, "binding": { "...": "..." }, "policy": { "...": "..." } }
  }
}

If you omit config, the Application is created with the complete default config (every axis the served checkpoint has, at its serving-calibrated threshold). Returns 201 Created. An invalid config returns 400 with the validation message.

{
  "detail": "application limit reached (free tier: 1 application(s)). Add a license token to create more."
}

3. Set the Application's policy¶

Policy updates are a merge — you send only the fields you want to change.

curl -s -X PUT http://localhost:8080/v1/glad/apps/contract_reviewer_4f2a9c/policy \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "thresholds": {"prompt_safety": 0.75, "jailbreak": 0.55},
      "enforcement": {"answer_safety": "block"},
      "block_input": true
    }
  }'

{
  "policy": {
    "thresholds": {"prompt_safety": 0.75, "jailbreak": 0.55, "rag_jailbreak": 0.2501,
                   "halluc_context": 0.6475, "halluc_closedbook": 0.58, "answer_safety": 0.7295,
                   "profanity": 0.90, "out_of_scope": 0.90, "prompt_complexity": 0.50},
    "enforcement": {"prompt_safety": "block", "jailbreak": "block", "rag_jailbreak": "block",
                    "halluc_context": "annotate", "halluc_closedbook": "annotate", "answer_safety": "block",
                    "profanity": "annotate", "out_of_scope": "annotate", "prompt_complexity": "off"},
    "block_input": true
  },
  "config_version": 2
}

The cost configuration works the same way via PUT /apps/{id}/cost (merge currency, input_per_mtok, output_per_mtok, budget_month, on_budget_exceeded, …). The full policy/cost field shape is documented in Managing Applications.

4. Mint and use an API key¶

curl -s http://localhost:8080/v1/glad/apps/contract_reviewer_4f2a9c/keys \
  -H "Content-Type: application/json" \
  -d '{"role": "invoke"}'

{
  "key_id": "ak_9b1f2c3d",
  "app_id": "contract_reviewer_4f2a9c",
  "key_preview": "g1k_***x8Qv",
  "role": "invoke",
  "api_key": "g1k_live_8sQ3...x8Qv"
}

The key is the Application's runtime identity on the data plane. Pass it as a Bearer token on a chat request to route that request through this Application:

curl -s http://localhost:8080/gw/v1/chat/completions \
  -H "Authorization: Bearer g1k_live_8sQ3...x8Qv" \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3.1:8b","stream":false,"messages":[{"role":"user","content":"Summarise clause 4."}]}'

A role: "admin" key additionally acts as an org_admin on the control plane (see RBAC).

5. Read metrics and forecast cost¶

curl -s http://localhost:8080/v1/glad/apps/contract_reviewer_4f2a9c/metrics

{
  "application_id": "contract_reviewer_4f2a9c",
  "total": 1284,
  "prompt_blocked": 17,
  "answer_blocked": 5,
  "hallucinated": 31,
  "grounded": 1102
}

curl -s "http://localhost:8080/v1/glad/apps/contract_reviewer_4f2a9c/cost/forecast?method=linreg"

{
  "period": "2026-06",
  "currency": "EUR",
  "spent_mtd": 42.18,
  "days_elapsed": 18,
  "days_in_month": 30,
  "projected_month": 71.94,
  "budget": 100.0,
  "projected_pct": 0.7194,
  "over_budget": false,
  "method": "linreg",
  "ci80": [61.40, 82.48]
}

The forecast is deterministic and numpy-only. run_rate (the default) extrapolates the month-to-date average; moving_avg uses the trailing 7 days; linreg / linreg_dow fit a trend (the latter applies a day-of-week factor) and return an 80% confidence band in ci80. Pass budget via the Application's cost config — the route reads budget_month from it. The summary endpoint (/cost/summary) returns the same period's token totals and avg_cost_per_call.

Data-plane routing header¶

The control plane defines Applications; the data plane selects one per request (_resolve_app). A chat or RAG request picks its Application via either an explicit identifier or an Application API key, in this order:

1. Explicit id / header — the body field application_id (alias app_id), or the X-Geodesia-App: <app_id> request header. An explicit id always wins, including an explicit default.
2. Application API key — an invoke (or admin) key sent as Authorization: Bearer g1k_live_…, used only as a fallback when no explicit id/header is present. The gateway verifies the key and routes the request to the Application that key belongs to.

The gateway resolves that identifier to the Application's config — its upstream binding, block_input, and per-axis thresholds are merged into the request. An unknown identifier, or the literal default, falls back to the global / default configuration, so existing single-upstream integrations keep working unchanged.

Route via the header (or application_id in the body):

curl -s http://localhost:8080/gw/v1/chat/completions \
  -H "X-Geodesia-App: contract_reviewer_4f2a9c" \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3.1:8b","stream":false,"messages":[{"role":"user","content":"Is this NDA mutual?"}]}'

Route via an Application API key (no header needed):

curl -s http://localhost:8080/gw/v1/chat/completions \
  -H "Authorization: Bearer g1k_live_8sQ3...x8Qv" \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3.1:8b","stream":false,"messages":[{"role":"user","content":"Is this NDA mutual?"}]}'

The key belongs to exactly one Application, so it resolves the Application implicitly — a raw API client that authenticates with just Authorization: Bearer g1k_live_… is still routed to, scoped to, and billed against its own Application. If you send both an explicit id/header and a g1k_ key, the explicit id/header wins. For the full chat request/response contract, see the Chat API.

See also¶

• Managing Applications — the Application config shape (binding, policy, cost, governance) and lifecycle.
• Licensing — the entitlement cap, license tokens, and how they raise the Application limit.
• Cost & FinOps — the usage ledger, daily roll-up, budgets, and forecasting model.
• Chat API — the data-plane endpoint that consumes the routing header and the per-Application policy.