Visão geral da API

A API do Standcast permite que os seus sistemas leiam os dados da sua organização e recebam eventos. Ela é versionada em /v1 e descrita por um documento OpenAPI 3.1.

• URL base: https://api.standcast.app
• Documento OpenAPI: https://api.standcast.app/openapi.json
• Referência interativa, com cada operação, parâmetro, exemplo e erro: referência da API (em inglês)

O que a API oferece

• Ler os dados da organização com uma API key:

  Operação	Escopo	Devolve
  GET /v1/org/teams	teams:read	Os times do standcast.yml: nome, fuso, dias úteis, horários e membros
  GET /v1/org/dailies	dailies:read	Dailies confirmadas, filtradas por date e team
  GET /v1/org/dailies/{id}	dailies:read	Uma daily
  GET /v1/org/digests	digests:read	Entregas do consolidado, com quem não enviou a daily, filtradas por team, from e to
  GET /v1/org/blockers	blockers:read	Impedimentos confirmados, filtrados por date e team
  GET /health	nenhum	Saúde do serviço

• Receber eventos com webhooks: daily.submitted, blocker.opened e digest.sent.

A API devolve só o que as pessoas confirmaram e o que já aparece no consolidado. Ela nunca devolve rascunhos, sugestões, métricas por pessoa, rankings ou agregados.

O que a API não oferece

Não dá para enviar uma daily pela API pública. Agentes de IA enviam dailies pelo servidor MCP ou pela skill do Claude Code, e scripts pela CLI.

Por quê: o Standcast nunca envia uma daily em nome de alguém sem a confirmação explícita da pessoa. Essa regra mora num lugar só, o servidor MCP e a skill, que mostram a daily para a pessoa e só enviam depois que ela confirma. Uma API key pertence à organização, não a uma pessoa, então não tem como carregar essa confirmação. As rotas que a CLI usa para enviar dailies são internas, autenticadas com a sessão de uma pessoa, e não fazem parte do contrato público.

Começo rápido

curl -H "Authorization: Bearer $STANDCAST_API_KEY" \
  https://api.standcast.app/v1/org/teams

{
  "data": [
    {
      "name": "Alpha",
      "timezone": "America/Sao_Paulo",
      "workdays": ["mon", "tue", "wed", "thu", "fri"],
      "remindAt": "09:00",
      "digestAt": "10:00",
      "memberLogins": ["alice", "bob"]
    }
  ],
  "next_cursor": null
}

Autenticação

A API pública do Standcast autentica com uma API key. Mande a key como bearer token em toda requisição:

GET /v1/{resource} HTTP/1.1
Host: your-standcast-host
Authorization: Bearer sck_xxxxxxxxxxxxxxxxxxxxxxxx

As API keys começam com sck_. Toda operação em /v1/org exige uma. Só keys sck_ são aceitas ali: um token de sessão (sc_) mandado para /v1/org falha com 401 unauthorized, e uma API key mandada para uma rota só de sessão falha do mesmo jeito.

Criar uma key

Só um admin da organização cria keys. O admin entra com o GitHub, abre a página de setup da organização e usa a seção API keys: dá um nome, escolhe os escopos e cria. Numa conta pessoal, o dono da conta é o admin. Cada key pertence a uma organização e vê só os dados dela.

O segredo completo aparece uma vez, quando a key é criada. O Standcast guarda só um hash e não consegue mostrar de novo, então copie na hora. A lista mostra o prefixo de cada key (os 8 primeiros caracteres depois de sck_), os escopos, a data de criação e o último uso, atualizado no máximo uma vez por minuto.

Escopos

Dê o menor escopo que funciona.

Escopo	Permite
teams:read	GET /v1/org/teams
dailies:read	GET /v1/org/dailies e GET /v1/org/dailies/{id}
digests:read	GET /v1/org/digests
blockers:read	GET /v1/org/blockers

Uma requisição que precisa de um escopo que a key não tem falha com 403 insufficient_scope. O erro informa o escopo que falta em required_scope:

{
  "error": {
    "code": "insufficient_scope",
    "message": "api key lacks the dailies:read scope",
    "required_scope": "dailies:read"
  }
}

Keys ausentes, malformadas, desconhecidas e revogadas falham com 401 unauthorized. Cada key tem limite de 600 requisições por minuto (veja Limites de taxa).

Revogar uma key

Um admin pode revogar uma key a qualquer momento. A revogação vale na hora, e as próximas requisições com essa key falham com 401 unauthorized. Para trocar uma key, crie a nova primeiro, coloque em produção e depois revogue a antiga.

Guardar as keys com segurança

• Guarde as keys num gerenciador de segredos ou em variáveis de ambiente, nunca no controle de versão nem em código do cliente.
• Use uma key por integração, para revogar uma sem quebrar as outras.
• Nunca registre o header Authorization em log.
• Se uma key pode ter vazado, revogue na hora.

Tokens de sessão (sc_)

