CapRover API Documentation

This document provides information about the CapRover API endpoints, their parameters, and response formats. It is unofficial. It is mostly discovered using CapRover's codebase. It is mostly intended for LLMs to consume. Go to index.md for the Markdown version of this file.

API Response Format

All API responses follow a standard format:

{
  "status": 100,           // Status code (100 = success, 1000+ = error)
  "description": "OK",     // Status message
  "data": {}               // Optional response data
}

Common Concepts

Authentication

All API endpoints (except login) require authentication using a JWT token. Include the token in the x-captain-auth header:

Headers:
  x-captain-auth: <token>
  Content-Type: application/json

To obtain a token, use the login endpoint:

POST /api/v2/login
Body: {
  "password": "your-password",
  "otpToken": "optional-otp-token"
}

Response:

{
  "status": 100,
  "description": "OK",
  "data": {
    "token": "jwt-token-string"
  }
}

Status Codes:

Status Codes

Code Description
100 Success
101 Success - Deploy Started
102 Success - Partial
1000 Error - Generic
1001 Error - Captain Not Initialized
1101 Error - User Not Initialized
1102 Error - Not Authorized
1103 Error - Already Exists
1104 Error - Bad Name
1105 Error - Wrong Password
1106 Error - Auth Token Invalid
1107 Error - Verification Failed
1108 Error - Illegal Operation
1109 Error - Build Error
1110 Error - Illegal Parameter
1111 Error - Not Found
1112 Error - Authentication Failed
1113 Error - Password Back Off
1114 Error - OTP Required
1115 Error - Pro API Key Invalid
1116 Error - Nginx Validation Failed

App Naming Rules

When creating or updating apps, the app name must:

App Management APIs

Get App Definitions

Retrieves all app definitions and system configuration.

GET /api/v2/user/apps/appDefinitions/

Description:

Retrieves a list of all application definitions and system configuration settings. This endpoint provides information about all apps registered in the CapRover instance, including their basic configuration and the system's root domain settings.

Authentication: Required - JWT token in x-captain-auth header

Response:

{
  "status": 100,
  "description": "OK",
  "data": {
    "appDefinitions": [
      {
        "appName": "my-app",
        "hasPersistentData": false,
        "instanceCount": 1,
        "notExposeAsWebApp": false,
        "forceSsl": true,
        "containerHttpPort": 80,
        "customDomain": "example.com",
        "hasSsl": true,
        "volumes": [
          {
            "hostPath": "/captain/data/my-app",
            "containerPath": "/data"
          }
        ],
        "ports": [
          {
            "containerPort": "3000",
            "hostPort": "5000"
          }
        ],
        "envVars": [
          {
            "key": "NODE_ENV",
            "value": "production"
          }
        ]
      }
    ],
    "rootDomain": "example.com",
    "defaultNginxConfig": "nginx configuration template",
    "forceSsl": true,
    "hasRootSsl": true
  }
}

Status Codes:

Notes:

Register App

Creates a new application definition in CapRover.

POST /api/v2/user/apps/appDefinitions/register/

Description:

Creates a new application definition in CapRover with default settings. This endpoint registers a new app that can be customized later using the update endpoint.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "appName": "my-app",           // Required: Name of the application
  "projectId": "project-123",    // Optional: ID of the project this app belongs to
  "hasPersistentData": false     // Optional: Whether the app has persistent data
}

Response:

{
  "status": 100,
  "description": "App Definition Saved",
  "data": {
    "appName": "my-app",
    "hasPersistentData": false
  }
}

Status Codes:

Notes:

Update App

Updates an application's configuration.

POST /api/v2/user/apps/appDefinitions/update/

Description:

Modifies the configuration of an existing application. This endpoint allows you to update various aspects of the app including instance count, SSL settings, container configuration, volumes, ports, environment variables, and Git repository settings.

Authentication: Required - JWT token in x-captain-auth header

Important: Most fields are completely replaced, not merged. You must include ALL fields you want to keep in your update request, not just the ones you want to change.

Request Body:

{
  "appName": "my-app",                    // Required: Name of the application
  "projectId": "project-123",             // Optional: ID of the project this app belongs to
  "description": "My application",         // Optional: Description of the application
  "instanceCount": 2,                     // Optional: Number of instances to run (WARNING: if not provided, defaults to 0)
  "notExposeAsWebApp": false,             // Optional: Whether to expose the app as a web service
  "forceSsl": true,                       // Optional: Whether to force SSL for the app
  "containerHttpPort": 80,                // Optional: HTTP port inside the container
  "websocketSupport": false,              // Optional: Whether to enable WebSocket support
  "nodeId": "node-1",                     // Optional: ID of the node to deploy to
  "customNginxConfig": "",                // Optional: Custom Nginx configuration
  "redirectDomain": "",                   // Optional: Domain to redirect to
  "preDeployFunction": "",                // Optional: Function to run before deployment
  "serviceUpdateOverride": "",            // Optional: Override for service update configuration
  "appPushWebhook": {                     // Optional: Git repository configuration
    "repoInfo": {
      "repo": "https://github.com/user/repo.git",  // Required: Git repository URL
      "branch": "main",                            // Required: Branch to deploy
      "user": "username",                          // Required if using password auth
      "password": "password-or-token",             // Required if using password auth
      "sshKey": "-----BEGIN OPENSSH PRIVATE KEY-----..."  // Required if using SSH auth
    }
  },
  "envVars": [                            // Optional: Environment variables
    {
      "key": "NODE_ENV",
      "value": "production"
    }
  ],
  "volumes": [                            // Optional: Volume mounts
    {
      "hostPath": "/captain/data/my-app",
      "containerPath": "/data"
    }
  ],
  "ports": [                              // Optional: Port mappings
    {
      "containerPort": "3000",
      "hostPort": "5000"
    }
  ],
  "tags": [                               // Optional: Application tags
    {
      "key": "environment",
      "value": "production"
    }
  ],
  "httpAuth": {                           // Optional: HTTP authentication
    "user": "admin",
    "password": "secret"
  },
  "appDeployTokenConfig": {               // Optional: App deployment token configuration
    "enabled": true,
    "appDeployToken": "optional-token"
  }
}

