Armazenamento chave/valor: referência da API, endpoints e exemplos

OpenAPI YAML OpenAPI JSON problemas YAML Visã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.

Armazenamento chave/valor do aplicativo

GET/api/applications/{application_id}/kv¶

Listar KV

Retorna no máximo 200 entradas em ordem crescente de chave. next_cursor é a última chave retornada; passe-a como after para buscar a próxima página. next_cursor é nulo quando não há mais entradas. Uma sessão do painel lê aqui as entradas do seu projeto para a prévia do app web; o painel não tem escrita de KV.

Autenticação: projectBearer OU dashboardSession
Corpo da solicitação: nenhum
ID da operação: listKV

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.
application_id	caminho	obrigatório
depois	consulta	opcional

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv'

Respostas

Status	Significado	Corpo e cabeçalhos
200	Entradas KV	KVList (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)

GET/api/applications/{application_id}/kv/{key}¶

Obter KV

Autenticação: projectBearer OU dashboardSession
Corpo da solicitação: nenhum
ID da operação: getKV

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.
application_id	caminho	obrigatório
key	caminho	obrigatório

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv/KEY'

Respostas

Status	Significado	Corpo e cabeçalhos
200	Entrada KV	KVEntry (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)

PUT/api/applications/{application_id}/kv/{key}¶

Colocar KV

Autenticação: projectBearer
Corpo da solicitação: KVWrite
ID da operação: putKV

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.
application_id	caminho	obrigatório
key	caminho	obrigatório
If-Match	cabeçalho	opcional	Revisão positiva opcional do recurso. Omitir para criar ou sobrescrever uma chave; 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
value_base64 (obrigatório, string)	maxLength: 1398104
content_type (opcional, string)	padrão: "application/octet-stream" minLength: 1 maxLength: 127

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv/KEY'

Respostas

Status	Significado	Corpo e cabeçalhos
200	Entrada KV	KVEntry (application/json)
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)

EXCLUIR/api/applications/{application_id}/kv/{key}¶

Excluir KV

Autenticação: projectBearer
Corpo da solicitação: nenhum
ID da operação: deleteKV

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.
application_id	caminho	obrigatório
key	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

shell · modelo de requisição

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv/KEY'

Respostas

Status	Significado	Corpo e cabeçalhos
204	Excluído	sem corpo
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)

GET/api/applications/{application_id}/kv-webhooks¶

Listar KVWebhooks

Lista os webhooks de chave/valor de entrada do aplicativo, do mais antigo para o mais recente (no máximo 20), cada um com a chave que grava, sua URL de ingestão e last_used_at uma vez que tenha gravado. O segredo nunca é retornado aqui.

Autenticação: projectBearer
Corpo da solicitação: nenhum
ID da operação: listKVWebhooks

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.
application_id	caminho	obrigatório

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks'

Respostas

Status	Significado	Corpo e cabeçalhos
200	Os webhooks de chave/valor do aplicativo.	KVWebhookList (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)

POST/api/applications/{application_id}/kv-webhooks¶

Criar KVWebhook

Cria um webhook de entrada chave/valor: uma URL que grava uma chave desta aplicação, para que um sistema externo (Zapier, Make, um ponto de venda, um cron job, curl) envie dados para telas com um POST HTTP; veja POST /api/applications/{application_id}/kv-webhooks/{webhook_id}/write. A chave pode não existir ainda.

A resposta é o único lugar onde o segredo aparece (com a resposta de rotação): armazene-o no sistema de envio imediatamente; o servidor mantém um resumo. Um aplicativo tem no máximo 20 webhooks (kv_webhook_limit_reached). Acrescenta kv_webhook.created. Uma nova tentativa exata com a mesma Idempotency-Key retorna esta mesma resposta, segredo incluído, por vinte e quatro horas.

Autenticação: projectBearer
Corpo da solicitação: KVWebhookCreate
ID da operação: createKVWebhook

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.
application_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.

Campos do corpo da solicitação

Campo	Descrição
key (obrigatório, string)	minLength: 1 maxLength: 256 padrão: "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$"
descrição (opcional, string)	O que envia para ele, para as pessoas que leem a lista. Resumido; não deve conter credencial. maxLength: 200

Modelo e respostas da solicitação

shell · modelo de requisição

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks'

Respostas

Status	Significado	Corpo e cabeçalhos
201	Criado, com sua URL e segredo.	KVWebhookWithSecret (application/json); headers: Cache-Control
400	invalid_request, incluindo uma chave malformada ou uma descrição que contém uma credencial.	Problema (application/problem+json)
404	not_found — o aplicativo não está neste projeto.	Problema (application/problem+json)
409	kv_webhook_limit_reached ou idempotency_mismatch.	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/api/applications/{application_id}/kv-webhooks/{webhook_id}¶

