API reference OpenAPI 3.1, v0.3.0

What changed in v0.3. The Subject service: the controls a person holds over what is learned about them, as governed operations. Learning can be paused and resumed (/identities//learning), any learned record can be forgotten (/forget: the record is emptied in place and the chain keeps the act and a SHA-256 of what it was, never the content), the learned graph can be reset (/reset), and the whole record can be exported in one signed document with a fingerprint and the lineage of chain events behind it (/export). Every one is policy-evaluated, receipted and chained. The 42 v0.2 paths are unchanged.

What changed in v0.2. The MCP governance model entered the REST contract: the Projection service with purpose profiles (GET /purposes), caller resolution (GET /identities/me), purpose-bounded projections with node budgets and a per-node gate explanation, obligations carrying attested or proposed status, read-only consent records, and interaction records (POST /audit/interactions).

The API contract for Identity Governed Logic (IGL). The API exposes governed identity, authority, knowledge, policy, evidence, outcome, graph, query, research, agent, workflow, and audit services. It is model-agnostic: reasoning providers can be changed without changing the governed intelligence contract. Version 0.2 adds purpose-bounded projections: purpose profiles, identity projections with per-node gate explanations, obligations with attestation status, caller resolution, consent records, and interaction records, so applications and model callers share one governance model. Version 0.3 adds the Subject service: the controls a person holds over what is learned about them, as governed operations with signed receipts. Learning can be paused and resumed, any learned record can be forgotten (the record is emptied in place and the chain keeps the act and a hash, never the content), the learned graph can be reset, and the whole record can be exported with a fingerprint and the lineage of chain events that produced it.

The contract covers 46 paths, 51 operations, 72 reusable schemas and 3 webhooks. The source of truth is the specification file in the repository, spec/openapi.yaml, also served here as igl-openapi.yaml. Earlier versions are in the repository history.

Authentication, tenancy and conventions

Every call carries a credential and the tenant boundary header. The credential is an API key sent as the bearer token, or a one-hour EdDSA access token minted from that key at the token endpoint (OAuth 2.0 client credentials: the key id is the client id and the key is the secret) when a workload should hold narrower scope than the key. The X-IGL-API-Key header is accepted on the operations that list it. A credential in the query string is ignored.

Errors use application/problem+json (RFC 9457): type, title, status, traceId and optional field-level violations. 403 means the action was denied by authority or policy; 422 means the request was valid but could not be governed or executed; 429 carries Retry-After. Lists page with cursor and limit (max 200) and return page.nextCursor / page.hasMore.

# governed query from WellSite: obligations due in the next 30 days
curl -X POST https://sandbox.id-me.ai/v1/query \
  -H "Authorization: Bearer $IGL_TOKEN" \
  -H "X-IGL-Tenant-Id: e7bcde63-4ccd-4594-aa64-6de1cce72ae8" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Which obligations are due for this asset in the next 30 days, who owns them, and what evidence is required?",
        "scope": { "assetId": "95dcad56-20a5-4b65-b8e7-6bb3e91510a2" },
        "maxHops": 4, "requireCitations": true, "minimumConfidence": 0.8 }'

Operations by service

Each row is one operation. The scope column is what the token must carry; public needs no credential.

Identity Resolve identities, context, and relationships.

Projection Purpose-bounded projections of an identity: what a caller may see, why, and what was withheld.

Subject The controls a person holds over what is learned about them: pause, forget, reset, export. Every one is a governed action with a signed receipt and a chain entry.

Authority Evaluate access, roles, delegations, and decision authority.

Knowledge Create and retrieve governed entities and facts.

Policy Create policies and evaluate governed actions.

Evidence Capture provenance, citations, corroboration, and findings.

Outcomes Record decisions, actions, measurements, and feedback.

Graph Traverse and manage governed graph relationships.

Intelligence Run governed queries, research, crosswalks, and investigations.

