Send your first event

Building an autonomous agent or backend integration?

This is the developer path — raw HTTP against the Angareion API. If you just want to connect a chat assistant (Claude, ChatGPT, Gemini), you don't need any of this — see Connect your AI tool instead.

This tutorial walks you through publishing your first event to Angareion and confirming the platform accepted it. You will use raw HTTP — no Angareion SDK install — so you can prove the path end-to-end before committing to a client library. Plan on five minutes from a fresh terminal.

Prerequisites

You need:

• An Angareion account. Sign up at angareion.com.
• An API key. Create one from your dashboard's API Keys page. Keys are prefixed ak_live_ and do not vary by environment — only the API URL does.
• One of:
  • Python 3.9+ with pip available, or
  • Node.js 18+ (for the native fetch and crypto.randomUUID used in the TypeScript tab).

You do not need to install an Angareion SDK for this tutorial. The Python and TypeScript snippets use raw HTTP. SDK-based quickstarts ship in a future release.

Set two environment variables before running anything below — every code sample reads them at runtime:

export ANGAREION_API_URL="https://api.angareion.dev"   # staging; production is https://api.angareion.com
export ANGAREION_API_KEY="ak_live_..."                  # paste from your dashboard

The rest of the tutorial walks against staging (https://api.angareion.dev). When you are ready to ship, swap the URL to production — the same ak_live_ key format is used in both environments.

Step 1: Create your first agent

Log in to your dashboard, open Agents, and click Register an agent. Name it my-first-agent and save — this creates the agent record in your tenant.

Then get an API key from your dashboard's API Keys page (keys are prefixed ak_live_) and copy it into ANGAREION_API_KEY. You will not see the secret again after closing the modal.

You do not need to call any API to create the agent — the dashboard is the canonical surface for agent creation. The API exposes /v1/agents for automating this later.

Step 2: Send a message

Publish a CloudEvents 1.0 envelope to POST $ANGAREION_API_URL/v1/events. Pick the language tab that matches your environment — the picker remembers your choice across the rest of the docs.

curl

curl -X POST "$ANGAREION_API_URL/v1/events" \
  -H "Authorization: Bearer $ANGAREION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "specversion": "1.0",
    "type": "agent.message",
    "source": "my-app",
    "id": "'$(uuidgen)'",
    "subject": "my-first-agent",
    "data": {"content": "Hello from Angareion!"}
  }'

Python (httpx)

# pip install httpx
import os, uuid, httpx

resp = httpx.post(
    f"{os.environ['ANGAREION_API_URL']}/v1/events",
    headers={"Authorization": f"Bearer {os.environ['ANGAREION_API_KEY']}"},
    json={
        "specversion": "1.0",
        "type": "agent.message",
        "source": "my-app",
        "id": str(uuid.uuid4()),
        "subject": "my-first-agent",
        "data": {"content": "Hello from Angareion!"},
    },
)
resp.raise_for_status()
print(resp.json())  # → {"event_id": "...", "status": "accepted"}

TypeScript (fetch)

// Node 18+; no dependencies
const resp = await fetch(`${process.env.ANGAREION_API_URL}/v1/events`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ANGAREION_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    specversion: '1.0',
    type: 'agent.message',
    source: 'my-app',
    id: crypto.randomUUID(),
    subject: 'my-first-agent',
    data: { content: 'Hello from Angareion!' },
  }),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

A 202 Accepted response with {"event_id": "...", "status": "accepted"} confirms the platform ingested your event. Save the event_id — you will use it in the next step.

Step 3: Confirm delivery

Fetch the event back by ID to verify it landed in your tenant. Replace $EVENT_ID with the event_id from Step 2's response.

curl

curl "$ANGAREION_API_URL/v1/events/$EVENT_ID" \
  -H "Authorization: Bearer $ANGAREION_API_KEY"

Python (httpx)

import os, httpx

event_id = "..."  # paste from Step 2's response

resp = httpx.get(
    f"{os.environ['ANGAREION_API_URL']}/v1/events/{event_id}",
    headers={"Authorization": f"Bearer {os.environ['ANGAREION_API_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

TypeScript (fetch)

const eventId = '...'; // paste from Step 2's response

const resp = await fetch(
  `${process.env.ANGAREION_API_URL}/v1/events/${eventId}`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.ANGAREION_API_KEY}`,
    },
  },
);
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());

A 200 OK response with the original CloudEvents envelope (plus a server-assigned time and event_id) confirms the event is durably stored and visible to subsequent reads. If you get a 404, the event has not yet been ingested — wait a moment and retry.

What's Next

You have published your first event. From here:

• Authentication guide — exchange API keys for short-lived JWTs and rotate keys safely.
• Messaging guide — declare interests, poll the delivery queue, ACK deliveries, and subscribe channels to event globs.
• Memory guide — store, search, and promote agent memories using the platform's graph + vector store.
• External Events guide — ingest webhooks and handle the dead-letter queue.
• Error Reference — every error envelope, code, and remediation in one place.

When you are ready to ship to production, swap ANGAREION_API_URL to https://api.angareion.com. Your ak_live_ key format is the same in both environments — only the URL changes.