API de Missões para Agentes de IA

Se você usa um agente de IA local (como o Claude Code) para trabalhar nas suas Missões, não precisa mais copiar a descrição manualmente de nenhum lugar. A API de Missões da Startellite deixa seu próprio agente listar as Missões atribuídas a você e reportar conclusão automaticamente.

A API devolve dois tipos de missão, diferenciados pelo campo source: "company" são Missões reais de empresas (com prazo, valor-hora e ciclo de vida); "personal" são cartões do Quadro dos seus Meus Projetos (sem empresa, sem pagamento, sem aprovação — só você e sua IA).

Importante: a API nunca mexe no Git

Esta API só entrega os dados da missão e recebe a confirmação de que o trabalho foi enviado. Ela nunca faz commit, push ou pull, e nunca clona nem executa nada sozinha — editar os arquivos e subir o código pro seu repositório continua 100% manual, no seu computador, depois de você revisar o que a IA fez.

Segurança: você só vê o que é seu

Sua chave só lista missões de empresa em que você é o satélite principal ou um satélite adicional, e cartões de Meus Projetos que são só seus — nunca de outro satélite, e nunca de um projeto de empresa em que você não foi aceito. Não existe forma de listar ou agir sobre uma missão que não seja sua.

1. Gere sua chave de API

No seu painel de Satélite, vá em Configurações → "API de Missões (para agentes de IA)" → "Gerar chave". Copie a chave exibida — ela só aparece uma vez.

2. Recomendado: salve no .env + CLAUDE.md (a chave nunca aparece na conversa)

Em vez de colar a chave dentro do chat toda sessão, guarde-a como uma variável de ambiente no seu repositório e ensine seu agente a usá-la sozinho, uma única vez:

echo "STARTELLITE_API_KEY=stl_sat_XXXXX..." >> .env

Confirme que .env está no seu .gitignore (praticamente todo projeto já vem assim por padrão). Depois, no seu painel da Startellite, clique em "Copiar trecho para CLAUDE.md" (ao lado do botão de gerar chave) e cole o resultado no arquivo CLAUDE.md do seu repositório — o Claude Code carrega esse arquivo sozinho no início de toda sessão, então ele já sabe usar a API sem você repetir nada.

A partir daí, um pedido solto já funciona de primeira, sem colar chave nenhuma:

Liste minhas missões mais urgentes desta semana por ordem de prioridade
e execute as 2 mais difíceis.

Usa outro agente/editor (Cursor, Aider, etc.)? O mesmo trecho funciona em qualquer arquivo de instrução persistente que ele leia automaticamente (.cursorrules, AGENTS.md, etc.) — o conteúdo é só texto e endpoints REST, não é específico do Claude Code.

3. Alternativa rápida: colar a chave direto no chat

Pra um teste pontual (sem mexer no .env/CLAUDE.md), ainda dá pra só colar a chave na conversa — mas evite fazer isso como rotina, já que ela fica registrada no histórico do chat:

Minha chave de API da Startellite é: stl_sat_XXXXX...

Busque minhas missões em https://www.startellite.com/api/v1/missions,
me mostre as opções (de empresa e de Meus Projetos) e pergunte qual
eu quero que você execute agora.

Também dá pra pedir pra IA trabalhar sozinha em várias missões seguidas, sem parar pra perguntar a cada uma — só peça assim (ela usa a ordem de priority que a API já devolve, então "as 3 de maior prioridade" não exige nenhum cálculo da sua parte):

No repositório tal, execute as 3 missões de maior prioridade,
faça tudo sem eu precisar conferir. Vou só checar o final antes de eu commitar.

Repare que isso não muda a regra de ouro: a IA nunca faz commit/push sozinha, mesmo trabalhando várias missões em sequência — ela só edita os arquivos de cada uma e chama /submit ao final de cada uma; quem revisa e commita continua sendo só você, no final de tudo.

Depois que você escolher uma (ou a IA passar pela lista sozinha):

Quero que você trabalhe na missão "Criar endpoint de webhook da Stripe".
Crie a branch sugerida antes de mexer em qualquer arquivo e implemente
o que a descrição e o objetivo pedem.

Quando a IA terminar e você já tiver revisado o resultado:

Terminei de revisar e já commitei. Me diga quantas horas você calculou
pra essa missão (se for de empresa) e, se estiver de acordo, chame o
/submit da Startellite pra reportar a conclusão.

O agente entende os endpoints, monta as chamadas técnicas e te devolve o resultado em português — as seções abaixo mostram o que acontece "por baixo do capô", caso você (ou sua IA) queira conferir os detalhes.

4. Liste suas Missões e escolha uma

curl https://www.startellite.com/api/v1/missions \
  -H "Authorization: Bearer $STARTELLITE_API_KEY"

Retorna toda missão em progresso — de empresa OU cartão de Meus Projetos na coluna "Em Andamento" — (opcionalmente filtre por projeto com ?project_id=ID_DO_PROJETO), já ordenadas da maior pra menor prioridade, pra você (ou sua IA) decidir qual executar agora:

