API reference

Base URL and response format

Every route is served under the /api prefix. Locally the base URL is http://localhost:8000/api. On a server it is your API's address followed by /api, the same value the website and the dashboard read from NEXT_PUBLIC_API_BASE_URL (Environment variables). Files are served outside the prefix: the kit's brand files at /media/… and uploads at /media/uploads/….

Request bodies are JSON, except file uploads. Every answer comes in the same envelope:

{
  "success": true,
  "data": { },
  "message": ""
}

data holds the result. message is a short code some writes fill in, such as project_created or invitation_sent, and is empty otherwise. Workspaces, projects and tasks are named by their public ids (org_forma, prj_01); members, invitations, keys and files by their number. Project and task texts carry both languages as { "en": { … }, "ar": { … } }.

The health check needs no token:

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

Until the database answers and holds its tables, it answers 503 with "status":"unavailable" and "database":"down". The Docker image's health check reads that status, and Docker Compose starts the website and the dashboard only once it passes.

Browsers may call the API only from the addresses in CORS_ORIGIN. Left unset it allows http://localhost:3030 and http://localhost:3031, and in production the API refuses to start without it (CORS problems).

Errors

A failure keeps the envelope, with success: false, data: null and the HTTP status:

{
  "success": false,
  "data": null,
  "message": "seat_limit_reached",
  "errors": { "email": ["…"] }
}

• errors appears on a validation failure (400), with the problems per field.
• An unknown field in a body is refused with 400: every body takes only the fields listed below.
• When the API has a sentence for the error, message is that sentence in the request's language (Accept-Language: ar for Arabic): a refused sign-in, every 429, closed sign-ups, an account guarded from a password or email change, a missing webhook secret, a subscription Stripe could not cancel, a platform role or permission the caller does not hold, and maintenance mode among them.
• Otherwise, on 401, 403 and 404 message is a general sentence for the status, and on 400, 402, 409, 410 and 503 it is the reason as a short code (seat_limit_reached, slug_taken, over_plan_limit, payment_declined, preview_expired, invitation_expired, payment_unavailable), which a client turns into its own sentence. A downgrade refused for usage also carries blockers.
• 402 means a plan upgrade the payment provider would not charge: payment_declined, payment_needs_action (the bank wants the payment confirmed) or payment_method_missing. The plan stays as it was.
• While platform staff have maintenance mode on, every route outside the short list in Maintenance mode answers 503 to anyone who is not platform staff, with the sentence in message and code: "maintenance_mode".
• 401 means no token, an expired one, or wrong credentials. 403 means signed in without the permission, or a write to a suspended workspace. 404 also answers for a workspace the caller is not a member of, so a stranger cannot tell which workspaces exist.
• A request over a limit answers 429 (Limits per address).

Signing in

1. 01

   Sign in

   TerminalCopy

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"owner@northstack.example","password":"YOUR_PASSWORD"}'

   Put the seeded password from Installation in place of YOUR_PASSWORD, or use an account of your own. data.access_token is the token, with token_type Bearer, expires_in, and admin, the account with its platform roles, permissions and workspaces.
2. 02

   Call a protected route

   TerminalCopy

   curl http://localhost:8000/api/workspaces \
     -H "Authorization: Bearer YOUR_TOKEN"

   That lists the account's workspaces with its role in each. Every workspace route then takes the workspace's public id in its path:

   TerminalCopy

   curl "http://localhost:8000/api/workspaces/org_forma/projects?limit=20" \
     -H "Authorization: Bearer YOUR_TOKEN"

• remember: true signs a token for 30 days and remember: false one for 12 hours; left out, the token lasts JWT_EXPIRATION, 7d by default.
• An unknown email and a wrong password both answer 401 with the same message, after the same password-hashing work, so neither the answer nor its timing tells which emails have accounts.
• Ten failed sign-ins from one address within 15 minutes answer 429 until the oldest failure is 15 minutes old (RATE_LIMIT_LOGIN). Successful sign-ins are not counted.
• Tokens are stateless: POST /api/auth/logout answers at once, and signing out is the client forgetting its token.

