API

Introduction

The API connector exposes a single POST /api/message endpoint authenticated with a Bearer token. It's the only connector that runs synchronously — the agent's reply is returned in the same HTTP response, with no queue in between. Use it for webhooks, internal tools, and any client that wants a request-response shape.

Setup

Run the connector wizard:

php artisan laraclaw:setup-connector api

It generates a 64-character random token, stores its SHA-256 hash in laraclaw_accounts, prints the plaintext token once, and sets:

LARACLAW_API_ENABLED=true

!WARNING The plaintext token is only printed once. Save it somewhere safe. If you lose it, re-run the wizard to generate a new one.

Authentication

Every request must include the token as a Bearer header:

Authorization: Bearer YOUR_TOKEN

The middleware hashes the incoming token and looks it up in laraclaw_accounts. Anything that doesn't match returns 401.

Sending a Message

POST /api/message accepts the following parameters:

curl -X POST https://your-app.com/api/message \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "What's on my calendar tomorrow?"}'

The response:

{
  "success": true,
  "text": "You have a 9am standup and a 2pm dentist appointment.",
  "key": "550e8400-e29b-41d4-a716-446655440000",
  "attachments": []
}

Continuing a Conversation

Pass the key from a previous response in your next request to continue the same conversation:

curl -X POST https://your-app.com/api/message \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Reschedule the dentist to next week.",
    "key": "550e8400-e29b-41d4-a716-446655440000"
  }'

Omit the key to start a new conversation. Each token can hold any number of independent conversations.

Attachments

Files uploaded as multipart form data are saved to the attachments disk and made available to the agent the same way Telegram and Slack uploads are. Outbound attachments produced by tools come back in the response under the attachments key, each entry pointing at a file on the attachments disk.

The reply does not delete outbound files — your client is responsible for fetching them and any cleanup.