Skip to main content

​
Base URL

https://connect.enigma.click
All endpoints use this base URL unless otherwise specified.

​
Session Endpoints

​
POST /start/start-session

Create a new persistent session that can run multiple tasks. Authentication: Required Request Body: 
{
  "taskDetails": "Go to amazon.com",
  "maxDuration": 300000,
  "maxInputTokens": 100000,
  "maxOutputTokens": 100000,
  "startingUrl": "https://amazon.com",
  "avoidDomains": ["facebook.com"],
  "mode": "default",
  "terminateOnCompletion": false
}
Response (200 OK): 
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "socketURL": "https://connect.enigma.click",
  "streaming": {
    "webRTCURL": "https://74.235.190.31:8889/a1b2c3d4e5f6/whep",
    "webViewURL": "https://74.235.190.31:8889/a1b2c3d4e5f6",
    "dimensions": { "width": 1024, "height": 600 }
  },
  "initialPrompt": "Go to amazon.com",
  "expiresIn": 300000,
  "balance": 12.50,
  "message": "Connect to instance using sessionId in auth"
}
Error Responses:
  • 401 - Missing or invalid API key
  • 402 - Insufficient balance
  • 403 - Account deactivated
  • 429 - Rate limit exceeded
  • 503 - No available instances
See Parameters Reference for detailed parameter descriptions.

​
POST /start/send-message

Universal endpoint for all session control commands. Handles tasks, state changes, interactions, and guardrails. Authentication: Required Request Body: 
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "newTask | state | interaction | guardrail",
    // ... action-specific fields
  }
}
Supported Action Types:

​
actionType: newTask

Start a new task. Returns taskId for polling. 
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "newTask",
    "newState": "start",
    "taskDetails": "Search for laptops",
    "maxDuration": 60000,
    "maxInputTokens": 50000,
    "maxOutputTokens": 50000,
    "startingUrl": "https://amazon.com",
    "avoidDomains": ["facebook.com"],
    "terminateOnCompletion": true
  }
}
Response (completed within 50 seconds): 
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "result": {
    "type": "task_completed",
    "data": {
      "message": "Found 50 laptop results",
      "prompt_tokens": 8500,
      "completion_tokens": 2300,
      "total_tokens": 10800
    }
  }
}
Response (still running): 
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "pending": true,
  "pollUrl": "https://connect.enigma.click/task/a1b2c3d4e5f6/x9y8z7w6v5u4",
  "message": "Task still running. Poll GET /task/:sessionId/:taskId for result."
}

​
actionType: state

Control task execution (pause, resume, stop, terminate). Returns immediate success. 
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "state",
    "newState": "pause | resume | stop | terminate"
  }
}
Response: 
{
  "success": true,
  "message": "Message sent successfully"
}

​
actionType: interaction

Manual browser control. Returns immediate success. 
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "interaction",
    "action": {
      "type": "CLICK | TYPE | KEY_PRESS | takeOverControl | releaseControl",
      // ... action-specific parameters
    }
  }
}
Available Interaction Types:
  • takeOverControl - Enable manual mode
  • releaseControl - Return control to AI
  • CLICK - Click at coordinates {x, y}
  • DOUBLE_CLICK - Double click at coordinates {x, y}
  • TYPE - Type text {text, humanLike}
  • KEY_PRESS - Press key {key}
Response: 
{
  "success": true,
  "message": "Message sent successfully"
}

​
actionType: guardrail

Respond to guardrail trigger. Returns immediate success. 
{
  "sessionId": "a1b2c3d4e5f6",
  "message": {
    "actionType": "guardrail",
    "taskDetails": "Username: user@example.com, Password: pass123",
    "newState": "resume"
  }
}
Response: 
{
  "success": true,
  "message": "Message sent successfully"
}
Error Responses:
  • 400 - Missing required fields (sessionId, message)
  • 401 - Session not found or unauthorized

​
POST /start/run-task

Execute a single task with auto-terminating session. Simplified version of start-session + send-message. Authentication: Required
terminateOnCompletion is automatically set to true for this endpoint. The session will close after task completion.
Request Body: 
{
  "taskDetails": "Search Google for Anthropic",
  "maxDuration": 300000,
  "maxInputTokens": 100000,
  "maxOutputTokens": 100000,
  "startingUrl": "https://google.com",
  "avoidDomains": [],
  "mode": "default"
}
Response (completed within 50 seconds): 
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "complete",
  "result": {
    "type": "task_completed",
    "data": {
      "message": "Successfully searched for Anthropic",
      "prompt_tokens": 12450,
      "completion_tokens": 3200,
      "total_tokens": 15650,
      "completion_time": 23.5
    }
  }
}
Response (still running): 
{
  "success": true,
  "sessionId": "a1b2c3d4e5f6",
  "taskId": "x9y8z7w6v5u4",
  "status": "pending",
  "pollUrl": "https://connect.enigma.click/task/a1b2c3d4e5f6/x9y8z7w6v5u4",
  "message": "Task still running. Poll GET /task/:sessionId/:taskId for result."
}
Error Responses:
  • 400 - Missing taskDetails
  • 401 - Missing or invalid API key
  • 402 - Insufficient balance
  • 503 - No available instances

