API Usage

Understanding the API usage of the Commander Service Mode

API Versions

The service provides two API versions based on queue configuration:

  • /api/v2/ - Queue enabled (default): Asynchronous request processing with no request loss

  • /api/v1/ - Queue disabled (v17.1.6 and older): Direct synchronous execution

The v2 queue API was introduced in Commander 17.1.7 with release date Aug 28 2025

Request Queue System (API v2)

When queue is enabled (default), the service uses an asynchronous request queue system that provides:

  • Sequential Processing: Requests are processed one at a time in FIFO order

  • Request Tracking: Each request receives a unique ID for status tracking

  • No Dropped Requests: All requests are queued and processed

  • Result Retrieval: Asynchronous result retrieval using request IDs

Queue API Endpoints

Submit Request (Async):

curl -X POST 'http://localhost:<port>/api/v2/executecommand-async' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{"command": "tree"}'

Response (202 Accepted):

{
    "success": true,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "message": "Request queued successfully. Use /api/v2/status/<request_id> to check progress, /api/v2/result/<request_id> to get results, or /api/v2/queue/status for queue info."
}

Check Request Status:

curl 'http://localhost:<port>/api/v2/status/<request_id>' \
--header 'api-key: <your-api-key>'

Response:

{
    "success": true,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "command": "tree", 
    "status": "completed",
    "created_at": "2024-01-15T10:30:00.000000",
    "started_at": "2024-01-15T10:30:01.000000",
    "completed_at": "2024-01-15T10:30:03.000000"
}

Get Request Result:

curl 'http://localhost:<port>/api/v2/result/<request_id>' \
--header 'api-key: <your-api-key>'

Response (for completed request) (similar to direct execution via api/v1/executecommand):

{
    "result": "...",
    "status": "success"
}

Get Queue Status:

curl 'http://localhost:<port>/api/v2/queue/status' \
--header 'api-key: <your-api-key>'

Response:

{
    "success": true,
    "queue_size": 3,
    "active_requests": 5,
    "completed_requests": 12,
    "currently_processing": "550e8400-e29b-41d4-a716-446655440000",
    "worker_running": true
}

Request States

  • queued - Request accepted and waiting in queue

  • processing - Currently being executed

  • completed - Successfully completed

  • failed - Execution failed

  • expired - Request timed out before processing

Queue Configuration

The queue system is configured as:

queue_max_size: 100          # Maximum queued requests
request_timeout: 300         # Request timeout (5 minutes)
result_retention: 3600       # Result retention (1 hour)

Error Responses

  • 503 Service Unavailable: Queue is full

  • 404 Not Found: Request ID not found

  • 500 Internal Server Error: Command execution failed

  • 429 Too Many Requests: Rate limit exceeded

Direct Execution (API v1)

When queue is disabled, use the legacy synchronous endpoint:

curl --location 'http://localhost:<port>/api/v1/executecommand' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
    "command": "tree"
}'

If you're using Ngrok, the Curl command will be:

curl --location 'http://<your-ngrok-url>/api/v1/executecommand' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
	"command": "tree"
}'

If you're using Cloudflare, the Curl command will be:

curl --location 'http://<your-cloudflare-url>/api/v1/executecommand' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
	"command": "tree"
}'

File Input Parameters (FILEDATA)

Commands requiring file input can use the FILEDATA placeholder with JSON content sent in the filedata field. This feature enables seamless file-based operations through the REST API without requiring physical file uploads.

FILEDATA Examples

PAM Project Import:

curl -X POST 'http://localhost:<port>/api/v2/executecommand-async' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
  "command": "pam project import --filename=FILEDATA --name=\"My PAM Project\"",
  "filedata": {
    "project": "My PAM Project",
    "pam_data": {
      "resources": [
        {
          "type": "pamDirectory",
          "title": "Domain Controller",
          "directory_type": "active_directory",
          "host": "dc.example.com",
          "port": "636",
          "use_ssl": true,
          "domain_name": "example.com"
        }
      ]
    }
  }
}'

Import Command:

curl -X POST 'http://localhost:<port>/api/v2/executecommand-async' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
  "command": "import FILEDATA --format=json",
  "filedata": {
    "records": [
      {
        "title": "My Website", 
        "login": "[email protected]", 
        "password": "MyPassword123!"
      }
    ]
  }
}'

FILEDATA Features

  • Automatic Processing: No manual file handling required

  • Temporary File Management: Service handles file creation and cleanup automatically

  • Security: Sensitive data automatically masked in logs for privacy

  • Error Handling: Robust error handling with proper cleanup on failures

  • Both API Versions: Works with both /api/v1/executecommand and /api/v2/executecommand-async

Postman

You can send requests through the Postman app. Just ensure that the Content-Type header and api-key header is provided. Example screenshot below:

HTTP Body Configuration in Postman
Header Configuration in Postman
HTTP Request and Response in v2 in Postman
Demonstrating v2 API Request/Response Structure in Postman

All responses in api/v1 and get request result in api/v2 use this basic format: 

{ "command": "<command_name>", "data": <command_specific_data> , "status": "success"}

Command Specific Responses

Some commands have been modified to return formatted JSON. Other commands will return data exactly as they normally do through the Commander CLI version.

Examples of modified output:

List Command (ls):

{ "status": "success", "command": "ls", "data": { "folders": [ { "number": 1, "uid": "folder_uid_string", "name": "My Folder", "flags": "RW" } ], "records": [ { "number": 1, "uid": "record_uid_string", "type": "login", "title": "My Login", "description": "Optional description" } ] } }

Tree Command:

{ "status": "success", "command": "tree", "data": [ { "level": 0, "name": "Root Folder", "path": "Root Folder" }, { "level": 1, "name": "Subfolder", "path": "Root Folder/Subfolder" } ] }

Make Directory Command (mkdir):

{ "status": "success", "command": "mkdir", "data": { "folder_uid": "new_folder_uid_string" } }

Record Add Command:

{ "status": "success", "command": "record-add", "data": { "record_uid": "new_record_uid_string" } }

Search Record Command:

{ "status": "success", "command": "search record", "data": [ { "number": 1, "uid": "record_uid_string", "type": "login", "title": "Matching Record", "description": "Optional description" } ] }

Search Folder Command:

{ "status": "success", "command": "search folder", "data": [ { "number": 1, "uid": "folder_uid_string", "name": "Matching Folder" } ] }

Get Command:

{ "command": "get", "data": { "attachments": "service_config.yaml 537b ID: XYZ", "last_modified": "2025-01-18 15:35:21", "share_admins": "[email protected]", "shared": "False", "shared_users": "[email protected] (Owner)", "title": "Commander Service Mode", "type": "", "uid": "folder_uid_string" }, "status": "success" }

Commands with --format = json enabled (e.g. audit-report --format=json):

{ "status": "success", "command": "audit-report", "data": [ { "audit_event_type": "open_record", "created": "2025-02-18T10:30:45+00:00", "geo_location": "New York, NY, US", "ip_address": "192.168.1.100", "keeper_version": "Commander 16.11.0", "message": "User [email protected] opened record UID ABCD1234EFGH5678", "username": "[email protected]" } ] }

PreviousService Mode REST APINextService Tunneling

Last updated

Was this helpful?