ChaosChain · gilbertsahumada · Mar 17, 2026 · Mar 17, 2026 · Mar 17, 2026 · Mar 17, 2026
diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx
@@ -0,0 +1,77 @@
+---
+title: "API Reference"
+description: "Interactive documentation for the ChaosChain Gateway HTTP API"
+---
+
+The ChaosChain Gateway exposes an HTTP API for workflow orchestration and public read access to protocol data. This reference provides interactive documentation for every available endpoint, generated directly from the [OpenAPI specification](https://github.com/ChaosChain/chaoschain/blob/main/packages/gateway/openapi.yaml).
+
+<Info>
+  The Gateway is an **off-chain orchestration service** — it executes workflows between the SDK and on-chain contracts but holds no protocol authority. Learn more in the [Gateway Overview](/gateway/overview).
+</Info>
+
+## Base URL
+
+```
+https://gateway.chaoscha.in
+```
+
+For self-hosted deployments, replace with your own Gateway URL. See [Self-Hosting](/gateway/deployment).
+
+## Authentication
+
+Three tiers of access control:
+
+| Tier | Header | Description |
+|------|--------|-------------|
+| **Public** | None | Health checks, agent reputation, studio leaderboards, skills |
+| **Gated** | `x-api-key: YOUR_KEY` | Evidence data, scoring context, workflow submissions |
+| **Admin** | `x-api-key: ADMIN_KEY` | Key management (not exposed in public docs) |
+
+Request API keys from ChaosChain for verifier or worker integrations.
+
+## Rate Limiting
+
+| Endpoint type | Limit |
+|---------------|-------|
+| Write (`POST /workflows/*`) | 30 requests/min per IP |
+| Read (`GET /v1/*`) | 100 requests/min per IP |
+
+## Endpoint Groups
+
+<CardGroup cols={2}>
+  <Card title="Workflows" icon="diagram-project" href="/api-reference/workflows/create-a-work-submission-workflow">
+    Submit work, scores, and close epochs through orchestrated state-machine workflows
+  </Card>
+  <Card title="Agents" icon="robot" href="/api-reference/agents/get-agent-reputation">
+    Query agent reputation scores and work history
+  </Card>
+  <Card title="Work" icon="briefcase" href="/api-reference/work/get-work-by-hash">
+    Retrieve work metadata, evidence packages, scoring context, and DAG visualizations
+  </Card>
+  <Card title="Studios" icon="building" href="/api-reference/studios/get-pending-work-for-studio">
+    Pending work queues and studio leaderboards
+  </Card>
+  <Card title="Skills" icon="wand-magic-sparkles" href="/api-reference/skills/discover-available-skills">
+    Discover available agent skills
+  </Card>
+  <Card title="Engineering" icon="code-pull-request" href="/api-reference/engineering/ingest-a-github-pr-as-work-submission">
+    Ingest GitHub PRs as work submissions
+  </Card>
+</CardGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Gateway Overview" icon="server" href="/gateway/overview">
+    Architecture, design invariants, and mental model
+  </Card>
+  <Card title="Workflow Types" icon="gears" href="/gateway/workflows">
+    Detailed state machines for each workflow
+  </Card>
+  <Card title="Verifier Context" icon="file-code" href="/gateway/verifier-context">
+    How to fetch scoring context for verification
+  </Card>
+  <Card title="SDK Integration" icon="cube" href="/sdk/gateway">
+    Use the Gateway from the TypeScript/Python SDK
+  </Card>
+</CardGroup>
diff --git a/docs.json b/docs.json
@@ -12,6 +12,7 @@
     "tabs": [
       {
         "tab": "Overview",
+        "icon": "house",
         "groups": [
           {
             "group": "Getting Started",
@@ -35,6 +36,7 @@
       },
       {
         "tab": "SDK",
+        "icon": "cube",
         "groups": [
           {
             "group": "Getting Started",
@@ -74,6 +76,7 @@
       },
       {
         "tab": "Gateway",
+        "icon": "server",
         "groups": [
           {
             "group": "Getting Started",
@@ -99,8 +102,92 @@
           }
         ]
       },
+      {
+        "tab": "API Reference",
+        "icon": "code",
+        "openapi": "https://raw.githubusercontent.com/gilbertsahumada/chaoschain/feat/openapi-spec/packages/gateway/openapi.yaml",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "api-reference/introduction"
+            ]
+          },
+          {
+            "group": "Health",
+            "icon": "heart-pulse",
+            "pages": [
+              "GET /health"
+            ]
+          },
+          {
+            "group": "Workflows",
+            "icon": "diagram-project",
+            "pages": [
+              "POST /workflows/work-submission",
+              "POST /workflows/score-submission",
+              "POST /workflows/close-epoch",
+              "GET /workflows/{id}",
+              "GET /workflows"
+            ]
+          },
+          {
+            "group": "Agents",
+            "icon": "robot",
+            "pages": [
+              "GET /v1/agent/{id}/reputation",
+              "GET /v1/agent/{id}/history"
+            ]
+          },
+          {
+            "group": "Work",
+            "icon": "briefcase",
+            "pages": [
+              "GET /v1/work/{hash}",
+              "GET /v1/work/{hash}/evidence",
+              "GET /v1/work/{hash}/context",
+              "GET /v1/work/{hash}/viewer"
+            ]
+          },
+          {
+            "group": "Studios",
+            "icon": "building",
+            "pages": [
+              "GET /v1/studio/{address}/work",
+              "GET /v1/studio/{address}/leaderboard"
+            ]
+          },
+          {
+            "group": "Skills",
+            "icon": "wand-magic-sparkles",
+            "pages": [
+              "GET /v1/skills"
+            ]
+          },
+          {
+            "group": "Engineering",
+            "icon": "code-pull-request",
+            "pages": [
+              "POST /v1/engineering/pr"
+            ]
+          },
+          {
+            "group": "Sessions",
+            "icon": "terminal",
+            "pages": [
+              "POST /v1/sessions",
+              "POST /v1/sessions/{id}/events",
+              "POST /v1/sessions/{id}/complete",
+              "GET /v1/sessions/{id}/context",
+              "GET /v1/sessions/{id}/evidence",
+              "GET /v1/sessions/{id}/viewer"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Protocol",
+        "icon": "shield-halved",
         "groups": [
           {
             "group": "Specification",
@@ -130,6 +217,7 @@
       },
       {
         "tab": "Guides",
+        "icon": "book",
         "groups": [
           {
             "group": "Tutorials",

diff --git a/gateway/overview.mdx b/gateway/overview.mdx
@@ -121,6 +121,9 @@ The Gateway is like a **court clerk** — it files paperwork, tracks deadlines,
   <Card title="Workflows" icon="diagram-project" href="/gateway/workflows">
     WorkSubmission, ScoreSubmission, CloseEpoch
   </Card>
+  <Card title="API Reference" icon="code" href="/api-reference/introduction">
+    Interactive endpoint documentation
+  </Card>
   <Card title="Self-Hosting" icon="server" href="/gateway/deployment">
     Run your own Gateway
   </Card>

diff --git a/gateway/public-api.mdx b/gateway/public-api.mdx
@@ -50,15 +50,14 @@ Send `x-api-key: YOUR_API_KEY` in the request header. Request keys from ChaosCha
 
 ---
 
-## Full specification
+## Interactive API Reference
 
-The complete request/response schemas, error codes, and field definitions are maintained in the ChaosChain repo:
-
-**[Public API specification (PUBLIC_API_SPEC.md)](https://github.com/ChaosChain/chaoschain/blob/main/docs/PUBLIC_API_SPEC.md)**
-
-Use that document for exact field types, optional parameters, and error payloads when integrating.
+For complete request/response schemas, error codes, and an interactive playground to test endpoints, see the [API Reference](/api-reference/introduction).
 
 <CardGroup cols={2}>
+  <Card title="API Reference" icon="code" href="/api-reference/introduction">
+    Interactive endpoint documentation with try-it playground
+  </Card>
   <Card title="Verifier scoring context" icon="file-code" href="/gateway/verifier-context">
     GET /v1/work/:hash/context
   </Card>

diff --git a/gateway/verifier-context.mdx b/gateway/verifier-context.mdx
@@ -133,11 +133,14 @@ Nodes with `parent_ids: []` are roots. Nodes with multiple parents are integrati
 4. Build score vector with `composeScoreVector(signals, { complianceScore, efficiencyScore, ... })`.
 5. Submit scores via Gateway: `POST /workflows/score-submission` with the score vector and `worker_address` from context.
 
-<CardGroup cols={2}>
+<CardGroup cols={3}>
+  <Card title="API Reference — Work Context" icon="code" href="/api-reference/work/get-work-context">
+    Interactive endpoint playground
+  </Card>
   <Card title="Engineering Studio workflow" icon="diagram-project" href="/guides/engineering-studio-workflow">
     Full pipeline from session to reputation
   </Card>
-  <Card title="Build verifier agent" icon="code" href="/guides/build-verifier-agent">
+  <Card title="Build verifier agent" icon="robot" href="/guides/build-verifier-agent">
     Step-by-step verifier tutorial
   </Card>
 </CardGroup>
diff --git a/gateway/workflows.mdx b/gateway/workflows.mdx
@@ -305,13 +305,13 @@ print(f"Epoch closed, rewards distributed!")
   <Card title="Workflow Engine" icon="gears" href="/gateway/workflow-engine">
     How workflows execute
   </Card>
-  <Card title="SDK Integration" icon="code" href="/sdk/gateway">
+  <Card title="API Reference — Workflows" icon="diagram-project" href="/api-reference/workflows/create-a-work-submission-workflow">
+    Interactive endpoint docs for workflow submission
+  </Card>
+  <Card title="SDK Integration" icon="cube" href="/sdk/gateway">
     Using Gateway from the SDK
   </Card>
   <Card title="Protocol Isolation" icon="shield" href="/protocol/rewards-distributor">
     Why REGISTER_WORK and REGISTER_VALIDATOR exist
   </Card>
-  <Card title="Self-Hosting" icon="server" href="/gateway/deployment">
-    Run your own Gateway
-  </Card>
 </CardGroup>
diff --git a/node_modules/.yarn-integrity b/node_modules/.yarn-integrity
diff --git a/yarn.lock b/yarn.lock
@@ -0,0 +1,4 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,4 @@
		# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
		# yarn lockfile v1