Glossary

A common vocabulary to understand Shara’s documentation, organized into topic blocks. Each term links, where applicable, to the guide where it’s covered in depth. Missing a concept? Write to us at support@aiginer.com.

The glossary is split into blocks: consumption and billing, agents and orchestration, models, security and control, integration (API, webhooks, connectors) and operation (multi-tenant, auditing, licensing). Terms marked with a link have a dedicated guide; the rest are defined here in a self-contained way.

Shara bills for abstract consumption: you never pay for “a provider’s tokens”, but for a single, stable unit of your own. This decouples your invoice from the specific model used underneath and from market price changes.

Mental rule: quota is what you’ve already paid, overage is what you pay extra if you go over, and rollover is what you rescue from a slow month. The kill-switch is the brake that prevents surprises.

Shara isn’t a single chatbot: it’s a team of specialized agents coordinated by an orchestrator. The client talks to just one; the rest work in the background. See Agents.

Shara never exposes the real provider behind a model. It works with stable aliases that abstract power and cost, so we can swap providers underneath without your integration or your invoice ever knowing. See No vendor lock-in.

Control isn’t optional: Shara is designed so that nothing important ever runs without supervision and spending never spikes without a brake. See What Shara is.

The public API is the surface an external developer uses to integrate Shara with their systems. It authenticates with an API key and applies usage limits. See API and Connectors.

# Example of an API-key-authenticated call (Authorization header)
curl -X POST https://api.aiginer.com/v1/messages \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Summarize the latest support ticket and suggest a reply.",
    "idempotency_key": "req_2026-06-16_001"
  }'

Shara exposes signed inbound webhooks: an external system (your CRM, a form, another automation…) signs an event and POSTs it to Shara, which verifies the signature and hands it to the configured agent. There are no outbound webhooks via event subscription: the model is external → Shara, not the other way around.

The public endpoint and its canonical headers:

POST /webhooks/inbound/{slug}
Content-Type: application/json
X-SHARA-Signature: <hmac-hex>      # signature of the raw body (HMAC-SHA256 by default)
X-SHARA-Timestamp: <unix-seconds>  # anti-replay (±300 s); required if the webhook declares it
X-SHARA-Event-Id: <unique-id>      # idempotency (X-Event-Id, X-Request-Id… also accepted)

Body example (you define it; Shara verifies it, audits it and delivers it to the agent):

{
  "event": "lead.created",
  "id": "evt_9f2c1ab7",
  "occurred_at": "2026-06-16T09:30:00Z",
  "contact": {
    "name": "Marta Ruiz",
    "email": "marta@example.com",
    "phone": "+34600111222",
    "company": "Example SL"
  },
  "source": "landing-form"
}

Correct response (200) and idempotent variant when you resend the same X-SHARA-Event-Id:

// 200: event accepted and queued for the agent
{ "ok": true, "code": "ok", "eventId": "8b1d…-uuid", "runId": "run_…-uuid" }

// 200: duplicate: Shara already processed it, doesn't run again
{ "ok": true, "code": "duplicate", "eventId": "8b1d…-uuid" }

Possible errors (without leaking internals):

How to sign it on the sending side (Node). The HMAC is calculated over the exact raw body you’re about to send, not over a re-serialized JSON:

import { createHmac } from 'node:crypto';

const secret = process.env.SHARA_WEBHOOK_SECRET;     // per-tenant secret, never in the client
const rawBody = JSON.stringify(payload);             // the SAME bytes you send
const timestamp = Math.floor(Date.now() / 1000);     // unix-seconds, for anti-replay

const signature = createHmac('sha256', secret)
  .update(rawBody)
  .digest('hex');                                    // lowercase hex, 64 chars

await fetch('https://api.aiginer.com/webhooks/inbound/my-slug', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-SHARA-Signature': signature,
    'X-SHARA-Timestamp': String(timestamp),
    'X-SHARA-Event-Id': payload.id,                  // idempotency
  },
  body: rawBody,
});

Retries: Shara doesn’t retry ingestion; it responds synchronously. If you get a 5xx or a timeout, you retry, reusing the same X-SHARA-Event-Id: idempotency guarantees the execution isn’t duplicated.

Looking for a concept in more depth? Start with What Shara is, STU and quotas, API or Connectors.