{
  "ok": true,
  "missions": [
    {
      "source": "company",
      "mission_id": "a1b2c3d4-...",
      "project_id": "p9z8...",
      "title": "Criar endpoint de webhook da Stripe",
      "description": "...",
      "objective": "...",
      "required_areas": ["Backend"],
      "required_skills": ["Node.js", "Stripe"],
      "priority": "high",
      "complexity": 6,
      "deadline": "2026-08-01T00:00:00Z",
      "hours_until_deadline": 36.5,
      "started_at": "2026-07-30T14:03:00Z",
      "currency": "BRL",
      "hourly_rate": 65,
      "estimated_hours": 4,
      "worked_hours": 0,
      "suggested_branch": "mission/criar-endpoint-de-webhook-da-stripe-a1b2c3",
      "project": {
        "title": "Loja Online XPTO",
        "description": "...",
        "required_tech_stack": ["Node.js", "Prisma", "Express"],
        "github_repo": "empresa-xyz/loja-online"
      }
    },
    {
      "source": "personal",
      "mission_id": "f7e6d5c4-...",
      "project_id": "m3n2...",
      "title": "Configurar autenticação com Google",
      "description": "...",
      "objective": null,
      "required_areas": [],
      "required_skills": [],
      "priority": "medium",
      "complexity": null,
      "deadline": null,
      "hours_until_deadline": null,
      "started_at": null,
      "currency": null,
      "hourly_rate": null,
      "estimated_hours": null,
      "worked_hours": null,
      "suggested_branch": "mission/configurar-autenticacao-com-google-f7e6d5",
      "project": {
        "title": "App de finanças pessoais",
        "description": "...",
        "required_tech_stack": ["React Native"],
        "github_repo": null
      }
    }
  ],
  "agent_instructions": [
    "Never run git commit, push, or pull yourself — only edit files...",
    "Create and work inside the branch in suggested_branch...",
    "source: 'personal' missions have no budget/rate...",
    "..."
  ]
}

Missões com source "personal" vêm dos seus próprios projetos em Projetos → Meus Projetos — sem empresa, sem pagamento, sem aprovação de ninguém. Por isso vários campos vêm null (complexity, deadline, currency, hourly_rate, estimated_hours, worked_hours): eles só existem quando uma empresa define uma Missão de verdade.

required_skills e project.required_tech_stack existem justamente pra sua IA já saber com qual stack está lidando sem você precisar explicar. agent_instructions é um texto fixo (sem custo de IA) com as regras que todo agente deve seguir — inclusive nunca mexer em Git e nunca estourar estimated_hours nas missões de empresa.

priority é a mesma escala usada nos Blocos do seu Quadro (baixa/média/alta/urgente) — numa Missão de empresa, quem define é a empresa; num cartão de Meus Projetos, é você mesmo. O array missions já vem ordenado da maior prioridade pra menor (empate é resolvido pelo prazo mais próximo), então "execute as 3 de maior prioridade" é sempre missions[0], missions[1] e missions[2].

complexity é um número de 1 a 10 que mede o quão tecnicamente difícil é ESSA missão especificamente (1-2: ajuste visual simples ou CRUD básico; 5-6: feature Full Stack completa; 9-10: sistemas distribuídos/infra crítica) — só existe pra Missões de empresa; num cartão de Meus Projetos vem null.

started_at é preenchido automaticamente pela própria plataforma assim que a Missão de empresa entra em progresso — não é a IA quem define isso, é o momento real em que o trabalho começou. Cartões de Meus Projetos não têm esse campo (vem null).

Não quer escolher? GET /api/v1/missions/next devolve só a primeira desse mesmo ranking (maior prioridade, prazo mais próximo como critério de desempate, misturando company e personal), no mesmo formato, dentro de um campo mission em vez de missions.

5. Trabalhe numa branch isolada

Antes de deixar a IA editar qualquer arquivo, crie e entre na branch sugerida (suggested_branch na resposta) — assim, se algo sair errado, a main do repositório nunca é afetada. O nome já inclui um resumo do título da missão, então fica fácil identificar no histórico de branches:

git checkout -b mission/criar-endpoint-de-webhook-da-stripe-a1b2c3

Só faça merge pra main depois de revisar o resultado — a Startellite nunca cria, muda ou apaga branches por você.

6. Avise quando terminar

Depois de editar os arquivos localmente (e você já ter revisado o resultado), chame /submit — o comportamento muda de acordo com a origem da missão, detectado automaticamente pelo ID:

curl -X POST https://www.startellite.com/api/v1/missions/ID_DA_MISSAO/submit \
  -H "Authorization: Bearer $STARTELLITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proof_url": "https://github.com/seu-usuario/seu-repo/pull/12"}'

Missão de empresa (source "company"): proof_url é obrigatório (um link do PR/commit). worked_hours é opcional — se você omitir, a Startellite calcula sozinha quantas horas se passaram desde started_at. A resposta traz o worked_hours realmente gravado e muda o status real da Missão para "aguardando validação" — o mesmo status que a empresa vê no painel dela. A API nunca aprova nem paga uma Missão sozinha; isso continua sendo uma decisão da empresa.

Cartão de Meus Projetos (source "personal"): não precisa de proof_url nem de worked_hours — o /submit simplesmente move o cartão pra coluna "Concluído" do seu Quadro. Sem aprovação de ninguém, porque o projeto é só seu.

Recomendado (missões de empresa): peça pra sua IA te contar quantas horas ela calculou antes de chamar o /submit de fato, pra você confirmar (ou ajustar manualmente passando worked_hours explicitamente, se o tempo cronometrado não bater com o esforço real).

Limite diário

O plano Free tem um limite baixo de chamadas por dia; o plano PRO tem um limite bem mais alto. Se você estourar o limite, a API retorna erro 429 e o horário em que o limite libera de novo (meia-noite UTC).