Excluir KVWebhook

Exclui o webhook. Sua URL para de funcionar imediatamente; a chave que ele escreveu mantém seu valor. Acrescenta kv_webhook.deleted.

Autenticação: projectBearer
Corpo da solicitação: nenhum
ID da operação: deleteKVWebhook

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.
application_id	caminho	obrigatório
webhook_id	caminho	obrigatório	O id de um dos webhooks chave/valor do aplicativo.
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

shell · modelo de requisição

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks/WEBHOOK_ID'

Respostas

Status	Significado	Corpo e cabeçalhos
204	Excluído.	sem corpo
404	not_found — o webhook não está neste aplicativo.	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)

POST/api/applications/{application_id}/kv-webhooks/{webhook_id}/rotate-secret¶

Rotacionar segredo KVWebhook

Substitui o segredo do webhook e retorna o novo, uma vez. O segredo antigo para de funcionar imediatamente; atualize o sistema de envio. Acrescenta kv_webhook.secret_rotated. Uma nova tentativa exata com a mesma Idempotency-Key retorna esta mesma resposta, segredo incluído, por vinte e quatro horas.

Autenticação: projectBearer
Corpo da solicitação: nenhum
ID da operação: rotateKVWebhookSecret

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.
application_id	caminho	obrigatório
webhook_id	caminho	obrigatório	O id de um dos webhooks chave/valor do aplicativo.
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

shell · modelo de requisição

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks/WEBHOOK_ID/rotate-secret'

Respostas

Status	Significado	Corpo e cabeçalhos
200	O webhook com seu novo segredo.	KVWebhookWithSecret (application/json); headers: Cache-Control
404	not_found — o webhook não está neste aplicativo.	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)

POST/api/applications/{application_id}/kv-webhooks/{webhook_id}/write¶

Receber KVWebhook

A URL para a qual um sistema externo envia o novo valor de uma chave. Autentica-se apenas com o segredo do webhook no cabeçalho Authorization: Bearer <secret>, ou HTTP Basic com o ID do webhook como nome de usuário e o segredo como senha. Um segredo na URL ou na query nunca é aceito.

Um webhook desconhecido, de outro aplicativo e um segredo errado respondem todos com o mesmo 401. O corpo bruto, no máximo 1 MiB, torna-se o valor da chave do webhook, e o cabeçalho Content-Type seu content_type (application/octet-stream quando ausente; um cabeçalho que não é um tipo de mídia é invalid_request).

A escrita é PUT /api/applications/{application_id}/kv/{key} sem If-Match: substitui o valor, incrementa a revisão, é medida e verificada por cota como qualquer escrita K/V, é uma solicitação API cobrada que nunca é recusada por saldo, e acrescenta kv.updated.

Idempotency-Key (de 8 a 200 caracteres) desduplica as novas tentativas de um remetente em uma gravação por vinte e quatro horas, e a mesma chave com outro corpo ou tipo de conteúdo é idempotency_mismatch; sem ela, cada envio é uma nova gravação. A resposta são os novos metadados da chave, nunca o valor dela.

No máximo 120 gravações por minuto por webhook; cada uma também conta para as taxas de gravação da organização e da chave (PUT /api/card-data/{key}).

Autenticação: kvWebhookBearer OU kvWebhookBasic
Corpo da solicitação: string
ID da operação: receiveKVWebhook

Parâmetros

Nome	Enviar	Obrigatório?	Descrição
application_id	caminho	obrigatório
webhook_id	caminho	obrigatório	O id de um dos webhooks chave/valor do aplicativo.
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

shell · modelo de requisição

curl --request POST --header 'Content-Type: */*' --data-binary '@request.bin' 'https://api.screenrig.ai/api/applications/APPLICATION_ID/kv-webhooks/WEBHOOK_ID/write'

Respostas

Status	Significado	Corpo e cabeçalhos
200	Os novos metadados da chave.	KVWebhookWriteResult (application/json); headers: RateLimit-Policy, RateLimit, Cache-Control
400	invalid_request — o corpo é maior que 1 MiB, o Content-Type não é um tipo de mídia único, ou a Idempotency-Key está malformada.	Problema (application/problem+json)
401	não autorizado — credenciais ausentes ou incorretas, ou um webhook desconhecido. WWW-Authenticate indica os realms Bearer e Basic.	Problema (application/problem+json)
409	idempotency_mismatch — a Idempotency-Key foi usada para outro corpo ou tipo de conteúdo.	Problema (application/problem+json)
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)