Get started with the REST API

The Eventdoor REST API lets your own scripts and tools work with the hubs and broadcasts of your organizations. You call it with a scoped API credential that you issue in the admin.

A credential can call 12 operations: list and read hubs, and list, read, create, update and bulk-change broadcasts. The API reference lists every operation that accepts a credential; no other operation does.

How the API is organizedCopy Anchor Link

Platform
└── Organization        /organizations/{orgSlug}
    ├── Broadcast       /organizations/{orgSlug}/broadcasts/{broadcastSlug}
    └── Hub             /organizations/{orgSlug}/hubs/{hubSlug}
        └── Broadcast   /organizations/{orgSlug}/hubs/{hubSlug}/broadcasts/{broadcastSlug}

Every path starts with /organizations/{orgSlug}. Paths scoped to a hub add /hubs/{hubSlug}.

Before you startCopy Anchor Link

• You must be an owner or admin of the organization to issue its credential. A platform-wide credential is issued by a platform admin. See Who can issue a credential.
• You need your organization's slug. It is the first part of the admin's address while that organization is selected: in /acme/settings/integrations, the slug is acme. An organization's page in the admin also shows it as Slug under Details.

Make your first callCopy Anchor Link

https://<your platform's API host>/eventdoor/api/v1

export EVENTDOOR_API="https://<your platform's API host>/eventdoor/api/v1"
export EVENTDOOR_TOKEN="<the token you copied>"

curl -s -H "Authorization: Bearer $EVENTDOOR_TOKEN" \
  "$EVENTDOOR_API/organizations/acme/hubs"

{
  "hubs": [
    {
      "id": "6f1c2a9e-0b7d-4c1e-9a52-3d8e4f7a1b20",
      "slug": "home-games",
      "name": "Home games"
    }
  ],
  "total": 1,
  "paging": { "next": null, "hasMore": false }
}

Next stepsCopy Anchor Link

List the broadcasts in a hubCopy Anchor Link

List broadcasts in a hub:

curl -s -H "Authorization: Bearer $EVENTDOOR_TOKEN" \
  "$EVENTDOOR_API/organizations/acme/hubs/home-games/broadcasts"

Create a broadcastCopy Anchor Link

Create a broadcast with a Read and write credential. title is required. Keep it to 72 characters: a longer title is not refused, but only its first 72 characters are stored. A startsAt, if you send one, must be in the future, or the call is refused with 422. A new broadcast returns 201. A 400 on tagIds can arrive after the broadcast was created, since the tags are checked once it is saved: list the hub's broadcasts and look for the title before you create it again.

curl -s -X POST \
  -H "Authorization: Bearer $EVENTDOOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"vs Celtics"}' \
  "$EVENTDOOR_API/organizations/acme/hubs/home-games/broadcasts"

Learn the rulesCopy Anchor Link

• Authentication: what each access level may do, scope, expiry and revoking.
• Errors and rate limits: what each refusal means and how to retry.

Your platform's interactive referenceCopy Anchor Link

In the admin, Settings > Integrations has an API reference button. It opens your platform's own interactive copy of the reference, where Try it calls your platform directly.