REST API & Webhooks Reference

Pitaj.io provides a robust, enterprise-grade REST API empowering engineers to integrate autonomous agent reasoning directly into backend microservices, mobile apps, or internal business portals.

Base Architecture & Conventions

Base URL: https://api.pitaj.io/v1
Payload Format: application/json (UTF-8)
Authentication: All API requests require a secret workspace key passed in the Authorization header:

Authorization: Bearer pitaj_sec_live_98a7b6c5d4e3f210

1. Chat Completion (`POST /chat`)

Submit a visitor prompt and retrieve an authoritative answer synthesized against your Knowledge Base:

curl -X POST https://api.pitaj.io/v1/chat \
  -H "Authorization: Bearer pitaj_sec_live_98a7b6c5d4e3f210" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_01h9x8y7z6",
    "conversation_id": "conv_998877",
    "message": "What are the store hours for your Austin location?",
    "stream": false
  }'

const response = await fetch('https://api.pitaj.io/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pitaj_sec_live_98a7b6c5d4e3f210',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_id: 'agt_01h9x8y7z6',
    conversation_id: 'conv_998877',
    message: 'What are the store hours for your Austin location?'
  })
});

const data = await response.json();
console.log(data.response.text);

import requests

url = "https://api.pitaj.io/v1/chat"
headers = {
    "Authorization": "Bearer pitaj_sec_live_98a7b6c5d4e3f210",
    "Content-Type": "application/json"
}
payload = {
    "agent_id": "agt_01h9x8y7z6",
    "conversation_id": "conv_998877",
    "message": "What are the store hours for your Austin location?"
}

res = requests.post(url, json=payload, headers=headers)
print(res.json()["response"]["text"])

Response (200 OK)

{
  "id": "msg_01h9xyz123",
  "conversation_id": "conv_998877",
  "created_at": "2026-10-28T10:14:02Z",
  "response": {
    "text": "Our Austin showroom (400 Congress Ave) is open Monday through Friday from 8:00 AM to 5:00 PM CT, and Saturdays from 9:00 AM to 2:00 PM CT.",
    "model": "pro-v2",
    "sources": [
      {
        "title": "Store Locations & Hours",
        "url": "https://brand.com/locations"
      }
    ]
  },
  "credits_used": 2
}

2. Querying Captured Leads (`GET /leads`)

Retrieve paginated records collected via Lead Capture Forms:

curl -X GET "https://api.pitaj.io/v1/leads?agent_id=agt_01h9x8y7z6&limit=50" \
  -H "Authorization: Bearer pitaj_sec_live_98a7b6c5d4e3f210"

3. Webhooks & Cryptographic Signature Verification

Pitaj.io delivers HTTP POST requests upon key platform events:

lead.captured: A prospect submitted an interactive contact form.
ticket.escalated: A session requested human agent handover.
conversation.completed: A user concluded a chat or submitted CSAT feedback.

Verifying the `X-Pitaj-Signature` Header

Each payload includes an HMAC-SHA256 signature in the X-Pitaj-Signature header:

import crypto from 'crypto';

function verifyWebhook(payload: string, signatureHeader: string, secret: string): boolean {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expectedSignature)
  );
}