Surya / API
Documentation

REST API

To integrate Surya into your workflow. OAuth 2.0 auth, OpenAPI spec, rate limits per workspace.

Authentication

Bearer token for machine-to-machine calls, OAuth 2.0 Authorization Code for user-context calls.

Authorization: Bearer sk_live_xxxx

Base URL

https://api.suryatool.io

Rate limits

Default: 600 requests / minute / workspace. Burst: 60 / second. Headers: X-RateLimit-Remaining, X-RateLimit-Reset.

Key endpoints

  • GET /api/clients — list clients in the workspace
  • GET /api/clients/:id/metrics — aggregated MTD metrics
  • GET /api/change-proposals?status=pending — pending proposals
  • POST /api/change-proposals/:id/approve — approve a proposal
  • GET /api/reports/:id — monthly report
  • POST /api/agents/:role/run — run an agent on demand

OpenAPI spec

Full spec: openapi.json. Generated from the router, always up to date.

Webhooks

Subscribe to: proposal.created, proposal.approved, proposal.executed, report.published, alert.triggered. HMAC-SHA256 signature in X-Surya-Signature header.