🌐 Gateway HTTP API Reference

The PicoClaw gateway provides several HTTP endpoints for health monitoring, management, and direct chat interaction.

By default, the gateway listens on 127.0.0.1:18790.

💬 Chat API

The /chat endpoint allows you to interact with the PicoClaw agent via a simple HTTP interface. This API is designed to be asynchronous to avoid timeouts during long-running LLM tasks or tool executions.

1. Initiate a Chat Session (POST)

Start a new chat request.

<<<<<<< HEAD Endpoint: `POST /chat`

Endpoint: POST /chat

security_shield_v2 Content-Type: application/json

Request Body:

{
  "message": "What is the capital of France?",
  "session_id": "optional-custom-id"
}

Response (202 Accepted):

{
  "session_id": "chat-1711352400000",
  "status": "pending"
}

2. Poll for Results (GET)

Retrieve the status and response of a previously initiated session.

Endpoint: GET /chat?session_id=<ID>

Possible Responses:

Still processing (200 OK):

{
  "session_id": "chat-123",
  "status": "pending"
}

Completed (200 OK):

{
  "session_id": "chat-123",
  "status": "completed",
  "response": "The capital of France is Paris."
}

Error (500 Internal Server Error):

{
  "session_id": "chat-123",
  "status": "error",
  "error": "LLM call failed: context deadline exceeded"
}

💾 Data Persistence & Cleanup

Expiry: Completed or failed results are kept for 1 hour. Pending sessions are kept for 2 hours.
In-Memory: Results are stored in memory and are lost if the gateway process is restarted.

🛠️ Management Endpoints

Health Check

GET /health
Returns OK (200) if the server is running. Used for basic uptime monitoring.

Readiness Check

GET /ready
Returns OK (200) once the gateway and all enabled channels have successfully initialized.

Configuration Reload

POST /reload
Triggers a hot-reload of the .picoclaw/config.json file without restarting the process.

2.1 KiB Raw Blame History