Response:

{
  "status": 100,
  "description": "App Definition Updated",
  "data": {
    "appName": "my-app",
    "instanceCount": 2,
    "notExposeAsWebApp": false,
    "forceSsl": true
  }
}

Status Codes:

Notes:

Example of field replacement behavior:

// Current app configuration:
{
  "instanceCount": 2,
  "envVars": [{"key": "FOO", "value": "bar"}],
  "ports": [{"containerPort": "3000", "hostPort": "80"}]
}

// If you want to change just instanceCount to 3, you MUST send:
{
  "appName": "my-app",
  "instanceCount": 3,
  "envVars": [{"key": "FOO", "value": "bar"}],
  "ports": [{"containerPort": "3000", "hostPort": "80"}]
}

// If you only send:
{
  "appName": "my-app",
  "instanceCount": 3
}
// This will clear out envVars and ports arrays because they weren't included!

Data Handling:

Deploy App

Deploys an application from source code or a Docker image.

POST /api/v2/user/apps/appData/:appName

Description:

Deploys or updates an application using either a source code archive or a Docker image definition. The deployment process includes building the application (if source code is provided) and deploying it to the specified number of instances.

Authentication: Required - JWT token in x-captain-auth header

Request Options:

  1. Using Source Code Archive:
POST /api/v2/user/apps/appData/:appName
Content-Type: multipart/form-data

Form Data:
- sourceFile: Tarball file (.tar.gz) containing the application source code
  1. Using Docker Image Definition:
{
  "captainDefinitionContent": "{\"schemaVersion\":2,\"dockerfileLines\":[\"FROM node:14-alpine\",\"WORKDIR /usr/src/app\",\"COPY ./ /usr/src/app\",\"RUN npm install --production\",\"ENV NODE_ENV production\",\"ENV PORT 80\",\"EXPOSE 80\",\"CMD [ \\\"npm\\\", \\\"start\\\" ]\"]}",
  "gitHash": "optional-git-hash"
}

The captainDefinitionContent can be specified in several ways:

  1. Using dockerfileLines (array of strings):
{
  "schemaVersion": 2,
  "dockerfileLines": [
    "FROM node:14-alpine",
    "WORKDIR /usr/src/app",
    "COPY ./ /usr/src/app",
    "RUN npm install --production",
    "ENV NODE_ENV production",
    "ENV PORT 80",
    "EXPOSE 80",
    "CMD [ \"npm\", \"start\" ]"
  ]
}
  1. Using dockerfilePath (path to Dockerfile):
{
  "schemaVersion": 2,
  "dockerfilePath": "./Dockerfile"
}
  1. Using templateId (predefined template):
{
  "schemaVersion": 2,
  "templateId": "node/14"
}
  1. Using imageName (existing Docker image):
{
  "schemaVersion": 2,
  "imageName": "nginx:latest"
}

Available templates include:

Response:

{
  "status": 101,
  "description": "Deploy Started",
  "data": {
    "appName": "my-app",
    "deploymentId": "deploy-123"
  }
}

Status Codes:

Notes:

Enable SSL for Base Domain

Enables HTTPS for the CapRover base domain using Let's Encrypt.

POST /api/v2/user/apps/appDefinitions/enablebasedomainssl/

Description:

Obtains and configures an SSL certificate for the CapRover base domain using Let's Encrypt. This endpoint enables HTTPS for the CapRover dashboard and all apps using the base domain.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "appName": "my-app"
}

Response:

{
  "status": 100,
  "description": "Base Domain SSL Enabled",
  "data": {
    "appName": "my-app",
    "hasSsl": true,
    "rootDomain": "example.com"
  }
}

Status Codes:

Notes:

Delete App

Deletes one or more applications and their associated resources.

POST /api/v2/user/apps/appDefinitions/delete/

Description:

Removes one or more applications from the CapRover instance. This endpoint can delete multiple apps at once and optionally remove their associated volumes. The operation is irreversible and will remove all app data unless volumes are preserved.

Authentication: Required - JWT token in x-captain-auth header

Request Body (Single App):

{
  "appName": "my-app"
}

Request Body (Multiple Apps):

{
  "appNames": ["app1", "app2"],
  "volumes": ["volume1", "volume2"]
}

Response:

{
  "status": 100,
  "description": "App(s) Deleted Successfully",
  "data": {
    "deletedApps": ["app1", "app2"],
    "deletedVolumes": ["volume1", "volume2"]
  }
}

Status Codes:

Notes:

Rename App

Renames an existing application.

POST /api/v2/user/apps/appDefinitions/rename/

Description:

Renames an existing application while preserving its configuration, data, and relationships. This endpoint allows you to change an application's name while maintaining all its settings, volumes, and deployments.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "oldAppName": "old-app-name",    // Required: Current name of the application
  "newAppName": "new-app-name"     // Required: New name for the application
}

Response:

{
  "status": 100,
  "description": "AppName is renamed",
  "data": {}
}

Status Codes:

Notes:

Implementation Details

Error Handling

If the rename operation fails, the system will return an error with one of these messages:

Example error response:

{
  "status": 1104,
  "description": "App Name is not allowed. Only lowercase letters and single hyphens are allowed",
  "data": {}
}

Get App Logs

Retrieves application logs and deployment information.

GET /api/v2/user/apps/appData/:appName/logs

Description:

Retrieves logs and deployment information for a specific application. This endpoint can be used to monitor application status, debug issues, and track deployment progress.

Authentication: Required - JWT token in x-captain-auth header

Query Parameters:

Response:

{
  "status": 100,
  "description": "OK",
  "data": {
    "logs": [
      {
        "timestamp": "2024-03-20T10:00:00Z",
        "message": "Container started successfully",
        "type": "info"
      },
      {
        "timestamp": "2024-03-20T10:00:01Z",
        "message": "Application listening on port 3000",
        "type": "info"
      }
    ],
    "deploymentStatus": {
      "status": "running",
      "lastDeployment": {
        "id": "deploy-123",
        "timestamp": "2024-03-20T09:55:00Z",
        "status": "completed"
      }
    }
  }
}

