API Endpoints

All endpoints are served from the control plane on port 3001 (HTTP) and 3002 (gRPC). Fabric also provides a GraphQL API at /graphql — see GraphQL API below.

System (Public, No Auth Required)

Method	Path	Description
GET	/healthz	Health check
GET	/readyz	Readiness check
GET	/openapi.json	OpenAPI specification

Auth (see Authentication)

Method	Path	Description
POST	/v1/auth/signup	Sign up with email/password
POST	/v1/auth/login	Log in with email/password
POST	/v1/auth/logout	Log out (revoke current token)
POST	/v1/auth/logout-all	Invalidate all sessions
POST	/v1/auth/token/refresh	Refresh access token (single-use rotation)
POST	/v1/auth/social-login	Consumer-driven social login
GET	/v1/auth/verify	Verify email address
POST	/v1/auth/resend-verification	Resend verification email
POST	/v1/auth/forgot-password	Send password reset email
POST	/v1/auth/reset-password	Reset password with token
POST	/v1/auth/change-password	Change password (requires auth)
GET	/v1/auth/social/{provider}	Initiate server-side social login
GET	/v1/auth/callback	Social login OAuth callback

Identity

Method	Path	Description
GET	/v1/me	Current principal
GET	/v1/me/organizations	My organizations
GET	/v1/me/teams	My teams
GET	/v1/me/permissions	Effective permissions
GET	/v1/me/social-connections	Connected social providers
DELETE	/v1/me/social-connections/{provider}	Disconnect a social provider

Admin: User Management

Method	Path	Description
GET	/v1/admin/users	List all users
GET	/v1/admin/users/{id}	Get user details
DELETE	/v1/admin/users/{id}	Soft-delete a user
POST	/v1/admin/users/{id}/unlock	Unlock locked account
POST	/v1/admin/users/{id}/verify	Force-verify email
POST	/v1/admin/users/{id}/logout-all	Invalidate all sessions for user

Tenancy

Method	Path	Description
POST	/v1/organizations	Create organization
GET	/v1/organizations/{id}	Get organization
GET	/v1/organizations/{id}/teams	List teams
GET	/v1/organizations/{id}/members	List members
POST	/v1/teams	Create team (RBAC enforced)
GET	/v1/teams/{id}	Get team

Invitations (see Invitations & Notifications)

Method	Path	Description
POST	/v1/invitations	Create invitation (Admin+, duplicate/rate-limit guarded)
GET	/v1/invitations	List invitations for org (?organization_id=)
GET	/v1/invitations/{id}	Get invitation by ID
GET	/v1/invitations/{id}/accept	Accept invitation (token verified, creates membership)
POST	/v1/invitations/{id}/revoke	Revoke invitation

Organization Settings

Method	Path	Description
GET	/v1/organizations/{id}/settings	Get org settings (branding, rate limits)
PUT	/v1/organizations/{id}/settings	Update org settings (Owner only)

Authorization

Method	Path	Description
POST	/v1/authz/check	Single permission check
POST	/v1/authz/check-batch	Batch permission check

Jobs

Method	Path	Description
POST	/v1/jobs	Submit a job (with idempotency key, cost estimate)
GET	/v1/jobs/{id}	Get job by canonical job_id
GET	/v1/jobs	List jobs
GET	/v1/jobs/{id}/usage	Job cost/usage roll-up
GET	/v1/jobs/{id}/events	Per-job event stream (SSE)

Workflows

Method	Path	Description
POST	/v1/workflow-definitions	Create definition (supports NodeDefinition schema)
GET	/v1/workflow-definitions	List definitions
POST	/v1/workflow-runs	Create run (with idempotency key)
GET	/v1/workflow-runs/{id}	Get run status
POST	/v1/workflow-runs/{id}/start	Start execution
POST	/v1/workflow-runs/{id}/cancel	Cancel run
GET	/v1/workflow-runs/{id}/events	Per-run event stream (SSE)

Request body formats

POST /v1/workflows/runs accepts request bodies in JSON, YAML, or TOML, selected by the Content-Type header (plan 077). JSON is the default when the header is missing or unrecognised, so existing clients are unaffected.

Header	Parser
application/json (default)	serde_json
application/yaml / text/yaml / application/x-yaml	serde_yaml_ng
application/toml / text/toml / application/x-toml	toml

Response bodies remain JSON. See the Submitting Jobs guide for usage examples.

Providers

Method	Path	Description
GET	/v1/providers	List available providers and capabilities
POST	/v1/providers/execute	Execute a provider request
POST	/v1/providers/execute/stream	Execute with SSE token streaming
POST	/v1/providers/estimate	Cost estimation

API Keys

Method	Path	Description
POST	/v1/api-keys	Create key (returns raw key once)
GET	/v1/api-keys	List keys
GET	/v1/api-keys/{id}	Get key metadata
DELETE	/v1/api-keys/{id}	Revoke key
POST	/v1/api-keys/{id}/disable	Disable key

Assets

Method	Path	Description
POST	/v1/assets	Upload asset
GET	/v1/assets/{id}	Download asset

