Events API

An event is the StreamLayer entity linked to your stream — usually one game or broadcast. Everything you configure in StreamLayer Studio (games, promotions, features) hangs off an event, and your app opens an SDK session with that event's id.

Use the Events API to create events from your own scheduling system instead of creating them by hand in Studio. You give each event your own id (providerId), so you can address it later without storing the StreamLayer id.

📘

Full schema reference

Every field, response schema, and error is documented in the Events API OpenAPI reference.

Base URL and authentication

https://api.streamlayer.io/datasets

Authenticate every request with your Private API Key, sent as a bearer token:

Authorization: Bearer {PRIVATE_API_KEY}

Find the key in Studio under Settings → Developer → Private API Key. This is not the SDK Key you put in your app — keep the Private API Key on your server and never ship it in a client.

All endpoints are POST with a JSON body, except GET /get, which takes query parameters. Every request is scoped to the organization that owns the key, and kind is always "event".

Event ids

Every endpoint that targets one event takes an id. You can pass either:

• Your provider id — the string you sent in event.raw.providerId on create, or
• The StreamLayer id — the numeric id returned in data.event.id on create.

Create an event

POST /create

Required fields

Minimal request

curl --location 'https://api.streamlayer.io/datasets/create' \
  --header 'Authorization: Bearer {PRIVATE_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "kind": "event",
    "event": {
      "raw": {
        "providerId": "match-2026-11-01-atl-mia"
      }
    }
  }'

With only a providerId, the event is scheduled for the time of the request, its status is 1 (pregame), and its name is set to Event YYYY-MM-DD.

Request with optional fields

curl --location 'https://api.streamlayer.io/datasets/create' \
  --header 'Authorization: Bearer {PRIVATE_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "kind": "event",
    "event": {
      "raw": {
        "providerId": "match-2026-11-01-atl-mia"
      },
      "scheduled": "2026-11-01T14:00:00.000Z",
      "status": 1,
      "venue": {
        "city": "Atlanta",
        "country": "USA",
        "stadium": "State Farm Arena"
      },
      "customFields": {
        "name": "ATL vs MIA",
        "logo": "https://example.com/logos/atl-mia.png"
      }
    }
  }'

Optional fields

Response

The new event is returned in data.event. Store data.event.id if you want to address the event by its StreamLayer id. Abbreviated example:

{
  "data": {
    "event": {
      "id": 4467,
      "attributes": {
        "id": 4467,
        "scheduled": "2026-11-01T14:00:00.000Z",
        "status": 1,
        "customFields": "{\"name\":\"ATL vs MIA\",\"logo\":\"https://example.com/logos/atl-mia.png\"}",
        "venue": { "city": "Atlanta", "country": "USA", "stadium": "State Farm Arena" }
      },
      "meta": {
        "created": "2026-10-05T12:00:00.000Z",
        "updated": "2026-10-05T12:00:00.000Z"
      }
    }
  }
}

Note that customFields comes back as a stringified JSON object.

If an event with the same providerId already exists in your organization, the API returns 409.

Update an event

POST /update

Only the fields you send are changed. Accepts the same event fields as create, except season.

curl --location 'https://api.streamlayer.io/datasets/update' \
  --header 'Authorization: Bearer {PRIVATE_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "kind": "event",
    "id": "match-2026-11-01-atl-mia",
    "event": {
      "status": 2,
      "startTime": "2026-11-01T14:05:00.000Z"
    }
  }'

Get an event

GET /get?kind=event&id={id}

URL-encode the id if your provider id contains spaces or special characters.

curl --location 'https://api.streamlayer.io/datasets/get?kind=event&id=match-2026-11-01-atl-mia' \
  --header 'Authorization: Bearer {PRIVATE_API_KEY}'

Returns the event in data.event, including data.event.meta.raw with your provider id. Returns 404 if no event with that id belongs to your organization.

List events

POST /list

curl --location 'https://api.streamlayer.io/datasets/list' \
  --header 'Authorization: Bearer {PRIVATE_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "kind": "event"
    },
    "sort": {
      "field": "scheduled",
      "order": "DESC"
    },
    "pagination": {
      "page": 1,
      "pageSize": 20
    }
  }'

The response returns events in data (an array) and the total number of matches, ignoring pagination, in meta.count.

Query conditions

query narrows the list further. Each operator takes an array of { "key", "value" } conditions:

Example — events scheduled in November 2026:

{
  "filter": { "kind": "event" },
  "query": {
    "between": [
      { "key": "scheduled", "value": ["2026-11-01T00:00:00.000Z", "2026-11-30T23:59:59.999Z"] }
    ]
  }
}

Remove an event

POST /remove

Detaches the event from your organization. The underlying event record is kept.

curl --location 'https://api.streamlayer.io/datasets/remove' \
  --header 'Authorization: Bearer {PRIVATE_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "kind": "event",
    "id": 4467
  }'

Event status values

status is always returned as an integer.

Errors

Errors return JSON with statusCode, error, and message.

Related

• Managing Events — Create and configure events in StreamLayer Studio
• Developer Settings — Find your SDK Key and Private API Key
• Events API OpenAPI reference — Full request and response schemas