Visão geral da documentação

PREVIEWSHIP / HTTP API

Referência da HTTP API

Crie e gerencie previews no servidor ou CI. Todos os exemplos usam a mesma API Key e URL base.

Envie X-API-Key em todas as requisições. Guarde a chave em um cofre de segredos no servidor, nunca no código do navegador ou em arquivos públicos. Antes de usar os exemplos, crie uma API Key no console e defina a variável de ambiente PREVIEWSHIP_API_KEY.

Guarde a API Key no servidor; recursos são restritos à conta proprietária. Se um POST expirar, consulte o histórico antes de tentar novamente para evitar duplicatas.

Os exemplos de resposta mostram alguns campos; limites, IDs e datas são ilustrativos.

IDs são números inteiros. Horários como createdAt e updatedAt são strings ISO 8601 UTC. Um campo omitido é diferente de null; consulte cada endpoint. Domínios e cotas são exemplos. Na paginação, page começa em 0 e o servidor normaliza size para 1–100. current indica se este registro é o deploy apontado por latestDeploymentId do projeto, retained indica a retenção do artefato, canRollback avalia estado, provedor e artefato, e proOnly indica a restrição de direitos da conta. Esses booleanos são independentes e não garantem o sucesso da operação.

Erros comuns: 401 INVALID_API_KEY, 403 ACCOUNT_BLOCKED, 404 recurso não encontrado, 409 conflito, 410 artefato indisponível, 413 upload grande demais e 402 ao esgotar a cota diária ou mensal de deploys. Erros de negócio da aplicação incluem error.code e error.message; error.details pode ser omitido. Erros do gateway ou proxy podem ter outro formato.

error.code →
POST/v1/deployments

Criar deploy

Envie um artefato pronto para o navegador e coloque o deploy na fila.

Requisição
multipart/form-data: projectName e zip são obrigatórios; source, visibility e password são opcionais. zip aceita ZIP estático ou um arquivo HTML, Markdown ou PDF. projectName aceita até 100 pontos de código Unicode. source é apenas um identificador de origem: CONSOLE, CLI, MCP, EXTENSION, API ou GUEST; omitido ou inválido, em pedidos com API Key assume API. Não altera a autenticação. Ao definir uma nova senha, ela deve ter 6–100 caracteres após remover espaços nas extremidades; um projeto existente pode manter a senha salva.
Resposta
201: deploymentId, status, deploymentSource, visibility, createdAt. visibility é o acesso atual; a alteração solicitada se aplica após ativação bem-sucedida.
Valores dos campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida do deploy: READY indica ativação bem-sucedida, mas pode mudar depois para SUPERSEDED, EXPIRED ou BLOCKED. Alguns deploys BLOCKED podem se recuperar após a correção. Nenhum estado é garantido como permanente; status por si só não garante acesso à URL.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

Na criação e no PATCH apenas PUBLIC e PASSWORD são aceitos; PRIVATE pode aparecer em leituras históricas.

source: CONSOLE, CLI, MCP, EXTENSION, API, GUEST

O source opcional é uma identificação de origem e não controla a autenticação. Se ausente ou inválido em chamadas com API key, o padrão é API.

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

A origem na resposta não é uma enumeração fechada: valores históricos ou futuros podem ocorrer. Na maioria dos detalhes/listas o REDEPLOY histórico vira CONSOLE; versões pode retornar o valor armazenado.

Limites e comportamento
Sem visibility, um projeto novo é PUBLIC e um existente mantém seu acesso. PASSWORD exige plano elegível. Cotas e verificações se aplicam; 201 não significa conclusão.
Detalhes de campos e comportamento

O campo multipart projectName deve estar presente; se estiver em branco, o servidor tenta deduzi-lo do nome do arquivo enviado. HTTP 201 apenas indica que a tarefa entrou na fila. A visibility retornada é o acesso atual; a alteração solicitada vale após a ativação. No upload de deploy, uma nova senha é salva sem espaços nas extremidades.

Exemplo

curl -X POST 'https://api.previewship.com/v1/deployments' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY" \
  -F 'projectName=my-project' \
  -F 'zip=@./site.zip'

Resposta

{
  "deploymentId": 42,
  "status": "QUEUED",
  "deploymentSource": "API",
  "visibility": "PUBLIC",
  "createdAt": "2026-11-13T10:00:00Z"
}
GET/v1/deployments/{id}

Consultar deploy

Consulte o estado e a disponibilidade do preview.

