Send Your First Message in 5 Minutes

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; staging keys are prefixed ak_test_ and production keys are prefixed ak_live_.
• 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_test_..."                  # 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 and exchange the staging key for a ak_live_* key.

Step 1: Create your first agent

Log in to your dashboard, click New Agent, name it my-first-agent, and save. The dashboard creates the agent record and provisions an API key tied to your tenant. Copy the API key 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 the /v1/agents endpoint for automating later, but for this tutorial the dashboard click-through is the fastest path.

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 and exchange your ak_test_* key for an ak_live_* key from the production dashboard.