> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Pedir upload de mídia > URL pré-assinada e os cabeçalhos exatos do upload; o evento leva só a referência e o hash. ## OpenAPI ````yaml openapi/pt/cell.json POST /v1/media/uploads openapi: 3.1.0 info: title: API de dados da Niadra version: '1' description: >- Escrita, contexto, histórico, objetos, identidade, privacidade e governança de um espaço. Cada espaço tem um endereço estável, com o espaço e a região no nome. servers: - url: https://{space}.{region}.api.niadra.com variables: space: default: acme-prod description: O espaço, que vem na chave de fonte. region: default: us-east-1 description: A região do espaço, que também vem na chave. security: [] paths: /v1/media/uploads: post: tags: - ingest summary: Pedir upload de mídia description: >- Reserva o lugar de um áudio ou anexo e devolve uma `upload_url` pré-assinada. Envie os bytes com `PUT` mandando exatamente os cabeçalhos de `upload_headers`: o armazenamento recusa qualquer outro conteúdo, e é assim que o SHA-256 declarado vale. Depois mande o evento com `content.media_ref` e `content.media_sha256`. Passe `subject` para que um `forget` alcance o arquivo mesmo que nenhum evento aponte para ele. **Autenticação.** Chave de fonte: `Authorization: Bearer nia_sk_...`. Escopo exigido: `track`. operationId: media_upload_v1_media_uploads_post requestBody: content: application/json: schema: $ref: '#/components/schemas/MediaUploadIn' example: content_type: audio/ogg size_bytes: 48213 sha256: a3f1c2d4e5b6978812ab34cd56ef7890a1b2c3d4e5f60718293a4b5c6d7e8f90 subject: type: phone_e164 value: '+14155550123' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/MediaUploadResponse' example: media_ref: med_01J8ZM2 upload_url: https://uploads.us-east-1.api.niadra.com/med_01J8ZM2?sig=... upload_headers: Content-Type: audio/ogg x-amz-checksum-sha256: o/HC1OW2l4gSqzTNVu94kKGyw9Tl9gcYKTpLXG1+j5A= expires_at: '2026-09-22T17:17:03Z' description: O lugar do upload, válido até `expires_at`. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: >- 422 `invalid_input`, `verification_not_allowed` ou `about_without_link`. security: - sourceKey: [] x-codeSamples: - lang: python label: Python source: >- # Reserves the upload, sends the bytes with the exact upload_headers, returns the reference media = niadra.upload_media(audio_bytes, "audio/ogg", subject=phone("+14155550123")) niadra.track({ "channel": "whatsapp", "conversation_id": "wa-8812", "handles": [phone("+14155550123")], "speaker": {"role": "customer"}, "content": {"type": "audio", "media_ref": media.media_ref, "media_sha256": media.media_sha256}, }) - lang: typescript label: TypeScript source: >- // Reserves the upload, sends the bytes with the exact upload_headers, returns the reference const { data: media } = await niadra.uploadMedia({ data: audioBytes, content_type: "audio/ogg", subject: handles.phone("+14155550123"), }); niadra.track({ channel: "whatsapp", conversation_id: "wa-8812", handles: [handles.phone("+14155550123")], speaker: "customer", content: { type: "audio", media_ref: media!.media_ref, media_sha256: media!.media_sha256 }, }); components: schemas: MediaUploadIn: additionalProperties: false properties: content_type: maxLength: 256 minLength: 1 title: Content Type type: string sha256: pattern: ^[0-9a-f]{64}$ title: Sha256 type: string size_bytes: exclusiveMinimum: 0 maximum: 524288000 title: Size Bytes type: integer subject: anyOf: - $ref: '#/components/schemas/Handle' - type: 'null' description: >- De quem é a mídia. O objeto fica guardado sob o handle do titular, então o `forget` o alcança mesmo que nenhum evento aponte para ele. required: - content_type - size_bytes - sha256 title: MediaUploadIn type: object MediaUploadResponse: additionalProperties: false properties: expires_at: format: date-time title: Expires At type: string media_ref: title: Media Ref type: string upload_headers: additionalProperties: type: string description: >- Envie exatamente estes cabeçalhos com o upload; o armazenamento recusa qualquer outro conteúdo. title: Upload Headers type: object upload_url: title: Upload Url type: string description: URL pré-assinada. Envie os bytes com `PUT`. required: - media_ref - upload_url - expires_at title: MediaUploadResponse type: object Problem: additionalProperties: false description: >- Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de erros versionado. properties: code: title: Code type: string detail: anyOf: - type: string - type: 'null' default: null title: Detail request_id: anyOf: - type: string - type: 'null' default: null title: Request Id status: title: Status type: integer title: title: Title type: string type: default: about:blank title: Type type: string required: - title - status - code title: Problem type: object Handle: additionalProperties: false description: >- Um identificador de um sujeito num canal ou sistema: um telefone, um e-mail, um id do CRM. properties: scope: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: >- Espaço de nomes dos identificadores com escopo: a conta do WhatsApp Business para `wa_bsuid`, o sistema para `system_id`, o país para `gov_id_hmac`. title: Scope subject_kind: anyOf: - $ref: '#/components/schemas/SubjectKind' - type: 'null' description: >- O padrão é `person`, exceto nos tipos de handle que só identificam organizações. type: $ref: '#/components/schemas/HandleType' value: maxLength: 320 minLength: 1 title: Value type: string description: >- O identificador. Normalizado no servidor: E.164 para telefone, minúsculas para e-mail. required: - type - value title: Handle type: object SubjectKind: enum: - person - account - partner title: SubjectKind type: string description: >- Uma pessoa, uma organização cliente (`account`) ou uma organização que participa sem ser cliente (`partner`). HandleType: enum: - phone_e164 - wa_id - wa_jid - wa_lid - wa_bsuid - email - gov_id_hmac - app_user_id - system_id - org_registry_hmac - email_domain - anon_id title: HandleType type: string description: >- O tipo de identificador. O valor é classificado pelo formato, nunca pelo campo de onde veio. securitySchemes: sourceKey: type: http scheme: bearer description: nia_sk_... ````