API reference

Forginate exposes a REST API on the product host. The SPA is itself a client of this API, so everything the UI can do has an HTTP endpoint behind it.

Evolving, unversioned API

The API is unversioned and evolving. Endpoints listed here reflect the current implementation and may change without notice. Treat this page as an honest survey, not a contract.

Base URL

All endpoints are served under /api/ on the product host:

https://dev.forginate.com/api/...

Tenant resources follow the convention:

/api/orgs/:orgSlug/<resource>...

where :orgSlug is your organization's slug (e.g. acme-corp). Every request is authorized against your membership and role in that organization.

Authentication

Two mechanisms are accepted:

Session cookie (browser)

Logging in through the web UI sets a JWT session cookie named forginate_session. The SPA uses this transparently; it is not intended for programmatic clients.

Personal access tokens (programmatic)

Create a token under your account settings (or via POST /api/me/tokens). Tokens look like fgn_pat_<random>; the plaintext secret is shown once at creation and stored hashed server-side. Send it as a bearer token:

curl -H "Authorization: Bearer fgn_pat_..." \
  https://dev.forginate.com/api/orgs/acme-corp/projects

Token properties:

• Scopes: read, write, admin. Managing tokens themselves requires a session or an admin-scoped PAT (a read PAT cannot mint new tokens).
• Optional org binding — a token can be limited to one organization.
• Optional expiry — up to 365 days; omitted means no expiry.
• Revocable at any time; creation and revocation are audit-logged and rate-limited.

Token management endpoints:

Method	Path	Purpose
GET	/api/me/tokens	List your tokens (metadata only)
POST	/api/me/tokens	Create a token; returns the secret once
DELETE	/api/me/tokens/:id	Revoke a token

Resource groups

The representative endpoints below are taken from the gateway's route implementations. This is not exhaustive — the pipeline surface in particular has many more action endpoints.

Projects & teams

Method	Path	Purpose
GET	/api/orgs/:orgSlug/projects	List projects
POST	/api/orgs/:orgSlug/projects	Create a project
GET	/api/orgs/:orgSlug/projects/:projectSlug	Project detail
PATCH	/api/orgs/:orgSlug/projects/:projectSlug	Update a project
GET / POST	/api/orgs/:orgSlug/projects/:projectSlug/team	Project team & invites
GET / POST	/api/orgs/:orgSlug/members	Org members & invites
POST	/api/orgs/:orgSlug/transfer-ownership	Transfer org ownership

Requests (pipeline)

Improvement/build requests are the unit of pipeline work.

Method	Path	Purpose
GET / POST	/api/orgs/:orgSlug/requests	List / create requests
GET / PATCH	/api/orgs/:orgSlug/requests/:requestId	Request detail / update
GET	/api/orgs/:orgSlug/requests/:requestId/lifecycle	Full pipeline lifecycle view
POST	/api/orgs/:orgSlug/requests/:requestId/advance	Advance the request a stage
POST	/api/orgs/:orgSlug/requests/:requestId/advance-to-build	Move into build
POST	/api/orgs/:orgSlug/requests/:requestId/build-tasks/run-all	Run all build tasks
POST	/api/orgs/:orgSlug/requests/:requestId/build/pause	Pause the build
GET	/api/orgs/:orgSlug/requests/:requestId/build-cost-estimate	Estimated build cost
POST	/api/orgs/:orgSlug/requests/:requestId/integration/approve	Approve merge/integration

Improvement requests (bug reports / feature asks, including auto-filed deployment incidents) live alongside these:

Method	Path	Purpose
GET / POST	/api/orgs/:orgSlug/projects/:projectSlug/improvements	List / file improvements
POST	/api/orgs/:orgSlug/improvements/:id/approve	Approve an improvement for build
POST	/api/orgs/:orgSlug/improvements/:id/reject	Reject it

Documents

Planning documents (TOC + section docs) with versioning, approval, feedback, and AI editing.

