Skip to content
MeridFlow AiFlow v8.x • self-hosted

Quickstart

This walks through your first real call against your own AiFlow deployment: confirm it's reachable, then send it an event.

1. Confirm your deployment is reachable

GET /health needs no authentication. It's a good first check that your base URL is correct and the server is up.

curl https://api.your-domain.com/health

import httpx

response = httpx.get("https://api.your-domain.com/health")
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.your-domain.com/health");
console.log(await response.json());

{ "status": "ok" }

2. Get an API key

Everything past this point needs an API key. Keys are created by an admin, not something you can self-serve from a quickstart, so ask whoever administers your deployment for one scoped to events:write. See Authentication for the full picture of how keys and scopes work.

3. Send your first event

With a key in hand, post an event to a specific agent. 1 below stands in for that agent's agent_id: your admin team tells you which id to use. See Agents & channels for why that id shows up in the path.

curl -X POST https://api.your-domain.com/api/v1/agents/1/events \
  -H "Authorization: Bearer af_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
        "event_type": "test_event",
        "payload": {"message": "hello from my integration"}
      }'

import httpx

response = httpx.post(
    "https://api.your-domain.com/api/v1/agents/1/events",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "event_type": "test_event",
        "payload": {"message": "hello from my integration"},
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://api.your-domain.com/api/v1/agents/1/events",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      event_type: "test_event",
      payload: { message: "hello from my integration" },
    }),
  },
);
console.log(await response.json());

A successful call returns 201 Created:

{
  "event_id": 42,
  "matched": false,
  "call_ids": []
}

matched: false is expected the first time

matched is true only if the event matched a trigger your admin team has configured on that agent, and call_ids is populated only when a trigger placed an outbound call. matched: false just means the event was recorded and nothing acted on it, which is completely normal if no trigger is configured yet. Setting up a trigger is an admin-dashboard step: see Triggers & events for what determines a match.

What's next