Os tokens que começam com sc_ são tokens de sessão emitidos para a CLI, a skill e o servidor MCP do Standcast depois de um login no GitHub. Eles não são um meio de integração, e as operações que liberam não fazem parte desta referência.

Erros

Toda resposta de erro usa o mesmo envelope:

{ "error": { "code": "invalid_daily", "message": "invalid daily", "issues": [] } }

O code é o contrato estável: decida pelo code, não pela message. A message é sempre em inglês e pode mudar. issues só aparece em erros de validação e lista os campos com problema. required_scope só aparece em erros de escopo.

Código	Status HTTP	O que fazer
unauthorized	401	A credencial está ausente, inválida, expirada ou revogada. Autentique de novo ou use uma key válida.
invalid_request	422	A requisição está malformada. Confira issues e corrija os campos listados.
invalid_daily	422	O payload da daily falhou na validação. Confira issues contra o schema.
org_not_found	404	A organização não existe ou o app do Standcast não está instalado nela. Confira o nome e a instalação.
org_not_configured	409	A organização não tem um standcast.yml válido. Adicione ou corrija o arquivo no repositório .github e tente de novo.
not_in_team	422	A pessoa não está em nenhum time desta organização. Adicione a pessoa a um time no standcast.yml.
forbidden	403	A credencial é válida, mas a pessoa ou a organização não pode fazer esta ação.
insufficient_scope	403	Falta à API key o escopo de que esta operação precisa. O erro traz required_scope. Crie uma key com esse escopo.
not_found	404	O recurso não existe na organização da key.
suggestion_already_decided	409	O impedimento sugerido já foi decidido no sentido oposto. Busque o rascunho de novo; ele não o lista mais.
invalid_state	400	Um link de autorização expirou ou foi adulterado. Comece o fluxo de novo.
installation_pending	409	A instalação ainda está sendo processada. Tente de novo em alguns segundos.
access_denied	403	A pessoa negou a autorização. Nada mudou.
slack_oauth_failed	502	O Slack recusou a conexão. Tente conectar de novo.
linear_oauth_failed	502	O Linear recusou a conexão. Tente conectar de novo.
rate_limited	429	Requisições demais. Espere Retry-After segundos e tente de novo (veja Limites de taxa).
internal	500	Erro inesperado no servidor. Tente de novo com backoff e fale com o suporte se persistir.

Paginação

As operações de listagem usam cursores opacos.

Parâmetro	Onde	Descrição
limit	query	Tamanho da página, de 1 a 100. O padrão é 50.
cursor	query	O next_cursor da página anterior. Omita para pegar a primeira página.

Uma resposta paginada traz os itens e um next_cursor:

{ "data": [], "next_cursor": "eyJpZCI6MTIzfQ" }

Quando next_cursor é null, não há mais páginas. Trate o cursor como texto opaco: não interprete, não monte e não guarde por muito tempo. Mantenha os mesmos filtros durante a paginação.

Um cursor inválido ou um limit fora de 1 a 100 falha com 422 invalid_request. Dailies e consolidados vêm do mais recente para o mais antigo. Nos impedimentos, limit conta impedimentos, não dailies.

Limites de taxa

Os limites usam uma janela fixa de 60 segundos.

Credencial	Limite
Token de sessão (sc_)	120 requisições por minuto
API key (sck_)	600 requisições por minuto
Requisições sem autenticação	Contadas por endereço IP
Início de uma sessão da CLI	10 requisições por minuto por endereço IP

Os limites valem por credencial, então uma integração barulhenta não gasta o limite de outra.

Headers

As rotas com limite devolvem estes headers em toda resposta:

Header	Significado
RateLimit-Limit	Requisições permitidas na janela.
RateLimit-Remaining	Requisições que sobram na janela atual.
RateLimit-Reset	Segundos até a janela reiniciar.

Quando você passa do limite

A resposta é 429 com o código rate_limited e um header Retry-After com os segundos de espera:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 23

Espere Retry-After segundos antes de tentar de novo e espalhe as novas tentativas com jitter.

Versionamento

A API é versionada no caminho. /v1 é a versão atual. O info.version do documento OpenAPI é a versão do Standcast (por exemplo 0.2.0).

• Beta público. Enquanto o Standcast estiver na versão 0.x, a /v1 ainda pode mudar de forma incompatível. Essas mudanças entram no changelog antes de sair, com a maior antecedência possível. O aviso de 90 dias abaixo vale a partir da 1.0.
• Novos campos podem aparecer nas respostas a qualquer momento. Ignore os campos que você não conhece.
• Novos parâmetros opcionais e novas operações podem entrar na /v1 sem aviso.
• Uma mudança que quebra clientes existentes só sai na /v2.
• Antes de remover ou mudar de forma incompatível um comportamento da /v1, a mudança é anunciada no changelog com pelo menos 90 dias de antecedência.

Veja o changelog com todas as versões. Elas são as mesmas dos releases no GitHub.