OpenAPI YAMLOpenAPI JSONproblemas YAMLVisão geral da API
Este grupo tem 9 operações, geradas a partir de api/openapi.yaml. Filtre por caminho, ação ou autenticação. Cada endpoint lista suas entradas; expanda-o para ver um modelo de solicitação e os códigos de resposta. Os modelos precisam de seus próprios valores e de um corpo válido conforme o esquema.
Substitua os espaços reservados em maiúsculas pelos seus valores. Para uma solicitação JSON, salve um corpo que corresponda ao esquema em request.json. Exemplos de cookies usam um jar local de cookies de uma sessão autenticada.
Webhooks: entrega de eventos assinados
Listar webhooks
Lista as notificações de webhook do projeto no formato de webhook, mais antigas primeiro (no máximo 50); GET /api/notifications lista todos os canais. O segredo de assinatura nunca é retornado aqui. Exige a capacidade de projeto; uma credencial somente de relatórios é recusada com 403 forbidden, porque a resposta inclui URLs de receptores.
Parâmetros
| Nome | Enviar | Obrigatório? | Descrição |
|---|---|---|---|
| ScreenRig-Project | cabeçalho | opcional | Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token. |
Modelo e respostas da solicitação
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks'Respostas
| Status | Significado | Corpo e cabeçalhos |
|---|---|---|
| 200 | Os webhooks do projeto. | WebhookList (application/json) |
| padrão | Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico. | Problema (application/problem+json) |
Criar webhook
Cria um webhook que recebe os próprios eventos duráveis do projeto como POSTs HTTPS assinados. A URL deve ser https em um host público da Internet: um literal IP ou toda resposta DNS atual do nome deve ser pública (privada, loopback, link-local, CGNAT, IPv6 fora de 2000::/3, documentação e outras faixas reservadas são recusadas com webhook_url_rejected).
A porta deve ser 443 (padrão) ou 8443, caso contrário webhook_url_rejected. O host é resolvido e verificado novamente antes de cada entrega e a conexão é feita exatamente para o endereço verificado, então uma resposta DNS que muda depois não pode redirecionar entregas. event_types lista tipos exatos de eventos (screen.online) ou prefixos terminando em .* (screen.*).
Uma organização tem no máximo 50 notificações, em todos os canais (webhook_limit_reached). O servidor gera o segredo de assinatura e o retorna apenas nesta resposta e em rotate-secret; guarde-o. Repetir a requisição exatamente igual, com o mesmo Idempotency-Key, retorna esta mesma resposta, com o segredo, por vinte e quatro horas.
A entrega começa com o primeiro evento depois de notification.created.
Parâmetros
| Nome | Enviar | Obrigatório? | Descrição |
|---|---|---|---|
| ScreenRig-Project | cabeçalho | opcional | Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token. |
| Idempotency-Key | cabeçalho | opcional | Omitir para uma operação nova. Forneça e reutilize uma chave para deduplicar tentativas; o CLI gerencia as chaves automaticamente. |
Campos do corpo da solicitação
| Campo | Descrição |
|---|---|
| url (obrigatório, string) | URL https em um host público na Internet, porta 443 (padrão) ou 8443. Sem informações de usuário ou fragmento. maxLength: 2048 formato: "uri" |
| event_types (obrigatório, WebhookEventTypes) | Tipos de evento exatos, como screen.online, ou prefixos terminados em .*, como screen.* (todo tipo que começa com screen.). notification.test nunca é distribuído por uma assinatura; é enviado apenas por POST /api/webhooks/{id}/test. |
| habilitado (opcional, boolean) | padrão: true |
| descrição (opcional, string) | maxLength: 200 |
Modelo e respostas da solicitação
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webhooks'Respostas
| Status | Significado | Corpo e cabeçalhos |
|---|---|---|
| 201 | Criado. O segredo é mostrado apenas aqui e na rotação do segredo. | WebhookWithSecret (application/json); cabeçalhos: Cache-Control |
| 400 | invalid_request ou webhook_url_rejected. | Problema (application/problem+json) |
| 409 | webhook_limit_reached, idempotency_mismatch ou resource_conflict quando o projeto não pertence a nenhuma organização. | Problema (application/problem+json) |
| padrão | Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico. | Problema (application/problem+json) |
Obter webhook
Exige a capacidade do projeto; uma credencial somente para relatórios é recusada com 403 proibido, porque a resposta inclui URLs do receptor.
Parâmetros
| Nome | Enviar | Obrigatório? | Descrição |
|---|---|---|---|
| ScreenRig-Project | cabeçalho | opcional | Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token. |
| id | caminho | obrigatório |
Modelo e respostas da solicitação
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID'Respostas
| Status | Significado | Corpo e cabeçalhos |
|---|---|---|
| 200 | Um webhook. | Webhook (application/json); cabeçalhos: ETag |
| padrão | Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico. | Problema (application/problem+json) |
Atualizar webhook
Altera qualquer um de url, event_types, enabled e description (uma descrição vazia limpa ela). Uma nova url é verificada como na criação.
Definir enabled true em um webhook desativado limpa seu estado de falha e inicia a entrega no evento que registra a mudança; eventos enquanto estava desativado não são reproduzidos, e entregas pendentes anteriores à desativação falham com webhook_disabled. Definir enabled false falha as entregas pendentes com webhook_disabled.
Registra notification.updated. If-Match protege a revisão.
Parâmetros
| Nome | Enviar | Obrigatório? | Descrição |
|---|---|---|---|
| ScreenRig-Project | cabeçalho | opcional | Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token. |
| id | caminho | obrigatório | |
| If-Match | cabeçalho | opcional | Revisão positiva opcional do recurso. Omitir para escrever o recurso atual; uma revisão obsoleta fornecida é revision_conflict. |
| Idempotency-Key | cabeçalho | opcional | Omitir para uma operação nova. Forneça e reutilize uma chave para deduplicar tentativas; o CLI gerencia as chaves automaticamente. |
Campos do corpo da solicitação
| Campo | Descrição |
|---|---|
| url (opcional, string) | maxLength: 2048 format: "uri" |
| event_types (opcional, WebhookEventTypes) | Tipos de evento exatos, como screen.online, ou prefixos terminados em .*, como screen.* (todo tipo que começa com screen.). notification.test nunca é distribuído por uma assinatura; é enviado apenas por POST /api/webhooks/{id}/test. |
| habilitado (opcional, boolean) | |
| descrição (opcional, string) | Uma string vazia limpa a descrição. maxLength: 200 |
Modelo e respostas da solicitação
curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webhooks/RESOURCE_ID'Respostas
| Status | Significado | Corpo e cabeçalhos |
|---|---|---|
| 200 | Webhook atualizado. | Webhook (application/json); cabeçalhos: ETag |
| 400 | invalid_request ou webhook_url_rejected. | Problema (application/problem+json) |
| 412 | revision_conflict — If-Match está desatualizado; a current_revision do erro contém a revisão atual. | Problema (application/problem+json) |
| padrão | Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico. | Problema (application/problem+json) |
Excluir webhook
Exclui o webhook e registra notification.deleted. Suas entregas pendentes são marcadas como falhas com webhook_deleted; seu registro de entregas deixa de estar acessível e expira com a retenção de eventos.
Parâmetros
| Nome | Enviar | Obrigatório? | Descrição |
|---|---|---|---|
| ScreenRig-Project | cabeçalho | opcional | Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token. |
| id | caminho | obrigatório | |
| If-Match | cabeçalho | opcional | Revisão positiva opcional do recurso. Omitir para escrever o recurso atual; uma revisão obsoleta fornecida é revision_conflict. |
| Idempotency-Key | cabeçalho | opcional | Omitir para uma operação nova. Forneça e reutilize uma chave para deduplicar tentativas; o CLI gerencia as chaves automaticamente. |
Modelo e respostas da solicitação
curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID'Respostas
| Status | Significado | Corpo e cabeçalhos |
|---|---|---|
| 204 | Excluído. | sem corpo; cabeçalhos: Cache-Control |
| 412 | revision_conflict — If-Match está desatualizado; a current_revision do erro contém a revisão atual. | Problema (application/problem+json) |
| padrão | Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico. | Problema (application/problem+json) |
Rotacionar segredo do webhook
Substitui o segredo de assinatura e retorna o novo; o segredo antigo deixa de assinar imediatamente: toda tentativa que assina depois que esta operação é confirmada usa o novo segredo, e no máximo uma tentativa por webhook já em andamento ainda pode chegar assinada com o antigo, então aceite os dois por um curto período. Registra notification.updated com details.changed [secret].
Uma nova tentativa exata com a mesma Idempotency-Key retorna o mesmo novo segredo por vinte e quatro horas.
Parâmetros
| Nome | Enviar | Obrigatório? | Descrição |
|---|---|---|---|
| ScreenRig-Project | cabeçalho | opcional | Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token. |
| id | caminho | obrigatório | |
| If-Match | cabeçalho | opcional | Revisão positiva opcional do recurso. Omitir para escrever o recurso atual; uma revisão obsoleta fornecida é revision_conflict. |
| Idempotency-Key | cabeçalho | opcional | Omitir para uma operação nova. Forneça e reutilize uma chave para deduplicar tentativas; o CLI gerencia as chaves automaticamente. |
Modelo e respostas da solicitação
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/webhooks/RESOURCE_ID/rotate-secret'Respostas
| Status | Significado | Corpo e cabeçalhos |
|---|---|---|
| 200 | O webhook e seu novo segredo. | WebhookWithSecret (application/json); cabeçalhos: Cache-Control |
| 412 | revision_conflict — If-Match está desatualizado; a current_revision do erro contém a revisão atual. | Problema (application/problem+json) |
| padrão | Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico. | Problema (application/problem+json) |
Testar webhook
Registra um evento de projeto notification.test e enfileira uma entrega dele somente para este webhook (nenhum outro webhook recebe notification.test). Funciona em um webhook desativado, é tentado uma única vez (sem novas tentativas), é medido como qualquer entrega e nunca altera o estado de falha do webhook. Consulte o registro de entregas para ver o resultado.
Parâmetros
| Nome | Enviar | Obrigatório? | Descrição |
|---|---|---|---|
| ScreenRig-Project | cabeçalho | opcional | Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token. |
| id | caminho | obrigatório | |
| Idempotency-Key | cabeçalho | opcional | Omitir para uma operação nova. Forneça e reutilize uma chave para deduplicar tentativas; o CLI gerencia as chaves automaticamente. |
Modelo e respostas da solicitação
curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/webhooks/RESOURCE_ID/test'Respostas
| Status | Significado | Corpo e cabeçalhos |
|---|---|---|
| 202 | A entrega de teste na fila. | WebhookDelivery (application/json); cabeçalhos: RateLimit-Policy, RateLimit |
| 429 | Problema estável rate_limited. Refaça só após o intervalo Retry-After autoritativo. Negativas de janela fixa incluem também RateLimit-Policy e membros RateLimit aplicáveis; negativas de concorrência e orçamento de bytes omitem essas divulgações opcionais. | Problema (application/problem+json); cabeçalhos: Retry-After, RateLimit-Policy, RateLimit |
| padrão | Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico. | Problema (application/problem+json) |
Listar entregas de webhook
O log de entrega do webhook, evento mais recente primeiro. Uma linha por (webhook, evento); tentativas atualizam a linha e GET .../deliveries/{delivery_id}/attempts lista suas tentativas mais recentes. As linhas são mantidas como eventos (a retenção de eventos do plano, pelo menos a janela de tentativa de 24 horas). Passe next_cursor de volta como antes para a próxima página.
Parâmetros
| Nome | Enviar | Obrigatório? | Descrição |
|---|---|---|---|
| ScreenRig-Project | cabeçalho | opcional | Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token. |
| id | caminho | obrigatório | |
| before | consulta | opcional | next_cursor da página anterior de entregas. |
| limite | consulta | opcional |
Modelo e respostas da solicitação
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID/deliveries'Respostas
| Status | Significado | Corpo e cabeçalhos |
|---|---|---|
| 200 | Uma página de entregas. | WebhookDeliveryList (application/json) |
| padrão | Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico. | Problema (application/problem+json) |
Listar tentativas de entrega de webhook
As tentativas de uma entrega, as mais recentes primeiro, as 20 mais recentes, mantidas com a linha de entrega e por tempo indeterminado. Cada uma tem seu número de tentativa, quando terminou, o status HTTP do receptor (nulo quando nenhum respondeu), a classe de erro (nulo em sucesso) e sua duração. Corpos e cabeçalhos de resposta nunca são mantidos. Uma entrega registrada antes de tentativas serem mantidas lista nenhuma.
Uma entrega que não é deste webhook, ou um webhook de outro projeto, é not_found.
Parâmetros
| Nome | Enviar | Obrigatório? | Descrição |
|---|---|---|---|
| ScreenRig-Project | cabeçalho | opcional | Obsoleto por uma versão. Deve ser consistente com as concessões de projetos JWT; adiciona cabeçalhos Deprecation e Warning. Sem troca de token. |
| id | caminho | obrigatório | |
| delivery_id | caminho | obrigatório | O id de uma das entregas do webhook. |
Modelo e respostas da solicitação
curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID/deliveries/DELIVERY_ID/attempts'Respostas
| Status | Significado | Corpo e cabeçalhos |
|---|---|---|
| 200 | As tentativas mantidas da entrega. | WebhookDeliveryAttemptList (application/json) |
| 404 | Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico. | Problema (application/problem+json) |
| padrão | Resposta de problema estável RFC 9457. Um 421 server_draining tem Retry-After de 1 segundo, um 500 not_ready ou dependency_unavailable tem 5, e um 500 manifest_degraded tem 60, a menos que o handler defina valor mais específico. | Problema (application/problem+json) |