Eventos e streams - Base de conhecimento

Live

O objeto evento

Campo	Tipo	Descrição
id	string	Identificador único do objeto.
type	string	Valores possíveis: one-time, recurring

Criar evento

POST https://api.kinescope.io/v2/live/events

Cria um evento ao vivo. O evento fica no estado draft até ser agendado e ativado.

Criar um evento

Campo	Tipo	Descrição
name	string	Nome do evento. Obrigatório
type	string	Valores possíveis: recurring, one-time. Obrigatório
parent_id	UUID	ID do projeto ou da pasta do evento. Não obrigatório
auto_start	boolean	Início automático da transmissão. Padrão false. Não obrigatório
protected	boolean	Ativa a criptografia da transmissão. Padrão false. Não obrigatório
time_shift	boolean	Padrão false. Não obrigatório
reconnect_window	integer	Padrão 600 segundos. Não obrigatório
scheduled	object	Configurações do evento agendado. Chaves disponíveis — 'time'. 'time' — hora de início da transmissão. Não obrigatório
record	object	Configurações para salvar os vídeos depois do fim da transmissão. Não obrigatório. Chaves disponíveis — 'parent_id'. 'parent_id' — ID do projeto ou da pasta onde o vídeo vai ficar depois do fim da transmissão. Não obrigatório
video	object	Configurações do vídeo. Não obrigatório. Chaves disponíveis — 'presets'. 'presets' — array de strings. Escolha as qualidades dos vídeos. Valores possíveis — 360p 480p 720p 1080p 1440p 2160p. Não obrigatório
restreams	[]object{}	Não obrigatório. Cada objeto tem as chaves — "name", "url", "key", "description", "enabled". "name" — string. Obrigatório. "url" — string. Obrigatório. "key" — string. Obrigatório. "description" — string. Não obrigatório. "enabled" — boolean. Não obrigatório
latency_mode	string	Valores possíveis: standard, reduced. Padrão 'standard'. Não obrigatório.
show_members	bool	Exibir/ocultar os participantes do chat. Padrão true.
chat_active	bool	Chat ativado/desativado depois do fim da transmissão. Padrão false.
chat_after_stream	bool	Exibir/ocultar o chat depois do fim da transmissão. Padrão true.
chat_preview	bool	Exibir/ocultar o chat na pré-visualização do vídeo. Padrão true.
privacy_type	string	Onde o player pode ser incorporado. Valores possíveis: anywhere, nowhere, custom. Não obrigatório
privacy_domains	[]string	Domínios onde o player pode ser incorporado. Obrigatório se privacy_type for custom
privacy_email_domains	[]string	Domínios de e-mail dos espectadores que podem assistir, por exemplo `company.com`. Não obrigatório
privacy_share	object	Quem pode assistir. Chaves disponíveis: "password", "link_hash", "sso". Um objeto vazio significa qualquer pessoa com o link. Não obrigatório
unique_codes_enabled	boolean	Acesso por códigos únicos. Padrão false. Quando true, "privacy_share" é redefinido. Não obrigatório

As chaves de privacy_share:

Campo	Tipo	Descrição
password	string	O espectador digita esta senha para assistir. No mínimo 2 caracteres. Não pode ser usado junto com "link_hash"
link_hash	string	Acesso somente por link privado. 6 letras ou dígitos. O link pronto é retornado em "link"
sso	boolean	Acesso pelo SSO do workspace. Disponível somente se o SSO estiver ativado no workspace

Se você não enviar nenhum campo de privacidade, o evento herda as configurações de privacidade do projeto.

A resposta abaixo não corresponde à requisição: reconnect_window volta como 1800 em vez dos 600 enviados, chat_active como true em vez de false e video.presets como null. Se o API normaliza esses valores ou se o exemplo está desatualizado não foi apurado — o exemplo fica como registrado até a confirmação do time de Live.

Request body (json)

