Guía desarrolladores.

Documentación técnica para integrar Orkelia en tu stack or build your own vertical AI agents on our infrastructure. Public stack: Vercel Edge + Supabase Postgres + Anthropic Claude.

Stack técnica

  • Runtime · Vercel Edge Functions (Fluid Compute), Paris + Frankfurt regions
  • Database · Supabase Postgres 15, project ykafzpuxicvgatdluuel, region eu-west-3
  • LLM · Anthropic Claude Sonnet 4.6 (generation) + Haiku 4.5 (classification), zero retention
  • Embeddings · Voyage AI voyage-3
  • Email · Resend, per-workspace branded tracking domain
  • Auth · Supabase Auth (magic link + TOTP 2FA) · signed JWT, 7d rotation
  • Pricing model · usage-based, raw upstream cost visible client-side

API REST pública

Base URL: https://www.orkelia.com/api. Autenticación vía header Authorization: Bearer YOUR_API_KEY. Keys are generated in the workspace dashboard (rotation supported).

Workspaces

GET/api/workspaces
List workspaces accessible by your API key.
GET/api/workspaces/:id/config
Full workspace configuration (templates, value_props, FAQ, daily_cap).

Drafts & send

GET/api/drafts?workspace=&status=draft|approved|sent
List drafts per workspace, filterable by status.
POST/api/drafts/:id/approve
Approve draft for send. Auto-send picks up next cron cycle (10am UTC Mon-Fri).

Replies & classification

GET/api/replies?workspace=&intent=hot|warm|cold|unsubscribe
List replies classified by Claude Haiku per intent.

Agent conversations (Clinic/Restau/Transport)

POST/api/agent/message
Send message to agent and receive response. Body: { workspace_id, channel, content, sender_id }.
GET/api/conversations/:id/history
Full conversation history with prompts and tools used (audit log).

Webhooks salientes

Configura un endpoint in your workspace dashboard. Orkelia POSTs as application/json with HMAC SHA-256 signature in header X-Orkelia-Signature.

Eventos soportados

// Exhaustive list (v1)
draft.created      // A new draft was generated
draft.approved     // A draft was validated
email.sent         // An email was sent
email.opened       // Resend open tracking
email.clicked      // Resend click tracking
reply.received     // A reply was received
reply.classified   // Haiku classified intent
hot_lead.detected  // Automatic escalation
conversation.escalated// Agent handed off to human

Signature verification (Node.js)

import crypto from 'node:crypto';
const sig = req.headers['x-orkelia-signature'];
const expected = crypto.createHmac('sha256', process.env.ORKELIA_WEBHOOK_SECRET).update(JSON.stringify(req.body)).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
  return res.status(401).end();
}

MCP server (Model Context Protocol)

Orkelia exposes an official MCP server at https://www.orkelia.com/api/mcp to expose its tools to any MCP-compatible AI agent (Claude Code, Cursor, Cline, etc).

Exposed tools (workspace-scoped)

get_workspace_config(workspace_id)
list_prospects(workspace_id, filters?)
get_prospect_history(prospect_id)
create_draft(workspace_id, prospect_id, template_key, variables)
approve_draft(draft_id)
get_reply_classification(reply_id)
escalate_to_human(conversation_id, reason)
add_to_suppression_list(email, reason)
get_kpis(workspace_id, date_range)

Claude Code config

// ~/.claude/mcp.json
{
  "mcpServers": {
    "orkelia": {
      "transport": "http",
      "url": "https://www.orkelia.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Rate limits

  • Free / Trial · 60 req/min, 1,000 req/day
  • Essential · 300 req/min, 50,000 req/day
  • Pro · 1,000 req/min, 250,000 req/day
  • Group · Custom (negotiated)

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Returns 429 with Retry-After.

¿Pregunta técnica precisa?

El fundador responde directamente questions about the API, webhooks, MCP server. Respuesta <24h hábiles.

alexandre@orkelia.com