Referência da API

A API do Prewalk faz parte do plano Corporativo. Com uma chave de API, o seu próprio software pode criar tours, enviar cenas, publicar, consultar projetos e estatísticas e receber um webhook assinado a cada etapa do processamento. Esta página é a referência; o estúdio e o visualizador público continuam funcionando como antes.

URL base e convenções

• URL base: https://prewalk.co. Não use app.prewalk.co: ele redireciona (308), e a maioria dos clientes HTTP descarta o cabeçalho Authorization em um redirecionamento para outro host.
• Formato: JSON na entrada e na saída (Content-Type: application/json), exceto no envio de cenas, que manda a imagem como o corpo bruto da requisição.
• IDs são formados por 12 letras minúsculas e dígitos, por exemplo teeg8crtm0u0. As datas seguem a ISO 8601, em UTC.
• Erros têm sempre o mesmo formato: um status HTTP e {"error": {"code": "…", "message": "…"}}; os erros de validação acrescentam field. Os códigos estão listados no fim desta página.
• Limite de requisições: 600 requisições por minuto por chave. Acima disso, você recebe 429 com um cabeçalho Retry-After (em segundos).

Autenticação

Crie uma chave em Configurações → API (proprietário ou administrador da conta, plano Corporativo). Uma chave pertence à conta, pode ser limitada a um perfil de marca e tem até três escopos: read, write e stats. A chave completa é exibida uma única vez; a lista mostra somente o prefixo. São até 20 chaves por conta; uma chave revogada deixa de funcionar na hora.

Authorization: Bearer pw_…

Uma chave age em nome de uma conta. GET /api/me descreve o que a chave pode ver: a conta e os limites do plano dela, os perfis dessa conta, o perfil em nome do qual a chave age (actor) e a própria chave, com os seus escopos. Ele nunca retorna o e-mail do proprietário da chave nem as outras contas dessa pessoa.

Endpoints

Método e caminho	Escopo	O que faz
GET /api/me	read	A conta, os perfis e os escopos da chave
GET /api/tours	read	Lista os tours da conta (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}	read	Um tour com as cenas, os hotspots e as configurações
GET /api/tours/{id}/events	read	O andamento do processamento como um fluxo de server-sent events
POST /api/tours	write	Cria um tour ({"title": "…"})
PATCH /api/tours/{id}	write	Altera título, descrição, categoria, localização, tags, slug (o endereço legível), ordem das cenas, cena inicial e nomes das cenas
POST /api/tours/{id}/scenes	write	Envia uma imagem 360° como corpo bruto
POST /api/content/{id}/visibility	write	Publica um tour ou projeto, ou o deixa somente com o link ou protegido por senha
GET /api/projects	read	Lista os projetos da conta (limit, cursor, profileId)
GET /api/projects/{id}	read	Um projeto com os tours, as imagens, os vídeos e as plantas baixas
GET /api/stats/{contentId}	stats	Visualizações de um tour ou projeto (range em dias)
GET /api/stats/{contentId}/export.csv	stats	O mesmo em CSV (table = daily, scenes ou referrers)

Com uma chave, todos os outros endpoints respondem 403 api_key_forbidden. Conta, equipe, cobrança, chaves de API e webhooks são gerenciados no navegador.

Tours

Listar. GET /api/tours?limit=50 retorna {"items": […], "next": "…", "usage": {…}}. Passe next de volta como cursor para obter a página seguinte; usage traz o número de cenas da conta e os limites. Cada item tem id, title, visibility, publishedAt, createdAt, updatedAt, o perfil e o número de cenas.

