API overview

Scopingly is built on a microservices backend fronted by a single API gateway. All external requests route through it, so integrations target one base URL and inherit the same authentication and access control as the app.

Base URL & gateway

In production the gateway is served at https://api.scopingly.io, and all REST endpoints live under the /api prefix (for example https://api.scopingly.io/api/requirements).

Interactive reference

The gateway serves a live, always-current API reference:

• Swagger UI: /docs on the gateway host
• OpenAPI spec: /openapi.json

The OpenAPI document is generated from the gateway's own route definitions, so it always matches the deployed API. Use it to explore request/response shapes and to generate a client.

Authentication

Requests authenticate the same way the app does — a verified session (JWT-backed). Every request is org-scoped: you only ever see and act on data in your own organization, and resource permissions (owner / editor / viewer, team owner, org admin) are enforced on every read and write. There is no way to reach another organization's data.

Write requests from a browser context are CSRF-protected, and all endpoints are rate-limited.

REST and GraphQL

• REST is the primary surface and covers everything — reads, writes, generation jobs, and streams.
• A read-only GraphQL endpoint (POST /api/graphql) offers a few aggregated read models (prdWorkspace, scopeWorkspace, epicBoard) for efficient dashboard-style fetches. All writes stay on REST.

Real-time

• Server-Sent Events (SSE) stream live updates (notifications, long-running generation progress).
• WebSocket powers real-time PRD co-editing, served at wss://api.scopingly.io/collab/<document>.

Stability

The /api surface is versioned through the gateway. When a route's method, auth, request, or response changes, the reference and OpenAPI spec are updated in the same change — so the interactive docs above are the authoritative, up-to-date contract.