Governance API — REST reference

Quickstart

Issue a key from your dashboard and export it as GIL_API_KEY. Each request carries a timestamp and a signature computed over the body, so a plain curl needs a few lines of shell:

export GIL_API_KEY=gil_<80 hex characters>

BODY='{"prompt":"Summarize the open decisions for this week."}'
TS=$(date +%s)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')
SIG=$(printf '%s.%s' "$TS" "$BODY_HASH" \
  | openssl dgst -sha256 -hmac "$GIL_API_KEY" -hex | awk '{print $NF}')

curl -X POST https://human-exe.ca/api/gil/analyze \
  -H "Authorization: Bearer $GIL_API_KEY" \
  -H "X-GiL-Timestamp: $TS" \
  -H "X-GiL-Signature: $SIG" \
  -H "Content-Type: application/json" \
  --data-raw "$BODY"

Never paste your GIL_API_KEY into a chat prompt, into a file an AI agent reads, or into any model context. It is a service credential, not part of the conversation.

Authentication & signing

Every request carries three headers:

Authorization:   Bearer <your GiL key>
X-GiL-Timestamp: <unix seconds>
X-GiL-Signature: <lowercase hex HMAC-SHA256>

How the signature is built

1. Serialize the body as canonical JSON: object keys sorted, no whitespace. A GET request has an empty body (an empty string).
2. Hash that string with SHA-256 and write the digest as lowercase hex.
3. The message to sign is {timestamp}.{body-hash-hex}.
4. Compute HMAC-SHA256 of the message. The HMAC key is your whole key string (the UTF-8 bytes of gil_…, exactly as shown at issuance). Do not decode it.
5. Send the result as lowercase hex in X-GiL-Signature.

The body you send must be byte-identical to the string you hashed. If a proxy or client library reformats the JSON, the signature will not match. The SDK serializes once and reuses that exact string.

Timing and replay

• The timestamp must be within 5 minutes of server time.
• Each signed request is accepted once. Sending the exact same signed request again (same timestamp and body) returns gil.replay_detected. Use a fresh timestamp for every request.

The key is shown once at issuance and cannot be retrieved. If you lose it, issue a new key from the dashboard, deploy it, then revoke the old one.

Endpoints

Base URL: https://human-exe.ca/api/gil

Keys are issued and revoked from the dashboard.

POST /analyze

Submit a prompt. GiL governs it, applies session memory if you supply a session, records an audit entry, and returns the response.

Request

POST https://human-exe.ca/api/gil/analyze
X-GiL-Session: <optional session id>   # reuse the same value to share session memory

{
  "prompt":      "…",                  // required
  "provider":    "anthropic" | "openai" | "google",   // optional
  "providerKey": "sk-…",               // optional: your own provider key (never stored)
  "model":       "…",                  // optional
  "temperature": 0.2,                  // optional
  "max_tokens":  1024                  // optional
}

You do not need a provider account: provider and providerKey are optional. If you send them, your chosen provider answers and bills you directly. Send X-GiL-Session as a header (not in the body); the SDK’s sessionId option sets it for you.

Response (200)

{
  "governed":   true,
  "session_id": "…",                   // pass back as X-GiL-Session to continue the session
  "response":   "…",                   // the governed answer
  "v0_stub":    false,
  "provider":   "…",
  "model":      "…",
  "usage": {
    "provider_tokens_in":    1240,
    "provider_tokens_out":   512,
    "gil_governance_units":  1
  },
  "advisories": [ { "kind": "…", "message": "…" } ],
  "audit": {
    "audit_id":              "…",
    "audit_mode":            "…",
    "cost_delta_pct":        0,
    "coherency_score":       0.82,
    "routing":               "…",
    "timestamp":             "2026-10-09T18:00:00Z",
    "decision_chain":        ["…"],
    "governance_state":      "green",
    "provenance_signature":  "…" ,
    "session_memory_active": true,
    "drift_score":           0.0
  }
}

Response headers

• governance-state: green | amber | red | black — see Governance state
• governance-advisory — present when the state is not green
• x-request-id — quote this when you contact support

GET /usage

Per-day governance units and provider tokens for your account. Provider tokens are informational only; if you use your own provider, they are billed by that provider, not by Human.Exe.

GET https://human-exe.ca/api/gil/usage?from=2026-10-01&to=2026-10-31
Authorization: Bearer <your GiL key>      # sign an empty body

{
  "from": "2026-10-01",
  "to":   "2026-10-31",
  "days": [
    { "date": "2026-10-09", "governanceUnits": 3, "providerTokensIn": 0, "providerTokensOut": 0 }
  ],
  "total": { "governanceUnits": 3, "providerTokensIn": 0, "providerTokensOut": 0 }
}

POST /feedback

Report a bug, slow response, unexpected governance result or docs gap directly to the team.

POST https://human-exe.ca/api/gil/feedback

{
  "severity":     "low" | "medium" | "high" | "critical",   // optional
  "category":     "latency",             // required
  "message":      "…",                   // required
  "context":      { },                   // optional
  "userFeedback": "…"                    // optional
}

→ { "id": "…", "status": "open", "createdAt": "…" }

Governance state

Governance state never blocks your call. It controls how much of a response is visible to the calling agent. Your request always completes.

Error codes

Errors return JSON with a code and a human-readable error message. Treat an unknown code as a generic failure and rely on the HTTP status.