Sessions & Tasks API

Sessions represent conversations or workflows with AI Workers, while Tasks are individual AI operations within those sessions. This API allows you to create, manage, and interact with AI Workers through structured conversations.

Base URL

https://api.engine.boolbyte.com/api/session

Sessions

Create Session

POST /api/session/create

Creates a new conversation session for an AI Worker.

Using JavaScript SDK:

import { EngineClient } from '@boolbyte/engine';

const client = new EngineClient({ apiKey: 'YOUR_API_KEY' });

const session = await client.session.createSession({
  workerId: 'worker-456',
  messages: [
    {
      content: 'Hello, I need help analyzing patient data',
      role: 'user'
    }
  ],
  metadata: {
    name: 'patient-analysis-session',
    patientId: 'patient-123',
    clinicalContext: 'routine_checkup'
  }
});

Request Body:

{
  "workerId": "worker-456",
  "messages": [
    {
      "content": "Hello, I need help analyzing patient data",
      "role": "user"
    }
  ],
  "metadata": {
    "name": "patient-analysis-session",
    "patientId": "patient-123",
    "clinicalContext": "routine_checkup"
  }
}

Response:

{
  "success": true,
  "message": "Session created successfully",
  "data": {
    "id": "session-789",
    "workerId": "worker-456",
    "metadata": {
      "name": "patient-analysis-session",
      "patientId": "patient-123",
      "clinicalContext": "routine_checkup"
    },
    "toolConfigs": null,
    "messages": [
      {
        "id": "msg-001",
        "content": "Hello, I need help analyzing patient data",
        "role": "user",
        "status": "completed",
        "sessionId": "session-789",
        "assistantId": null,
        "completedAt": "2024-01-15T10:35:00.000Z",
        "incompleteAt": null,
        "incompleteDetails": null,
        "attachments": null,
        "metadata": {},
        "createdAt": "2024-01-15T10:35:00.000Z",
        "updatedAt": "2024-01-15T10:35:00.000Z"
      }
    ],
    "createdAt": "2024-01-15T10:35:00.000Z",
    "updatedAt": "2024-01-15T10:35:00.000Z"
  }
}

Create Session and Task

POST /api/session/create-with-task

Creates a new session and executes the first task in one request.

Using JavaScript SDK:

const sessionAndTask = await client.session.createSessionAndTask({
  workerId: 'worker-456',
  messages: [
    {
      content: 'Analyze the recent lab results for patient-123',
      role: 'user'
    }
  ],
  metadata: {
    patientId: 'patient-123'
  },
  task: {
    model: 'openai/gpt-4',
    temperature: 0.7,
    maxCompletionTokens: 1000
  }
});

List Sessions

GET /api/session/list

Retrieves all sessions for your team.

Using JavaScript SDK:

const sessions = await client.session.listSessions();

Response:

{
  "success": true,
  "message": "Sessions retrieved successfully",
  "data": [
    {
      "id": "session-789",
      "workerId": "worker-456",
      "metadata": {
        "name": "patient-analysis-session",
        "patientId": "patient-123"
      },
      "toolConfigs": null,
      "messages": [],
      "createdAt": "2024-01-15T10:35:00Z",
      "updatedAt": "2024-01-15T10:35:00Z"
    }
  ]
}

Get Session

GET /api/session/{sessionId}

Retrieves a specific session and its messages.

Using JavaScript SDK:

const session = await client.session.getSession('session-789');

Update Session

PUT /api/session/{sessionId}

Updates session metadata or tool configurations.

Using JavaScript SDK:

const updatedSession = await client.session.updateSession('session-789', {
  metadata: {
    name: 'updated-session-name',
    status: 'in-review'
  }
});

Delete Session

DELETE /api/session/{sessionId}

Permanently deletes a session and all its tasks.

Using JavaScript SDK:

await client.session.deleteSession('session-789');

Messages

Send Message

POST /api/session/{sessionId}/messages

Sends a message to a session, which creates a new task automatically.

Using JavaScript SDK:

const message = await client.session.sendMessage('session-789', {
  content: 'Can you analyze the lab results for this patient?',
  role: 'user'
});

Request Body:

{
  "content": "Can you analyze the lab results for this patient?",
  "role": "user"
}

List Messages

GET /api/session/{sessionId}/messages

Retrieves all messages in a session.

Using JavaScript SDK:

