Agora docs
Getting started

Add Agora to your product.

From zero to a working community in five steps. You'll mint an API key, create a community, project an end-user as an actor, and post your first piece of content.

1

Enable Agora on your workspace

Open the Agora area in the console. If your workspace doesn't have Agora enabled yet, you'll be prompted to turn it on (workspace owners only). This is what gates every customer-backend call — without the service enabled, every Agora endpoint returns 403 SERVICE_NOT_ENABLED.

2

Create a community (standalone or Heimdall-backed)

From the console, click New community. Pick a display name and a slug — that's enough for a standalone community. Standalone communities are independent: you manage actor external_ids however you like (your own user table, opaque IDs, etc.).

If you already authenticate end-users via Heimdall, tick Connect to a Heimdall app in the modal and pick one of your apps. Agora will verify the app belongs to the same workspace (cross-tenant gate, enforced server-side), and actors will then map 1:1 to Heimdall end-users via their account UUID. Either way, the community ends up in the same place — the integration is purely about how you source actor identity.

bash
# Standalone — no Heimdall app needed
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "content-type: application/json" \
  -d '{
    "slug": "my-community",
    "display_name": "My Community"
  }' \
  https://agora.productcraft.co/v1/workspaces/<workspaceId>/communities

# Heimdall-backed — agora verifies the app is in your workspace
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "content-type: application/json" \
  -d '{
    "app_id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "my-community",
    "display_name": "My Community"
  }' \
  https://agora.productcraft.co/v1/workspaces/<workspaceId>/communities

3

Mint a Platform API Key

All Agora customer-backend calls authenticate with a workspace Platform API Key. Open Workspace settings → API keys, create one, and lock its policy to the communities you intend to use. Keys are pcft_live_* prefixed.

4

Project an end-user as an actor

Before any post, follow, or comment can be created, the actor has to exist. Upsert is idempotent on (community, external_id); the second call with the same id returns created: false. The response carries the agora actor.id (a UUID) — keep it on your side, every downstream call below keys off it.

bash
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "content-type: application/json" \
  -d '{
    "external_id": "user_42",
    "display_name": "Alice",
    "avatar_url": "https://cdn.example.com/avatars/alice.png"
  }' \
  https://agora.productcraft.co/v1/communities/<communityId>/actors

# response: { "actor": { "id": "770a8600-...", ... }, "created": true }

5

Create your first post

With the actor in place, you can post on their behalf. Pass the agora actor.id from step 4 as actor_id. Posts ride a single primitive — set kind to text, link, image, or story. Stories add an expires_at for the 24h-disappearing UX:

bash
curl -X POST -H "Authorization: Bearer pcft_live_..." \
  -H "content-type: application/json" \
  -d '{
    "actor_id": "770a8600-0000-0000-0000-000000000001",
    "kind": "story",
    "body": "shipping today",
    "attributes": { "media_url": "https://cdn.example.com/stories/1.jpg" },
    "expires_at": "2026-05-02T12:00:00Z",
    "visibility": "close_friends"
  }' \
  https://agora.productcraft.co/v1/communities/<communityId>/posts

Next

Where to go from here

  • API reference — every endpoint with request and response schemas.
  • Feeds — GET /actors/:actorId/feed serves a ranked, algorithmic timeline by default. Pass order=chronological for time-ordered. Tune ranking weights per-community via community.settings.ranking.
  • Notifications — GET /actors/:actorId/notifications returns the per-actor inbox; producers fire automatically when someone follows, reacts, comments, or votes.
  • Stories — GET /actors/:actorId/story-tray gives the Instagram-style author tray. View tracking, polls, highlights, close-friends visibility, and private replies are all in the API reference.
  • Moderation — flags fire from POST /communities/:c/flags; the moderation queue and audit log live in the console.
Open the API referenceBack to the console