# API reference (nexus-core v0.1)

**ST:** `[ST:portfolio:docs:api]`  
**Worker:** `bluehand-nexus-core` (`surfaces/nexus-core`)  
**Hosts:** `api.bluehand.dev`, `mcp.bluehand.dev` (Access-gated)

## Health

```
GET /health
GET /
```

Returns service name, version, `advisory_only`, `canonical_state: supabase`.

**Authority posture:** `projection_not_truth` — JSON responses orient only; Access gate is control representation, not organizational reality (OSO-003).

## Capabilities manifest

```
GET /mcp/capabilities
```

Returns v0.1 capability list, refused ops, route map.

## Governance routes

| Method | Path | Capability |
|--------|------|------------|
| POST | `/mcp/govern/evaluate` | `govern.evaluate` |
| POST | `/mcp/govern/attest` | `govern.attest` |
| POST | `/mcp/govern/authorize` | **403 refused** |

## State routes

| Method | Path | Capability |
|--------|------|------------|
| GET/POST | `/mcp/state/observe` | `state.observe` |
| POST | `/mcp/state/transition/propose` | `state.transition.propose` |

## Portfolio routes

| Method | Path | Capability |
|--------|------|------------|
| GET | `/mcp/issuance/status` | `issuance.status` |
| GET | `/mcp/capsule/orient` | `capsule.orient` |
| POST | `/mcp/ontology/query` | `ontology.query` |
| POST | `/mcp/graph/neighborhood` | `graph.neighborhood` |

## Lineage

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/mcp/execute` | `op: lineage.append` only |
| GET | `/mcp/events` | List `lineage:*` KV keys |

## Service binding pattern (planned)

```text
gateway → state → mcp → govern
```

Documented in skill v0.1; not deployed until multi-worker `wrangler.jsonc` lands.

## Errors

| Status | Meaning |
|--------|---------|
| 403 | Advisory refusal (`govern.authorize`, `kv.write`, …) |
| 400 | Unknown op or deprecated `kv.read`/`d1.query` vocabulary |
| 404 | Unknown path |

Full packet: `surfaces/nexus-core/skills/adv-wrangler-api-mcp/SKILL.md`