Consultar. GET /api/tours/{id} retorna o tour completo: title, description, category, location, tags, slug, visibility (public, link ou password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes em ordem, hotspots, settings, audio e links (player é o endereço para compartilhar; post, a página pública, quando o tour está publicado).

Uma cena tem id, name, status (queued, processing, ready ou error), createdAt, opcionalmente view (a direção da vista inicial: yaw, pitch e fov em radianos), north (em radianos; 0 é o centro da imagem, e o valor aumenta para a direita) e, enquanto ela está sendo processada, stage e pct. Uma cena pronta traz meta com os níveis de blocos e a raiz da mídia.

Criar. POST /api/tours com {"title": "Harbor View — Unit 4"} retorna o novo tour. Sem título, ele se chama “Untitled tour”.

Atualizar. PATCH /api/tours/{id} aceita qualquer um destes campos e retorna o tour:

• title, description, category, location, tags (array de strings), slug (o endereço público: letras minúsculas, dígitos e hifens), commentsEnabled;
• order: um array com os ids das cenas na ordem que você quiser; as cenas que você deixar de fora mantêm a posição, depois das que você listou;
• startScene: o id de uma cena; ela passa para o início (a primeira cena é a cena inicial);
• coverScene: o id de uma cena, ou null para usar a cena inicial;
• scenes: um objeto indexado pelo id da cena, com name, view ({"yaw", "pitch", "fov"}) e north (em graus).

Envie If-Match: "<revision>" com a revision que você leu por último para recusar uma gravação por cima da alteração de outra pessoa: nesse caso, a resposta é 409 revision_conflict, com o tour atual em error.tour. Sem If-Match, prevalece a última gravação.

Envio de cenas

POST /api/tours/{id}/scenes com o arquivo de imagem como corpo bruto. Cabeçalhos:

• Content-Type: image/jpeg, image/png, image/tiff ou image/webp;
• x-file-name: o nome do arquivo, codificado para URL (encodeURIComponent); a cena recebe o nome do arquivo, então 01-living-room.jpg vira “01 living room”;
• x-pw-upload-batch e x-pw-upload-index (opcionais): quando você envia em paralelo vários arquivos de uma mesma seleção, dê a eles o mesmo id de lote (letras, dígitos, - e _, até 32 caracteres) e o índice de cada um na seleção; assim, o servidor mantém essa ordem, não importa qual arquivo termine primeiro. Sem esses cabeçalhos, as cenas são adicionadas na ordem de chegada.

Imagens aceitas: panoramas equirretangulares 2:1 até a largura do plano (8K no plano Gratuito, 16K a partir do Pro) ou panoramas estéreo top-bottom 1:1 a partir do Pro (olho esquerdo em cima), com até 1 GiB. A resposta é a cena (status: "queued"). O processamento acontece em etapas: primeiro a cena fica visível (blocos de prévia), depois chegam os blocos em resolução total (“refinando”) e, a partir do Pro, as texturas de VR; essas duas etapas rodam em paralelo, e qualquer uma delas pode terminar primeiro. O meta.pending da cena, o fluxo de eventos e os webhooks informam quais etapas ainda estão em andamento.

Erros: 400 unsupported_format (não é JPG, PNG, TIFF nem WebP), 400 unsupported_ratio (não é 2:1 nem 1:1 top-bottom), 400 unreadable_image (arquivo danificado), 402 plan_required (16K ou estéreo em um plano que não inclui esse recurso), 402 quota_exceeded (o limite de cenas da conta), 413 file_too_large.

Andamento do processamento

GET /api/tours/{id}/events é um fluxo de server-sent events (text/event-stream). Eventos: hello ao conectar, queue (a posição na fila das cenas em espera e um resumo do tour, a cada poucos segundos enquanto algo está em andamento), scene (status, stage, pct ou error) e tour (o tour mudou; consulte o tour de novo). Para integrações entre servidores, prefira os webhooks descritos abaixo.

Publicação e visibilidade

POST /api/content/{id}/visibility funciona para tours e projetos e retorna o conteúdo:

• {"visibility": "link"} — acessível somente pelo endereço (o padrão de todo tour novo);
• {"visibility": "public", "rightsAccepted": true} — no perfil, no Explorar e indexável; é obrigatório ter uma category (defina antes com PATCH), e você confirma que tem o direito de publicar as imagens. Para um projeto, adicione "tourIds": [...] para publicar tours junto com ele;
• {"visibility": "password", "password": "…"} — a partir do Pro; omita password para manter a senha atual.

Um tour dentro de um projeto protegido por senha não pode ficar público nem ter senha própria (409 in_password_project); quem controla o acesso é a senha do projeto.

Projetos

Por enquanto, os projetos são somente leitura na API. GET /api/projects lista os projetos com id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount e as datas; GET /api/projects/{id} acrescenta description, location, tags, urls (public e o link privado), os tours com as respectivas cenas e, da galeria, images, videos e floorplans com os marcadores. Crie projetos e adicione mídia no estúdio.

Estatísticas

GET /api/stats/{contentId}?range=30 retorna as visualizações de um tour ou projeto. O que você recebe depende do plano: o total de todo o período no plano Gratuito; uma série daily preenchida com zeros (from, to, até 90 dias) no Pro; até 365 dias, além de sources (página, conteúdo incorporado, acesso direto), devices (celular, computador, óculos VR), scenes e os referrers que incorporam o conteúdo, no Office e no Corporativo. …/export.csv?range=30&table=daily traz a tabela diária; table=scenes, as visualizações por cena; e table=referrers, os sites que incorporam o conteúdo. As visualizações são contadas por endereço do visitante e por conteúdo, uma vez a cada 30 minutos; nenhum dado pessoal é armazenado.

Webhooks

Adicione até cinco webhooks em Configurações → API. Enviamos um POST assinado com um corpo JSON:

{"eventId": "evt_…", "eventType": "scene.ready", "occurredAt": "2026-10-22T09:12:03.000Z",
 "data": {"tourId": "…", "sceneId": "…", "status": "ready", "pending": ["refine", "vr"]}}

Evento	Quando	Dados
scene.ready	A cena está visível (blocos de prévia)	pending: etapas ainda em andamento — refine (blocos em resolução total) e vr (texturas para óculos VR); [] quando a prévia é a versão final
scene.sharpened	Os blocos em resolução total estão prontos	stage: "refine", ok (false quando a etapa foi descartada e a cena fica com a qualidade da prévia), pending
scene.vr_ready	As texturas de VR estão prontas	stage: "vr", ok, pending
scene.failed	O processamento falhou de vez	error com o motivo
ping	O botão “Enviar teste”	vazio

Cabeçalhos: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, em que h1 é o HMAC-SHA256 de ts + ":" + body com o segredo do seu webhook (calculado sobre os bytes exatos que você recebeu), além de Prewalk-Event-Id e Prewalk-Event-Type. Enquanto uma troca de segredo estiver em andamento, o cabeçalho traz dois valores h1 (ts=…;h1=<new>;h1=<old>) até o segredo anterior expirar: aceite a entrega quando qualquer um deles for válido. Verifique a assinatura, rejeite timestamps com mais de alguns minutos e descarte duplicatas pelo eventId: uma entrega é repetida até que o seu endpoint responda com 2xx (dez tentativas, com intervalos que começam em 30 s e vão dobrando, cerca de quatro horas no total), e o corpo reenviado é idêntico byte a byte. Depois de 20 entregas seguidas com falha, o webhook é desativado e o proprietário da conta recebe um e-mail. Os endpoints devem usar https em um endereço público; redirecionamentos não são seguidos. Você pode gerar um novo segredo; o anterior continua válido por 24 horas.

Passo a passo

# 1. create a tour
curl -s https://prewalk.co/api/tours -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: application/json" -d '{"title":"Harbor View — Unit 4"}'

# 2. upload two scenes in order
curl -s https://prewalk.co/api/tours/$TOUR/scenes -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: image/jpeg" -H "x-file-name: 01-living-room.jpg" \
  -H "x-pw-upload-batch: sel-1" -H "x-pw-upload-index: 0" --data-binary @01-living-room.jpg
curl -s https://prewalk.co/api/tours/$TOUR/scenes -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: image/jpeg" -H "x-file-name: 02-kitchen.jpg" \
  -H "x-pw-upload-batch: sel-1" -H "x-pw-upload-index: 1" --data-binary @02-kitchen.jpg

# 3. set a category and publish
curl -s -X PATCH https://prewalk.co/api/tours/$TOUR -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: application/json" -d '{"category":"real-estate","location":"Istanbul"}'
curl -s https://prewalk.co/api/content/$TOUR/visibility -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: application/json" -d '{"visibility":"public","rightsAccepted":true}'

# 4. views of the last 30 days
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"

Incorporação

A incorporação não precisa de chave: todo tour tem https://prewalk.co/embed/{id}, e o embed.js ajusta o tamanho do frame e o abre em tela cheia na sua página. Os sites que podem exibir seu conteúdo incorporado são definidos em Configurações → Marca. O guia de incorporação traz os detalhes.

Códigos de erro

Status	Código	Significado
400	invalid_request	Um campo está ausente ou é inválido; field indica qual
400	unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content	Pré-condições de envio ou de publicação (um projeto precisa de um tour público, uma imagem ou um vídeo)
401	unauthorized, invalid_api_key	Nenhuma chave, ou uma chave malformada ou revogada
402	plan_required, quota_exceeded	O plano não inclui o recurso, ou um limite foi atingido (feature ou limit indica qual)
403	api_key_forbidden, api_scope_missing	O endpoint não está aberto a chaves, ou a chave não tem o escopo
404	not_found	Não é seu, foi excluído ou o id não existe
409	revision_conflict, slug_taken, in_password_project	Edição simultânea (o tour atual vem incluído), endereço já em uso, regra de senha do projeto
413	file_too_large	Acima do limite de tamanho
429	rate_limited	Requisições demais; aguarde Retry-After segundos
503	maintenance	O Prewalk está sendo atualizado; tente novamente depois de um minuto

Alterações

• 10 de novembro de 2026: um projeto pode ser publicado ou protegido por senha só com imagens ou vídeos. Um projeto sem nada para mostrar responde 400 project_needs_content, seja público ou com senha; esse código substitui project_needs_public_tour e project_needs_tour, que não são mais enviados. GET /api/projects acrescenta videoCount.
• 22 de outubro de 2026: scene.ready traz pending; novos eventos scene.sharpened e scene.vr_ready; cabeçalhos de ordem de envio x-pw-upload-batch e x-pw-upload-index; com uma chave, GET /api/me descreve somente a conta da chave.

Tem dúvidas ou sente falta de algum endpoint? Escreva para hello@prewalk.co.