Workspaces and permissions

• Workspace routes start with /api/workspaces/:workspaceId, the workspace's public id. On every request the API checks that the caller has an active membership there (otherwise 404) and holds the permission the route names (otherwise 403). The role is the membership's: one person can be the owner of one workspace and an admin of another.
• A workspace holds four roles (owner, admin, member, billing) and its own matrix of 14 permissions: workspace.read, workspace.update, workspace.delete, projects.read, projects.write, members.invite, members.remove, roles.manage, billing.read, billing.manage, keys.manage, audit.read, ai.read and ai.apply. The owner holds them all, and workspace.delete and roles.manage stay with the owner whatever the matrix says. A change to the matrix applies to the next request.
• A suspended workspace keeps every GET and refuses every other method with 403.
• A past-due workspace keeps everything until BILLING_GRACE_DAYS (7 by default) have passed; then it cannot create projects, invitations or API keys (403), while every read and every other write keeps working.
• Platform routes (/api/platform, /api/users, /api/admins, /api/roles, /api/settings) check the account's platform permissions instead, granted through platform roles. The seed creates Platform admin, with all 21, and Support, which reads every platform page and exports reports. A route that lists several permissions accepts any one of them.

• Team, roles and permissions
• Platform administration

Lists and paging

{ "data": [ ], "total": 12, "page": 1, "limit": 7, "totalPages": 2 }

• Projects, archived projects, activity, chat conversations and their messages, and the platform's organizations and users page with page and limit, at most 100 a page. The defaults are 7 projects, 12 events, 20 conversations and 10 organizations or users.
• Staff, platform settings and platform roles page with page and page_count instead (10 by default, at most 100). Platform roles page only when both are given; otherwise every role is returned.
• Lists come newest first (projects, users and organizations by their last change), with the id as a tiebreaker, unless a sort is given; platform roles come by name. The projects list also returns counts per tab.
• What belongs to one workspace and is shown whole answers without paging: a board's tasks, members, invitations, API keys, a project's files, the latest 36 invoices and the latest 8 notifications.

Workspaces, members and the roles matrix

Invitations

Invitation emails go through the API's SMTP settings, or into its log while SMTP_HOST is empty, link included.

Projects and files

Creating a project in a past-due workspace whose grace period has ended answers 403.

Tasks and the board

A task is listed and created under its project, and changed by its own id under the workspace.

An assignee who is not a member answers 400 with assignee_not_member. Every change writes an event to the activity trail, such as task.moved with the columns it went from and to.

Overview, activity, notifications and search

The overview's latest events and the bell show the whole trail to a caller with projects.read or audit.read, only the billing. events to one with billing.read and neither of those, and nothing to anyone else.

Billing, its webhook and the test checkout

• Checkout uses Stripe Checkout when STRIPE_SECRET_KEY is set, and the built-in test checkout otherwise, or whenever BILLING_PROVIDER=simulator. The test checkout charges nobody.
• The return address alone never changes a plan: only the signed webhook, or the session read back on sync, does.
• Each plan's Stripe price is created on first use, with the lookup key northstack_<plan>_usd_<cents>_month, so nothing is set up in Stripe first.
• A completed Stripe checkout for a workspace that already has a Stripe subscription cancels the old one, with its unused time credited. invoice.paid stores Stripe's invoice once (invoices are unique per provider invoice id), with its amount and period, moves the workspace's period to the one an invoice starts, and on a renewal applies a downgrade scheduled for it.
• On the test checkout the API renews each period at its end (a paid invoice, the next 30 days, a scheduled downgrade applied) and ends one set to cancel. A trial that reaches its end becomes past due, with the grace period. Usage counters start again at zero each period. This runs on every billing read and once an hour.
• Point your Stripe webhook at https://<your API>/api/billing/webhooks/stripe with the events above plus checkout.session.expired.

• Billing
• Payment settings

API keys and the public API

curl http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer nst_live_…"