Agents Register and invoke governed agents.

Workflows Define and run governed workflows.

Audit Retrieve immutable activity and runtime receipts.

System Service health and capability discovery.

Webhooks

IGL calls your endpoint over https and expects 200 or 202; payloads reuse the public schemas. Subscriptions are registered per tenant with POST /admin/webhooks (a platform or admin credential), which returns the signing secret once. Every delivery carries X-IGL-Event, X-IGL-Delivery and X-IGL-Signature: t=<unix seconds>,v1=<HMAC-SHA256(secret, t + "." + body)>; verify the signature and reject stale timestamps. A delivery that does not get a 2xx is retried twice more with backoff and every attempt is recorded.

Examples from the specification

GET /identities/me: response 200

{
  "identityId": "b9d4507a-36ce-4d1b-970d-d85797141ff7",
  "purpose": "identity-introduction",
  "nodes": [
    {
      "id": "b9d4507a-36ce-4d1b-970d-d85797141ff7",
      "type": "Person",
      "label": "Maria Santos",
      "status": "certified"
    },
    {
      "id": "6b1d3e2a-5a51-4b0c-9a7e-0a2c0e3f9c11",
      "type": "Role",
      "label": "Compliance Lead",
      "status": "certified"
    },
    {
      "id": "e7bcde63-4ccd-4594-aa64-6de1cce72ae8",
      "type": "Organization",
      "label": "Rio Diablo Operating",
      "status": "certified"
    },
    {
      "id": "3d2c1b0a-9f8e-4d7c-b6a5-4e3d2c1b0a99",
      "type": "Jurisdiction",
      "label": "US-TX",
      "status": "certified"
    }
  ],
  "edges": [],
  "truncated": false,
  "withheld": {
    "Credential": 2,
    "Obligation": 3,
    "Facility": 1
  },
  "governance": {
    "receiptId": "0c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "actor": {
      "identityId": "b9d4507a-36ce-4d1b-970d-d85797141ff7"
    },
    "authorityDecision": {
      "decisionId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "effect": "allow",
      "evaluatedAt": "2026-10-14T14:02:11Z"
    },
    "policiesEvaluated": [],
    "createdAt": "2026-10-14T14:02:11Z"
  },
  "createdAt": "2026-10-14T14:02:11Z"
}

POST /query: Run a governed intelligence query

{
  "question": "Which obligations are due for this asset in the next 30 days, who owns them, and what evidence is required?",
  "actor": {
    "identityId": "b9d4507a-36ce-4d1b-970d-d85797141ff7",
    "organizationId": "e7bcde63-4ccd-4594-aa64-6de1cce72ae8",
    "roleIds": [
      "07e7a6c8-30aa-4a22-85ba-61c3f024e401"
    ]
  },
  "scope": {
    "assetId": "95dcad56-20a5-4b65-b8e7-6bb3e91510a2"
  },
  "filters": [
    {
      "field": "dueDate",
      "operator": "between",
      "value": [
        "2026-10-06",
        "2026-11-05"
      ]
    }
  ],
  "maxHops": 4,
  "requireCitations": true,
  "minimumConfidence": 0.8
}

POST /crosswalk: Run a multi-hop crosswalk

{
  "question": "Map the relationships among sites, products, manufacturers, witnesses, experts, and treaters.",
  "scope": {
    "matterIndependent": true,
    "domains": [
      "toxic-tort",
      "silica"
    ]
  },
  "filters": [
    {
      "field": "relationship.status",
      "operator": "in",
      "value": [
        "proposed",
        "certified"
      ]
    }
  ],
  "maxHops": 6,
  "asOf": "2026-10-06T00:00:00Z",
  "requireCitations": true,
  "minimumConfidence": 0.65
}

Schemas (72)

Required fields are marked with an asterisk; enumerations are listed inline. The status values seed, proposed and certified are the governance ladder: nothing is certified without a human or a rule the organization controls.