Platform · API & webhooks

Integrate over HTTPS, not slides

Ship server-to-server chat, stream tokens to your own UI, and fire automations from webhooks that terminate on your FlexyAgents host. The routes below are the real Next.js handlers—copy values from Deployment after you generate a FlexyAgents API connection.

  • POST /api/agents/{agentId}/chat accepts Bearer tokens tied to the FlexyAgents automation-app connection, then runs the same RAG + model stack as the widget
  • Optional streaming returns newline-delimited JSON chunks while non-streaming responses collapse to a single assistant payload
  • Per-IP rate limits apply before plan checks; hosted plans still enforce token budgets and BYOK plans return explicit errors when a provider key is missing
  • Webhook triggers, channel callbacks, and outbound integrations share the same tenancy model—everything resolves to an organization and agent record
Read the docsDeveloper hub

Need keys first? Create a workspace and open Settings → API Keys or the agent's connection modal.

HTTP surfaces at a glance

Paths mirror the Next.js route tree. Replace placeholders with the agent ID and host from your deployment screen.

  • POST/api/agents/{agentId}/chat

    Agent chat & streaming

    Send a JSON body with a messages array (role + content) and optional stream flag. Bearer auth validates against the FlexyAgents API key you store on the agent connection; successful key auth resolves the organization automatically.

  • POST/api/webhooks/automations/...

    Automation trigger ingress

    Published automations can expose webhook URLs that deserialize payloads and call executeAutomation—useful when your own services need to kick off flows without OAuth.

  • GET/POST/api/webhooks/*

    Channel & provider webhooks

    Sibling routes under /api/webhooks handle WhatsApp, Instagram, Facebook Messenger, inbound email, and similar vendor callbacks so omnichannel deployments stay on your domain.

  • —Integrations → Webhooks

    Outbound delivery

    Configure signed outbound webhooks from the dashboard when you want FlexyAgents to push conversation or system events to your SIEM, data lake, or ticketing bridge.

Minimal non-streaming call

curl -X POST "https://YOUR_APP_HOST/api/agents/AGENT_ID/chat" \
  -H "Authorization: Bearer YOUR_FLEXYAGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}],"stream":false}'

Swap in the values copied from Deployment → API after you connect the FlexyAgents app on that agent.

Invoke

HTTPS-first chat with the same brain as the widget

The deployment screen copies a curl snippet against your live host. Under the hood the handler validates API keys with the automation connection store, loads behavior + knowledge, and increments usage like any other channel.

  • Messages array contract

    Bodies must include at least one chat turn. The executor trims history to the latest user message for retrieval while still accepting multi-turn arrays for future use.

    • Roles limited to user, assistant, or system in the validator
    • Attach metadata in headers only when documented—stick to the JSON contract first
    • Invalid shapes return 400 with Zod detail strings for faster debugging
    Open Deployment tab

  • Streaming mode

    Set stream: true to receive NDJSON chunks (one JSON object per line) that frontends can flush to UI as tokens arrive.

    • Ideal for mobile or desktop clients that want parity with the hosted widget
    • Errors mid-stream still serialize as JSON lines so parsers can recover
    • Disable streaming when proxies buffer responses aggressively

  • Bearer API keys vs session cookies

    Service accounts should use the FlexyAgents connection key generated per agent. Interactive testers can rely on authenticated dashboard sessions, but server-to-server calls should always use Bearer tokens.

    • Keys encrypt at rest alongside other automation credentials
    • Rotating a key does not change the agent ID in your URL
    • Invalid or missing keys return 401 before any model spend accrues
    Model billing context

  • Limits you will see in production

    Redis-backed rate limits return 429 when traffic spikes. Plan enforcement adds MESSAGE_LIMIT_REACHED for hosted/BYOK monthly caps and token ceilings for hosted inference.

    • Automations and chat share the same org-level accounting story
    • Log correlation IDs from error payloads when talking to support
    • Upgrade or add credits where billing allows additional throughput
    Usage & plans

Events

Bring your stack to FlexyAgents—and push events back out

Inbound routes normalize vendor signatures while outbound configuration lives next to other integrations. Automations can also POST arbitrary HTTP within a flow.

  • Automation webhook triggers

    When a flow publishes a webhook trigger, FlexyAgents stores the path segment and verifies payloads before calling executeAutomation with the parsed body.

    • Pair with agent steps that call Slack, CRMs, or custom REST endpoints
    • Feature gating may require upgraded plans before generic ingress is enabled
    • Logs surface in the same automation run history as OAuth triggers
    Automations overview

  • Channel provider callbacks

    WhatsApp, Instagram DMs, Messenger, and inbound email each register public HTTPS endpoints so Meta, Twilio, or mail providers can verify and deliver events.

    • Configure callback URLs in the vendor console to match your deployment host
    • Verification handshakes happen on the same routes as live traffic
    • Keeps compliance-sensitive payloads on infrastructure you already audit
    Channel deployments

  • Outbound HTTP actions

    Automation actions can POST or PUT to customer-owned URLs with templated bodies—think “notify Opsgenie” or “create Jira ticket” without waiting for a first-party connector.

    • Map trigger fields into JSON bodies with the automation builder
    • Retries and error handling follow automation executor defaults
    • Combine with agent steps for human-readable summaries before delivery

Reference

Specs, docs, and exploratory tools

Marketing pages stay narrative; engineers should rely on the docs site, inline OpenAPI definitions in the repo, and the deployment page snippets that always match your tenant IDs.

  • Documentation hub

    Start from /docs for conceptual guides, then cross-link to the developer-focused /api page for quick starts, authentication primers, and tabbed references when available.

    • Examples emphasize curl, JavaScript, and widget embed patterns
    • SDK and Postman promises should match whatever downloads we actually ship
    • Report gaps via support so we can align marketing and technical writers
    Open docs

  • OpenAPI source of truth

    The repository carries a comprehensive OpenAPI document describing auth schemes, chat payloads, and ancillary REST resources—generate clients or import into Postman from that file.

    • Versioning follows the package release cadence, not this landing page
    • Staging and production base URLs are enumerated in the spec servers list
    • Local developers hit the same /api/agents/{id}/chat path on localhost that production uses on your tenant host
    Developer API page

  • Widget & mobile companions

    Not every experience needs raw REST—the embeddable script calls the same chat endpoint with visitor context. Pair API access with the widget when you want web self-service plus backend jobs.

    • Hosted pages reuse the agent configuration you already tested
    • CSP and cookie policies should allow the widget origin you configure
    • Deep links from email can open hosted chat with query parameters
    Web surfaces

Pair APIs with Automations, Channels, and governance on Analytics.

Next step

Copy a working curl, then harden for production

Generate the FlexyAgents connection key, paste it into your secret store, and aim automation webhooks at the paths you own. When you are ready, wire observability into the same analytics workspace your success team already uses.

Try it freeBook a demo