• A production key's secret starts with nst_live_, a demo key's with nst_demo_. A demo key works only while the API runs in demo mode.
• No key, an unknown or revoked one answers 401; a key without the route's scope answers 403; a suspended workspace refuses the write.
• Every route but the project list runs as the key's creator: what it creates is recorded as made by them, with the dashboard's validation, activity events and plan limits. It answers 404 once the creator has left the workspace, and the three writes answer 403 once the creator's role no longer holds projects.write.
• Every call counts toward the plan's API requests, which the billing page and the plan limits read.

• API keys

Platform overview and organizations

Users, staff, platform roles and settings

The guard on passwords and emails: a caller other than the account itself may set its password or change its email only when they are a Platform admin or hold every platform permission the account holds; otherwise the API answers 403. The email is guarded too, because a password reset is sent to it.

The guard on roles: nobody can grant, remove or raise a platform role beyond their own permissions, so admins.assign_roles or roles.assign_permissions alone never leads to the Platform admin role.

The 21 platform permissions are platform.view, reports.export, organizations.view, organizations.manage, users.view, users.create, users.update, users.delete, users.restore, admins.view, admins.create, admins.edit, admins.delete, admins.assign_roles, roles.view, roles.create, roles.edit, roles.delete, roles.assign_permissions, settings.view and settings.edit.

Public settings and maintenance mode

While the platform setting maintenance_mode is true, every request from anyone who is not platform staff (an account holding platform.view) answers 503, with code: "maintenance_mode" and the message "The platform is closed for maintenance. Please try again shortly." A missing or wrong token gets the same 503. These stay open to everyone:

• GET /api/health and GET /api/public-settings;
• POST /api/auth/login and POST /api/auth/logout, where sign-in still refuses anyone who is not staff with the 503 once the credentials are right;
• POST /api/billing/webhooks/stripe and the signed invoice download;
• the MCP endpoint, which keeps its own key, and GET /api/demo/status;
• the website's POST /api/contact and every /api/licenses route, so the contact form and the licence checkout keep working.

Everything else is closed to non-staff, sign-up, password recovery, invitations, onboarding, the public API under /api/v1, uploads and the assistant included. The list is back-end/src/common/constants/maintenance.constants.ts.

The contact form

• A repeated clientToken returns the first message's id instead of storing a second one, so a retry is safe.
• A filled website field is treated as a bot: the answer looks the same, and nothing is stored.
• Each address may send five an hour; the next answers 429.
• Messages are stored in the contact_messages table and forwarded to CONTACT_INBOX when it is set.

The licence checkout

• The price is the server's own, from back-end/src/modules/licenses/constants/license-offers.ts; the browser never sends one.
• A card goes to Stripe Checkout when STRIPE_SECRET_KEY is set, PayPal to PayPal when PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET are set, and either to the test checkout otherwise. In demo mode a provider with live keys is never offered.
• An order is paid once, by whichever comes first of Stripe's checkout.session.completed on POST /api/billing/webhooks/stripe, the return's confirm, or the test checkout's Pay. Only that one issues the licence key and mails the receipt. checkout.session.expired marks the order failed.
• The order's id is a long random string carried only by the buyer's return links. A repeated clientToken answers the first order. Each address may start ten orders an hour.

• The licence checkout

Uploads and media

Pictures and project files go to the Cloudflare R2 bucket when its five R2_* variables are set, and to MEDIA_UPLOAD_DIR otherwise, served at PUBLIC_MEDIA_URL followed by /uploads/….

Everything the API serves under /media carries X-Content-Type-Options: nosniff, and a file that is not a raster image, a PDF, plain text, audio or video (an HTML or SVG file, for one) is sent with Content-Disposition: attachment, so it downloads rather than opening as a page on the API's address. Files in an R2 bucket are served by the bucket, with the type they were uploaded with.

Limits per address

A request over a limit answers 429, with a sentence naming what was limited and how long to wait, such as "Too many sign-ups from this address. Wait an hour, then try again." The counts live in the API's memory, so a restart clears them. Behind a reverse proxy, set TRUST_PROXY to the number of proxies in front of the API, or every visitor is counted as the proxy's one address.

The AI assistant, its conversations and proposals

MCP server

Live permission updates over socket.io

Demo mode routes