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).

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 (all 6 axes, serving-calibrated thresholds). 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.05, "halluc_context": 0.32, "halluc_closedbook": 0.58, "answer_safety": 0.90},
    "enforcement": {"prompt_safety": "block", "jailbreak": "block", "rag_jailbreak": "block", "halluc_context": "annotate", "halluc_closedbook": "annotate", "answer_safety": "block"},
    "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/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/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/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.