Skip to content
Keliplay Docs

Get a channel

GET
/v1/channels/{channelId}
curl --request GET \
  --url https://api.keliplay.com/v1/channels/example \
  --header 'Authorization: Bearer <token>'

Returns one channel and its campaigns in timeline order. A campaign with no start time comes first, then the rest by start time.

Permission: campaigns.read.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
channelId
required
string

The channel’s id.

Responses

Section titled “Responses”

200

Section titled “200”

The channel and its campaigns.

Media typeapplication/json
object
channel
required
object
id
required
string
name
required
string
status
required
string
Allowed values: active disabled
betweenCampaigns
required
One of:

What the channel shows when no campaign is live.

object
title
string
<= 120 characters
body
string
<= 600 characters
imageUrl

An https URL, or a file from your media library.

string
<= 2048 characters
maxPlaysPerParticipant
required

Plays allowed per player across every campaign on this channel.

integer | null
maxPlaysPerParticipantPerDay
required

Plays allowed per player per day across every campaign on this channel.

integer | null
playLimitTimezone
required
string
createdAt
required
string format: date-time
updatedAt
string format: date-time
campaigns
required
Array<object>

A campaign as listed on its channel’s timeline.

object
id
required
string
name
required
string
status
required
  • draft: being set up. Players cannot see it.
  • active: live on its channel, during its live window.
  • paused: hidden for now. Plays and results are kept.
  • archived: finished and put away. Can be restored.
string
Allowed values: draft active paused archived
gameSlug
required
string
liveFrom
required
string | null format: date-time
liveUntil
required
string | null format: date-time
prize
required
One of:

What the campaign is giving away, as shown to winners.

object
label
required
string
>= 1 characters
description
string
externalRef

Your own reference for the prize, such as a SKU.

string
winnerSelectionTrigger
required

When winners are drawn.

  • manual: when you call the draw operation.
  • auto_on_session_end: after each play ends.
  • auto_on_schedule: once, at scheduleAt.
string
default: manual
Allowed values: manual auto_on_session_end auto_on_schedule
Example
{
  "channel": {
    "id": "0192f3a1-0000-7000-8000-00000000c001",
    "name": "Homepage banner",
    "status": "active",
    "betweenCampaigns": null,
    "maxPlaysPerParticipant": null,
    "maxPlaysPerParticipantPerDay": 3,
    "playLimitTimezone": "Europe/London",
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z"
  },
  "campaigns": [
    {
      "id": "0192f3a1-0000-7000-8000-0000000ca001",
      "name": "Autumn wheel",
      "status": "active",
      "gameSlug": "spin-wheel",
      "liveFrom": "2026-10-01T00:00:00.000Z",
      "liveUntil": "2026-10-31T23:59:59.000Z",
      "prize": {
        "label": "Free coffee"
      },
      "winnerSelectionTrigger": "manual"
    }
  ]
}

401

Section titled “401”

The API key is missing, malformed or revoked.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key."
  }
}

403

Section titled “403”

The API key does not carry the permission this needs, or the request is not allowed.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "forbidden",
    "message": "Your role does not allow this (draws.run)."
  }
}

404

Section titled “404”

Nothing with that id exists in your account.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "not_found",
    "message": "Channel 0192f3a1-0000-7000-8000-00000000c009 not found."
  }
}

Product tour, pricing and demos: keliplay.com