> ## 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. # As câmeras da conta > As câmeras que esta chave enxerga, paginadas, cada uma com o local monitorado e o cliente-dono já resolvidos — é a rota que casa o seu cadastro com o nosso. **Dois eixos, e eles discordam de propósito.** `status` é CADASTRO: o que sabemos da câmera desde a última vez que alguém a configurou ou testou. `transmitting` é IMAGEM: se um quadro chegou dentro da janela. Uma câmera `active` que não transmite existe, e é o caso mais comum de reclamação de morador. Para "quais câmeras estão sem imagem agora", filtre `transmitting=no` — uma chamada por conta responde pela frota inteira, e é muito mais barato que diagnosticar câmera por câmera. `transmitting_witness_fresh` no envelope diz se a medição de imagem está viva. Quando vier `false`, "0 câmeras transmitindo" significa **não deu para medir**, não "todas caídas" — tratar os dois como a mesma coisa gera alarme falso em massa. **A armadilha do identificador.** `device_id` é o identificador do equipamento e é único **dentro da conta**, não entre contas. Se você atende várias contas, a sua chave primária tem de ser o par (conta, `device_id`) — ou o `device_uuid`, que é único em qualquer lugar. ## OpenAPI ````yaml /api-reference/openapi.json get /api/devices 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: [] paths: /api/devices: get: tags: - cameras summary: As câmeras da conta description: >- As câmeras que esta chave enxerga, paginadas, cada uma com o local monitorado e o cliente-dono já resolvidos — é a rota que casa o seu cadastro com o nosso. **Dois eixos, e eles discordam de propósito.** `status` é CADASTRO: o que sabemos da câmera desde a última vez que alguém a configurou ou testou. `transmitting` é IMAGEM: se um quadro chegou dentro da janela. Uma câmera `active` que não transmite existe, e é o caso mais comum de reclamação de morador. Para "quais câmeras estão sem imagem agora", filtre `transmitting=no` — uma chamada por conta responde pela frota inteira, e é muito mais barato que diagnosticar câmera por câmera. `transmitting_witness_fresh` no envelope diz se a medição de imagem está viva. Quando vier `false`, "0 câmeras transmitindo" significa **não deu para medir**, não "todas caídas" — tratar os dois como a mesma coisa gera alarme falso em massa. **A armadilha do identificador.** `device_id` é o identificador do equipamento e é único **dentro da conta**, não entre contas. Se você atende várias contas, a sua chave primária tem de ser o par (conta, `device_id`) — ou o `device_uuid`, que é único em qualquer lugar. operationId: list_devices_api_devices_get parameters: - in: query name: limit required: false schema: default: 100 maximum: 500 minimum: 1 title: Limit type: integer - in: query name: offset required: false schema: default: 0 minimum: 0 title: Offset type: integer - description: >- Busca por nome da câmera, external_id, rótulo do local, DVR, nome do Local Monitorado ou do cliente-dono in: query name: q required: false schema: anyOf: - type: string - type: 'null' description: >- Busca por nome da câmera, external_id, rótulo do local, DVR, nome do Local Monitorado ou do cliente-dono title: Q - description: 'Filtro server-side: online | offline' in: query name: status required: false schema: anyOf: - type: string - type: 'null' description: 'Filtro server-side: online | offline' title: Status - description: >- Eixo de IMAGEM (testemunha de quadro), independente de `status`: yes = chegou quadro dentro da janela; no = já chegou quadro, mas fora da janela; unknown = nunca chegou quadro desta câmera in: query name: transmitting required: false schema: anyOf: - pattern: ^(yes|no|unknown)$ type: string - type: 'null' description: >- Eixo de IMAGEM (testemunha de quadro), independente de `status`: yes = chegou quadro dentro da janela; no = já chegou quadro, mas fora da janela; unknown = nunca chegou quadro desta câmera title: Transmitting - description: Recorte exato por cliente-dono (UUID) in: query name: client_id required: false schema: anyOf: - format: uuid type: string - type: 'null' description: Recorte exato por cliente-dono (UUID) title: Client Id - description: Recorte exato por Local Monitorado (UUID) in: query name: site_id required: false schema: anyOf: - format: uuid type: string - type: 'null' description: Recorte exato por Local Monitorado (UUID) title: Site Id - description: >- Hidratação por external_id (CSV, máx 16) — a rota do mural, que exibe no máximo 16 câmeras in: query name: ids required: false schema: anyOf: - type: string - type: 'null' description: >- Hidratação por external_id (CSV, máx 16) — a rota do mural, que exibe no máximo 16 câmeras title: Ids - description: >- Inclui `diagnostico_resumo` (rollup de causa sobre o recorte inteiro). DESLIGADO por padrão: é uma agregação sobre todas as câmeras do recorte, e no maior tenant custa ~30 ms — caro demais para a abertura normal da grade, que não desenha o resumo. in: query name: resumo required: false schema: default: false description: >- Inclui `diagnostico_resumo` (rollup de causa sobre o recorte inteiro). DESLIGADO por padrão: é uma agregação sobre todas as câmeras do recorte, e no maior tenant custa ~30 ms — caro demais para a abertura normal da grade, que não desenha o resumo. title: Resumo type: boolean - description: >- imagem (default) = câmeras que estão entregando quadro primeiro, depois por recência do último quadro; recentes = ordem de cadastro (comportamento anterior). Com a testemunha de quadro parada, `imagem` cai para `recentes`. in: query name: sort required: false schema: default: imagem description: >- imagem (default) = câmeras que estão entregando quadro primeiro, depois por recência do último quadro; recentes = ordem de cadastro (comportamento anterior). Com a testemunha de quadro parada, `imagem` cai para `recentes`. pattern: ^(imagem|recentes)$ title: Sort type: string - 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: 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 ````