Status Codes:

Notes:

Get App Build Logs

Retrieves real-time build logs for an application during deployment.

GET /api/v2/user/apps/appData/:appName/

Description:

Retrieves build logs and deployment status for a specific application. This endpoint is used during the deployment process to stream build progress in real-time.

Authentication: Required - JWT token in x-captain-auth header

Headers:

x-captain-auth: <token>
x-namespace: captain

Query Parameters:

Response:

{
  "status": 100,
  "description": "App build status retrieved",
  "data": {
    "isAppBuilding": true,
    "isBuildFailed": false,
    "logs": {
      "firstLineNumber": 1,
      "lines": [
        "Step 1/10: FROM node:14",
        "Step 2/10: WORKDIR /app",
        "Step 3/10: COPY package*.json ./"
      ]
    }
  }
}

Status Codes:

Notes:

Polling Implementation

The client should implement a polling mechanism to retrieve build logs in real-time. Here's how the polling should work:

  1. Make an initial request to get the first set of logs
  2. Check the isAppBuilding field in the response
  3. If isAppBuilding is true:
    • Wait 2 seconds
    • Make another request
    • Repeat until isAppBuilding becomes false
  4. If isAppBuilding is false:
    • Check isBuildFailed to determine build outcome
    • Stop polling

Example polling implementation:

async function pollBuildLogs(appName, token) {
    while (true) {
        const response = await fetch(`/api/v2/user/apps/appData/${appName}/`, {
            headers: {
                'x-captain-auth': token,
                'x-namespace': 'captain'
            }
        });
        
        const data = await response.json();
        
        // Process logs
        if (data.data.logs) {
            console.log(data.data.logs.lines.join('\n'));
        }
        
        // Check if build is complete
        if (!data.data.isAppBuilding) {
            if (data.data.isBuildFailed) {
                console.log('Build failed');
            } else {
                console.log('Build completed successfully');
            }
            break;
        }
        
        // Wait 2 seconds before next poll
        await new Promise(resolve => setTimeout(resolve, 2000));
    }
}

The polling mechanism ensures that:

Example Usage:

# Poll for build logs with follow mode
while true; do
  response=$(curl -s -H "x-captain-auth: $TOKEN" -H "x-namespace: captain" \
    "http://your-server:3000/api/v2/user/apps/appData/myapp/?follow=true&limit=100")
  
  # Process logs
  echo "$response" | jq -r '.data.logs.lines[]'
  
  # Check if build is complete
  if [ "$(echo "$response" | jq -r '.data.isAppBuilding')" = "false" ]; then
    break
  fi
  
  sleep 2
done

Status Codes:

Notes:

Example Usage:

# Poll for build logs with follow mode
while true; do
  response=$(curl -s -H "x-captain-auth: $TOKEN" -H "x-namespace: captain" \
    "http://your-server:3000/api/v2/user/apps/appData/myapp/?follow=true&limit=100")
  
  # Process logs
  echo "$response" | jq -r '.data.logs.lines[]'
  
  # Check if build is complete
  if [ "$(echo "$response" | jq -r '.data.isAppBuilding')" = "false" ]; then
    break
  fi
  
  sleep 2
done

Follow Parameter

The follow parameter is used to enable real-time log streaming in several endpoints. When follow=true, the response will stream logs in real-time instead of returning a single response.

Supported Endpoints:

  1. Get App Logs (GET /api/v2/user/apps/appData/:appName/logs)
  2. Get App Build Logs (GET /api/v2/user/apps/appData/:appName/)

Implementation Details:

Example Usage with cURL:

# Stream app logs in real-time
curl -N -H "x-captain-auth: $TOKEN" \
  "http://your-server:3000/api/v2/user/apps/appData/myapp/logs?follow=true"

# Stream build logs in real-time
curl -N -H "x-captain-auth: $TOKEN" \
  "http://your-server:3000/api/v2/user/apps/appData/myapp/?follow=true"

Example Usage with JavaScript:

// Stream app logs
fetch('http://your-server:3000/api/v2/user/apps/appData/myapp/logs?follow=true', {
  headers: {
    'x-captain-auth': token
  }
}).then(response => {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  
  function readStream() {
    reader.read().then(({done, value}) => {
      if (done) {
        console.log('Stream complete');
        return;
      }
      
      const text = decoder.decode(value);
      console.log(text);
      readStream();
    });
  }
  
  readStream();
});

Notes:

# Stream logs in real-time
curl -N -H "x-captain-auth: YOUR_JWT_TOKEN" \
     "https://captain.yourdomain.com/api/v2/user/apps/appData/myapp/logs?follow=true"

# Stream build logs in real-time
curl -N -H "x-captain-auth: YOUR_JWT_TOKEN" \
     "https://captain.yourdomain.com/api/v2/user/apps/appData/myapp/buildlogs?follow=true"

// Stream logs in real-time
fetch('https://captain.yourdomain.com/api/v2/user/apps/appData/myapp/logs?follow=true', {
  headers: {
    'x-captain-auth': 'YOUR_JWT_TOKEN'
  }
}).then(response => {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  
  function readStream() {
    reader.read().then(({done, value}) => {
      if (done) {
        console.log('Stream complete');
        return;
      }
      
      const chunk = decoder.decode(value);
      console.log('Received chunk:', chunk);
      readStream();
    });
  }
  
  readStream();
});

Streaming Response Format

When follow=true, the response is a continuous stream of JSON objects, each representing a log entry. Here's how the streaming data looks:

{"status":100,"description":"OK","data":{"logs":[{"timestamp":"2024-03-20T10:00:00Z","message":"Container started successfully","type":"info"}]}}
{"status":100,"description":"OK","data":{"logs":[{"timestamp":"2024-03-20T10:00:01Z","message":"Application listening on port 3000","type":"info"}]}}
{"status":100,"description":"OK","data":{"logs":[{"timestamp":"2024-03-20T10:00:02Z","message":"Database connection established","type":"info"}]}}
{"status":100,"description":"OK","data":{"logs":[{"timestamp":"2024-03-20T10:00:03Z","message":"Cache initialized","type":"info"}]}}
{"status":100,"description":"OK","data":{"logs":[{"timestamp":"2024-03-20T10:00:04Z","message":"Request received: GET /api/users","type":"info"}]}}
{"status":100,"description":"OK","data":{"logs":[{"timestamp":"2024-03-20T10:00:05Z","message":"Error: Database query timeout","type":"error"}]}}

