Skip to content
Keliplay Docs

Update a channel

PATCH
/v1/channels/{channelId}
curl --request PATCH \
  --url https://api.keliplay.com/v1/channels/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Homepage hero", "maxPlaysPerParticipantPerDay": null }'

Changes a channel’s name, status, between-campaigns message or play limits. Send only the fields you want to change, and at least one. Send null to clear a play limit or the between-campaigns message.

Set status to disabled to take a channel out of service. This keeps its history and can be undone.

Permission: channels.manage.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
channelId
required
string

The channel’s id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
>= 1 properties
name
string
>= 1 characters <= 200 characters
status
string
Allowed values: active disabled
betweenCampaigns
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

Most plays allowed per player. Null removes the limit. Leave out to keep the current value.

integer | null
>= 1 <= 10000
maxPlaysPerParticipantPerDay

Most plays allowed per player. Null removes the limit. Leave out to keep the current value.

integer | null
>= 1 <= 10000
playLimitTimezone

IANA time zone that decides when a day starts for the daily limit, such as Europe/London.

string
default: UTC >= 1 characters <= 64 characters
Example
{
  "name": "Homepage hero",
  "maxPlaysPerParticipantPerDay": null
}

Responses

Section titled “Responses”

200

Section titled “200”

The updated channel.

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
Example
{
  "channel": {
    "id": "0192f3a1-0000-7000-8000-00000000c001",
    "name": "Homepage hero",
    "status": "active",
    "betweenCampaigns": null,
    "maxPlaysPerParticipant": null,
    "maxPlaysPerParticipantPerDay": null,
    "playLimitTimezone": "Europe/London",
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-10-05T10:00:00.000Z"
  }
}

400

Section titled “400”

The request is not valid. details lists each field that failed, where there is one.

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": "invalid_request",
    "message": "Invalid request json.",
    "details": [
      {
        "path": "name",
        "message": "Too small, expected string to have >=1 characters"
      }
    ]
  }
}

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