Skip to main content

REST API & OpenAPI Reference

NodeStack dynamically generates an OpenAPI 3.0 specification and serves interactive documentation explorers.


Interactive Documentation Viewers​

When your NodeStack instance is running, navigate to:

http://localhost:8090/_/docs

By default, NodeStack renders Scalar, a modern, responsive API reference viewer with:

  • Live API request playground (Try It Out).
  • Code snippet generators in TypeScript, cURL, Python, Go, and PHP.
  • Dark / Light mode toggle.

To view with Swagger UI, append ?ui=swagger:

http://localhost:8090/_/docs?ui=swagger

OpenAPI 3.0 JSON Specification​

Download the complete JSON schema spec for tools like Postman, Insomnia, or custom code generators:

GET /api/openapi.json
GET /_/openapi.json

Core REST Endpoints Summary​

Collection Records​

MethodEndpointDescription
GET/api/collections/:collection/recordsQuery, filter, sort, and paginate records.
POST/api/collections/:collection/recordsInsert a new record (JSON or multipart).
GET/api/collections/:collection/records/:idRetrieve single record by ID.
PATCH/api/collections/:collection/records/:idUpdate record fields.
DELETE/api/collections/:collection/records/:idDelete record.

Authentication & OAuth2​

MethodEndpointDescription
POST/api/collections/:collection/auth-with-passwordAuthenticate user with identity & password.
GET/api/collections/:collection/auth-methodsList active OAuth2 providers with PKCE challenge and auth URLs.
POST/api/collections/:collection/auth-with-oauth2Exchange OAuth2 code and PKCE codeVerifier for session JWT.
GET/api/collections/:collection/records/:id/external-authsList linked social identities for an authenticated user.
DELETE/api/collections/:collection/records/:id/external-auths/:providerUnlink an external social identity.
POST/api/collections/users/request-password-resetSend password reset email.
POST/api/collections/users/confirm-password-resetComplete password reset with token.
POST/api/collections/users/auth-refreshRefresh an active JWT session.

API Keys & Machine-to-Machine (M2M) Tokens (Superuser)​

MethodEndpointDescription
GET/api/api-keysList all API keys with redacted tokens and usage stats.
POST/api/api-keysGenerate a new scoped API key.
GET/api/api-keys/:idRetrieve metadata for a single API key.
PATCH/api/api-keys/:idUpdate key name, scopes, IP allowlist, or expiration.
DELETE/api/api-keys/:idRevoke and delete an API key.
POST/api/api-keys/:id/rotateRotate secret key entropy.

Realtime & Files​

MethodEndpointDescription
GET/api/realtimeOpen Server-Sent Events (SSE) stream.
POST/api/realtimeSubmit topic subscriptions.
GET/api/files/:collection/:recordId/:filenameStream uploaded binary file.

Webhooks​

MethodEndpointDescription
GET/api/webhooksList registered webhooks.
POST/api/webhooksRegister a new webhook endpoint.
POST/api/webhooks/:id/testDispatch a test payload.
GET/api/webhooks/:id/deliveriesRetrieve delivery logs.
POST/api/webhooks/deliveries/:deliveryId/retryRetry failed delivery.

Serverless Functions​

MethodEndpointDescription
GET/api/functionsList all registered serverless functions (Superuser).
GET/api/functions/statsRetrieve aggregate metrics: total functions, active count, executions, success rate.
POST/api/functionsCreate a new serverless function (name, code, authPolicy, timeoutMs, etc.) (Superuser).
GET/api/functions/:idOrNameRetrieve details, configuration, and source code for a function.
PATCH/api/functions/:idUpdate code, metadata, lifecycle hook triggers, limits, or env secrets (Superuser).
DELETE/api/functions/:idDelete a serverless function and execution logs. Returns 409 Conflict if referenced by active flows unless ?force=true is passed (Superuser).
ANY/api/functions/:name/invokeInvoke a serverless function via HTTP (GET, POST, PUT, PATCH, DELETE).
POST/api/functions/:id/testLive test runner: execute function isolated in sandbox and inspect output (Superuser).
GET/api/functions/logsQuery paginated execution logs across all functions with status filter.
GET/api/functions/:id/logsQuery execution logs for a specific function.
DELETE/api/functions/logsClear execution history logs (Superuser).
ANY/api/apps/:appId/functions/:name/invokeInvoke a serverless function scoped to a specific tenant application.

Function Flows & State Machines​

