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 →/v1/deploymentsCriar 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,BLOCKEDCiclo 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,PRIVATENa 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,GUESTO 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,REDEPLOYA 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"
}/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,BLOCKEDCiclo 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,UNAVAILABLEDisponibilidade 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,PRIVATENa 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,REDEPLOYA 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_UNAVAILABLEEstado de hospedagem calculado; só é retornado quando o serviço correspondente está disponível.
contentRisk.status:PENDING,CHECKING,RETRYING,COMPLETEDcontentRisk pode ser null; seu status descreve a verificação, não o acesso à URL.
contentRisk.decision:PASS,HOLD,UNKNOWNcontentRisk.decision é o resultado da revisão e não garante acesso à prévia.
contentRisk.riskLevel:LOW,MEDIUM,HIGH,UNKNOWNCategoria de risco de contentRisk; UNKNOWN não significa seguro.
contentRisk.notificationStatus:PENDING,RETRYING,ACCEPTED,FAILED,SKIPPED_NO_RECIPIENT,SKIPPED,SUPERSEDEDEstado 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_CHARSAparece 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_SUPERSEDEDValores 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"
}/v1/deploymentsListar 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,BLOCKEDCiclo 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,UNAVAILABLEDisponibilidade 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,REDEPLOYA 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
}
}/v1/deployments/{id}/retry-content-checkRepetir 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,BLOCKEDCiclo 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,PRIVATENa 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,REDEPLOYA 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"
}/v1/projectsListar 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,BLOCKEDCiclo 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,UNAVAILABLEDisponibilidade 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,PRIVATENa 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,REDEPLOYA 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,BLOCKEDEstados conhecidos do projeto; trate também outros valores históricos ou futuros.
hostingState:HOSTED,ARCHIVEDO estado de hospedagem é independente de projectStatus e de restrições de conteúdo.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLEEstado 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"
}
]
}/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,BLOCKEDCiclo 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,UNAVAILABLEDisponibilidade 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,PRIVATENa 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,REDEPLOYA 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,BLOCKEDEstados conhecidos do projeto; trate também outros valores históricos ou futuros.
hostingState:HOSTED,ARCHIVEDO estado de hospedagem é independente de projectStatus e de restrições de conteúdo.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLEEstado 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"
}/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/v1/projects/{id}/redeploy-latestRepublicar 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,BLOCKEDCiclo 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,REDEPLOYA 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"
}/v1/projects/{id}/accessConsultar 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,PRIVATENa 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
}/v1/projects/{id}/accessAlterar 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,PRIVATENa 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
}/v1/projects/{id}/versionsListar 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,BLOCKEDCiclo 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,REDEPLOYA 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
}/v1/projects/{id}/versions/{deploymentId}/rollbackReverter 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,BLOCKEDCiclo 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,REDEPLOYA 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
}/v1/usageConsultar 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_YEARLYplan é o direito vigente; subscriptionPlan é o plano assinado e pode continuar Pro após o término do direito.
subscriptionStatus:FREE,ACTIVE,PAST_DUE,CANCELEDEstado 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