Referência da API

A API REST do GoShip cobre organizações, projetos, ambientes, clusters, apps, bancos, domínios e volumes. O CLI usa exatamente esses endpoints.

• Base URL: https://api.goship.sh/api/v1
• OpenAPI / Swagger: em breve

A autenticação é via bearer token — veja API → Autenticação.

Organizações, ambientes e projetos

Os recursos vivem dentro de um projeto e de um ambiente, então os caminhos têm a forma /orgs/{org}/projects/{project}/environments/{env}/..., com o slug do ambiente (production, staging…) em {env}. Isso vale pra apps, databases, services, volumes, plans e available-plans.

curl -H "Authorization: Bearer $GOSHIP_TOKEN" \
  https://api.goship.sh/api/v1/orgs/acme/projects/loja/environments/production/apps

available-plans aceita ?kind=app ou ?kind=database e lista os planos que o ambiente oferece, conforme o cluster dele. Ambientes e clusters são da organização, não de um projeto: as rotas deles estão abaixo.

Projetos

Os papéis na API são admin (administrador), developer (desenvolvedor) e viewer (leitor), como aparecem no painel.

O slug segue ^[a-z]([a-z0-9-]{0,29}[a-z0-9])?$ e não pode ser new, settings, members, projects nem o slug de um ambiente de partida (production, staging, development).

Ambientes

Os ambientes são da organização. Veja Ambientes pras regras do slug e pro que cada escolha significa.

Só o dono e os administradores da organização criam, mudam e apagam ambientes.

A resposta do PATCH traz kept, uma lista de {project, cluster}: os projetos que já tinham app, banco ou volume no ambiente e ficaram no cluster em que estavam quando você trocou o cluster_id. Esses projetos seguem fixados até os recursos serem recriados no destino. A lista vem vazia quando nenhum ficou pra trás.

O DELETE responde 409 enquanto algum projeto tem app, banco ou volume no ambiente, e o corpo lista quais projetos seguram algo.

Clusters

Os clusters também são da organização. Veja Clusters.

O DELETE responde 409 enquanto algum ambiente aponta pro cluster (o corpo lista os ambientes) ou algum projeto ainda roda algo nele.

Quatro rotas abaixo de /orgs/{org}/clusters/{id} cuidam do resto da vida do cluster:

Ambientes de um projeto

Apps privados

Caminhos abaixo de /orgs/{org}/projects/{project}/environments/{env}/apps/{app}. Veja Apps privados.

Para criar o app já privado, envie "private": true no corpo de POST /orgs/{org}/projects/{project}/environments/{env}/apps.

Convites e papéis

Os convites são criados com POST /orgs/{org}/invitations. O papel na organização é admin, member ou collaborator; projects é opcional e dá um papel (admin, developer ou viewer) por projeto. Colaborador exige pelo menos um projeto:

{
  "email": "carla@example.com",
  "role": "collaborator",
  "projects": [{"slug": "app-mobile", "role": "developer"}]
}

GET /auth/me devolve, além do usuário, a lista projects com o seu papel efetivo em cada projeto e a lista environments, com os ambientes de cada organização dele: [{"org": "acme", "slug": "staging", "name": "Staging", "is_default": false}].

O que as respostas trazem

• GET /orgs: cada organização ganha default_environment, o ambiente padrão dela.
• Um app (e as listas de apps) ganha environment, o slug do ambiente, e cluster, com {id, name, shared}: o cluster onde ele roda.
• GET /auth/me: a lista environments, descrita acima.

Caminhos antigos

Os caminhos por projeto, sem ambiente, continuam respondendo por mais uma versão, como aliases do ambiente padrão da organização: /orgs/{org}/projects/{project}/apps, /databases, /services, /volumes, /plans e /available-plans. Cada resposta traz Deprecation: true e Link: <novo caminho>; rel="successor-version". Migre pro caminho com /environments/{env}.

Os caminhos que não têm mais correspondência respondem 410 Gone, com o corpo {"error": "this route moved", "code": "route_moved", "successor": "<caminho>"}, e o successor aponta o caminho novo:

Erros

Os erros chegam com o status HTTP que diz a classe do problema e um corpo {"error": "...", "code": "..."}. O code é o motivo estável: decida por ele, nunca pelo texto de error, que pode mudar. A lista completa está em Códigos de erro.

• 409 com code: in_use: o pedido conflita com o que existe, e o corpo lista o que bloqueia: os projetos que ainda têm recursos num ambiente que você quer apagar, ou os ambientes que ainda apontam pra um cluster que você quer remover.
• 502 com code: platform_error: a plataforma por baixo falhou, e a mensagem diz a etapa e o cluster onde aconteceu.
• 410 com code: route_moved: o caminho saiu do ar; o corpo traz o successor (veja a tabela acima).

Deploy, logs e comandos

Operações que duram o tempo que o trabalho durar respondem com um stream de eventos: Content-Type: application/x-ndjson, um objeto JSON por linha.

Eventos

{"type":"output","data":"---> building\n"}
{"type":"log","date":"2026-09-19T12:00:00Z","source":"web","unit":"...","message":"..."}
{"type":"ping"}
{"type":"result","ok":false,"error":"deploy failed: main.go:3: undefined: x","code":"deploy_failed"}

• output é o texto da operação, na ordem em que sai.
• ping só mantém a conexão viva; ignore.
• result é sempre a última linha. O status HTTP 200 sai antes do trabalho começar, então quem diz se deu certo é o result. Um result de falha traz o code, como qualquer erro da API. Um stream que termina sem result foi interrompido — trate como falha.

Recusas que acontecem antes do trabalho começar (app inexistente, app pausada, arquivo grande demais) chegam como status HTTP normal com {"error": "...", "code": "..."}.

Deploy

O corpo é multipart/form-data: os campos de texto opcionais message e dockerfile, e por último o arquivo file, um tarball gzip do código. file precisa ser o último campo — o arquivo é repassado enquanto chega. Limite: 100 MB.

tar -czf app.tgz -C ./meu-app .
curl -N -X POST https://api.goship.sh/api/v1/orgs/acme/projects/loja/environments/production/apps/blog/deploys \
  -H "Authorization: Bearer $GOSHIP_TOKEN" \
  -F 'message=corrige o título' -F 'file=@app.tgz'

Fechar a conexão não cancela o deploy: o release segue até o fim e fica registrado no histórico com o resultado real. Você perde só a saída ao vivo.

Limites

Até 8 streams abertos por usuário ao mesmo tempo (deploys, comandos e logs com follow). O nono recebe 429.