MethodEndpointDescription
GET/api/flowsList all registered state machine flows (Superuser).
POST/api/flowsCreate a new flow (name, triggerType, eventTrigger, definition) (Superuser).
GET/api/flows/:idRetrieve flow details, triggers, and JSON state machine definition (Superuser).
PATCH/api/flows/:idUpdate flow metadata, triggers, enabled state, or definition (Superuser).
DELETE/api/flows/:idDelete a flow and its execution history (Superuser).
POST/api/flows/:id/executeExecute a flow with an input payload (:id can be flow ID or unique name).
GET/api/flows/executionsList recent executions across all flows with optional status filter (Superuser).
GET/api/flows/:id/executionsQuery execution history and step-level metrics for a specific flow (Superuser).
GET/api/flows/executions/:executionIdInspect complete details and step logs for an individual execution (Superuser).
DELETE/api/flows/:id/executionsClear execution history records for a specific flow (Superuser).
Any/api/apps/:appId/flows/*Access flow management and execution endpoints scoped to a tenant application.

Queues & Background Workers​

MethodEndpointDescription
GET/api/queuesList all registered queues with concurrency, lease timeouts, and strict order settings (Superuser).
POST/api/queuesCreate or update a queue configuration (name, concurrency, visibilityTimeoutSeconds, maxAttempts, targetFunction, strictOrder) (Superuser).
GET/api/queues/:nameRetrieve configuration and metadata for a specific queue (Superuser).
DELETE/api/queues/:nameDelete a queue and purge its messages (Superuser).
GET/api/queues/statsRetrieve aggregate queue metrics: queued, processing, completed, failed, and dead-letter counts.
GET/api/queues/messagesQuery paginated messages across all queues with status and queue filters (Superuser).
GET/api/queues/messages/:idRetrieve detailed payload, status, attempts, and execution logs for a message.
POST/api/queues/:name/messagesPublish / enqueue a new message (payload, groupKey, delaySeconds, priority, maxAttempts).
GET/api/queues/:name/messagesList paginated messages for a specific queue.
POST/api/queues/:name/messages/:id/ackAcknowledge job completion (result, claimToken).
POST/api/queues/:name/messages/:id/nackMark job failure to schedule retry or dead-letter (error, claimToken).
POST/api/queues/:name/messages/:id/touchExtend lease visibility timeout heartbeat for an active worker (claimToken).
POST/api/queues/:name/messages/:id/skipForce-skip a failed or blocking message in a strict FIFO partition.
POST/api/queues/:name/messages/:id/retryManually retry a failed or dead-letter message.
POST/api/queues/:name/dlq/retryRe-drive all dead-letter messages back into the active queue.
DELETE/api/queues/:name/messages/:idDelete a specific queue message.
DELETE/api/queues/:name/purgePurge all messages from a queue (Superuser).
Any/api/apps/:appId/queues/*Route any queue operation to a specific application tenant.

Applications & Multi-Tenancy​

MethodEndpointDescription
GET/api/appsList all applications (Superuser).
POST/api/appsCreate a new application with optional template (Superuser).
GET/api/apps/:idGet details for an application by ID or slug (Superuser).
PATCH/api/apps/:idUpdate application name or metadata (Superuser).
DELETE/api/apps/:idDelete an application, its database, and files (default app is protected) (Superuser).
Any/api/apps/:appId/*Route any collection, auth, file, or search request to a specific application tenant.

[!TIP] Clients can also route requests to any application without changing URLs by passing the x-nodestack-app: <appId-or-slug> HTTP header. See the Multi-Application Platform Guide.

Application Snapshots​

MethodEndpointDescription
GET/api/snapshotsList all snapshots, capacity status, and schema drift (Superuser).
POST/api/snapshotsCreate an atomic state snapshot checkpoint ({ label, description, evictOldest }) (Superuser).
GET/api/snapshots/:idGet details and metadata for a specific snapshot (Superuser).
POST/api/snapshots/:id/restoreNon-destructively restore application state to this checkpoint (Superuser).
DELETE/api/snapshots/:idDelete a snapshot checkpoint (Superuser).
POST/api/snapshots/clearDelete all snapshots for the active application (Superuser).
GET/api/snapshots/statusRetrieve snapshot count, 10-snapshot limit, and capacity warnings (Superuser).
Any/api/apps/:appId/snapshots/*Route any snapshot operation to a specific application tenant.

Database Engine & Management (v2.5.0)​

MethodEndpointDescription
GET/api/system/database/statusRetrieve active database engine, connection health, and latency (Superuser).
GET/api/system/database/migration-progressCheck real-time progress for active database migration and cutover (Superuser).
POST/api/system/database/testTest connectivity to a target SQLite, PostgreSQL, or MSSQL database (Superuser).
POST/api/system/database/switchSwitch active database engine with optional live schema and data migration (Superuser).