Requisição
O id na rota é o ID do deploy; sem corpo.
Resposta
200: deploymentId, projectId, status, previewUrl, urlStatus, failureCode, errorMessage, contentRisk e disponibilidade de nova tentativa.
Valores dos campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida do deploy: READY indica ativação bem-sucedida, mas pode mudar depois para SUPERSEDED, EXPIRED ou BLOCKED. Alguns deploys BLOCKED podem se recuperar após a correção. Nenhum estado é garantido como permanente; status por si só não garante acesso à URL.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Disponibilidade da URL calculada pelo estado do backend; confira junto com o estado do deploy. READY não garante acesso sem senha nem a todos os visitantes; controles de acesso, rede e hospedagem continuam influenciando.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

Na criação e no PATCH apenas PUBLIC e PASSWORD são aceitos; PRIVATE pode aparecer em leituras históricas.

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

A origem na resposta não é uma enumeração fechada: valores históricos ou futuros podem ocorrer. Na maioria dos detalhes/listas o REDEPLOY histórico vira CONSOLE; versões pode retornar o valor armazenado.

hostingStatus: BLOCKED, ARCHIVED, RESTORING, SUBSCRIPTION_ACTIVE, GRACE, FREE_ACTIVE, EXPIRED, RESTORE_UNAVAILABLE

Estado de hospedagem calculado; só é retornado quando o serviço correspondente está disponível.

contentRisk.status: PENDING, CHECKING, RETRYING, COMPLETED

contentRisk pode ser null; seu status descreve a verificação, não o acesso à URL.

contentRisk.decision: PASS, HOLD, UNKNOWN

contentRisk.decision é o resultado da revisão e não garante acesso à prévia.

contentRisk.riskLevel: LOW, MEDIUM, HIGH, UNKNOWN

Categoria de risco de contentRisk; UNKNOWN não significa seguro.

contentRisk.notificationStatus: PENDING, RETRYING, ACCEPTED, FAILED, SKIPPED_NO_RECIPIENT, SKIPPED, SUPERSEDED

Estado da notificação; ACCEPTED significa aceito pelo serviço de e-mail, não entregue. RUNNING é exibido como PENDING. Os valores conhecidos não formam uma lista fechada.

contentRisk.findings[].limit.scope: TOTAL_BYTES, FILE_BYTES, MARKUP_NODES, LINKED_SCRIPT_BYTES, AI_TAG_CHARS_AT_LEAST, AI_CONTEXT_CHARS, AI_CANDIDATES, AI_BATCHES, AI_INPUT_CHARS

Aparece apenas em certos findings; os valores scope conhecidos não são uma lista fechada. As unidades de actual e maximum aparecem abaixo.

failureCode: UNBUILT_SOURCE, EMPTY_ARCHIVE, MISSING_ENTRY_FILE, MULTIPLE_BUILD_OUTPUTS, INVALID_PDF_FILE, INVALID_ARCHIVE_PATH, ARCHIVE_READ_FAILED, UPLOAD_ARTIFACT_MISSING, DEPLOYMENT_PROVIDER_FAILED, CONTENT_CHECK_UNAVAILABLE, CONTENT_RISK_HIGH, MULTIPLE_PDF_FILES, ZIP_TOO_LARGE, DEPLOYMENT_SUPERSEDED

Valores failureCode comuns de deploy assíncrono, não exaustivos; confira errorMessage e a disponibilidade de nova tentativa.

Limites e comportamento
Somente deploys da conta proprietária. Consulte periodicamente até o estado final e use o link quando estiver READY e disponível.
Detalhes de campos e comportamento

status indica o estado do deploy e urlStatus a disponibilidade da prévia; podem divergir após restrição ou expiração. contentRisk pode ser null; attempt, maxAttempts e nextRetryAt podem ser omitidos. contentCheckRetryAvailable não garante que os direitos atuais permitam a tentativa; contentCheckRetryExpiresAt null pode indicar que uma tentativa existente pode ser recuperada. contentCheckUploadQuotaRestored marca o processamento da compensação, sem provar que o contador do período atual mudou. hostingStatus, hostingUntil, paidThrough, autoRenews e restorable são condicionais; hostingUntil e paidThrough podem ser null. contentRisk.findings é um array; reasonCode é uma string extensível e limit pode ser omitido. verifiedSafeRecheck=true exige um PASS concluído, uma versão de modelo não vazia e um resultado SAFE do modelo com confiança HIGH registrado; PASS sozinho não satisfaz essa condição.

Exemplo

curl 'https://api.previewship.com/v1/deployments/42' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Resposta

{
  "deploymentId": 42,
  "projectId": 7,
  "projectName": "my-project",
  "status": "READY",
  "deploymentSource": "API",
  "previewUrl": "https://example.previewship.net",
  "urlStatus": "READY",
  "contentRestricted": false,
  "previewExpiresAt": null,
  "errorMessage": null,
  "failureCode": null,
  "contentRisk": null,
  "contentCheckArtifactExpiresAt": null,
  "contentCheckUploadQuotaRestored": false,
  "contentCheckRetryAvailable": false,
  "contentCheckRetryExpiresAt": null,
  "visibility": "PUBLIC",
  "createdAt": "2026-11-13T10:00:00Z",
  "updatedAt": "2026-11-13T10:01:00Z"
}
GET/v1/deployments