For build logs, the streaming format is similar but includes build-specific information:

{"status":100,"description":"OK","data":{"logs":{"lines":["Step 1/10 : FROM node:16-alpine","Step 2/10 : WORKDIR /app"],"firstLineNumber":1}}}
{"status":100,"description":"OK","data":{"logs":{"lines":["Step 3/10 : COPY package*.json .","Step 4/10 : RUN npm install"],"firstLineNumber":3}}}
{"status":100,"description":"OK","data":{"logs":{"lines":["Step 5/10 : COPY . .","Step 6/10 : RUN npm run build"],"firstLineNumber":5}}}
{"status":100,"description":"OK","data":{"logs":{"lines":["Step 7/10 : EXPOSE 3000","Step 8/10 : CMD [\"npm\", \"start\"]"],"firstLineNumber":7}}}
{"status":100,"description":"OK","data":{"logs":{"lines":["Successfully built abc123","Successfully tagged myapp:latest"],"firstLineNumber":9}}}

Each chunk in the stream:

The stream continues until:

Domain Management

Add Custom Domain

Adds a custom domain to an application.

POST /api/v2/user/apps/appDefinitions/customdomain/

Description:

Associates a custom domain with an application. This endpoint sets up the necessary DNS and Nginx configurations to route traffic from the custom domain to your application.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "appName": "my-app",
  "customDomain": "example.com"
}

Response:

{
  "status": 100,
  "description": "Custom Domain Added",
  "data": {
    "appName": "my-app",
    "customDomain": "example.com"
  }
}

Status Codes:

Notes:

Enable SSL for Custom Domain

Enables HTTPS for a custom domain using Let's Encrypt.

POST /api/v2/user/apps/appDefinitions/enablecustomdomainssl/

Description:

Obtains and configures an SSL certificate for a custom domain using Let's Encrypt. This endpoint automates the SSL certificate issuance and renewal process.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "appName": "my-app",
  "customDomain": "example.com"
}

Response:

{
  "status": 100,
  "description": "SSL Enabled for Custom Domain",
  "data": {
    "appName": "my-app",
    "customDomain": "example.com",
    "hasSsl": true
  }
}

Status Codes:

Notes:

Remove Custom Domain

Removes a custom domain from an application.

POST /api/v2/user/apps/appDefinitions/removecustomdomain/

Description:

Removes a custom domain configuration from an application. This endpoint disassociates a custom domain from your application and updates the necessary DNS and Nginx configurations.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "appName": "my-app",           // Required: Name of the application
  "customDomain": "example.com"  // Required: Custom domain to remove
}

Response:

{
  "status": 100,
  "description": "Custom domain is removed for: my-app at example.com",
  "data": {}
}

Status Codes:

Notes:

Implementation Details

Error Handling

If the remove operation fails, the system will return an error with one of these messages:

Example error response:

{
  "status": 1000,
  "description": "Custom domain example.com does not exist in my-app",
  "data": {}
}

Project Management

Create Project

Creates a new project in CapRover.

POST /api/v2/user/projects/register

Description:

Creates a new project that can be used to organize and group related applications. Projects help manage multiple apps and their resources more effectively.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "id": "project-123",           // Optional: Custom project ID (auto-generated if not provided)
  "name": "my-project",          // Required: Name of the project
  "description": "Project description"  // Optional: Project description
}

Response:

{
  "status": 100,
  "description": "Project Created",
  "data": {
    "id": "project-123",
    "name": "my-project",
    "description": "Project description",
    "createdAt": "2024-03-20T10:00:00Z"
  }
}

Get Projects

Retrieves all projects and their hierarchical structure.

GET /api/v2/user/projects

Description:

Retrieves a list of all projects in the CapRover instance. The projects are returned in a hierarchical order, with parent projects followed by their children.

Authentication: Required - JWT token in x-captain-auth header

Response:

{
  "status": 100,
  "description": "Projects are retrieved.",
  "data": {
    "projects": [
      {
        "id": "project-123",
        "name": "parent-project",
        "description": "Parent project description",
        "parentProjectId": ""
      },
      {
        "id": "project-456",
        "name": "child-project",
        "description": "Child project description",
        "parentProjectId": "project-123"
      }
    ]
  }
}

Status Codes:

Notes:

Delete Projects

POST /api/v2/user/projects/delete

Request Body:

{
  "projectIds": ["project-id-1", "project-id-2"]
}

Update Project

Updates an existing project.

POST /api/v2/user/projects/update/

Description:

Updates an existing project's configuration. This endpoint allows you to modify the project's name, description, and parent project relationship.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "projectDefinition": {
    "id": "project-123",           // Required: ID of the project to update
    "name": "updated-project",     // Required: New name for the project
    "description": "Updated description",  // Optional: New project description
    "parentProjectId": "parent-123"  // Optional: ID of the parent project (empty string for root level)
  }
}

Response:

{
  "status": 100,
  "description": "Project Saved",
  "data": {}
}

Status Codes:

Notes:

Rename Project

Renames an existing project.

POST /api/v2/user/projects/rename/

Description:

Renames an existing project while preserving its ID and relationships.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "projectId": "project-123",      // Required: ID of the project to rename
  "newName": "new-project-name"    // Required: New name for the project
}

Response:

{
  "status": 100,
  "description": "Project Renamed",
  "data": {}
}

Status Codes:

Notes:

One-Click Apps

Get One-Click App List

GET /api/v2/user/oneclick/template/list/

Description:

Retrieves a list of all available one-click apps from both the official CapRover repository and any custom repositories that have been added. This endpoint aggregates apps from all configured repositories and returns their metadata.

Authentication: Required - JWT token in x-captain-auth header