{
  "name": "New event",
  "type": "recurring",
  "auto_start": true,
  "protected": false,
  "time_shift": false,
  "parent_id": "<UUID>",
  "reconnect_window": 600,
  "scheduled": {
    "time": "2022-12-19T00:05:41.634922Z"
  },
  "record": {
    "parent_id": "<UUID>"
  },
  "video": {
    "presets": [
      "360p",
      "1080p"
    ]
  },
  "restreams": [
    {
      "name": "Restream 1",
      "url": "rtmp://rtmp.kinescope.io/live",
      "key": "stream key"
    }
  ],
  "latency_mode": "standard",
  "show_members": true,
  "chat_active": false,
  "chat_after_stream": true,
  "chat_preview": true,
  "privacy_type": "custom",
  "privacy_domains": [
    "example.com"
  ],
  "privacy_share": {
    "password": "my password"
  }
}

Responses

{
  "data": {
    "id": "<UUID>",
    "workspace_id": "<UUID>",
    "parent_id": "<UUID>",
    "name": "New event",
    "subtitle": "New subtitle",
    "type": "recurring",
    "streamkey": "a6739c5535504feaa45da338dc62f752",
    "auto_start": true,
    "protected": false,
    "time_shift": false,
    "chat_after_stream": true,
    "chat_active": true,
    "record": {
      "parent_id": "<UUID>"
    },
    "video": {
      "presets": null
    },
    "audio": {
      "channel_mapping": null
    },
    "restreams": [
      {
        "id": "<UUID>",
        "event_id": "<UUID>",
        "name": "Restream 1",
        "url": "rtmp://rtmp.kinescope.io/live",
        "key": "stream key",
        "status": "disconnected",
        "enabled": true,
        "description": "",
        "created_at": "2022-11-15T12:25:04.095926Z",
        "updated_at": null
      }
    ],
    "reconnect_window": 1800,
    "play_link": "https://kinescope.io/bK3mQx7ZtNvRs2WdYpLc9F",
    "rtmp_link": "rtmp://rtmp.kinescope.io/live",
    "scheduled": {
      "time": "2022-12-19T00:05:41.634922Z"
    },
    "stream": {
      "id": "<UUID>",
      "event_id": "<UUID>",
      "status": "pending",
      "started_at": "2022-12-19T00:05:41.634922Z",
      "finished_at": null
    },
    "created_at": "2022-11-15T12:25:04.095926Z",
    "updated_at": null,
    "latency_mode": "standard",
    "privacy_type": "custom",
    "privacy_domains": [
      "example.com"
    ],
    "privacy_email_domains": [],
    "privacy_share": {
      "password": "my password"
    },
    "unique_codes_enabled": false,
    "poster": {
      "id": "<UUID>",
      "type": "image",
      "status": "done",
      "active": true,
      "original": "https://static.kinescopecdn.net/assets/event_default_poster.png",
      "md": "https://static.kinescopecdn.net/assets/event_default_poster.png",
      "sm": "https://static.kinescopecdn.net/assets/event_default_poster.png",
      "xs": "https://static.kinescopecdn.net/assets/event_default_poster.png",
      "from_time": 0,
      "to_time": 0
    }
  }
}

curl -X POST \
  'https://api.kinescope.io/v2/live/events' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "New event",
  "type": "recurring",
  "auto_start": true,
  "protected": false,
  "time_shift": false,
  "parent_id": "<UUID>",
  "reconnect_window": 600,
  "scheduled": {
    "time": "2022-12-19T00:05:41.634922Z"
  },
  "record": {
    "parent_id": "<UUID>"
  },
  "video": {
    "presets": [
      "360p",
      "1080p"
    ]
  },
  "restreams": [
    {
      "name": "Restream 1",
      "url": "rtmp://rtmp.kinescope.io/live",
      "key": "stream key"
    }
  ],
  "latency_mode": "standard",
  "show_members": true,
  "chat_active": false,
  "chat_after_stream": true,
  "chat_preview": true,
  "privacy_type": "custom",
  "privacy_domains": [
    "example.com"
  ],
  "privacy_share": {
    "password": "my password"
  }
}'

