> ## Documentation Index > Fetch the complete documentation index at: https://docs.pictor.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Diagnosticar uma câmera > **Abre ou não abre, e por quê.** Um veredito único para uma câmera, com a causa raiz nomeada — o que faz a sua equipe parar de ligar para perguntar. A resposta tem três partes. `summary` traz o veredito (`ok`, `degraded`, `fail` ou `unknown`), a frase que explica e a próxima ação, tudo em texto que o seu operador pode ler na tela sem tradução. `media_route` diz por onde o vídeo chega. `checks` traz a cadeia inteira, na ordem em que ela realmente falha — então **a primeira falha da lista é a causa, e o resto é sintoma.** Os elos, nessa ordem: dados da câmera, licença do fabricante, conexão com o fabricante, usuário e senha do equipamento, código de verificação do aparelho, caminho do vídeo, contato com a câmera, recepção de vídeo, última imagem. **Imagem chegando ganha do resto.** Se estamos recebendo quadro, o pior veredito possível é `degraded`, nunca `fail`: há o que ajustar, não há o que socorrer. Sem essa regra a mesma tela dizia "Falha" acima de um vídeo que estava rodando. **`probe=true` (o padrão) disca na câmera de verdade.** É diagnóstico sob demanda — para quando alguém vai olhar —, não vigília. Para varrer a frota em laço use `probe=false`: devolve só o estado já conhecido, sem tocar a rede. E para "quem está sem imagem", `GET /api/devices?transmitting=no` responde pela conta inteira numa chamada. ## OpenAPI ````yaml /api-reference/openapi.json get /api/devices/{device_id}/diagnostics openapi: 3.1.0 info: description: > API de leitura do Pictor Cloud para integração de parceiro. ## Autenticação Toda chamada leva a chave no cabeçalho `Authorization`: ``` Authorization: Bearer pct_1a2b3c4d_ ``` A chave é emitida por um **administrador da conta** no console (Integrações → Chaves de API) e **aparece uma única vez**, no momento da criação. O servidor guarda apenas o resumo criptográfico dela: não existe "mostrar de novo". Se perder, emita outra e revogue a antiga. ## O que a chave enxerga A chave carrega o mesmo par permissão/alcance de um usuário: | Campo | Valores | Efeito | |---|---|---| | `role` | `viewer`, `operator`, `admin` | `viewer` basta para tudo que está documentado aqui | | `scope` | `tenant`, `client`, `video_wall` | recorta o que a chave vê dentro da conta | Uma chave com `scope=client` só devolve as câmeras (e os eventos, e o diagnóstico) daquele cliente. Uma chave nunca atravessa a fronteira da conta que a emitiu: não existe chave que enxergue duas contas. ## Validade Toda chave tem prazo — "nunca expira" não é um estado que exista. Quando ela vence, as chamadas passam a responder `401`; a cura é emitir outra no console. ## Cabeçalhos que não se aplicam - `X-Tenant-ID`: opcional. Se vier, precisa ser a conta da própria chave; divergente responde `403`. A chave decide a conta, o cabeçalho nunca a troca. - `X-Membership-ID`: responde `403`. Uma chave não troca de workspace. ## Limites Há um teto de requisições por chave por minuto. Ao estourar, a resposta é `429` com `Retry-After`. A emissão de URL de mídia tem teto próprio, bem menor: cada sessão de vídeo custa CPU no servidor de mídia. ## Erros | Código | Significado | |---|---| | `401` | chave ausente, malformada, revogada ou expirada (o motivo não é detalhado, de propósito) | | `403` | chave válida, sem permissão para o recurso — ou cabeçalho que contradiz a chave | | `404` | o recurso não existe **ou** não é desta chave (não distinguimos: dizer qual seria contar o que existe) | | `429` | teto de requisições estourado | title: Pictor Cloud — API de parceiro version: 1.0.0 servers: - description: Pictor Cloud url: https://api.pictor.cloud security: [] tags: - name: Câmeras - name: Vídeo ao vivo - name: Vídeo gravado - name: Eventos de IA - name: Ronda - name: Murais paths: /api/devices/{device_id}/diagnostics: get: tags: - Câmeras summary: Diagnosticar uma câmera description: >- **Abre ou não abre, e por quê.** Um veredito único para uma câmera, com a causa raiz nomeada — o que faz a sua equipe parar de ligar para perguntar. A resposta tem três partes. `summary` traz o veredito (`ok`, `degraded`, `fail` ou `unknown`), a frase que explica e a próxima ação, tudo em texto que o seu operador pode ler na tela sem tradução. `media_route` diz por onde o vídeo chega. `checks` traz a cadeia inteira, na ordem em que ela realmente falha — então **a primeira falha da lista é a causa, e o resto é sintoma.** Os elos, nessa ordem: dados da câmera, licença do fabricante, conexão com o fabricante, usuário e senha do equipamento, código de verificação do aparelho, caminho do vídeo, contato com a câmera, recepção de vídeo, última imagem. **Imagem chegando ganha do resto.** Se estamos recebendo quadro, o pior veredito possível é `degraded`, nunca `fail`: há o que ajustar, não há o que socorrer. Sem essa regra a mesma tela dizia "Falha" acima de um vídeo que estava rodando. **`probe=true` (o padrão) disca na câmera de verdade.** É diagnóstico sob demanda — para quando alguém vai olhar —, não vigília. Para varrer a frota em laço use `probe=false`: devolve só o estado já conhecido, sem tocar a rede. E para "quem está sem imagem", `GET /api/devices?transmitting=no` responde pela conta inteira numa chamada. operationId: device_diagnostics_api_devices__device_id__diagnostics_get parameters: - in: path name: device_id required: true schema: title: Device Id type: string - description: >- Sonda a rede (RTSP/appliance). false = só estado já conhecido, zero chamada de rede. in: query name: probe required: false schema: default: true description: >- Sonda a rede (RTSP/appliance). false = só estado já conhecido, zero chamada de rede. title: Probe type: boolean - in: header name: X-Membership-ID required: false schema: anyOf: - type: string - type: 'null' title: X-Membership-Id - in: header name: X-Tenant-ID required: false schema: anyOf: - type: string - type: 'null' title: X-Tenant-Id responses: '200': content: application/json: example: checked_at: '2026-09-03T18:40:12Z' checks: - detail: Endereço, canal e tipo de conexão preenchidos. id: cadastro label: Dados da câmera remediation: null status: ok - detail: Nenhuma credencial cadastrada para esta câmera. evidence: http_status: 401 id: credencial_dispositivo label: Usuário e senha do equipamento remediation: Informe usuário e senha em Configuração > Conexão. status: fail - detail: 'Não avaliado: a cadeia parou antes.' id: recepcao_de_video label: Recepção de vídeo remediation: null status: skip device_id: G87232574 media_route: kind: edge_mesh_pull label: Pelo servidor instalado no local transcode: false summary: headline: Falta o usuário e a senha desta câmera. next_action: Informe usuário e senha em Configuração > Conexão. verdict: fail transports: hls: available webrtc: available schema: {} description: Successful Response '401': description: Chave ausente, invalida, revogada ou expirada. '403': description: Chave valida, sem permissao para o recurso. '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error '429': description: Teto de requisicoes desta chave excedido. security: - HTTPBearer: [] components: schemas: HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object securitySchemes: HTTPBearer: description: Chave de API da conta, no formato `pct__`. scheme: bearer type: http ````