Response:

{
  "status": 100,
  "description": "All one click apps are retrieved",
  "data": {
    "oneClickApps": [
      {
        "baseUrl": "https://oneclickapps.caprover.com",
        "name": "mysql",
        "displayName": "MySQL",
        "isOfficial": true,
        "description": "MySQL Database Server",
        "logoUrl": "https://oneclickapps.caprover.com/v4/logos/mysql.png"
      }
    ]
  }
}

Status Codes:

Notes:

Get One-Click App Template

GET /api/v2/user/oneclick/template/app

Description:

Retrieves the detailed template configuration for a specific one-click app from a repository. This endpoint fetches the complete app template including deployment configuration, environment variables, and other settings needed to deploy the app.

Authentication: Required - JWT token in x-captain-auth header

Query Parameters:

Response:

{
  "status": 100,
  "description": "App template is retrieved",
  "data": {
    "appTemplate": {
      "name": "mysql",
      "displayName": "MySQL",
      "description": "MySQL Database Server",
      "version": "8.0",
      "variables": [
        {
          "id": "mysql_root_password",
          "label": "MySQL Root Password",
          "description": "Password for the MySQL root user",
          "type": "password",
          "defaultValue": ""
        }
      ],
      "dockerfileLines": [
        "FROM mysql:8.0",
        "ENV MYSQL_ROOT_PASSWORD=${mysql_root_password}"
      ],
      "captainDefinition": {
        "schemaVersion": 2,
        "dockerfilePath": "./Dockerfile"
      }
    }
  }
}

Status Codes:

Notes:

Deploy One-Click App

POST /api/v2/user/apps/appData/:appName

Description:

Deploys a one-click app using its template configuration. This endpoint takes a one-click app template and deploys it as a new application in your CapRover instance. The deployment process includes setting up the necessary configuration, environment variables, and volumes.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "appName": "my-mysql",                    // Required: Name for the deployed app
  "oneClickAppName": "mysql",               // Required: Name of the one-click app to deploy
  "oneClickAppBaseUrl": "https://oneclickapps.caprover.com",  // Required: Base URL of the one-click app repository
  "variables": {                            // Optional: Variables to customize the app deployment
    "mysql_root_password": "my-secure-password",
    "mysql_database": "myapp"
  },
  "hasPersistentData": true,               // Optional: Whether the app has persistent data (default: true for databases)
  "notExposeAsWebApp": false,              // Optional: Whether to expose the app as a web service
  "instanceCount": 1,                      // Optional: Number of instances to deploy
  "forceSsl": true,                        // Optional: Whether to force SSL for the app
  "volumes": [                             // Optional: Additional volumes to mount
    {
      "hostPath": "/captain/data/my-mysql",
      "containerPath": "/var/lib/mysql"
    }
  ],
  "envVars": [                             // Optional: Additional environment variables
    {
      "key": "MYSQL_CHARACTER_SET_SERVER",
      "value": "utf8mb4"
    }
  ]
}

Response:

{
  "status": 101,
  "description": "Deploy Started",
  "data": {
    "appName": "my-mysql",
    "deploymentId": "deploy-123"
  }
}

Status Codes:

Notes:

Insert Repository

Adds a new one-click app repository.

POST /api/v2/user/oneclick/repositories/insert

Description:

Adds a new one-click app repository.

Authentication: Required - JWT token in x-captain-auth header

Delete Repository

Deletes a one-click app repository.

POST /api/v2/user/oneclick/repositories/delete

Description:

Deletes a one-click app repository.

Authentication: Required - JWT token in x-captain-auth header

Get Repositories

Retrieves all one-click app repositories.

GET /api/v2/user/oneclick/repositories/

Description:

Retrieves a list of all configured one-click app repositories.

Authentication: Required - JWT token in x-captain-auth header

System Management

Get System Info

GET /api/v2/user/system/info

Description:

Retrieves system information about the CapRover instance, including SSL configuration, domain settings, and other system-wide configurations.

Authentication: Required - JWT token in x-captain-auth header

Response:

{
  "status": 100,
  "description": "Captain info retrieved",
  "data": {
    "hasRootSsl": true,      // Whether SSL is enabled for the root domain
    "forceSsl": true,        // Whether non-SSL traffic is forced to redirect to SSL
    "rootDomain": "example.com",  // The root domain configured for CapRover (empty if no custom domain)
    "captainSubDomain": "captain"  // The subdomain used for the CapRover dashboard
  }
}

Status Codes:

Notes:

Get Version Info

GET /api/v2/user/system/versionInfo

Description:

Retrieves version information about the CapRover instance, including current version, latest available version, and update status. This endpoint checks both the official CapRover API and Docker Hub for version information.

Authentication: Required - JWT token in x-captain-auth header

Response:

{
  "status": 100,
  "description": "Version Info Retrieved",
  "data": {
    "currentVersion": "1.5.3",
    "latestVersion": "1.5.4",
    "changeLogMessage": "Bug fixes and improvements",
    "canUpdate": true
  }
}

Status Codes:

Notes:

Create Backup

Creates a backup of the CapRover instance including all app data, configurations, and system settings.

POST /api/v2/user/system/createbackup/

Description:

Creates a comprehensive backup of the CapRover instance, including all application data, configurations, SSL certificates, and system settings. The backup is stored as a tar file and can be used to restore the instance to its current state.

Authentication: Required - JWT token in x-captain-auth header

Response:

{
  "status": 100,
  "description": "Backup created.",
  "data": {
    "downloadToken": "token-string"  // Token to download the backup file
  }
}

Status Codes:

Notes:

Change Root Domain

Changes the root domain for the CapRover instance.

POST /api/v2/user/system/changerootdomain

Description:

Changes the root domain for the CapRover instance. This affects all apps using the base domain pattern (appname.rootdomain.com) and the CapRover dashboard. The operation may require DNS configuration updates and can affect SSL certificates.

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "rootDomain": "new-domain.com",  // Required: The new root domain
  "force": false                   // Optional: Force change even if SSL is enabled
}

Response:

{
  "status": 100,
  "description": "Root domain changed.",
  "data": {}
}

Status Codes:

Notes:

Enable SSL for Captain

POST /api/v2/user/system/enablessl

Description:

Enables HTTPS for the CapRover dashboard using Let's Encrypt. This endpoint obtains and configures an SSL certificate for the CapRover dashboard domain (captain.yourdomain.com).

Authentication: Required - JWT token in x-captain-auth header

Request Body:

{
  "emailAddress": "admin@example.com"  // Required: Email address for Let's Encrypt notifications
}

Response:

{
  "status": 100,
  "description": "Root SSL Enabled.",
  "data": {}
}

Status Codes:

Notes:

Docker Registry Management

Get Registries

GET /api/v2/user/registries/

Description:

Retrieves a list of all configured Docker registries and the default push registry ID. This endpoint provides information about both local and remote Docker registries that are configured in the CapRover instance.

Authentication: Required - JWT token in x-captain-auth header

Response:

{
  "status": 100,
  "description": "All registries retrieved",
  "data": {
    "registries": [
      {
        "id": "registry-uuid",
        "registryUser": "username",
        "registryPassword": "password",
        "registryDomain": "registry.example.com",
        "registryImagePrefix": "prefix/",
        "registryType": "REMOTE_REG"
      }
    ],
    "defaultPushRegistryId": "registry-uuid"
  }
}

Status Codes:

Notes:

Get Unused Images

GET /api/v2/user/apps/appDefinitions/unusedImages

Description:

Retrieves a list of Docker images that are not currently in use by any application. This endpoint helps identify images that can be safely removed to free up disk space. The endpoint considers an image as unused if it's not associated with any current or recent deployments of any application.

Authentication: Required - JWT token in x-captain-auth header

Query Parameters:

Response:

{
  "status": 100,
  "description": "Unused images retrieved.",
  "data": {
    "unusedImages": [
      {
        "id": "sha256:abc123...",
        "tags": ["img-captain-myapp:8", "img-captain-myapp:9"]
      }
    ]
  }
}

Status Codes:

Notes:

System Management

Force SSL

Forces SSL for all applications.

POST /api/v2/user/system/forcessl/

Description:

Forces SSL for all applications by redirecting HTTP traffic to HTTPS.

Authentication: Required - JWT token in x-captain-auth header

Response:

{
  "status": 100,
  "description": "SSL forced for all apps",
  "data": {}
}

Get Load Balancer Info

Retrieves load balancer configuration information.

GET /api/v2/user/system/loadbalancerinfo/

Description:

Retrieves information about the load balancer configuration, including SSL settings and domain configurations.

Authentication: Required - JWT token in x-captain-auth header

Response:

{
  "status": 100,
  "description": "Load balancer info retrieved",
  "data": {
    "hasRootSsl": true,
    "forceSsl": true,
    "rootDomain": "example.com"
  }
}

Disk Cleanup

Manages disk cleanup operations.

GET /api/v2/user/system/diskcleanup/
POST /api/v2/user/system/diskcleanup/

Description:

Retrieves and manages disk cleanup operations, including unused images and volumes.

Authentication: Required - JWT token in x-captain-auth header

Response (GET):

{
  "status": 100,
  "description": "Disk cleanup info retrieved",
  "data": {
    "unusedImages": [
      {
        "id": "sha256:abc123...",
        "tags": ["img-captain-myapp:8"]
      }
    ]
  }
}

Netdata Monitoring

Manages Netdata monitoring configuration.

GET /api/v2/user/system/netdata/
POST /api/v2/user/system/netdata/

Description:

Retrieves and configures Netdata monitoring settings. Netdata is a real-time performance and health monitoring system that provides detailed metrics about your CapRover instance.

Authentication: Required - JWT token in x-captain-auth header

Get Netdata Configuration

GET /api/v2/user/system/netdata/

Response:

{
  "status": 100,
  "description": "Netdata info retrieved",
  "data": {
    "isEnabled": true,
    "netDataUrl": "captain.example.com/net-data-monitor"
  }
}

Status Codes:

Notes:

Update Netdata Configuration

POST /api/v2/user/system/netdata/

Request Body:

{
  "netDataInfo": {
    "isEnabled": true
  }
}

Response:

{
  "status": 100,
  "description": "Netdata info is updated",
  "data": {}
}

Status Codes:

Notes:

Implementation Details

Error Handling

If the Netdata container is not running, API requests may fail with the following error:

Something went wrong... err: NetData is not running! Are you sure you have started it?

This error occurs when the system cannot resolve the Netdata container hostname or when the container is not running.

GoAccess Analytics

Manages GoAccess analytics configuration and data.

GET /api/v2/user/system/goaccess/
POST /api/v2/user/system/goaccess/
GET /api/v2/user/system/goaccess/:appName/files
GET /api/v2/user/system/goaccess/:appName/files/:file

Description:

Retrieves and configures GoAccess analytics settings and data for applications. GoAccess is a real-time web log analyzer that provides detailed analytics about your application's web traffic.

Authentication: Required - JWT token in x-captain-auth header

Get GoAccess Configuration

GET /api/v2/user/system/goaccess/

Response:

{
  "status": 100,
  "description": "GoAccess info retrieved",
  "data": {
    "isEnabled": true,
    "data": {
      "rotationFrequencyCron": "0 0 1 * *",  // Monthly rotation by default
      "logRetentionDays": 30                 // Optional: Number of days to retain logs
    }
  }
}

Status Codes:

Notes:

Update GoAccess Configuration

POST /api/v2/user/system/goaccess/

Request Body:

{
  "goAccessInfo": {
    "isEnabled": true,
    "data": {
      "rotationFrequencyCron": "0 0 1 * *",
      "logRetentionDays": 30
    }
  }
}

Response:

{
  "status": 100,
  "description": "GoAccess info is updated",
  "data": {}
}

Status Codes:

Notes:

Get Application Log Files

GET /api/v2/user/system/goaccess/:appName/files

Description:

Retrieves a list of available log files and reports for a specific application.

Response:

{
  "status": 100,
  "description": "GoAccess info retrieved",
  "data": [
    {
      "domainName": "myapp.example.com",
      "name": "access.log.html",
      "lastModifiedTime": "2024-03-20T10:00:00Z",
      "url": "/user/system/goaccess/myapp/files/access.log.html"
    },
    {
      "domainName": "myapp.example.com",
      "name": "access.log--Live.html",
      "lastModifiedTime": "2024-03-20T10:00:00Z",
      "url": "/user/system/goaccess/myapp/files/access.log--Live.html"
    }
  ]
}

Status Codes:

Notes:

Get Log File Content

GET /api/v2/user/system/goaccess/:appName/files/:file

Description:

Retrieves the content of a specific log file or report.

Parameters:

Response:

Status Codes:

Notes:

Implementation Details

Nginx Configuration

Manages Nginx configuration settings for the CapRover instance.

GET /api/v2/user/system/nginxconfig/
POST /api/v2/user/system/nginxconfig/

Description:

Retrieves and updates Nginx configuration settings for the CapRover instance. This endpoint allows you to customize both the base Nginx configuration and the CapRover-specific configuration.

Authentication: Required - JWT token in x-captain-auth header

Get Nginx Configuration

GET /api/v2/user/system/nginxconfig/

Response:

{
  "status": 100,
  "description": "Nginx config retrieved",
  "data": {
    "baseConfig": {
      "byDefault": "default base nginx configuration",
      "customValue": "custom base nginx configuration"
    },
    "captainConfig": {
      "byDefault": "default captain nginx configuration",
      "customValue": "custom captain nginx configuration"
    }
  }
}

Status Codes:

Notes:

Update Nginx Configuration

POST /api/v2/user/system/nginxconfig/

Request Body:

{
  "baseConfig": {
    "customValue": "custom base nginx configuration"
  },
  "captainConfig": {
    "customValue": "custom captain nginx configuration"
  }
}

Response:

{
  "status": 100,
  "description": "Nginx config is updated",
  "data": {}
}

Status Codes:

Notes:

Implementation Details

Error Handling

If the Nginx configuration validation fails, the system will:

  1. Log the validation error
  2. Automatically revert to the previous configuration
  3. Return a 1116 error code with the validation error message

Example error response:

{
  "status": 1116,
  "description": "Nginx validation failed",
  "data": {
    "error": "unknown directive 'invalid_directive' in /etc/nginx/nginx.conf:10"
  }
}

Node Management

Manages cluster nodes in the CapRover Docker Swarm.

GET /api/v2/user/system/nodes/
POST /api/v2/user/system/nodes/

Description:

Retrieves and manages cluster node configurations in the Docker Swarm. This endpoint allows you to view node information and add new nodes to the cluster.

Authentication: Required - JWT token in x-captain-auth header

Get Nodes Information

GET /api/v2/user/system/nodes/

Response:

{
  "status": 100,
  "description": "Node info retrieved",
  "data": {
    "nodes": [
      {
        "nodeId": "node-id-string",
        "type": "manager",
        "isLeader": true,
        "hostname": "node-hostname",
        "architecture": "x86_64",
        "operatingSystem": "linux",
        "nanoCpu": 4000000000,
        "memoryBytes": 8589934592,
        "dockerEngineVersion": "20.10.0",
        "ip": "192.168.1.100",
        "state": "ready",
        "status": "active"
      }
    ]
  }
}

Status Codes:

Notes:

Add Node to Cluster

POST /api/v2/user/system/nodes/

Request Body:

{
  "nodeType": "manager",           // Required: Either "manager" or "worker"
  "privateKey": "ssh-private-key", // Required: SSH private key for authentication
  "remoteNodeIpAddress": "192.168.1.101",  // Required: IP address of the node to add
  "captainIpAddress": "192.168.1.100",     // Required: IP address of the CapRover node
  "sshPort": 22,                  // Optional: SSH port (default: 22)
  "sshUser": "root"               // Optional: SSH username (default: "root")
}

Response:

{
  "status": 100,
  "description": "Docker node is successfully joined.",
  "data": {}
}

Status Codes:

Notes:

Implementation Details

Error Handling

If node addition fails, the system will return an error with one of these messages:

Example error response:

{
  "status": 1000,
  "description": "Node type should be either manager or worker",
  "data": {}
}

Self-Hosted Registry

Manages the self-hosted Docker registry for the CapRover instance.

POST /api/v2/user/system/selfhostregistry/enableregistry/
POST /api/v2/user/system/selfhostregistry/disableregistry/

Description:

Enables or disables the self-hosted Docker registry for the CapRover instance. The self-hosted registry allows you to store and manage Docker images locally, reducing external dependencies and improving deployment speed.

Authentication: Required - JWT token in x-captain-auth header

Enable Registry

POST /api/v2/user/system/selfhostregistry/enableregistry/

Response:

{
  "status": 100,
  "description": "Local registry is created.",
  "data": {}
}

Status Codes:

Notes:

Disable Registry

POST /api/v2/user/system/selfhostregistry/disableregistry/

Response:

{
  "status": 100,
  "description": "Local registry is removed.",
  "data": {}
}

Status Codes:

Notes:

Implementation Details

SSL Configuration

If root SSL is enabled, the registry will automatically:

  1. Obtain an SSL certificate from Let's Encrypt
  2. Configure the registry to use HTTPS
  3. Set up Nginx to proxy HTTPS traffic to the registry
  4. Configure automatic certificate renewal

Error Handling

If enabling the registry fails, the system will return an error with one of these messages:

Example error response:

{
  "status": 1108,
  "description": "There is already a local registry set up!",
  "data": {}
}

Theme Management

Manages themes for the CapRover dashboard.

POST /api/v2/user/themes/setcurrent/
POST /api/v2/user/themes/update/
POST /api/v2/user/themes/delete/
GET /api/v2/user/themes/all/
GET /api/v2/public/themes/current

Description:

Manages themes for the CapRover dashboard. Themes control the appearance and behavior of the CapRover interface. The system includes built-in themes and supports custom themes.

Authentication: Required - JWT token in x-captain-auth header (except for public endpoints)