Agendar nova transmissão

POST https://api.kinescope.io/v2/live/events/:event_id/stream

Agenda uma nova transmissão dentro do evento. Retorna a URL de recebimento e a chave de transmissão.

Request body (json)

{
  "started_at": "2022-11-15T12:42:00.991558Z"
}

Responses

{
  "data": {
    "id": "<UUID>",
    "event_id": "<UUID>",
    "status": "pending",
    "started_at": "2022-11-15T12:42:00.991558Z",
    "finished_at": null
  }
}

curl -X POST \
  'https://api.kinescope.io/v2/live/events/:event_id/stream' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "started_at": "2022-11-15T12:42:00.991558Z"
}'

Enviar pôster

POST https://uploader.kinescope.io/v2/poster

Envia uma imagem de pôster personalizada para um evento ao vivo.

Cabeçalhos

Parâmetro	Descrição
`X-Event-ID`	`4iUMUmb63dLAvnbsMRkSUX`
`X-Poster-URL`	`url do pôster`

Obter evento

GET https://api.kinescope.io/v2/live/events/:event_id

Retorna os dados de um evento ao vivo pelo seu identificador único.

Responses

{
  "data": {
    "id": "<UUID>",
    "workspace_id": "<UUID>",
    "parent_id": "<UUID>",
    "name": "Novo evento",
    "subtitle": "",
    "type": "one-time",
    "streamkey": "5cbb30742b9b4a02971abd4cdd7fb22f",
    "auto_start": false,
    "protected": false,
    "time_shift": true,
    "record": {
      "parent_id": null
    },
    "video": {
      "presets": []
    },
    "audio": {
      "channel_mapping": null
    },
    "restreams": [
      {
        "id": "<UUID>",
        "event_id": "<UUID>",
        "name": "23234",
        "url": "rtmp://rtmp.kinescope.io/live",
        "key": "23234234",
        "status": "disconnected",
        "enabled": false,
        "description": "",
        "created_at": "2026-03-03T10:55:22.991595Z",
        "updated_at": "2026-03-03T11:10:05.345611Z"
      }
    ],
    "reconnect_window": 600,
    "play_link": "https://kinescope.io/0cxfXwkKh4Wzzd1boAnQFE",
    "rtmp_link": "rtmp://rtmp.kinescope.io/live",
    "scheduled": {
      "time": null
    },
    "stream": {
      "id": "<UUID>",
      "event_id": "<UUID>",
      "status": "pending",
      "started_at": "2026-02-18T17:50:37.774745Z",
      "finished_at": null
    },
    "chat_after_stream": true,
    "chat_active": true,
    "chat_preview": true,
    "show_members": true,
    "created_at": "2026-02-18T17:50:37.774745Z",
    "updated_at": "2026-03-14T11:23:19.777707Z",
    "latency_mode": "standard",
    "allow_chat_links": false,
    "moderators": null,
    "privacy_type": "anywhere",
    "privacy_domains": [],
    "privacy_email_domains": [],
    "privacy_share": {},
    "unique_codes_enabled": false,
    "poster": {
      "id": "<UUID>",
      "type": "image",
      "media_id": "<UUID>",
      "status": "done",
      "active": true,
      "original": "https://kinescopecdn.net/<UUID>/posters/<UUID>/<UUID>.jpg",
      "md": "https://kinescopecdn.net/<UUID>/posters/<UUID>/md/<UUID>.jpg",
      "sm": "https://kinescopecdn.net/<UUID>/posters/<UUID>/sm/<UUID>.jpg",
      "xs": "https://kinescopecdn.net/<UUID>/posters/<UUID>/xs/<UUID>.jpg",
      "from_time": 0,
      "to_time": 0
    }
  }
}

{
  "error": {
    "code": 400404,
    "message": "not found"
  }
}

Listar eventos

GET https://api.kinescope.io/v2/live/events

Retorna a lista de eventos ao vivo. Os resultados são paginados e podem ser filtrados por parâmetros de consulta.