Listar deploys

Pesquise o histórico de deploys da conta.

Requisição
Consultas opcionais: page (padrão 0), size (padrão 20), status, q, days. status aceita ALL ou um único valor: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED ou BLOCKED. q busca correspondências parciais no nome do projeto ou na URL de preview; days filtra os últimos N dias.
Resposta
200: content, page, size, totalElements, totalPages e statusCounts. statusCounts considera q e days, mas não o filtro status.
Valores dos campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida do deploy: READY indica ativação bem-sucedida, mas pode mudar depois para SUPERSEDED, EXPIRED ou BLOCKED. Alguns deploys BLOCKED podem se recuperar após a correção. Nenhum estado é garantido como permanente; status por si só não garante acesso à URL.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Disponibilidade da URL calculada pelo estado do backend; confira junto com o estado do deploy. READY não garante acesso sem senha nem a todos os visitantes; controles de acesso, rede e hospedagem continuam influenciando.

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

A origem na resposta não é uma enumeração fechada: valores históricos ou futuros podem ocorrer. Na maioria dos detalhes/listas o REDEPLOY histórico vira CONSOLE; versões pode retornar o valor armazenado.

Limites e comportamento
page começa em 0; size fica entre 1–100. days tem máximo de 365; valor não positivo não filtra por data. status inválido retorna 400.

Exemplo

curl -G 'https://api.previewship.com/v1/deployments' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY" \
  --data-urlencode 'page=0' --data-urlencode 'size=20' \
  --data-urlencode 'status=READY' --data-urlencode 'q=my-project' --data-urlencode 'days=30'

Resposta