Method	Path	Purpose
GET	/api/orgs/:orgSlug/products/:productId/documents	List a product's documents
GET	/api/orgs/:orgSlug/documents/:docId	Document detail
GET	/api/orgs/:orgSlug/doc-versions/:versionId/content	Version body
POST	/api/orgs/:orgSlug/doc-versions/:versionId/approve	Approve a version
POST	/api/orgs/:orgSlug/doc-versions/:versionId/request-changes	Request changes
POST	/api/orgs/:orgSlug/documents/:docId/edit	Direct edit
POST	/api/orgs/:orgSlug/documents/:docId/regenerate	AI regeneration
POST	/api/orgs/:orgSlug/patches/:patchId/accept	Accept an AI-proposed patch
GET / POST	/api/orgs/:orgSlug/products/:productId/shares	Public share links
POST	/api/orgs/:orgSlug/shares/:shareId/revoke	Revoke a share

Runs

Method	Path	Purpose
GET / POST	/api/orgs/:orgSlug/projects/:projectSlug/runs	List / start runs
GET	/api/orgs/:orgSlug/projects/:projectSlug/runs/:runId	Run status
POST	/api/orgs/:orgSlug/projects/:projectSlug/runs/:runId/cancel	Cancel a run
GET	/api/orgs/:orgSlug/projects/:projectSlug/runs/:runId/events	Live event stream (SSE)
GET	/api/orgs/:orgSlug/runs/:runId/logs	Run logs
GET	/api/orgs/:orgSlug/events	Org-wide event stream (SSE)

Deploy targets & deployments

See Deployment lifecycle for semantics.

Method	Path	Purpose
GET / POST	/api/orgs/:orgSlug/deploy-targets	List / register targets
POST	/api/orgs/:orgSlug/deploy-targets/:id/rotate-key	Rotate an agent enrollment key
DELETE	/api/orgs/:orgSlug/deploy-targets/:id	Remove a target
GET / POST	/api/orgs/:orgSlug/deployments	List / create deployments
GET	/api/orgs/:orgSlug/deployments/:id	Deployment detail (incl. telemetry)
POST	/api/orgs/:orgSlug/deployments/:id/approve	Approve the plan → deploy
POST	/api/orgs/:orgSlug/deployments/:id/replan	Re-run the planner
POST	/api/orgs/:orgSlug/deployments/:id/stop	Stop (scale to zero)
POST	/api/orgs/:orgSlug/deployments/:id/start	Start a stopped app
POST	/api/orgs/:orgSlug/deployments/:id/scale	Scale a workload
POST	/api/orgs/:orgSlug/deployments/:id/teardown	Delete the workload
POST	/api/orgs/:orgSlug/deployments/:id/separate	Hand the workload over to you
POST	/api/orgs/:orgSlug/deployments/:id/request-logs	Ask for fresh logs
GET	/api/orgs/:orgSlug/deployments/:id/metrics	Resource metrics
GET	/api/orgs/:orgSlug/deployments/:id/uptime	Availability history

Billing & usage

Method	Path	Purpose
GET	/api/orgs/:orgSlug/billing	Plan, usage, next invoice
GET	/api/orgs/:orgSlug/billing/plans	Available plans
POST	/api/orgs/:orgSlug/billing/checkout	Stripe Checkout session
POST	/api/orgs/:orgSlug/billing/portal	Stripe customer portal
GET / PUT	/api/orgs/:orgSlug/billing/payment-method	Payment method
GET	/api/orgs/:orgSlug/usage	Usage / cost breakdown

Other groups

• GitHub — /api/orgs/:orgSlug/github/...: GitHub App install flow, repo listing, repo provisioning and linking.
• Providers — /api/orgs/:orgSlug/providers...: bring-your-own LLM provider configs (create, test, set default).
• Attachments — /api/orgs/:orgSlug/attachments...: file uploads bound to requests/docs.
• Audit — GET /api/orgs/:orgSlug/audit: append-only audit log (admin-only).
• Share portal — /api/share/*: public, token-authenticated document review; no login, no org context.
• Admin & internal — /api/admin/* (platform-operator only) and /internal/* (cluster-internal service-to-service, not reachable externally). These are not part of the user-facing surface.

Errors

Errors are JSON bodies with an error code (e.g. deployment_not_found, insufficient_scope, invalid_status) and conventional HTTP status codes (400 validation, 401/403 auth, 404 not found, 409 state conflict, 429 rate limit). Exact shapes are not yet standardized across all routes.