Responses

{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 100,
      "total": 0
    },
    "order": {
      "created_at": "desc",
      "name": "asc"
    }
  },
  "data": []
}

curl -X GET \
  'https://api.kinescope.io/v2/live/events?page=1&per_page=100&order=created_at.desc,name.asc&folder_id=<UUID>&project_id=<UUID>&without_folder=true' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Vídeos do evento

GET https://api.kinescope.io/v2/live/events/:event_id/videos

Retorna as gravações geradas pelo evento, ordenadas por data de criação.

Responses

{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 0
    },
    "order": {
      "created_at": "desc"
    }
  },
  "data": []
}

QoS do evento

GET https://api.kinescope.io/v2/live/events/:event_id/qos

Retorna as estatísticas de qualidade de serviço do stream do evento junto com a última sessão conhecida do publisher — host RTMP, IP do cliente e país da conexão mais recente. É usado o stream atual; para um evento recorrente já encerrado, é usado o stream mais recente.

A janela de tempo assume por padrão o tempo de vida do stream — de started_at até finished_at (ou agora, para um stream em andamento) — e é limitada às últimas 12 horas dessa janela.

Parâmetros de query:

stream_id — retorna os dados de um stream específico deste evento em vez do atual (ou, para um evento recorrente encerrado, do mais recente) (opcional). Um stream de outro evento ou workspace não é acessível: a requisição responde 404 Not Found com código 404404;
from — início da janela, YYYY-MM-DD ou RFC 3339 YYYY-MM-DDTHH:MM:SSZ (opcional, ver acima);
to — fim da janela, mesmos formatos (opcional, ver acima);
group_time — tamanho do intervalo da série (opcional): 1m ou minute, hour, day, week, month, ou uma duração como 30s ou 5m. Padrão: 30 segundos.

status:

4 — diferença de tempo entre quadros-chave > 50%
3 — diferença de tempo entre quadros-chave > 20%
5 — perda de pacotes (causas possíveis: problemas de rede ou o codificador do streamer não dá conta do vídeo)

session é null quando não há sessão registrada para o stream. qos é o próprio array de eventos (array vazio quando não há dados para a janela).

Responses

{
  "session": {
    "host": "rtmp.kinescope.io",
    "client_ip": "1.2.3.4",
    "country": "RU"
  },
  "qos": [
    {
      "frame_rate": 30,
      "bitrate_video": 2438,
      "bitrate_audio": 156,
      "timestamp": "2026-03-07T09:01:30Z",
      "status": 0,
      "packet_loss": 0
    },
    {
      "frame_rate": 30,
      "bitrate_video": 2438,
      "bitrate_audio": 156,
      "timestamp": "2026-03-07T09:02:00Z",
      "status": 0,
      "packet_loss": 0
    }
  ]
}

{
  "error": {
    "code": 404404,
    "message": "no such entity"
  }
}

Chat

GET https://api.kinescope.io/v2/live/events/:event_id/stream/:stream_id/chat(.json|.csv|.txt)

Retorna o registro do chat do evento no formato solicitado — JSON, CSV ou texto puro.

Responses

