Skip to main content

API

Overview​

The API provides public endpoints for version checking, maintenance status, and user authentication tracking. All endpoints (except /health) require authentication via the x-api-token header.

Authentication​

All endpoints require authentication using a Base64-encoded API token in the header:

x-api-token: <base64-encoded-api-token>

How It Works​

  1. Obtain your API token from the AppCockpit dashboard
  2. Base64-encode the token
  3. Include it in the x-api-token header of every request

Authentication Errors​

StatusMeaning
401 UnauthorizedMissing or invalid token
402 Payment RequiredTeam subscription has expired or is inactive
403 ForbiddenTeam has been deleted or app ID does not match

Base URL​

https://api.appcockpit.dev

Common Response Format​

Error Response​

All error responses share the same format:

{
  "error": "Description of what went wrong"
}

Response Headers​

All JSON responses include:

HeaderDescription
Content-Typeapplication/json
ETagMD5 hash of the response body for caching

Endpoints​

Health Check​

Check if the API is running. Does not require authentication.

GET /health

Response: 200 OK (empty body)

Get Versions​

Check whether a specific app version requires an update.

GET /v2/versions

Enhanced version with localized update messages.

Query Parameters​

ParameterTypeRequiredDescription
app_idstringYesYour app ID (must match the authenticated app)
app_versionstringYesThe client's current app version (e.g. "2.5.0")
platformstringYes"ios" or "android"
environmentstringYesEnvironment alias (e.g. "production", "staging")

Success Response (200 OK)​

{
  "version": "2.5.0",
  "platform": "ios",
  "force_update": false,
  "default_update_message": "A new version is available.",
  "update_messages": {
    "en": "A new version is available.",
    "de": "Eine neue Version ist verfuegbar."
  }
}
FieldTypeDescription
versionstringThe version string that was matched
platformstringPlatform of the matched version
force_updatebooleanWhether the user must update before continuing
default_update_messagestring | nullDefault update message (fallback)
update_messagesobject | nullMap of locale codes to localized update messages

Errors​

StatusErrorCause
400"app_id is required"Missing app_id parameter
400"app_version is required"Missing app_version parameter
400"platform is required"Missing platform parameter
400"environment is required"Missing environment parameter
403"Forbidden"app_id does not match the authenticated app
404"Version not found"No matching version or minimum version rule exists

Behavior​

  1. Looks for an exact version match (version string + platform + environment, status=true)
  2. If no exact match, falls back to a minimum version rule for the platform and environment
  3. If a minimum version rule exists, compares the client's app_version against the minimum — returns the rule only if the client version is older
  4. Returns 404 if neither match is found

Get Maintenance Status​

Check whether the app is in maintenance mode for a given environment.

GET /v2/maintenance

V1 and V2 are identical for this endpoint.

Query Parameters​

ParameterTypeRequiredDescription
app_idstringYesYour app ID (must match the authenticated app)
environmentstringYesEnvironment alias to check (e.g. "production")

Success Response (200 OK)​

Maintenance active:

{
  "active": true,
  "title": "Scheduled Maintenance",
  "description": "We're performing an upgrade. Back soon!",
  "links": [
    {
      "title": "Status Page",
      "url": "https://status.example.com"
    }
  ]
}

Maintenance inactive:

{
  "active": false,
  "title": null,
  "description": null,
  "links": []
}
FieldTypeDescription
activebooleanWhether maintenance mode is currently active for this environment
titlestring | nullTitle shown to users during maintenance
descriptionstring | nullDescription / message shown to users
linksarrayList of links to show during maintenance (e.g. status page)
links[].titlestringDisplay text for the link
links[].urlstringURL of the link

Errors​

StatusErrorCause
400"environment is required"Missing environment parameter
403"Forbidden"app_id does not match the authenticated app
404"App not found"App could not be found in the database

Authenticate User​

Log a user authentication event and track the latest app version per user and platform.

info

This endpoint is only available in V2.

POST /v2/authenticate

Request Headers​

HeaderRequiredDescription
x-api-tokenYesBase64-encoded API token
Content-TypeYesMust be application/json

Request Body​

{
  "user_id": "user_12345",
  "platform": "ios",
  "app_version": "2.5.0",
  "environment": "production"
}
FieldTypeRequiredDescription
user_idstringYesUnique identifier for the user
platformstringYesMust be "ios" or "android"
app_versionstringYesClient's current app version
environmentstringNoEnvironment identifier (e.g. "production", "staging")

Success Response (200 OK)​

{
  "success": true,
  "user_id": "user_12345",
  "platform": "ios",
  "app_version": "2.5.0"
}
FieldTypeDescription
successbooleantrue on success
user_idstringEcho of the submitted user ID
platformstringEcho of the submitted platform
app_versionstringEcho of the submitted app version

Errors​

StatusErrorCause
400"Invalid request body"JSON payload could not be parsed
400"user_id is required"user_id is missing or empty
400"platform is required"platform is missing or empty
400"app_version is required"app_version is missing or empty
400"platform must be 'ios' or 'android'"Invalid platform value
500"Failed to fetch user data"Database read error
500"Failed to update user version data"Database write error

Behavior​

When called, this endpoint performs two operations:

  1. Logs an authentication session — creates a record with the user ID, platform, app version, environment, and timestamp (retained for 365 days)
  2. Updates the user's latest version record — tracks the most recent app version per platform (iOS / Android separately), including:
    • First authentication timestamp (set once, never overwritten)
    • Last authentication timestamp (updated on every call)
    • Latest app version and environment per platform

Endpoint Summary​

MethodPathAuthDescription
GET/healthNoHealth check
GET/v2/versionsYesGet version info (localized messages)
GET/v2/maintenanceYesGet maintenance status
POST/v2/authenticateYesLog user authentication event

Example Usage​

cURL Examples​

Check version:

curl -H "x-api-token: your-api-token" \
  "https://api.appcockpit.dev/v2/versions?app_id=YOUR_APP_ID&app_version=1.2.0&platform=ios&environment=production"

Check maintenance:

curl -H "x-api-token: your-api-token" \
  "https://api.appcockpit.dev/v2/maintenance?app_id=YOUR_APP_ID&environment=production"

Authenticate user:

curl -X POST \
  -H "x-api-token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_12345", "platform": "ios", "app_version": "2.5.0", "environment": "production"}' \
  "https://api.appcockpit.dev/v2/authenticate"

JavaScript Example​

const apiToken = "your-api-token";

// Check version (V2)
const versionResponse = await fetch(
  "https://api.appcockpit.dev/v2/versions?app_id=YOUR_APP_ID&app_version=1.2.0&platform=ios&environment=production",
  {
    headers: { "x-api-token": apiToken },
  }
);

// Check maintenance
const maintenanceResponse = await fetch(
  "https://api.appcockpit.dev/v2/maintenance?app_id=YOUR_APP_ID&environment=production",
  {
    headers: { "x-api-token": apiToken },
  }
);

// Authenticate user
const authResponse = await fetch(
  "https://api.appcockpit.dev/v2/authenticate",
  {
    method: "POST",
    headers: {
      "x-api-token": apiToken,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      user_id: "user_12345",
      platform: "ios",
      app_version: "2.5.0",
      environment: "production",
    }),
  }
);