Skip to content

HTTP API (Any Language)

The Hall Server exposes a plain HTTP API. Any language that can make a POST request works — no SDK required.

Base URL

http://localhost:8765

Hall Server runs locally. No outbound network call is made for the routing decision — it resolves against your local registry and policy database.

Endpoint

POST /api/route

Request

{
  "capability_id": "cap.doc.summarize",
  "env": "dev",
  "data_label": "PUBLIC",
  "tenant_id": "your-org"
}

Field	Type	Description
`capability_id`	string	The capability to request (e.g. `cap.doc.summarize`)
`env`	string	Environment: `dev`, `staging`, or `prod`
`data_label`	string	Data sensitivity: `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `SECRET`
`tenant_id`	string	Your org or tenant identifier

Response

{
  "decision_id": "uuid",
  "allowed": true,
  "worker_id": "worker.doc.summarize",
  "deny_reason": null
}

Field	Type	Description
`decision_id`	string	UUID for audit correlation
`allowed`	boolean	`true` = proceed, `false` = blocked
`worker_id`	string	Assigned worker when allowed
`deny_reason`	string or null	Machine-readable denial code when blocked

Examples

curl

export HALL_TOKEN="<your-session-token>"
curl -X POST http://localhost:8765/api/route \
  -H "Authorization: Bearer $HALL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"capability_id":"cap.doc.summarize","env":"dev","data_label":"PUBLIC","tenant_id":"org.you"}'

JavaScript (fetch)

const HALL_TOKEN = process.env.HALL_SESSION_TOKEN;
const decision = await fetch('http://localhost:8765/api/route', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${HALL_TOKEN}`,
  },
  body: JSON.stringify({
    capability_id: 'cap.doc.summarize',
    env: 'dev',
    data_label: 'PUBLIC',
    tenant_id: 'your-org',
  }),
}).then(r => r.json());

if (!decision.allowed) throw new Error(`Blocked: ${decision.deny_reason}`);

Go

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

type RouteRequest struct {
    CapabilityID string `json:"capability_id"`
    Env          string `json:"env"`
    DataLabel    string `json:"data_label"`
    TenantID     string `json:"tenant_id"`
}

type RouteResponse struct {
    Allowed    bool   `json:"allowed"`
    DenyReason string `json:"deny_reason"`
}

func hallRoute(capID, tenantID string) (RouteResponse, error) {
    body, _ := json.Marshal(RouteRequest{CapabilityID: capID, Env: "dev", DataLabel: "PUBLIC", TenantID: tenantID})
    req, _ := http.NewRequest("POST", "http://localhost:8765/api/route", bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+os.Getenv("HALL_SESSION_TOKEN"))
    resp, err := http.DefaultClient.Do(req)
    if err != nil { return RouteResponse{}, err }
    defer resp.Body.Close()
    var result RouteResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}

Reference