const messages = await client.session.listMessages('session-789');

Get Message

GET /api/session/{sessionId}/messages/{messageId}

Retrieves a specific message.

Using JavaScript SDK:

const message = await client.session.getMessage('session-789', 'msg-001');

Update Message

PUT /api/session/{sessionId}/messages/{messageId}

Updates a message's content.

Using JavaScript SDK:

const updatedMessage = await client.session.updateMessage('session-789', 'msg-001', {
  content: 'Updated message content'
});

Delete Message

DELETE /api/session/{sessionId}/messages/{messageId}

Deletes a message from a session.

Using JavaScript SDK:

await client.session.deleteMessage('session-789', 'msg-001');

Tasks

Create Task

POST /api/sessions/{sessionId}/tasks

Executes a task within a session, sending a message to the AI Worker.

Using JavaScript SDK:

const task = await client.task.createTask('session-789', {
  model: 'openai/gpt-4',
  instructions: 'Analyze the recent lab results for patient-123 and identify any concerning values',
  additionalMessages: [
    {
      role: 'user',
      content: 'Focus on diabetes-related markers and provide specific recommendations'
    }
  ],
  temperature: 0.7,
  maxCompletionTokens: 1000,
  toolChoice: 'auto'
});

Request Body:

{
  "model": "openai/gpt-4",
  "instructions": "Analyze the recent lab results for patient-123 and identify any concerning values",
  "additionalMessages": [
    {
      "role": "user",
      "content": "Focus on diabetes-related markers and provide specific recommendations"
    }
  ],
  "temperature": 0.7,
  "maxCompletionTokens": 1000,
  "toolChoice": "auto"
}

Response:

{
  "success": true,
  "message": "Task created successfully",
  "data": {
    "id": "task-xyz",
    "workerId": "worker-456",
    "sessionId": "session-789",
    "endpointId": "endpoint-789",
    "status": "completed",
    "state": null,
    "additionalInstructions": "Focus on diabetes-related markers and provide specific recommendations",
    "completedAt": "2024-01-15T10:40:00.000Z",
    "log": [],
    "metadata": [
      {
        "analysis": "Based on the lab results for patient-123, I've identified several key findings..."
      }
    ],
    "startedAt": "2024-01-15T10:35:00.000Z",
    "expiresAt": null,
    "cancelledAt": null,
    "failedAt": null,
    "createdAt": "2024-01-15T10:35:00.000Z",
    "updatedAt": "2024-01-15T10:40:00.000Z"
  }
}

List Tasks

GET /api/sessions/{sessionId}/tasks

Retrieves all tasks for a session with pagination support.

Using JavaScript SDK:

const tasks = await client.task.listTasks('session-789', {
  limit: 20,
  after: 'task-123',
  before: 'task-456',
  order: 'desc'
});

Query Parameters:

• limit - Number of tasks to return (default: 20, max: 100)
• after - Cursor for pagination (task ID)
• before - Cursor for reverse pagination (task ID)
• order - Sort order (asc or desc, default: desc)

Get Task

GET /api/sessions/{sessionId}/tasks/{taskId}

Retrieves the result of a completed or running task.

Using JavaScript SDK:

const taskResult = await client.task.getTask('session-789', 'task-xyz');

Submit Tool Outputs

POST /api/sessions/{sessionId}/tasks/{taskId}/submit_tool_outputs

Submits tool outputs when a task requires tool execution and is waiting for outputs.

Using JavaScript SDK:

const task = await client.task.submitToolOutputs('session-789', 'task-xyz', {
  toolOutputs: [
    {
      toolCallId: 'call_abc123',
      output: JSON.stringify({
        patientData: {
          id: 'patient-123',
          name: 'John Doe',
          age: 34,
          diagnosis: 'Type 2 Diabetes'
        }
      })
    },
    {
      toolCallId: 'call_def456', 
      output: JSON.stringify({
        labResults: {
          hba1c: '8.2%',
          glucose: '145 mg/dL',
          status: 'elevated'
        }
      })
    }
  ]
});

Request Body:

{
  "toolOutputs": [
    {
      "toolCallId": "call_abc123",
      "output": "{\"patientData\":{\"id\":\"patient-123\",\"name\":\"John Doe\",\"age\":34,\"diagnosis\":\"Type 2 Diabetes\"}}"
    },
    {
      "toolCallId": "call_def456",
      "output": "{\"labResults\":{\"hba1c\":\"8.2%\",\"glucose\":\"145 mg/dL\",\"status\":\"elevated\"}}"
    }
  ]
}