​
Task Endpoints

​
GET /task/:sessionId/:taskId

Poll for task result. No authentication required. No rate limit. Path Parameters:
  • sessionId - Session identifier
  • taskId - Task identifier
Response (still running): 
{
  "success": true,
  "status": "active",
  "pending": true,
  "usage": {
    "inputTokens": 8000,
    "outputTokens": 2100,
    "computeTime": 3,
    "cost": 0.0067
  }
}
Response (completed): 
{
  "success": true,
  "type": "task_completed",
  "data": {
    "message": "Task finished successfully",
    "prompt_tokens": 12450,
    "completion_tokens": 3200,
    "total_tokens": 15650,
    "completion_time": 23.5
  },
  "usage": {
    "inputTokens": 12450,
    "outputTokens": 3200,
    "computeTime": 5,
    "cost": 0.0124
  },
  "completedAt": "2024-01-15T10:30:00Z"
}
Response (guardrail triggered): 
{
  "success": true,
  "type": "guardrail_trigger",
  "data": {
    "type": "human_input_needed",
    "value": "I need login credentials to proceed"
  }
}
Response (failed): 
{
  "success": false,
  "status": "failed",
  "error": "Navigation timeout after 30 seconds",
  "usage": {
    "inputTokens": 5000,
    "outputTokens": 1200,
    "computeTime": 2,
    "cost": 0.0045
  }
}
Error Responses:
  • 404 - Task not found

​
OpenAI-Compatible Endpoints

​
POST /v1/chat/completions

OpenAI-compatible chat completions endpoint. Creates a new session for each request and auto-terminates after completion. Authentication: Required (Bearer token)
The OpenAI-compatible endpoint creates a new session for each request. For multi-task workflows, use the native REST API.
Request Body: 
{
  "model": "enigma-browser-1",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful browser automation assistant."
    },
    {
      "role": "user",
      "content": "Go to example.com and extract all headings"
    }
  ],
  "stream": false,
  "max_tokens": 2000
}
Response (Non-Streaming): 
{
  "id": "chatcmpl-a1b2c3d4e5f6",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "enigma-browser-1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I found 5 headings on example.com:\n1. Example Domain\n2. More Information\n3. Contact\n4. About\n5. Privacy Policy"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8450,
    "completion_tokens": 2100,
    "total_tokens": 10550
  },
  "enigma": {
    "sessionId": "a1b2c3d4e5f6",
    "taskId": "x9y8z7w6v5u4",
    "cost": 0.0089
  }
}
Response (Streaming): Server-Sent Events (SSE) format: 
data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"enigma-browser-1","choices":[{"index":0,"delta":{"role":"assistant","content":"I"},"finish_reason":null}]}

data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"enigma-browser-1","choices":[{"index":0,"delta":{"content":" found"},"finish_reason":null}]}

data: {"id":"chatcmpl-a1b2c3","object":"chat.completion.chunk","created":1704067200,"model":"enigma-browser-1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
Error Responses:
  • 401 - Invalid API key
  • 402 - Insufficient balance
  • 429 - Rate limit exceeded
  • 503 - No browser instances available
  • Guardrail error: {"error": {"message": "Guardrail triggered: I need login credentials to proceed", "type": "guardrail_error", "code": "guardrail_triggered"}}
See OpenAI-Compatible API for detailed integration guide.

​
GET /v1/models

List available models for OpenAI-compatible endpoint. Authentication: Required (Bearer token) Response: 
{
  "object": "list",
  "data": [
    {
      "id": "enigma-browser-1",
      "object": "model",
      "created": 1704067200,
      "owned_by": "enigma"
    }
  ]
}

​
Monitoring Endpoints

​
GET /start/health

System health check. No authentication required. Response: 
{
  "success": true,
  "status": "healthy",
  "instancesAvailable": true,
  "instanceCount": 5,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

​
GET /start/active-sockets

View active instance connections. No authentication required. Response: 
{
  "success": true,
  "sockets": ["socket_id_1", "socket_id_2", "socket_id_3"],
  "count": 3,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

​
Endpoint Summary

EndpointMethodAuthRate LimitDescription
/start/start-sessionPOSTRequired10/min per userCreate persistent session
/start/send-messagePOSTRequired10/min per userSend commands to session
/start/run-taskPOSTRequired10/min per userExecute single task
/task/:sessionId/:taskIdGETNot requiredNonePoll for task result
/v1/chat/completionsPOSTRequired10/min per userOpenAI-compatible chat
/v1/modelsGETRequiredNoneList available models
/start/healthGETNot requiredNoneSystem health check
/start/active-socketsGETNot requiredNoneActive connections

​
Next Steps

Parameters Reference

Detailed parameter documentation

Response Formats

Complete response format reference

Rate Limits

Rate limiting details and best practices

Quickstart

Get started in 5 minutes