Set Current Theme

POST /api/v2/user/themes/setcurrent/

Request Body:

{
  "themeName": "theme-name"  // Required: Name of the theme to set as current
}

Response:

{
  "status": 100,
  "description": "Current theme is stored.",
  "data": {}
}

Status Codes:

Update Theme

POST /api/v2/user/themes/update/

Request Body:

{
  "oldName": "old-theme-name",  // Optional: Name of the theme to update (omit for new theme)
  "name": "theme-name",         // Required: Name of the theme
  "content": "theme-content",   // Required: Theme content (CSS/JS)
  "extra": "extra-content",     // Optional: Additional theme content
  "headEmbed": "head-content"   // Optional: Content to embed in HTML head
}

Response:

{
  "status": 100,
  "description": "Theme is stored.",
  "data": {}
}

Status Codes:

Delete Theme

POST /api/v2/user/themes/delete/

Request Body:

{
  "themeName": "theme-name"  // Required: Name of the theme to delete
}

Response:

{
  "status": 100,
  "description": "Theme is deleted.",
  "data": {}
}

Status Codes:

Get All Themes

GET /api/v2/user/themes/all/

Response:

{
  "status": 100,
  "description": "Themes are retrieved.",
  "data": {
    "themes": [
      {
        "name": "theme-name",
        "content": "theme-content",
        "extra": "extra-content",
        "headEmbed": "head-content",
        "builtIn": true
      }
    ]
  }
}

Status Codes:

Get Current Theme (Public)

GET /api/v2/public/themes/current

Description:

Retrieves the current theme configuration (no authentication required).

Response:

{
  "status": 100,
  "description": "Current theme is retrieved.",
  "data": {
    "theme": {
      "name": "theme-name",
      "content": "theme-content",
      "extra": "extra-content",
      "headEmbed": "head-content",
      "builtIn": true
    }
  }
}

Status Codes:

Implementation Details

Theme File Format

Theme files use a special format with fields prefixed by ###CapRoverTheme.:

###CapRoverTheme.name:
Theme Name
###CapRoverTheme.content:
{
  "colorA": "#fff",
  "colorB": "#000"
}
###CapRoverTheme.extra:
Additional theme content
###CapRoverTheme.headEmbed:
<meta name="theme-color" content="#ffffff">

Error Handling

If theme operations fail, the system will return an error with one of these messages:

Example error response:

{
  "status": 1110,
  "description": "Cannot delete a built-in theme",
  "data": {}
}

Pro Features

Manage API Key

Manages Pro API key.

POST /api/v2/user/pro/apikey/

Description:

Manages the Pro API key configuration.

Authentication: Required - JWT token in x-captain-auth header

OTP Management

Manages OTP settings.

GET /api/v2/user/pro/otp/
POST /api/v2/user/pro/otp/

Description:

Retrieves and configures OTP settings.

Authentication: Required - JWT token in x-captain-auth header

Pro Configurations

Manages Pro feature configurations.

GET /api/v2/user/pro/configs/
POST /api/v2/user/pro/configs/

Description:

Retrieves and updates Pro feature configurations.

Authentication: Required - JWT token in x-captain-auth header

Get Pro State

Retrieves Pro feature state.

GET /api/v2/user/pro/state/

Description:

Retrieves the current state of Pro features.

Authentication: Required - JWT token in x-captain-auth header

Webhooks

Webhook Tokens

Webhook tokens are automatically generated when you configure a Git repository for an app. The token is used to authenticate webhook requests from Git providers.

Getting a Webhook Token

  1. Configure a Git repository for your app using the app update endpoint:
POST /api/v2/user/apps/appDefinitions/update/
{
  "appName": "my-app",
  "appPushWebhook": {
    "repoInfo": {
      "repo": "https://github.com/username/repo.git",
      "branch": "main",
      "user": "username",
      "password": "password-or-token"
    }
  }
}
  1. After updating, retrieve your app's configuration to get the webhook token:
GET /api/v2/user/apps/appDefinitions/

Look for appPushWebhook.pushWebhookToken in the response.

The webhook token is automatically managed by CapRover - you don't need to manually generate or manage it. It's created when you set up Git repository integration for your app.

Trigger Build

Triggers a build via webhook.

POST /api/v2/user/apps/webhooks/triggerbuild

Description:

Triggers a build for an application via webhook. This endpoint supports webhooks from various Git providers (GitHub, GitLab, Bitbucket) and can be used to automatically deploy new versions of your application when code changes are pushed to the repository.

Authentication: Required - Webhook token in query parameters:

Query Parameters:

?token=<webhook-token>&namespace=<namespace>

Request Headers (Git Provider Specific):

Response:

{
  "status": 100,
  "description": "Build webhook has triggered",
  "data": {}
}

Status Codes:

Notes:

Implementation Details

Error Handling

If the webhook fails, the system will return an error with one of these messages:

Example error response:

{
  "status": 1000,
  "description": "Error triggering a build",
  "data": {}
}

Security Considerations

Registry Management

Insert Registry

Adds a new registry.

POST /api/v2/user/registries/insert/

Description:

Adds a new Docker registry configuration.

Authentication: Required - JWT token in x-captain-auth header

Update Registry

Updates an existing registry.

POST /api/v2/user/registries/update/

Description:

Updates an existing Docker registry configuration.

Authentication: Required - JWT token in x-captain-auth header

Delete Registry

Deletes a registry.

POST /api/v2/user/registries/delete/

Description:

Deletes a Docker registry configuration.

Authentication: Required - JWT token in x-captain-auth header

Set Push Registry

Sets the default push registry.

POST /api/v2/user/registries/setpush/

Description:

Sets the default registry for pushing Docker images.

Authentication: Required - JWT token in x-captain-auth header

User Management

Change Password

Changes the user's password.

POST /api/v2/user/changepassword/

Description:

Changes the current user's password.

Authentication: Required - JWT token in x-captain-auth header

Download

Download Endpoint

Downloads files from the CapRover instance.

GET /api/v2/download/

Description:

Downloads files from the CapRover instance.

Authentication: Required - JWT token in x-captain-auth header