API Reference

Direct REST and WebSocket endpoints for Gao Internet services. Most developers should use @gao/system-sdk instead of calling these endpoints directly.

Base URLs

Service

Base URL

GAR (Agent Runtime)

https://gar.gao.global/v1

Studio API

https://api.studio.gao/v1

Identity

https://id.gao.global/v1

Settlement

https://pay.gao.global/v1

Storage

https://storage.gao.global/v1

Authentication

Authorization: Bearer <token>

Token obtained from Passkey auth flow or Studio API Keys.

Auth Endpoints

Passkey Registration

POST /auth/register/start
Body: { display_name: string }
Response: { options: PublicKeyCredentialCreationOptions }

POST /auth/register/finish
Body: { credential: RegistrationResponseJSON }
Response: { domain: string, token: string, expires_at: number }

---

### Passkey Login

POST /auth/login/start

Body: {}
Response: { options: PublicKeyCredentialRequestOptions }
POST /auth/login/finish
Body: { credential: AuthenticationResponseJSON }
Response: { domain: string, token: string, expires_at: number }

Token Refresh

POST /auth/refresh
Body: { refresh_token: string }
Response: { token: string, expires_at: number }

---

## Capability Endpoints

POST /sdk/capability/issue
Auth: Bearer token
Body: { capability: string, domain: string, ttl_seconds?: number }
Response: { token: string, hash: string, expires_at: number }
POST /sdk/capability/validate
Body: { token_hash: string, required_capability: string }
Response: { valid: boolean, domain: string, capability: string }
POST /sdk/capability/revoke
Auth: Bearer token
Body: { token_id: string }
Response: { revoked: true }

---


Identity Endpoints

GET /identity/resolve/:domain
Response: {
  domain: string,
  owner_address: string,
  public_key: string,
  records: object,
  chain: string,
  updated_at: number
}

GET /identity/address/:domain/:chain
Response: { address: string }

POST /identity/verify-signature
Body: { domain: string, message: string, signature: string }
Response: { valid: boolean }

GET /identity/is-owner/:domain/:address
Response: { is_owner: boolean }

Settlement Endpoints#

POST /settlement/intents
Auth: Bearer token
Body: {
  amount: string,
  currency: "USDC" | "USDT" | "GAO" | "USD",
  recipient: string,
  description?: string,
  idempotency_key: string,
  capability: string
}
Response: PaymentIntent

GET /settlement/intents/:intent_id
Auth: Bearer token
Response: PaymentIntent

POST /settlement/receipts/validate
Auth: Bearer token
Body: { receipt: PaymentReceipt }
Response: { valid: boolean }

GET /settlement/finality/:intent_id
Auth: Bearer token
Response: { status: "pending" | "confirmed" | "failed", hash?: string }

GET /settlement/budget/:domain
Auth: Bearer token
Response: { limit: string, used: string, remaining: string, currency: string }

---

Agent (GAR) Endpoints

POST /gar/agents
Auth: Bearer token
Body: AgentManifest
Response: { agent_id: string, status: "draft" }

GET /gar/agents
Auth: Bearer token
Query: ?domain=myapp.gao&status=active
Response: Agent[]

GET /gar/agents/:agent_id
Auth: Bearer token
Response: Agent

POST /gar/agents/:agent_id/compile
Auth: Bearer token
Response: { valid: boolean, errors?: string[] }

POST /gar/agents/:agent_id/pause
POST /gar/agents/:agent_id/revoke
Auth: Bearer token
Response: { status: string }

---

### Sessions

POST /gar/sessions
Auth: Bearer token
Body: { agent_id: string, intent: string, capability: string }
Response: { session_id: string, state: "initializing" }
GET /gar/sessions/:session_id
Auth: Bearer token
Response: GARSession
GET /gar/sessions/:session_id/stream
Auth: Bearer token

Response: text/event-stream


Events:
  data: {"type":"text","delta":"..."}\n\n
  data: {"type":"tool_use","tool":"...","input":{}}\n\n
  data: {"type":"artifact","artifact_id":"...","type":"..."}\n\n
  data: {"type":"step","step":"Planning complete"}\n\n
  data: {"type":"done","state":"completed"}\n\n
GET /gar/sessions/:session_id/result
Auth: Bearer token
Response: { state: string, artifacts: Artifact[], output: object }

---


Artifacts

GET /artifacts Auth: Bearer token Query: ?domain=myapp.gao&type=report Response: Artifact[]