Cancel Task

POST /api/sessions/{sessionId}/tasks/{taskId}/cancel

Cancels a running task.

Using JavaScript SDK:

const task = await client.task.cancelTask('session-789', 'task-xyz');

Resume Task

POST /api/sessions/{sessionId}/tasks/{taskId}/resume

Resumes a cancelled or paused task.

Using JavaScript SDK:

const task = await client.task.resumeTask('session-789', 'task-xyz');

Update Task

PUT /api/sessions/{sessionId}/tasks/{taskId}

Updates task metadata.

Using JavaScript SDK:

const task = await client.task.updateTask('session-789', 'task-xyz', {
  priority: 'high',
  department: 'cardiology'
});

Message Types and Content

Message Roles

• user: Messages from the user
• assistant: Messages from the AI Worker
• system: System messages (instructions, context)
• tool: Messages from tool executions

Message Content Types

Text Content

{
  "content": "Hello, how can I help you today?",
  "role": "assistant"
}

Rich Content with Annotations

{
  "content": [
    {
      "type": "text",
      "text": {
        "value": "Based on the patient's lab results, I found concerning values in the glucose levels.",
        "annotations": [
          {
            "type": "file_citation",
            "text": "Lab Report 2024-01-15",
            "file_citation": {
              "file_id": "file-123",
              "quote": "Glucose: 145 mg/dL (Normal: 70-100 mg/dL)"
            },
            "start_index": 45,
            "end_index": 65
          }
        ]
      }
    }
  ],
  "role": "assistant"
}

Image Content

{
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/xray-image.jpg",
        "detail": "high"
      }
    }
  ],
  "role": "user"
}

Task Status Values

Status	Description
queued	Task is waiting to be processed
in_progress	Task is currently being executed
requires_action	Task is waiting for tool outputs
cancelling	Task cancellation is in progress
cancelled	Task was cancelled
failed	Task execution failed
completed	Task completed successfully
incomplete	Task was incomplete (e.g., hit token limits)
expired	Task expired before completion

Common Use Cases

Clinical Consultation Session

// Create a session for clinical consultation
const session = await client.session.createSession({
  workerId: 'clinical-worker-123',
  metadata: {
    patientId: 'patient-456',
    consultationType: 'follow-up',
    department: 'cardiology'
  }
});

// Send initial message
const message = await client.session.sendMessage(session.data.id, {
  content: 'Please review the patient\'s recent echocardiogram results and provide recommendations.',
  role: 'user'
});

Lab Results Analysis

// Create task for lab analysis
const task = await client.task.createTask('session-789', {
  model: 'openai/gpt-4',
  instructions: 'Analyze the attached lab results and identify any abnormal values',
  additionalMessages: [
    {
      role: 'user',
      content: 'Patient is a 45-year-old male with diabetes. Focus on metabolic markers.'
    }
  ],
  toolChoice: 'auto',
  temperature: 0.3
});

Multi-step Workflow

// Create session for complex workflow
const session = await client.session.createSession({
  workerId: 'workflow-worker-123',
  metadata: {
    workflowType: 'patient-admission',
    priority: 'urgent'
  }
});

// Step 1: Initial assessment
await client.session.sendMessage(session.data.id, {
  content: 'Assess the patient\'s current condition based on vital signs',
  role: 'user'
});

// Step 2: Treatment planning
await client.session.sendMessage(session.data.id, {
  content: 'Based on the assessment, recommend treatment options',
  role: 'user'
});

Error Handling

{
  "success": false,
  "message": "Session not found",
  "data": null,
  "error": {
    "code": "session_not_found",
    "details": "Session with ID 'session-789' not found"
  }
}

Common Error Codes

• session_not_found: Session ID doesn't exist
• task_not_found: Task ID doesn't exist
• worker_not_found: Worker ID doesn't exist
• invalid_message_content: Message content is invalid
• task_already_completed: Cannot modify completed task
• tool_calls_required: Task requires tool outputs

Next Steps

• Workers - Create and manage AI Workers
• Knowledge Bases - Add domain knowledge to workers
• Models - Learn about available AI models
• Toolkits - Explore available tools and toolkits