Skip to main content

API Gateway

Expose Codebolt agent runs over HTTP so external systems, scripts, and services can trigger agents without knowing the WebSocket protocol.

When to Use​

  • You need a simple REST endpoint that triggers an agent run.
  • External services need to call Codebolt from a webhook or script.
  • You want to wrap Codebolt behind custom authentication.
  • You're building a backend service that orchestrates agent runs.

Approach: REST API​

The Codebolt server exposes a full REST API. External systems can call it directly to manage agents, tasks, projects, and more.

Start an agent​

curl -X POST http://localhost:2719/api/agent/startAgent \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "code-reviewer",
    "task": "Review the latest PR"
  }'

Search tasks​

curl -X POST http://localhost:2719/api/tasks/search \
  -H "Content-Type: application/json" \
  -d '{"status": "pending", "limit": 10}'

Get project info​

curl http://localhost:2719/api/projects/root

Git operations​

curl http://localhost:2719/api/git/status
curl -X POST http://localhost:2719/api/git/commit \
  -H "Content-Type: application/json" \
  -d '{"message": "automated commit"}'

Approach: Client SDK Wrapper​

Build a custom API server that wraps the Client SDK and adds your own auth, routing, or business logic.

import express from 'express';
import { CodeBoltClient } from '@codebolt/client-sdk';

const app = express();
const client = new CodeBoltClient({ host: 'localhost', port: 2719 });

app.use(express.json());

// Custom auth middleware
app.use((req, res, next) => {
  const apiKey = req.headers['x-api-key'];
  if (apiKey !== process.env.API_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});

// Start an agent run
app.post('/api/run', async (req, res) => {
  try {
    const result = await client.agents.startAgent({
      agentId: req.body.agentId,
      task: req.body.task,
    });
    res.json({ success: true, result });
  } catch (err: any) {
    res.status(500).json({ error: err.message });
  }
});

// Get tasks
app.get('/api/tasks', async (req, res) => {
  const result = await client.tasks.search({ limit: 50 });
  res.json(result);
});

app.listen(3000, () => console.log('API gateway on :3000'));

This gives you:

  • Custom authentication (API keys, OAuth, etc.)
  • Route different requests to different agents.
  • Rate limiting, logging, and monitoring.
  • A clean public API that hides Codebolt internals.

Approach: Channel Plugin​

For event-driven integrations (webhooks from external services), build a channel plugin:

  1. Receive the webhook in your plugin.
  2. Route to an agent via plugin.gateway.routeMessage().
  3. Handle the reply via plugin.gateway.onReply().
  4. Post the result back to the external service.

See Project Tool Integration for this pattern.

See Also​