GET /artifacts/:artifact_id Auth: Bearer token Response: Artifact

GET /artifacts/:artifact_id/download Auth: Bearer token Response: binary (file content)

GET /artifacts/:artifact_id/lineage
Auth: Bearer token
Response: { parents: string[], sessions: string[] }

Storage (DePIN)#

POST /storage/upload
Auth: Bearer token
Headers: Content-Type: application/octet-stream
         X-Encrypted: true
         X-Redundancy: 3
         X-TTL-Days: 30

Body: binary
Response: { cid: string, size: number, receipt: StorageReceipt }
GET /storage/:cid
Auth: Bearer token (if private)
Response: binary
DELETE /storage/:cid
Auth: Bearer token
Response: { deleted: true }
POST /storage/pin/:cid
Auth: Bearer token
Response: { pinned: true }

---

Transport (Messaging)

POST /transport/messages
Auth: Bearer token
Body: { to: string, content: string, type?: string, encrypted?: boolean }
Response: { message_id: string, delivered: boolean }

WebSocket: wss://relay.meshii.app/collab?token=`<jwt>`


Events (server → client):
  { type: "message", from: string, content: string, timestamp: number }
  { type: "ack", message_id: string }
  { type: "ping" }


---

## Scheduler

POST /scheduler/jobs
Auth: Bearer token
Body: SchedulerJob
Response: { job_id: string, status: "active" }

GET /scheduler/jobs Auth: Bearer token Query: ?domain=myapp.gao&status=active Response: SchedulerJob[]

GET /scheduler/jobs/:job_id/runs
Auth: Bearer token
Response: { runs: [{ run_id, started_at, state, session_id }] }

POST /scheduler/jobs/:job_id/pause
POST /scheduler/jobs/:job_id/resume
POST /scheduler/jobs/:job_id/run
DELETE /scheduler/jobs/:job_id
Auth: Bearer token
Response: { status: string }

POST /scheduler/webhook/:job_id
Auth: HMAC-SHA256 signature (X-Gao-Signature header)
Body: any (passed as trigger payload to agent)
Response: { triggered: true, session_id: string }

Audit

GET /audit/:domain
Auth: Bearer token
Query: ?limit=50&since=2026-01-01T00:00:00Z&event_type=action_executed
Response: AuditEvent[]
WebSocket: wss://api.studio.gao/v1/audit/stream?domain=myapp.gao&token=`<jwt>`
Events: AuditEvent (real-time stream)

---

## Connectors

GET /connectors Auth: Bearer token Response: Connector[]

POST /connectors/:connector_id/auth
Auth: Bearer token
Body: { redirect_uri?: string }
Response: { auth_url: string }  (for OAuth) or { authenticated: true }

POST /connectors/:connector_id/execute
Auth: Bearer token
Body: { action: string, payload: object, capability: string }
Response: ConnectorResult

Common Response Schemas

AuditEvent

{
  event_id:    string,
  domain:      string,
  event_type:  string,
  actor:       { type: "user" | "agent" | "system", id: string },
  session_id?: string,
  artifact_id?: string,
  timestamp:   string,
  outcome:     "success" | "failure" | "blocked" | "pending",
  detail:      object,
  immutable:   true
}

Artifact

{
  artifact_id:    string,
  owner_domain:   string,
  artifact_type:  string,
  content_hash:   string,
  version:        number,
  storage_ref:    string,
  taint_state:    "clean" | "tainted",
  status:         "active" | "archived" | "promoted",
  created_at:     string,
  lineage:        { parent_artifact_ids: string[] }
}

GARSession

{
  session_id:  string,
  domain:      string,
  agent_id:    string,
  state:       "initializing" | "planning" | "policy_check" | "executing" | "completed" | "failed",
  created_at:  string,
  updated_at:  string,
  context:     object
}


---

## Rate Limits

Endpoint Group

Free

Pro

Enterprise

Auth

10 req/min

60 req/min

Unlimited

Identity (read)

100 req/min

1000 req/min

Unlimited

Settlement

20 req/min

200 req/min

Custom

Agent runs

10/day

500/day

Custom

Storage upload

100 MB/day

10 GB/day

Custom

Messaging

100 msg/day

10,000/day

Custom

---

## Next Steps

-   SDK Guide — use `@gao/system-sdk` instead of direct API calls
    
-   Example Apps — complete working code
    

---