Pular navegação
Base de conhecimento

Acesso e integrações

Tokens de acesso e webhooks.

Access tokens

Criar token

POST https://api.kinescope.io/v1/access-tokens

Cria um token de acesso para o workspace. Guarde o valor devolvido — ele é exibido uma única vez.

Request body (json)
{
  "name": "token1",
  "scope": {
    "api": {
      "permissions": [
        "read",
        "write",
        "delete"
      ]
    },
    "upload": {
      "permissions": []
    }
  }
}

Criar token de upload para um projeto específico

POST https://api.kinescope.io/v1/access-tokens

Cria um token de acesso apenas para upload, restrito a um único projeto.

Request body (json)
{
  "name": "token for upload to project",
  "scope": {
    "upload": {
      "entities": [
        {
          "id": "<UUID>",
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        }
      ],
      "permissions": []
    }
  }
}
Responses
{
  "data": {
    "id": "9f8d2c31-4a6b-4e72-8d15-3b7c9e0a5f24",
    "name": "token for upload to project",
    "workspace_id": "4ba9dbbc-aec9-4e60-97ad-06a45bb7700d",
    "scope": {
      "upload": {
        "permissions": [],
        "entities": [
          {
            "id": "<UUID>",
            "permissions": [
              "read",
              "write",
              "delete"
            ]
          }
        ]
      }
    }
  }
}

Lista de tokens

GET https://api.kinescope.io/v1/access-tokens

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

Responses
{
  "meta": {
    "offset": 0,
    "limit": 10,
    "total": 16,
    "total_count": 0,
    "order": {
      "name": "asc"
    },
    "parent_id": null
  },
  "data": [
    {
      "id": "<UUID>",
      "name": "Koltin-Kinescope-Player",
      "workspace_id": "<UUID>",
      "scope": {
        "api": {
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        }
      }
    },
    {
      "id": "<UUID>",
      "name": "Kotlin-Kinescope-Shorts",
      "workspace_id": "<UUID>",
      "scope": {
        "api": {
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        }
      }
    },
    {
      "id": "<UUID>",
      "name": "Restream",
      "workspace_id": "<UUID>",
      "scope": {
        "api": {
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        },
        "upload": {
          "permissions": []
        }
      }
    },
    {
      "id": "<UUID>",
      "name": "sadfasdf",
      "workspace_id": "<UUID>",
      "scope": {
        "api": {
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        }
      }
    },
    {
      "id": "<UUID>",
      "name": "sdfsdfsdf",
      "workspace_id": "<UUID>",
      "scope": {
        "api": {
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        },
        "upload": {
          "permissions": []
        }
      }
    },
    {
      "id": "<UUID>",
      "name": "Speak",
      "workspace_id": "<UUID>",
      "scope": {
        "api": {
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        },
        "upload": {
          "permissions": []
        }
      }
    },
    {
      "id": "<UUID>",
      "name": "Speak LiveKit Test Token",
      "workspace_id": "<UUID>",
      "scope": {
        "api": {
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        },
        "upload": {
          "permissions": []
        }
      }
    },
    {
      "id": "<UUID>",
      "name": "Speak Room",
      "workspace_id": "<UUID>",
      "scope": {
        "api": {
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        },
        "upload": {
          "permissions": []
        }
      }
    },
    {
      "id": "<UUID>",
      "name": "Test MCP",
      "workspace_id": "<UUID>",
      "scope": {
        "api": {
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        }
      }
    },
    {
      "id": "<UUID>",
      "name": "Upload integration",
      "workspace_id": "<UUID>",
      "scope": {
        "api": {
          "permissions": [
            "read",
            "write",
            "delete"
          ]
        },
        "upload": {
          "permissions": []
        }
      }
    }
  ]
}

Obter token

GET https://api.kinescope.io/v1/access-tokens/:token_id

Retorna os dados de um token de acesso pelo seu identificador único.

Responses
{
  "data": {
    "id": "<UUID>",
    "name": "Koltin-Kinescope-Player",
    "workspace_id": "<UUID>",
    "scope": {
      "api": {
        "permissions": [
          "read",
          "write",
          "delete"
        ]
      }
    }
  }
}
{
  "error": {
    "code": 400404,
    "message": "not found"
  }
}