{
  "data": [
    {
      "id": "<UUID>",
      "username": "example_user",
      "external_id": "kinescope_admin_e3ec44ca-8d9f-4ca9-a36f-69bfcae502a7",
      "is_admin": "true",
      "message": "ewd",
      "created_at": "2025-02-26T08:16:38.21562Z",
      "cteated_at_local": "2025-02-26T08:16:38.21562Z"
    },
    {
      "id": "<UUID>",
      "username": "example_user",
      "external_id": "kinescope_admin_e3ec44ca-8d9f-4ca9-a36f-69bfcae502a7",
      "is_admin": "true",
      "message": "wde",
      "created_at": "2025-02-26T08:16:38.722139Z",
      "cteated_at_local": "2025-02-26T08:16:38.722139Z"
    },
    {
      "id": "<UUID>",
      "username": "example_user",
      "external_id": "kinescope_admin_e3ec44ca-8d9f-4ca9-a36f-69bfcae502a7",
      "is_admin": "true",
      "message": "wde",
      "created_at": "2025-02-26T08:16:39.12707Z",
      "cteated_at_local": "2025-02-26T08:16:39.12707Z"
    },
    {
      "id": "<UUID>",
      "username": "example_user",
      "external_id": "kinescope_admin_e3ec44ca-8d9f-4ca9-a36f-69bfcae502a7",
      "is_admin": "true",
      "message": "wde",
      "created_at": "2025-02-26T08:16:39.451017Z",
      "cteated_at_local": "2025-02-26T08:16:39.451017Z"
    },
    {
      "id": "<UUID>",
      "username": "asasas",
      "external_id": "<UUID>",
      "is_admin": "false",
      "message": "dcad",
      "created_at": "2025-02-26T08:17:56.752304Z",
      "cteated_at_local": "2025-02-26T08:17:56.752304Z"
    }
  ]
}

Atualizar evento

PUT https://api.kinescope.io/v2/live/events/:event_id

Atualiza as propriedades de um evento ao vivo (título, descrição, horário agendado, retransmissões e outras).

Somente os campos enviados na requisição são alterados. Os campos de privacidade são os mesmos de Criar evento: privacy_type, privacy_domains, privacy_email_domains, privacy_share, unique_codes_enabled. O evento só pode ser atualizado enquanto a transmissão estiver no status pending.

Para liberar o acesso por códigos únicos, defina unique_codes_enabled como true e gere os códigos em Criar lote de códigos únicos. Se você definir unique_codes_enabled como false, os espectadores que digitaram um código perdem o acesso.

Request body (json)

{
  "name": "Update event",
  "privacy_share": {
    "link_hash": "Ab12Cd"
  }
}

Responses

{
  "data": {
    "id": "<UUID>",
    "workspace_id": "<UUID>",
    "parent_id": "<UUID>",
    "name": "Update event",
    "subtitle": "Update subtitle",
    "type": "recurring",
    "streamkey": "a6739c5535504feaa45da338dc62f752",
    "auto_start": true,
    "protected": false,
    "time_shift": false,
    "chat_after_stream": true,
    "record": {
      "parent_id": "<UUID>"
    },
    "video": {
      "presets": null
    },
    "audio": {
      "channel_mapping": null
    },
    "restreams": [
      {
        "id": "<UUID>",
        "event_id": "<UUID>",
        "name": "Restream 1",
        "url": "rtmp://rtmp.kinescope.io/live",
        "key": "stream key",
        "status": "disconnected",
        "enabled": true,
        "description": "",
        "created_at": "2022-11-15T12:25:04.095926Z",
        "updated_at": null
      }
    ],
    "reconnect_window": 1800,
    "play_link": "https://kinescope.io/bK3mQx7ZtNvRs2WdYpLc9F",
    "rtmp_link": "rtmp://rtmp.kinescope.io/live",
    "scheduled": {
      "time": "2023-12-19T00:05:41.634922Z"
    },
    "stream": {
      "id": "<UUID>",
      "event_id": "<UUID>",
      "status": "pending",
      "started_at": "2023-12-19T00:05:41.634922Z",
      "finished_at": null
    },
    "created_at": "2022-11-15T12:25:04.095926Z",
    "updated_at": "2022-11-15T12:30:53.449823Z",
    "latency_mode": "standard",
    "privacy_type": "anywhere",
    "privacy_domains": [],
    "privacy_email_domains": [],
    "privacy_share": {
      "link_hash": "Ab12Cd",
      "link": "https://kinescope.io/bK3mQx7ZtNvRs2WdYpLc9F/plAb12Cd"
    },
    "unique_codes_enabled": false,
    "poster": {
      "id": "<UUID>",
      "type": "image",
      "status": "done",
      "active": true,
      "original": "https://static.kinescopecdn.net/assets/event_default_poster.png",
      "md": "https://static.kinescopecdn.net/assets/event_default_poster.png",
      "sm": "https://static.kinescopecdn.net/assets/event_default_poster.png",
      "xs": "https://static.kinescopecdn.net/assets/event_default_poster.png",
      "from_time": 0,
      "to_time": 0
    }
  }
}