{
  "content": [
    {
      "deploymentId": 42,
      "projectId": 7,
      "projectName": "my-project",
      "status": "READY",
      "deploymentSource": "API",
      "previewUrl": "https://example.previewship.net",
      "urlStatus": "READY",
      "contentRestricted": false,
      "previewExpiresAt": null,
      "current": true,
      "canRollback": true,
      "createdAt": "2026-11-13T10:00:00Z"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1,
  "statusCounts": {
    "all": 1,
    "queued": 0,
    "building": 0,
    "ready": 1,
    "superseded": 0,
    "failed": 0,
    "expired": 0,
    "blocked": 0
  }
}
POST/v1/deployments/{id}/retry-content-check

Repetir verificação de conteúdo

Repita uma falha técnica recuperável da verificação sem enviar novamente.

Requisição
O id na rota é o ID do deploy que falhou; sem corpo.
Resposta
201: deploymentId, status, deploymentSource, visibility e createdAt do novo deploy.
Valores dos campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida do deploy: READY indica ativação bem-sucedida, mas pode mudar depois para SUPERSEDED, EXPIRED ou BLOCKED. Alguns deploys BLOCKED podem se recuperar após a correção. Nenhum estado é garantido como permanente; status por si só não garante acesso à URL.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

Na criação e no PATCH apenas PUBLIC e PASSWORD são aceitos; PRIVATE pode aparecer em leituras históricas.

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

A origem na resposta não é uma enumeração fechada: valores históricos ou futuros podem ocorrer. Na maioria dos detalhes/listas o REDEPLOY histórico vira CONSOLE; versões pode retornar o valor armazenado.

Limites e comportamento
Confira contentCheckRetryAvailable. É preciso ter artefato retido e projeto e acesso elegíveis; uma versão publicada mais recente impede nova tentativa. Repetir a chamada retorna a tentativa existente.
Detalhes de campos e comportamento

Para contas sujeitas a limites comerciais, a primeira tentativa consome os limites diário e mensal de deploys sem acrescentar volume de upload. Uma solicitação repetida para a mesma falha pode retornar o deploy filho existente sem consumir a contagem novamente.

Exemplo

curl -X POST 'https://api.previewship.com/v1/deployments/42/retry-content-check' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Resposta

{
  "deploymentId": 43,
  "status": "QUEUED",
  "deploymentSource": "CONTENT_CHECK_RETRY",
  "visibility": "PUBLIC",
  "createdAt": "2026-11-13T10:05:00Z"
}
GET/v1/projects

Listar projetos

Liste os projetos da conta dona da API Key.

Requisição
Sem parâmetros ou corpo.
Resposta
200: array projects com ID, nome, estado mais recente, URL de preview e acesso.
Valores dos campos
latestDeploymentStatus: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida do deploy: READY indica ativação bem-sucedida, mas pode mudar depois para SUPERSEDED, EXPIRED ou BLOCKED. Alguns deploys BLOCKED podem se recuperar após a correção. Nenhum estado é garantido como permanente; status por si só não garante acesso à URL.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Disponibilidade da URL calculada pelo estado do backend; confira junto com o estado do deploy. READY não garante acesso sem senha nem a todos os visitantes; controles de acesso, rede e hospedagem continuam influenciando.

projectVisibility: PUBLIC, PASSWORD, PRIVATE

Na criação e no PATCH apenas PUBLIC e PASSWORD são aceitos; PRIVATE pode aparecer em leituras históricas.

latestDeploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

A origem na resposta não é uma enumeração fechada: valores históricos ou futuros podem ocorrer. Na maioria dos detalhes/listas o REDEPLOY histórico vira CONSOLE; versões pode retornar o valor armazenado.

projectStatus: ACTIVE, BLOCKED

Estados conhecidos do projeto; trate também outros valores históricos ou futuros.

hostingState: HOSTED, ARCHIVED

O estado de hospedagem é independente de projectStatus e de restrições de conteúdo.

hostingStatus: BLOCKED, ARCHIVED, RESTORING, SUBSCRIPTION_ACTIVE, GRACE, FREE_ACTIVE, EXPIRED, RESTORE_UNAVAILABLE

Estado de hospedagem calculado; só é retornado quando o serviço correspondente está disponível.

Limites e comportamento
Somente projetos da conta; projetos de convidado são excluídos.
Detalhes de campos e comportamento

latestDeploymentId, latestDeploymentStatus, latestDeploymentSource, latestDeployedAt, previewUrl e previewExpiresAt podem ser null. hostingStatus, hostingUntil, paidThrough, autoRenews e restorable só aparecem quando o estado de hospedagem está disponível; hostingUntil e paidThrough podem ser null. Se o registro apontado por latest estiver ausente, os valores exibidos como latestDeploymentStatus, latestDeploymentSource e previewUrl podem vir de um deploy Vercel READY anterior e não corresponder a latestDeploymentId.

Exemplo

curl 'https://api.previewship.com/v1/projects' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Resposta

{
  "projects": [
    {
      "id": 7,
      "name": "my-project",
      "latestDeploymentId": 42,
      "latestDeploymentStatus": "READY",
      "latestDeploymentSource": "API",
      "latestDeployedAt": "2026-11-13T10:00:00Z",
      "deploymentCount": 1,
      "previewUrl": "https://example.previewship.net",
      "previewExpiresAt": null,
      "projectStatus": "ACTIVE",
      "contentRestricted": false,
      "hostingState": "HOSTED",
      "projectVisibility": "PUBLIC",
      "passwordProtected": false,
      "abuseBlockedAt": null,
      "abuseBlockedReason": null,
      "urlStatus": "READY",
      "canRedeploy": false,
      "createdAt": "2026-11-13T10:00:00Z",
      "updatedAt": "2026-11-13T10:01:00Z"
    }
  ]
}
GET/v1/projects/{id}

Consultar projeto

Consulte o projeto e o deploy mais recente.

Requisição
O id na rota é o ID do projeto; sem corpo.
Resposta
200: id, name, latestDeploymentId, latestDeploymentStatus, previewUrl, projectVisibility, urlStatus e canRedeploy.
Valores dos campos
latestDeploymentStatus: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida do deploy: READY indica ativação bem-sucedida, mas pode mudar depois para SUPERSEDED, EXPIRED ou BLOCKED. Alguns deploys BLOCKED podem se recuperar após a correção. Nenhum estado é garantido como permanente; status por si só não garante acesso à URL.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Disponibilidade da URL calculada pelo estado do backend; confira junto com o estado do deploy. READY não garante acesso sem senha nem a todos os visitantes; controles de acesso, rede e hospedagem continuam influenciando.

projectVisibility: PUBLIC, PASSWORD, PRIVATE

Na criação e no PATCH apenas PUBLIC e PASSWORD são aceitos; PRIVATE pode aparecer em leituras históricas.

latestDeploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

A origem na resposta não é uma enumeração fechada: valores históricos ou futuros podem ocorrer. Na maioria dos detalhes/listas o REDEPLOY histórico vira CONSOLE; versões pode retornar o valor armazenado.

projectStatus: ACTIVE, BLOCKED

Estados conhecidos do projeto; trate também outros valores históricos ou futuros.

hostingState: HOSTED, ARCHIVED

O estado de hospedagem é independente de projectStatus e de restrições de conteúdo.

hostingStatus: BLOCKED, ARCHIVED, RESTORING, SUBSCRIPTION_ACTIVE, GRACE, FREE_ACTIVE, EXPIRED, RESTORE_UNAVAILABLE

Estado de hospedagem calculado; só é retornado quando o serviço correspondente está disponível.

Limites e comportamento
Somente projetos próprios que não sejam de convidado; ausentes ou de outra conta retornam 404.
Detalhes de campos e comportamento

latestDeploymentId, latestDeploymentStatus, latestDeploymentSource, latestDeployedAt, previewUrl e previewExpiresAt podem ser null. hostingStatus, hostingUntil, paidThrough, autoRenews e restorable só aparecem quando o estado de hospedagem está disponível; hostingUntil e paidThrough podem ser null. Se o registro apontado por latest estiver ausente, os valores exibidos como latestDeploymentStatus, latestDeploymentSource e previewUrl podem vir de um deploy Vercel READY anterior e não corresponder a latestDeploymentId.

Exemplo

curl 'https://api.previewship.com/v1/projects/7' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Resposta

{
  "id": 7,
  "name": "my-project",
  "latestDeploymentId": 42,
  "latestDeploymentStatus": "READY",
  "latestDeploymentSource": "API",
  "latestDeployedAt": "2026-11-13T10:00:00Z",
  "deploymentCount": 1,
  "previewUrl": "https://example.previewship.net",
  "previewExpiresAt": null,
  "projectStatus": "ACTIVE",
  "contentRestricted": false,
  "hostingState": "HOSTED",
  "projectVisibility": "PUBLIC",
  "passwordProtected": false,
  "abuseBlockedAt": null,
  "abuseBlockedReason": null,
  "urlStatus": "READY",
  "canRedeploy": false,
  "createdAt": "2026-11-13T10:00:00Z",
  "updatedAt": "2026-11-13T10:01:00Z"
}
DELETE/v1/projects/{id}

Excluir projeto

Exclua permanentemente o projeto e seus deploys.

Requisição
O id na rota é o ID do projeto; sem corpo.
Resposta
204 sem corpo.
Limites e comportamento
Remove a URL fixa, hospedagem, deploys associados e item do Showcase. A HTTP API não exige confirmação do nome; verifique o alvo antes da chamada.

Exemplo

curl -i -X DELETE 'https://api.previewship.com/v1/projects/7' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Resposta

HTTP 204 No Content
POST/v1/projects/{id}/redeploy-latest

Republicar versão mais recente

Coloque na fila um deploy do último artefato retido.

Requisição
O id na rota é o ID do projeto; sem corpo.
Resposta
201: deploymentId, projectId, status, deploymentSource e createdAt.
Valores dos campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida do deploy: READY indica ativação bem-sucedida, mas pode mudar depois para SUPERSEDED, EXPIRED ou BLOCKED. Alguns deploys BLOCKED podem se recuperar após a correção. Nenhum estado é garantido como permanente; status por si só não garante acesso à URL.

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

A origem na resposta não é uma enumeração fechada: valores históricos ou futuros podem ocorrer. Na maioria dos detalhes/listas o REDEPLOY histórico vira CONSOLE; versões pode retornar o valor armazenado.

Limites e comportamento
Exige projeto elegível e artefato retido de hospedagem própria. Normalmente a URL deve estar expirada; contas internas também podem republicar versão READY. Consulte o novo deploy.
Detalhes de campos e comportamento

Para contas sujeitas a limites comerciais, criar um redeploy consome os limites diário e mensal de deploys sem acrescentar upload. O deploy é assíncrono.

Exemplo

curl -X POST 'https://api.previewship.com/v1/projects/7/redeploy-latest' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Resposta

{
  "deploymentId": 43,
  "projectId": 7,
  "status": "QUEUED",
  "deploymentSource": "CONSOLE",
  "createdAt": "2026-11-13T10:05:00Z"
}
GET/v1/projects/{id}/access

Consultar acesso

Leia o modo de acesso do projeto.

Requisição
O id na rota é o ID do projeto; sem corpo.
Resposta
200: projectId, visibility, passwordProtected e proOnly.
Valores dos campos
visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

Na criação e no PATCH apenas PUBLIC e PASSWORD são aceitos; PRIVATE pode aparecer em leituras históricas.

Limites e comportamento
Somente projetos próprios; a senha nunca é retornada.
Detalhes de campos e comportamento

proOnly indica que a conta não possui o direito de acesso por senha; consulte visibility e passwordProtected para o modo e o estado da senha do projeto.

Exemplo

curl 'https://api.previewship.com/v1/projects/7/access' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Resposta

{
  "projectId": 7,
  "visibility": "PUBLIC",
  "passwordProtected": false,
  "proOnly": false
}
PATCH/v1/projects/{id}/access

Alterar acesso

Configure acesso público ou por senha.

Requisição
O id na rota é o ID do projeto. JSON: visibility PUBLIC ou PASSWORD; password pode ser omitida se já houver senha.
Resposta
200: projectId, visibility, passwordProtected e proOnly.
Valores dos campos
visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

Na criação e no PATCH apenas PUBLIC e PASSWORD são aceitos; PRIVATE pode aparecer em leituras históricas.

Limites e comportamento
PASSWORD exige plano elegível e senha de 6–100 caracteres se não houver uma. PUBLIC apaga a senha salva; visibility omitida ou vazia assume PUBLIC.
Detalhes de campos e comportamento

proOnly indica que a conta não possui o direito de acesso por senha; consulte visibility e passwordProtected para o modo e o estado da senha do projeto.

Se visibility for omitida ou estiver vazia, torna-se PUBLIC e apaga a senha salva. O comprimento é validado após remover espaços das extremidades, mas PATCH salva a entrada original, diferentemente do upload de deploy. Evite espaços no início ou no fim da senha.

Exemplo

curl -X PATCH 'https://api.previewship.com/v1/projects/7/access' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"visibility":"PUBLIC"}'

Resposta

{
  "projectId": 7,
  "visibility": "PUBLIC",
  "passwordProtected": false,
  "proOnly": false
}
GET/v1/projects/{id}/versions

Listar versões

Consulte o histórico e a disponibilidade de rollback.

Requisição
O id na rota é o ID do projeto. Consultas opcionais page (padrão 0) e size (padrão 20).
Resposta
200: projectId, latestDeploymentId, limit, versions, page, size, totalElements e totalPages.
Valores dos campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida do deploy: READY indica ativação bem-sucedida, mas pode mudar depois para SUPERSEDED, EXPIRED ou BLOCKED. Alguns deploys BLOCKED podem se recuperar após a correção. Nenhum estado é garantido como permanente; status por si só não garante acesso à URL.

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

A origem na resposta não é uma enumeração fechada: valores históricos ou futuros podem ocorrer. Na maioria dos detalhes/listas o REDEPLOY histórico vira CONSOLE; versões pode retornar o valor armazenado.

Limites e comportamento
page começa em 0 e size fica entre 1–100. O histórico visível depende da conta; confira retained e canRollback de cada versão.

Exemplo

curl -G 'https://api.previewship.com/v1/projects/7/versions' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY" --data-urlencode 'page=0' --data-urlencode 'size=20'

Resposta

{
  "projectId": 7,
  "latestDeploymentId": 42,
  "limit": 3,
  "versions": [
    {
      "deploymentId": 42,
      "current": true,
      "status": "READY",
      "deploymentSource": "API",
      "previewUrl": "https://example.previewship.net",
      "previewExpiresAt": null,
      "artifactExpiresAt": null,
      "artifactDeletedAt": null,
      "retained": true,
      "canRollback": true,
      "createdAt": "2026-11-13T10:00:00Z"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}
POST/v1/projects/{id}/versions/{deploymentId}/rollback

Reverter versão

Crie um novo deploy assíncrono a partir de uma versão histórica retida.

Requisição
O id na rota é o ID do projeto e deploymentId o da versão; sem corpo.
Resposta
200: rolledBack, status, deploymentSource, deploymentId e previewUrl (inicialmente null).
Valores dos campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida do deploy: READY indica ativação bem-sucedida, mas pode mudar depois para SUPERSEDED, EXPIRED ou BLOCKED. Alguns deploys BLOCKED podem se recuperar após a correção. Nenhum estado é garantido como permanente; status por si só não garante acesso à URL.

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

A origem na resposta não é uma enumeração fechada: valores históricos ou futuros podem ocorrer. Na maioria dos detalhes/listas o REDEPLOY histórico vira CONSOLE; versões pode retornar o valor armazenado.

Limites e comportamento
Apenas versões auto-hospedadas READY ou SUPERSEDED com artefato retido. A URL fixa muda após ativação bem-sucedida; consulte o deploymentId retornado. HTTP não exige confirmação do nome.
Detalhes de campos e comportamento

O rollback cria um deploy assíncrono sem consumir os limites diário ou mensal. rolledBack=true confirma a criação, não a ativação; consulte o deploymentId retornado.

Exemplo

curl -X POST 'https://api.previewship.com/v1/projects/7/versions/42/rollback' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Resposta

{
  "rolledBack": true,
  "status": "QUEUED",
  "deploymentSource": "ROLLBACK",
  "deploymentId": 43,
  "previewUrl": null
}
GET/v1/usage

Consultar uso

Consulte limites e uso atual da conta.

Requisição
Sem parâmetros ou corpo.
Resposta
200: plan, subscriptionStatus, businessLimitsApplied, maxUploadMb, daily, monthly, monthlyUpload, concurrentBuilds e projects.
Valores dos campos
plan / subscriptionPlan: FREE, PRO_MONTHLY, PRO_YEARLY

plan é o direito vigente; subscriptionPlan é o plano assinado e pode continuar Pro após o término do direito.

subscriptionStatus: FREE, ACTIVE, PAST_DUE, CANCELED

Estado atual da assinatura, independente do estado do deploy.

Limites e comportamento
Os limites dependem da política da conta e podem mudar; use os valores retornados.
Detalhes de campos e comportamento

HTTP 402 pode indicar limite diário ou mensal de deploys ou limite mensal de upload. Os limites reais e a aplicação de limites comerciais dependem da política da conta.

Exemplo

curl 'https://api.previewship.com/v1/usage' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Resposta

{
  "plan": "FREE",
  "subscriptionPlan": "FREE",
  "subscriptionStatus": "FREE",
  "paidThrough": null,
  "autoRenews": false,
  "businessLimitsApplied": true,
  "maxUploadMb": 15,
  "daily": {
    "used": 1,
    "limit": 5,
    "resetAt": "2026-11-14T00:00:00Z"
  },
  "monthly": {
    "used": 1,
    "limit": 20,
    "resetAt": "2026-12-01T00:00:00Z"
  },
  "monthlyUpload": {
    "usedMb": 1,
    "limitMb": 200,
    "resetAt": "2026-12-01T00:00:00Z"
  },
  "concurrentBuilds": {
    "current": 0,
    "limit": 1
  },
  "projects": {
    "used": 1,
    "limit": 1
  }
}

Valores dos campos

status

Ciclo de vida do deploy: READY indica ativação bem-sucedida, mas pode mudar depois para SUPERSEDED, EXPIRED ou BLOCKED. Alguns deploys BLOCKED podem se recuperar após a correção. Nenhum estado é garantido como permanente; status por si só não garante acesso à URL.

QUEUED
Aguardando na fila
BUILDING
Em processamento pelo worker
READY
Deploy ativado
SUPERSEDED
Substituído por deploy posterior
FAILED
Falha no deploy
EXPIRED
Prévia expirada
BLOCKED
Deploy bloqueado

urlStatus

Disponibilidade da URL calculada pelo estado do backend; confira junto com o estado do deploy. READY não garante acesso sem senha nem a todos os visitantes; controles de acesso, rede e hospedagem continuam influenciando.

READY
Calculada como disponível pelo estado do backend
BLOCKED
Acesso bloqueado ou restrito
EXPIRED
Prévia expirada
UNAVAILABLE
Nenhuma URL disponível no momento

visibility / projectVisibility

Na criação e no PATCH apenas PUBLIC e PASSWORD são aceitos; PRIVATE pode aparecer em leituras históricas.

PUBLIC
Acesso público
PASSWORD
Acesso por senha
PRIVATE
Modo privado histórico; não aceito nestas escritas

source

O source opcional é uma identificação de origem e não controla a autenticação. Se ausente ou inválido em chamadas com API key, o padrão é API.

CONSOLE
Identificação do console
CLI
Identificação CLI
MCP
Identificação MCP
EXTENSION
Identificação da extensão
API
Identificação de API direta
GUEST
Identificação de visitante

deploymentSource

A origem na resposta não é uma enumeração fechada: valores históricos ou futuros podem ocorrer. Na maioria dos detalhes/listas o REDEPLOY histórico vira CONSOLE; versões pode retornar o valor armazenado.

CONSOLE
Console ou redeploy histórico normalizado
CLI
CLI
MCP
MCP
EXTENSION
Extensão de editor
API
API direta
GUEST
Visitante
UNKNOWN
Origem desconhecida
CONTENT_CHECK_RETRY
Nova tentativa de verificação técnica
ROLLBACK
Deploy de rollback
SUBSCRIPTION_RESTORE
Restauração da assinatura
REDEPLOY
Origem histórica de redeploy armazenada

projectStatus

Estados conhecidos do projeto; trate também outros valores históricos ou futuros.

ACTIVE
Projeto ativo
BLOCKED
Projeto bloqueado

hostingState

O estado de hospedagem é independente de projectStatus e de restrições de conteúdo.

HOSTED
Projeto hospedado
ARCHIVED
Projeto arquivado

hostingStatus

Estado de hospedagem calculado; só é retornado quando o serviço correspondente está disponível.

BLOCKED
Projeto ou deploy bloqueado
ARCHIVED
Projeto arquivado
RESTORING
Restauração de assinatura em andamento
SUBSCRIPTION_ACTIVE
Hospedagem paga ativa
GRACE
Período de carência da hospedagem paga
FREE_ACTIVE
Hospedagem gratuita ativa
EXPIRED
Expirado e restaurável
RESTORE_UNAVAILABLE
Restauração indisponível

plan / subscriptionPlan

plan é o direito vigente; subscriptionPlan é o plano assinado e pode continuar Pro após o término do direito.

FREE
Plano gratuito
PRO_MONTHLY
Plano Pro mensal
PRO_YEARLY
Plano Pro anual

subscriptionStatus

Estado atual da assinatura, independente do estado do deploy.

FREE
Estado de assinatura gratuita
ACTIVE
Assinatura ativa
PAST_DUE
Pagamento em atraso
CANCELED
Assinatura cancelada

contentRisk.status

contentRisk pode ser null; seu status descreve a verificação, não o acesso à URL.

PENDING
Aguardando revisão
CHECKING
Revisão em andamento
RETRYING
Aguardando nova tentativa
COMPLETED
Verificação concluída; a decisão ainda pode ser UNKNOWN

contentRisk.decision

contentRisk.decision é o resultado da revisão e não garante acesso à prévia.

PASS
Verificação aprovada
HOLD
Retido por risco
UNKNOWN
Sem decisão conclusiva

contentRisk.riskLevel

Categoria de risco de contentRisk; UNKNOWN não significa seguro.

LOW
Baixo risco
MEDIUM
Risco médio
HIGH
Alto risco
UNKNOWN
Risco indeterminado

contentRisk.notificationStatus

Estado da notificação; ACCEPTED significa aceito pelo serviço de e-mail, não entregue. RUNNING é exibido como PENDING. Os valores conhecidos não formam uma lista fechada.

PENDING
Aguardando envio
RETRYING
Aguardando nova tentativa
ACCEPTED
Aceito pelo serviço de e-mail
FAILED
Falha no envio
SKIPPED_NO_RECIPIENT
Sem destinatário
SKIPPED
Notificação ignorada
SUPERSEDED
Aviso substituído por estado posterior

contentRisk.findings[].limit.scope

Aparece apenas em certos findings; os valores scope conhecidos não são uma lista fechada. As unidades de actual e maximum aparecem abaixo.

TOTAL_BYTES
Bytes totais do artefato
FILE_BYTES
Bytes do arquivo
MARKUP_NODES
Nós de marcação
LINKED_SCRIPT_BYTES
Bytes de scripts vinculados
AI_TAG_CHARS_AT_LEAST
Mínimo de caracteres de tag HTML inicial não concluída
AI_CONTEXT_CHARS
Caracteres do contexto de verificação
AI_CANDIDATES
Candidatos de segurança
AI_BATCHES
Lotes de revisão de IA
AI_INPUT_CHARS
Caracteres de entrada de IA

error.code

Valores HTTP error.code comuns, não exaustivos; confira message e o details opcional.

INVALID_API_KEY
Chave ausente ou inválida
ACCOUNT_BLOCKED
Conta bloqueada
INVALID_PARAM
Parâmetro inválido
DAILY_QUOTA_EXCEEDED
Cota diária de deploys excedida
MONTHLY_QUOTA_EXCEEDED
Cota mensal de deploys excedida
MONTHLY_UPLOAD_EXCEEDED
Cota mensal de upload excedida
MAX_PROJECTS_EXCEEDED
Cota de projetos excedida
ZIP_TOO_LARGE
Upload grande demais
DEPLOYMENT_NOT_REDEPLOYABLE
Deploy não permite nova tentativa direta
DEPLOYMENT_SUPERSEDED
Existe deploy mais recente
PROJECT_URL_NOT_EXPIRED
URL do projeto ainda não expirou
PROJECT_ARCHIVED
Projeto arquivado
ARTIFACT_NOT_RETAINED
Artefato não retido
PROJECT_NOT_FOUND
Projeto inexistente ou sem acesso
DEPLOYMENT_NOT_FOUND
Deploy inexistente ou sem acesso
PROJECT_BLOCKED
Projeto bloqueado
DOWNGRADE_NOT_ALLOWED
Operação não permitida pelo plano atual

failureCode

Valores failureCode comuns de deploy assíncrono, não exaustivos; confira errorMessage e a disponibilidade de nova tentativa.

UNBUILT_SOURCE
Código fonte não compilado
EMPTY_ARCHIVE
Arquivo compactado vazio
MISSING_ENTRY_FILE
Arquivo de entrada ausente
MULTIPLE_BUILD_OUTPUTS
Várias saídas de build
INVALID_PDF_FILE
PDF inválido
INVALID_ARCHIVE_PATH
Caminho do arquivo compactado inválido
ARCHIVE_READ_FAILED
Falha ao ler arquivo compactado
UPLOAD_ARTIFACT_MISSING
Artefato enviado ausente
DEPLOYMENT_PROVIDER_FAILED
Falha no provedor de hospedagem
CONTENT_CHECK_UNAVAILABLE
Verificação de conteúdo indisponível
CONTENT_RISK_HIGH
Risco de conteúdo confirmado
MULTIPLE_PDF_FILES
Vários arquivos PDF
ZIP_TOO_LARGE
Arquivo compactado grande demais
DEPLOYMENT_SUPERSEDED
Substituído por deploy mais recente