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

# Uma gravação, pronta para tocar

> Uma gravação, com o endereço de playback recém-assinado — e as câmeras irmãs.

Peça esta rota (em vez de reusar o `playback_url` da lista) quando o operador
for realmente abrir o vídeo: a assinatura sai nova, com prazo cheio.

`related` traz as OUTRAS gravações do mesmo alarme. Um evento num local com oito
câmeras produz oito gravações; sem essa lista quem abre uma não tem como saber
que as outras sete existem — e é justamente varrer os ângulos do mesmo instante
que resolve o atendimento.



## OpenAPI

````yaml /api-reference/openapi.json get /api/recording-segments/{recording_id}
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_<segredo>

    ```


    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/recording-segments/{recording_id}:
    get:
      tags:
        - recordings
      summary: Uma gravação, pronta para tocar
      description: >-
        Uma gravação, com o endereço de playback recém-assinado — e as câmeras
        irmãs.


        Peça esta rota (em vez de reusar o `playback_url` da lista) quando o
        operador

        for realmente abrir o vídeo: a assinatura sai nova, com prazo cheio.


        `related` traz as OUTRAS gravações do mesmo alarme. Um evento num local
        com oito

        câmeras produz oito gravações; sem essa lista quem abre uma não tem como
        saber

        que as outras sete existem — e é justamente varrer os ângulos do mesmo
        instante

        que resolve o atendimento.
      operationId: get_recording_segment_api_recording_segments__recording_id__get
      parameters:
        - in: path
          name: recording_id
          required: true
          schema:
            title: Recording Id
            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:
                $ref: '#/components/schemas/RecordingSegmentOut'
          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:
    RecordingSegmentOut:
      properties:
        alarm:
          anyOf:
            - $ref: '#/components/schemas/RecordingAlarmOut'
            - type: 'null'
        appliance_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Appliance Id
        camera_channel:
          anyOf:
            - type: integer
            - type: 'null'
          title: Camera Channel
        camera_id:
          title: Camera Id
          type: string
        camera_manufacturer:
          anyOf:
            - type: string
            - type: 'null'
          title: Camera Manufacturer
        camera_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Camera Model
        camera_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Camera Name
        camera_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Camera Ref
        client_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Name
        duration_s:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration S
        ended_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Ended At
        file:
          anyOf:
            - type: string
            - type: 'null'
          title: File
        partial:
          title: Partial
          type: boolean
        playback_url:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            URL do vídeo pelo proxy do gateway (/api/storage/…), com TTL de 1h.
            NUNCA a URL crua do object storage. `null` significa SEM VÍDEO
            TOCÁVEL — quem consome deve falhar honesto e não cair no ao vivo.
          title: Playback Url
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        recording_id:
          title: Recording Id
          type: string
        related:
          default: []
          items:
            $ref: '#/components/schemas/RecordingRelatedOut'
          title: Related
          type: array
        session:
          anyOf:
            - type: string
            - type: 'null'
          title: Session
        site_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Site Address
        site_contact_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Site Contact Name
        site_contact_phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Site Contact Phone
        site_external_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Site External Ref
        site_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Site Id
        site_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Site Name
        size_bytes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Size Bytes
        started_at:
          format: date-time
          title: Started At
          type: string
        storage_backend:
          title: Storage Backend
          type: string
        storage_bucket:
          title: Storage Bucket
          type: string
        storage_key:
          title: Storage Key
          type: string
        tenant_id:
          title: Tenant Id
          type: string
      required:
        - recording_id
        - tenant_id
        - camera_id
        - storage_backend
        - storage_bucket
        - storage_key
        - started_at
        - partial
      title: RecordingSegmentOut
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    RecordingAlarmOut:
      description: >-
        O alarme que mandou gravar — o "porquê" da gravação.


        Só existe quando a gravação nasceu de um evento
        (``pictor.alarm_event_log``

        casado pelo ``alarm_id`` determinístico). Gravação manual/agendada não
        tem

        alarme e o campo vem ``None`` — não se inventa evento para preencher
        tela.


        Os campos vêm de uma LISTA BRANCA de caminhos do payload do provedor. O

        dossiê cru carrega ``senha``/``contra_senha``/``coacao`` do local; nada
        disso

        pode vazar para uma tela de gravação, e a forma de garantir isso é nunca

        projetar o payload inteiro — só estes caminhos.
      properties:
        account:
          anyOf:
            - type: string
            - type: 'null'
          title: Account
        alarm_id:
          title: Alarm Id
          type: string
        event_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Event Code
        event_group:
          anyOf:
            - type: string
            - type: 'null'
          title: Event Group
        event_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Event Label
        event_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Event Ref
        occurred_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Occurred At
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
        received_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Received At
        site_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Site Ref
        triage_state:
          anyOf:
            - type: string
            - type: 'null'
          title: Triage State
      required:
        - alarm_id
      title: RecordingAlarmOut
      type: object
    RecordingRelatedOut:
      description: Outra gravação do MESMO alarme (outra câmera do local).
      properties:
        camera_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Camera Name
        camera_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Camera Ref
        duration_s:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration S
        partial:
          default: false
          title: Partial
          type: boolean
        recording_id:
          title: Recording Id
          type: string
        started_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Started At
      required:
        - recording_id
      title: RecordingRelatedOut
      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_<prefixo>_<segredo>`.
      scheme: bearer
      type: http

````