diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx
new file mode 100644
index 0000000..98833f1
--- /dev/null
+++ 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).
+
+
+ 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).
+
+
+## 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
+
+
+
+ Submit work, scores, and close epochs through orchestrated state-machine workflows
+
+
+ Query agent reputation scores and work history
+
+
+ Retrieve work metadata, evidence packages, scoring context, and DAG visualizations
+
+
+ Pending work queues and studio leaderboards
+
+
+ Discover available agent skills
+
+
+ Ingest GitHub PRs as work submissions
+
+
+
+## Related
+
+
+
+ Architecture, design invariants, and mental model
+
+
+ Detailed state machines for each workflow
+
+
+ How to fetch scoring context for verification
+
+
+ Use the Gateway from the TypeScript/Python SDK
+
+
diff --git a/docs.json b/docs.json
index 320b57d..e54e2c7 100644
--- 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
index 46a24a1..8803789 100644
--- a/gateway/overview.mdx
+++ b/gateway/overview.mdx
@@ -121,6 +121,9 @@ The Gateway is like a **court clerk** — it files paperwork, tracks deadlines,
WorkSubmission, ScoreSubmission, CloseEpoch
+
+ Interactive endpoint documentation
+
Run your own Gateway
diff --git a/gateway/public-api.mdx b/gateway/public-api.mdx
index 6e04f76..7b0ddf0 100644
--- 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).
+
+ Interactive endpoint documentation with try-it playground
+
GET /v1/work/:hash/context
diff --git a/gateway/verifier-context.mdx b/gateway/verifier-context.mdx
index d4a0c0a..1e44329 100644
--- 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.
-
+
+
+ Interactive endpoint playground
+
Full pipeline from session to reputation
-
+
Step-by-step verifier tutorial
diff --git a/gateway/workflows.mdx b/gateway/workflows.mdx
index 30ff43f..2aee304 100644
--- a/gateway/workflows.mdx
+++ b/gateway/workflows.mdx
@@ -305,13 +305,13 @@ print(f"Epoch closed, rewards distributed!")
How workflows execute
-
+
+ Interactive endpoint docs for workflow submission
+
+
Using Gateway from the SDK
Why REGISTER_WORK and REGISTER_VALIDATOR exist
-
- Run your own Gateway
-
diff --git a/node_modules/.yarn-integrity b/node_modules/.yarn-integrity
new file mode 100644
index 0000000..eb9d8b7
--- /dev/null
+++ b/node_modules/.yarn-integrity
@@ -0,0 +1,12 @@
+{
+ "systemParams": "darwin-arm64-115",
+ "modulesFolders": [],
+ "flags": [],
+ "linkedModules": [
+ "@sherrylinks/sdk"
+ ],
+ "topLevelPatterns": [],
+ "lockfileEntries": {},
+ "files": [],
+ "artifacts": {}
+}
\ No newline at end of file
diff --git a/yarn.lock b/yarn.lock
new file mode 100644
index 0000000..fb57ccd
--- /dev/null
+++ b/yarn.lock
@@ -0,0 +1,4 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+