Excluir token

DELETE https://api.kinescope.io/v1/access-tokens/:token_id

Exclui o token de acesso permanentemente. A ação não pode ser desfeita.

Webhooks

Os webhooks de saída avisam o seu endpoint sobre eventos de vídeos, transmissões ao vivo e chamadas do Speak. São enviados treze eventos: media.update.status para vídeos; live.created, live.connected, live.disconnected, live.finished, live.cancelled e live.enabled para transmissões ao vivo; speak.call.started, speak.call.finished, speak.participant.joined, speak.participant.left, speak.record.started e speak.record.finished para o Speak.

Uma entrega é um POST simples com corpo JSON. A única verificação do remetente é a autenticação HTTP Basic com o login e a password definidos na assinatura — as entregas não são assinadas, então trate o payload como um aviso e releia o objeto pelo API. Seu endpoint deve responder com qualquer 2xx; em qualquer outra resposta a entrega é repetida, mas o número de tentativas e o intervalo entre elas não são publicados. Não há identificador de entrega, então faça a deduplicação pelo conteúdo do payload.

Política de repetição, segundo dados internos de 13-08-2026 — não reproduzida por nós, confirme antes de depender dos números: o remetente espera 10 segundos pela resposta; só 2xx conta como sucesso; qualquer outra resposta, inclusive 4xx, é repetida; o intervalo é de cerca de 15 segundos sem backoff, até 50 tentativas (aproximadamente 12–13 minutos); as entregas para uma URL são limitadas a 20 por segundo com picos de até 100; a ordem das entregas não é garantida.

Criar webhook

POST https://api.kinescope.io/v1/webhooks

Assina um ou mais tipos de evento. O endpoint configurado recebe um POST simples com corpo JSON quando esses eventos acontecem — as entregas não são assinadas, e a única verificação do remetente é a autenticação HTTP Basic definida aqui.

Request body (json)
{
  "name": "webhook1",
  "endpoint": "https://example.io/kinescope/webhook",
  "login": "",
  "password": "",
  "events": [
    "media.update.status"
  ]
}
Responses
{
  "data": {
    "id": "<UUID>",
    "name": "doc_test_webhook_1776899949",
    "endpoint": "https://example.com/kinescope-doc-test",
    "login": "",
    "password": "<REDACTED>",
    "events": [
      "media.update.status"
    ],
    "created_at": "2026-04-22T23:19:10.316926Z",
    "updated_at": null,
    "deleted_at": null
  }
}

Listar webhooks

GET https://api.kinescope.io/v1/webhooks

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

Responses
{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 1
    },
    "order": {
      "name": "asc"
    }
  },
  "data": [
    {
      "id": "<UUID>",
      "name": "doc_test_webhook_1776899949",
      "endpoint": "https://example.com/kinescope-doc-test",
      "login": "",
      "password": "<REDACTED>",
      "events": [
        "media.update.status"
      ],
      "created_at": "2026-04-22T23:19:10.316926Z",
      "updated_at": null,
      "deleted_at": null
    }
  ]
}

Atualizar webhook

PUT https://api.kinescope.io/v1/webhooks/:webhook_id

Atualiza o webhook (URL, credenciais HTTP Basic, eventos assinados).

Request body (json)
{
  "name": "webhook1_edit2",
  "endpoint": "https://example.io/kin/webhook",
  "login": "123",
  "password": "2222",
  "events": [
    "media.update.status"
  ]
}
Responses
{
  "data": {
    "id": "<UUID>",
    "name": "doc_test_webhook_1776899949_upd",
    "endpoint": "https://example.com/kinescope-doc-test",
    "login": "",
    "password": "<REDACTED>",
    "events": [
      "media.update.status"
    ],
    "created_at": "2026-04-22T23:19:10.316926Z",
    "updated_at": "2026-04-22T23:19:11.087179Z",
    "deleted_at": null
  }
}

Excluir webhook

DELETE https://api.kinescope.io/v1/webhooks/:webhook_id

Exclui o webhook permanentemente. A ação não pode ser desfeita.

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