curl -X PUT \
  'https://api.kinescope.io/v2/live/events/:event_id' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Update event",
  "privacy_share": {
    "link_hash": "Ab12Cd"
  }
}'

Ativar evento

PUT https://api.kinescope.io/v2/live/events/:event_id/enable

Ativa o evento para que as transmissões possam ser recebidas e reproduzidas.

Encerrar evento

PUT https://api.kinescope.io/v2/live/events/:event_id/complete

Marca o evento como concluído. Os endpoints de recebimento param de aceitar transmissões.

Atualizar agendamento da transmissão

PUT https://api.kinescope.io/v2/live/events/:event_id/stream

Atualiza o agendamento de uma transmissão futura (hora de início, duração prevista).

Request body (json)

{
  "started_at": "2024-11-15T12:42:00.991558Z"
}

Responses

{
  "data": {
    "id": "<UUID>",
    "event_id": "<UUID>",
    "status": "pending",
    "started_at": "2024-11-15T12:42:00.991558Z",
    "finished_at": null
  }
}

curl -X PUT \
  'https://api.kinescope.io/v2/live/events/:event_id/stream' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "started_at": "2024-11-15T12:42:00.991558Z"
}'

Mover evento

PUT https://api.kinescope.io/v2/live/events/:event_id/move

Move o evento para outro projeto ou outra pasta.

Request body (json)

{
  "parent_id": "<UUID>"
}

Responses

{
  "data": {
    "id": "<UUID>",
    "workspace_id": "<UUID>",
    "parent_id": "<UUID>",
    "name": "Update event",
    "type": "recurring",
    "streamkey": "a6739c5535504feaa45da338dc62f752",
    "auto_start": true,
    "protected": false,
    "time_shift": false,
    "chat_after_stream": true,
    "chat_active": true,
    "record": {
      "parent_id": "<UUID>"
    },
    "video": {
      "presets": null
    },
    "audio": {
      "channel_mapping": null
    },
    "restreams": [
      {
        "id": "<UUID>",
        "event_id": "<UUID>",
        "name": "Restream 1",
        "url": "rtmp://rtmp.kinescope.io/live",
        "key": "stream key",
        "status": "disconnected",
        "enabled": true,
        "description": "",
        "created_at": "2022-11-15T12:25:04.095926Z",
        "updated_at": null
      }
    ],
    "reconnect_window": 1800,
    "play_link": "https://kinescope.io/bK3mQx7ZtNvRs2WdYpLc9F",
    "rtmp_link": "rtmp://rtmp.kinescope.io/live",
    "scheduled": {
      "time": null
    },
    "stream": {
      "id": "<UUID>",
      "event_id": "<UUID>",
      "status": "pending",
      "started_at": "2024-11-15T12:42:00.991558Z",
      "finished_at": null
    },
    "created_at": "2022-11-15T12:25:04.095926Z",
    "updated_at": "2022-11-15T12:46:31.301738Z",
    "latency_mode": "standard"
  }
}

curl -X PUT \
  'https://api.kinescope.io/v2/live/events/:event_id/move' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "parent_id": "<UUID>"
}'

Excluir evento

DELETE https://api.kinescope.io/v2/live/events/:event_id

Exclui o evento ao vivo permanentemente. A ação não pode ser desfeita.

Unique codes

Os códigos únicos restringem o acesso ao evento: o espectador digita um código antes de assistir. Os códigos são gerados em lotes. Um evento pode ter até 9999 códigos ativos.

Criar lote de códigos únicos

POST https://api.kinescope.io/v2/live/events/:event_id/unique-codes

Gera um lote de códigos únicos para o evento. Cada código tem 3 letras e 3 dígitos, por exemplo KQX482. O primeiro lote ativa unique_codes_enabled no evento.

