Builder API

Conecte seu próprio agente de IA e monte apps de membros inteiros por código.

Feito para IAs lerem

O contexto da Builder API vive em /llms-api.txt — um arquivo IA-friendly pronto pra colar na sua IA favorita. Copie o link ou abra direto no Claude / ChatGPT:

O que é

A Builder API (/api/v1) deixa um agente externo de IA — ou qualquer backend seu — construir um app de membros inteiro do Seu App Digital via HTTP, sem humano e sem dashboard. O agente cria o app, e dentro dele os produtos, módulos, aulas, conecta integrações de pagamento e cadastra membros — tudo por chamadas REST.

Ela é stateful e incremental: cada POST devolve um id estável, e você pode rebuscar qualquer recurso via GET a qualquer momento. Você constrói em pedaços, ao longo de dias, retomando exatamente de onde parou. Há também um atalho compose para nascer com app + produtos prontos num único request.

Há também um servidor MCP oficial — 14 ferramentas que expõe essas mesmas capacidades como ferramentas nativas de agente. É open-source, de instalação local (a pasta mcp-builder/ roda com node index.mjs) — sem pacote npx publicado nem endpoint hospedado. Aponte seu cliente (Claude Desktop, Cursor…) para ele com esta configuração:

{
  "mcpServers": {
    "appklub-builder": {
      "command": "node",
      "args": ["/caminho/mcp-builder/index.mjs"],
      "env": { "APPKLUB_API_KEY": "ak_live_..." }
    }
  }
}

Cada ferramenta espelha uma ação da API REST — criar app, subir aula, liberar membro — e usa a mesma chave ak_live_… via APPKLUB_API_KEY.

Autenticação

Toda requisição a /api/v1/* é autenticada pelo header Authorization com uma chave de API. Cookie nunca é aceito — a Builder API é server-to-server pura.

Authorization: Bearer ak_live_9f3c8a21b4e7d6c5f0a1928374655647382910abcdef0123456789a3f9

Como gerar a chave: no painel do creator (plano Business), clique em Criar chave de API. O valor bruto ak_live_… aparece uma única vez — copie na hora, pois o banco guarda apenas o hash (sha256) e a chave bruta é irrecuperável. Se perder, é só rotacionar (gera uma nova e revoga a antiga na hora).

• Base URL: https://seuapp.digital/api/v1
• Prefixo da chave: ak_live_ (sem sandbox na Fase 1).
• Acesso exclusivo do plano Business — os demais recebem 403.
• Limite de 10 chaves ativas por creator.

Hierarquia de recursos

Tudo parte do App, a raiz da árvore. O conteúdo desce em App → Produto → Módulo → Aula (Content). Produtos podem ser agrupados em Trilhas para vitrine, e o acesso de cada membro a um produto é controlado por um grant explícito.

App  (raiz; creatorId vem da chave, nunca do body)
 ├─ Trilha ────── agrupa Produtos do mesmo app (via productIds)
 ├─ Produto
 │   ├─ Módulo (opcional)
 │   │   └─ Aula (Content)   — vídeo / PDF / texto / embed
 │   └─ Aula (Content)        — moduleId pode ser null
 └─ Membro  ──(grant de acesso)──>  Produto

Uma aula sempre pertence a um produto; o módulo é opcional. Cadastrar um membro não concede acesso — isso é um passo separado e explícito (o grant liga o membro ao produto que ele pode ver).

Endpoints principais

Todos os caminhos abaixo são relativos à base https://seuapp.digital/api/v1. A v1 é allow-list por endpoint — rota não declarada retorna 404.

Exemplo end-to-end

Caminho granular completo: criar o app, adicionar um produto, criar uma aula e publicar. Cada mutação leva um header Idempotency-Key único.

# 1. Criar o app (name é o único obrigatório)
curl -X POST https://seuapp.digital/api/v1/apps \
  -H "Authorization: Bearer ak_live_<chave>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-0001-4d11-9f0a-c2e8b1d4a601" \
  -d '{ "name": "Mentoria Caes Felizes", "primaryColor": "#6366f1", "logoUrl": "https://cdn.exemplo.com/logo.png" }'
# -> 201 { "data": { "id": "<appId>", "slug": "mentoria-caes-felizes" } }

# 2. Criar um produto dentro do app
curl -X POST https://seuapp.digital/api/v1/apps/<appId>/products \
  -H "Authorization: Bearer ak_live_<chave>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-0002-4d11-9f0a-c2e8b1d4a601" \
  -d '{ "name": "Curso Base", "description": "Fundamentos.", "offerType": "MAIN" }'
# -> 201 { "data": { "id": "<productId>", ... } }

# 3. Criar uma aula (Content) no produto
curl -X POST https://seuapp.digital/api/v1/apps/<appId>/products/<productId>/contents \
  -H "Authorization: Bearer ak_live_<chave>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-0003-4d11-9f0a-c2e8b1d4a601" \
  -d '{ "name": "Aula 1 - Boas-vindas", "type": "YOUTUBE", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }'
# -> 201 { "data": { "id": "<contentId>", ... } }

# 4. Publicar o app (logoUrl precisa estar setado, senao 422)
curl -X POST https://seuapp.digital/api/v1/apps/<appId>/publish \
  -H "Authorization: Bearer ak_live_<chave>" \
  -H "Idempotency-Key: a1b2c3d4-0004-4d11-9f0a-c2e8b1d4a601"
# -> 200 { "data": { "published": true, "publishedAt": "..." } }

Idempotência e erros

Idempotência: toda mutação (POST/PATCH/DELETE) exige o header Idempotency-Key (um UUID v4). Reenviar a mesma key com o mesmo body em um retry devolve a resposta gravada — sem duplicar o recurso. A janela é de 24 horas.

Erros: ramifique sempre pelo error.type (contrato público estável), nunca pela message (PT-BR, mutável). Os principais:

Pronto pra automatizar a criação de apps?

A Builder API está disponível no plano Business. Assine e gere sua chave ak_live_ no painel.