API

Overview

The V1 API provides public endpoints for version checking and maintenance status. All endpoints require authentication via the x-api-token header.

Authentication

All endpoints require authentication using an API token in the header:

x-api-token: <api_token>

Base URL

https://api.appcockpit.dev/v1

---

Endpoint 1: Get Version Information

GET /v1/versions

Returns version information for a specific app, platform, and environment combination.

Request Parameters

Query Parameters (all required):

• app_id (string): The application identifier
• app_version (string): The version string to check
• platform (string): The platform (e.g., "ios", "android", "web")
• environment (string): The environment (e.g., "production", "staging", "development")

Request Example

GET /v1/versions?app_id=68ba7951f0a6fc6409a16103&app_version=1.2.0&platform=ios&environment=production
Headers:
  x-api-token: <api_token>

Success Response (200 OK)

{
  "version": "1.2.0",
  "platform": "ios",
  "force_update": false,
  "update_message": null
}

Response Fields

• version (string): The version string
• platform (string): The platform identifier
• force_update (boolean): Whether this version requires a forced update
• update_message (string | null): Optional message to show to the user

Error Responses

400 Bad Request - Missing Parameters:

{
  "error": "Missing required query parameters",
  "missing_params": ["app_version", "platform"]
}

401 Unauthorized - Missing Token:

{
  "error": "Missing x-api-token header"
}

401 Unauthorized - Invalid Token:

{
  "error": "Invalid x-api-token header"
}

401 Unauthorized - Invalid API Token:

{
  "error": "Invalid token"
}

402 Payment Required - Subscription Issues:

{
  "error": "Team subscription expired or invalid"
}

403 Forbidden - App ID Mismatch:

{
  "error": "Forbidden: app_id does not match token"
}

404 Not Found - Version Not Found:

{
  "error": "No version found"
}

500 Internal Server Error - Server Issues:

{
  "error": "<error_description>"
}

---

Endpoint 2: Get Maintenance Status

GET /v1/maintenance

Returns the maintenance status for a specific app and environment.

Request Parameters

Query Parameters (all required):

• app_id (string): The application identifier
• environment (string): The environment to check (e.g., "production", "staging", "development")

Request Example

GET /v1/maintenance?app_id=68ba7951f0a6fc6409a16103&environment=production
Headers:
  x-api-token: <api_tokenn>

Success Response (200 OK)

When maintenance is active:

{
  "active": true,
  "title": "System Maintenance",
  "description": "We're updating our database currently. Please try again later."
}

When maintenance is not active:

{
  "active": false
}

Response Fields

• active (boolean): Whether maintenance is currently active for the requested environment
• title (string, optional): The maintenance title (only present when active)
• description (string, optional): The maintenance description (only present when active)

Error Responses

400 Bad Request - Missing Environment:

{
  "error": "Missing required query parameter: environment"
}

401 Unauthorized - Missing Token:

{
  "error": "Missing x-api-token header"
}

401 Unauthorized - Invalid Token:

{
  "error": "Invalid x-api-token header"
}

401 Unauthorized - Invalid API Token:

{
  "error": "Invalid token"
}

402 Payment Required - Subscription Issues:

{
  "error": "Team subscription expired or invalid"
}

403 Forbidden - App ID Mismatch:

{
  "error": "Forbidden: app_id does not match token"
}

404 Not Found - App Not Found:

{
  "error": "App not found"
}

500 Internal Server Error - Server Issues:

{
  "error": "<error_description>"
}

---

Common HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Missing or invalid parameters
401	Unauthorized - Authentication failed
402	Payment Required - Subscription invalid
403	Forbidden - Access denied
404	Not Found - Resource not found
500	Internal Server Error - Server issues

Data Types

ErrorResponse

{
  "error": "string"
}

VersionResponse

{
  "version": "string",
  "platform": "string",
  "force_update": "boolean"
}

MaintenanceResponse

{
  "active": "boolean",
  "title": "string (optional)",
  "description": "string (optional)"
}

Example Usage

cURL Examples

Check version:

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

Check maintenance:

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

JavaScript Example

const apiToken = "your-api-token";

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

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