Campo	Tipo	Descrição
name	string	Nome do lote, até 255 caracteres. Deve ser único dentro do evento. Obrigatório
codes_amount	integer	Quantidade de códigos, de 1 a 9999. Obrigatório
max_count	integer	Quantas vezes cada código pode ser usado, de 1 a 9999. Não obrigatório, sem limite por padrão
sessions_per_code	integer	Sessões por código, de 1 a 100. Não obrigatório, sem limite por padrão
starts_at	string	Data a partir da qual os códigos valem, `YYYY-MM-DD`. Não pode estar no passado. Padrão: hoje. Não obrigatório
expires_at	string	Data até a qual os códigos valem, `YYYY-MM-DD`. Não pode ser anterior a starts_at. Não obrigatório, sem expiração por padrão

Request body (json)

{
  "name": "Promo batch",
  "codes_amount": 100,
  "max_count": 5,
  "sessions_per_code": 1,
  "starts_at": "2026-10-01",
  "expires_at": "2026-10-31"
}

Responses

{
  "data": {
    "id": "<UUID>",
    "entity_id": "<UUID>",
    "name": "Promo batch",
    "codes_count": 100,
    "used_count": 0,
    "max_count": 5,
    "sessions_per_code": 1,
    "starts_at": "2026-10-01T00:00:00Z",
    "expires_at": "2026-10-31T00:00:00Z",
    "created_at": "2026-09-24T09:40:12.123456Z"
  }
}

curl -X POST \
  'https://api.kinescope.io/v2/live/events/:event_id/unique-codes' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Promo batch",
  "codes_amount": 100,
  "max_count": 5,
  "sessions_per_code": 1,
  "starts_at": "2026-10-01",
  "expires_at": "2026-10-31"
}'

Listar lotes de códigos únicos

GET https://api.kinescope.io/v2/live/events/:event_id/unique-codes

Retorna os lotes de códigos únicos do evento. Os resultados são paginados. used_count é a quantidade de códigos ativados pelo menos uma vez.

Responses

{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 1
    }
  },
  "data": [
    {
      "id": "<UUID>",
      "entity_id": "<UUID>",
      "name": "Promo batch",
      "codes_count": 100,
      "used_count": 12,
      "max_count": 5,
      "sessions_per_code": 1,
      "starts_at": "2026-10-01T00:00:00Z",
      "expires_at": "2026-10-31T00:00:00Z",
      "created_at": "2026-09-24T09:40:12.123456Z"
    }
  ]
}

Obter lote de códigos únicos

GET https://api.kinescope.io/v2/live/events/:event_id/unique-codes/:batch_id

Retorna um lote de códigos únicos.

Responses

{
  "data": {
    "id": "<UUID>",
    "entity_id": "<UUID>",
    "name": "Promo batch",
    "codes_count": 100,
    "used_count": 12,
    "max_count": 5,
    "sessions_per_code": 1,
    "starts_at": "2026-10-01T00:00:00Z",
    "expires_at": "2026-10-31T00:00:00Z",
    "created_at": "2026-09-24T09:40:12.123456Z"
  }
}

Baixar códigos únicos

GET https://api.kinescope.io/v2/live/events/:event_id/unique-codes/:batch_id/download

Baixa os códigos do lote em um arquivo CSV. As datas de ativação ficam no fuso horário do workspace. A coluna "Usage Limit" aparece somente se o lote tiver max_count.

Responses

sep=,
Code,Activation Date,Times Used,Usage Limit
KQX482,2026-10-02T12:15:04+03:00,1,5
BMT907,,0,5

Excluir lote de códigos únicos

DELETE https://api.kinescope.io/v2/live/events/:event_id/unique-codes/:batch_id

Exclui o lote e todos os seus códigos. Os espectadores que digitaram esses códigos perdem o acesso. Quando o último lote é excluído, unique_codes_enabled é desativado no evento.

Responses

{
  "data": {
    "success": true
  }
}