API Overview

Conventions that apply to every ModStack REST endpoint — where they live, how to authenticate, how long-running operations work, and what errors look like.

Base URL

All ModStack REST endpoints are served by the ModStack App service. The base URL depends on where your account is hosted and is exposed to the browser via the console's runtime config:

{
  "appApiBaseUrl": "https://api.modstack.dev",
  "uiApiBaseUrl": "https://console.modstack.dev",
  "oidcIssuer": "https://auth.modstack.dev/auth/realms/app",
  "clientId": "modstackapp"
}

Each resource has its own path prefix under this base — for example, /v1.0/modstack/project for Projects and /v1.0/modstack/environment for Environments. The individual resource pages document the full path for every endpoint.

Authentication

Every endpoint requires a valid OIDC access token issued by the ModStack auth server. Pass it in the Authorization header as a bearer token:

Authorization: Bearer <access_token>

Tokens are obtained via the OAuth 2.0 Authorization Code flow with PKCE. The console handles this automatically via the browser redirect. For programmatic access, see Modstack Identity and User Management.

Asynchronous Operations

Any endpoint that mutates infrastructure — creating a project, scaling an environment, deploying a service — is asynchronous. The HTTP response returns immediately with a taskId; the real work runs on the ModStack task engine and may take seconds to minutes.

A typical async response looks like:

{
  "returnCode": { "code": "Success" },
  "taskId": "f12a3b4c-5d6e-7f80-91a2-b3c4d5e6f708"
}

A successful HTTP response only means the task was accepted, not that it completed. Poll the Tasks API with the returned taskId to observe progress, failures, and the final result.

Error Responses

Every response carries a returnCode object that describes success or the specific error condition. HTTP status codes follow the usual conventions (200 for accepted requests, 400 for validation errors, 401 for missing/invalid tokens, 403 for authorization failures, 404 for missing resources, 500 for server errors), but returnCode.code is the authoritative application-level error identifier.

{
  "returnCode": {
    "code": "InvalidEntityState",
    "message": "Project is not in a state that supports this operation"
  }
}