Usage & Cost

Method	Path	Description
GET	/v1/organizations/{id}/usage	Usage summary with breakdowns
GET	/v1/organizations/{id}/usage/records	Detailed usage records

Audit

Method	Path	Description
GET	/v1/organizations/{id}/audit-logs	Org audit trail
GET	/v1/audit-logs	Global audit logs

Events

Method	Path	Description
GET	/v1/events/stream	All events (SSE)
GET	/v1/events/ws	All events (WebSocket)
GET	/v1/jobs/{id}/events	Per-job events (SSE)
GET	/v1/workflow-runs/{id}/events	Per-run events (SSE)

GraphQL API

Fabric provides a full GraphQL API alongside REST, enabled with --features graphql. All GraphQL operations enforce the same authentication, RBAC, ACL, rate limiting, and audit logging as the REST API.

Method	Path	Description
POST	/graphql	Query and mutation endpoint
GET	/graphql	GraphiQL playground (dev mode only)
GET	/graphql/sdl	SDL schema export (dev mode only)
GET	/graphql/ws	WebSocket subscriptions (graphql-ws protocol)

Queries

Query	Description
organization(id)	Get organization by ID
organizations(first, after)	List organizations (paginated)
team(id)	Get team by ID
teams(orgId, first, after)	List teams in an organization
me	Current authenticated principal
myOrganizations	Organizations the caller belongs to
myTeams	Teams accessible to the caller
myPermissions	Effective permissions (highest role per scope)
apiKey(id)	Get API key metadata
apiKeys(orgId, first)	List API keys for an organization
workflows(orgId, first)	List registered workflows
workflow(name, orgId)	Resolve workflow by name
workflowRun(id)	Get workflow run status
workflowRuns(orgId, first)	List workflow runs
waitingRuns(orgId, first)	List runs waiting for signals
asset(id)	Get asset metadata
assets(orgId, first)	List assets
assetDownloadUrl(id, ttlSeconds)	Generate signed download URL
webhook(id)	Get webhook
webhooks(orgId, first)	List webhooks
webhookDeliveries(webhookId, first)	List delivery attempts

Mutations

Mutation	Description
createOrganization(name, slug)	Create organization (caller becomes Owner)
updateOrganization(id, name)	Update organization name
archiveOrganization(id)	Archive organization (soft-delete)
createTeam(orgId, name, slug)	Create team within organization
disableApiKey(id)	Disable an API key
deleteApiKey(id)	Permanently delete an API key
submitWorkflowRun(name, orgId, input)	Submit a workflow run
cancelWorkflowRun(id, reason)	Cancel a running workflow
pauseWorkflowRun(id, reason)	Pause a workflow
resumeWorkflowRun(id)	Resume a paused workflow
signalWorkflowRun(id, signalName, payload)	Send signal to a waiting workflow
approveWorkflowRun(id, approved, reason)	Approve or reject a waiting workflow
createWebhook(input)	Create webhook subscription
deleteWebhook(id)	Delete webhook

Subscriptions (WebSocket)

Subscription	Description
events(orgId)	All events for an organization
workflowRunEvents(runId)	Events for a specific workflow run

Security

The GraphQL API enforces all the same security controls as REST:

• Authentication: JWT or API key via Authorization header
• RBAC + ACL: Every resolver checks evaluate_with_acls() (3-layer: deny ACL > allow ACL > role hierarchy)
• API key scopes: Validated per-resolver when using API key auth
• Rate limiting: Same per-tenant + per-org limits as REST
• Depth limit: Max 10 levels of nesting
• Complexity limit: Max cost 200 (list fields multiply by page size)
• Pagination: All list fields require first (max 100)
• Query timeout: 30 seconds
• Batch rejection: Array-batched requests ([{query:...}]) are rejected
• CSRF: Rejects non-JSON Content-Type
• Introspection: Disabled in production
• Audit: All mutations logged with transport: "graphql"

Example Query

{
  me {
    principalId
    authenticated
  }
  organizations(first: 10) {
    id
    name
    slug
    teams(first: 5) {
      id
      name
    }
  }
}

Example Mutation

mutation {
  createOrganization(name: "Acme Corp") {
    id
    name
    slug
    createdAt
  }
}

GraphQL Response Format

GraphQL uses its own response format (not the REST envelope):

{
  "data": { ... },
  "errors": null,
  "extensions": {
    "requestId": "uuid"
  }
}

Response Envelope

Every response follows the standard envelope format:

{
  "meta": {
    "request_id": "uuid",
    "trace_id": "uuid",
    "timestamp": "2026-03-19T12:00:00Z",
    "status": 200,
    "version": "1.0"
  },
  "context": {
    "principal_id": "uuid",
    "organization_id": "uuid",
    "team_id": null
  },
  "data": { ... },
  "error": null,
  "links": { ... }
}

Error responses:

{
  "meta": { "status": 403, ... },
  "data": null,
  "error": {
    "code": "forbidden",
    "message": "Insufficient permissions"
  }
}