REST API · Para desenvolvedores
featury por HTTP puro
Tudo o que o featury expõe aos agentes também é uma REST API versionada: descubra workspaces e projetos, leia o inventário de features e o feed completo de mudanças, registre e atualize requests e pergunte ao agente do código: uma API key pessoal, um header Bearer, JSON de volta.
1. Crie uma API key
No app, vá em Conta → API keys → Criar API key. A chave completa é mostrada apenas uma vez. Guarde-a em um lugar seguro. No servidor só fica o hash, então ela não pode ser recuperada depois.
Uma chave age como você: o agente trabalha com a sua identidade e exatamente as suas permissões em cada workspace de que você faz parte, nem mais, nem menos. Revogue a chave na mesma página assim que ela vazar.
2. Convenções
Todas as URLs são relativas à origem da sua API (self-hosted? use a sua):
https://api.featury.appAs respostas sempre vêm em um envelope: { "data": … } em caso de sucesso, { "error": { "code", "message" } } em caso de erro. Os códigos de status são claros: 400 para uma chamada malformada, 401 para uma chave ausente ou revogada, 403 quando o seu papel não alcança o recurso, 404 quando ele não existe.
Cada parâmetro workspace e project aceita o slug ou o id: os mesmos slugs que você vê nas URLs do app. E uma chave age como o dono: cada endpoint vê exatamente o que você pode ver no app, nem mais.
Atribuição opcional: envie um cabeçalho X-Featury-Agent (ou vincule um agente à chave ao criá-la) e tudo que a chave fizer aparece como “{agent} · por você” em vez de apenas você. Sem isso, a featury ainda detecta o nome do próprio cliente quando dá.
3. Mudanças
O feed interno completo de mudanças classificadas: cada item traz visibility: PUBLIC | INTERNAL, incluindo as entradas internas que nunca chegam ao changelog público curado em /feed/{workspace}/{project}.json. Padrão de 50 itens, máximo 200.
| Endpoint | O que faz |
|---|---|
| GET /v1/changes | Mudanças classificadas, da mais recente à mais antiga. Filtre por kind, impactSurface, data from/to; pagine com limit/offset |
curl -H "Authorization: Bearer fk_…" \
"https://api.featury.app/v1/changes?workspace=acme&project=web&limit=50"4. Requests
Bugs e pedidos de feature, de ponta a ponta. Sem filtro de status, a lista retorna só as faixas vivas; repita o parâmetro para filtrar por várias. BUILDING e SHIPPED continuam derivados de sinais reais do código, não podem ser definidos manualmente. É a mesma regra do app.
| Endpoint | O que faz |
|---|---|
| GET /v1/requests | Lista requests. Filtros: status, size, impact (cada um repetível), kind, horizon, search; pagine com limit/offset. As linhas compactas trazem updatedAt, shippedAt e area |
| GET /v1/requests/:id | Detalhe completo de um request: jornada, comentários, artefatos de spec, reality read |
| POST /v1/requests | Registra um request ({ workspace, project, kind, title, body?, severity? }). Passa pela triagem padrão |
| PATCH /v1/requests/:id | Atualiza um request: title, body, severity e overrides de horizon/size/fit |
| POST /v1/requests/:id/status | Move um request pelas faixas manuais. { status, note?, declinedReason? } |
| POST /v1/requests/:id/comments | Comenta em um request ({ body }). Notifica os participantes; menções @Nome avisam |
curl -X POST "https://api.featury.app/v1/requests" \
-H "Authorization: Bearer fk_…" \
-H "Content-Type: application/json" \
-d '{"workspace":"acme","project":"web","kind":"BUG","title":"Export button returns 500"}'5. Features e descoberta
Comece aqui: liste seus workspaces, depois os projetos dentro de um, depois o inventário vivo de features de um projeto.
| Endpoint | O que faz |
|---|---|
| GET /v1/workspaces | Os workspaces de que você faz parte: id, nome, slug, seu papel |
| GET /v1/projects | Os projetos a que você tem acesso em um workspace |
| GET /v1/features | O inventário vivo de features do projeto |
curl -H "Authorization: Bearer fk_…" \
"https://api.featury.app/v1/features?workspace=acme&project=web"6. Pergunte ao código
Uma pergunta entra, uma resposta fundamentada sai. Não há streaming, então espere uma chamada longa. Devolva o conversationId recebido para continuar a conversa. Consome o orçamento de IA do workspace, como uma mensagem de chat no app.
| Endpoint | O que faz |
|---|---|
| POST /v1/ask | Pergunte ao agente do código: { question, conversationId? } → { data: { answer, conversationId, sources } }. `sources` nomeia os documentos e funcionalidades que a resposta realmente leu. |
curl -X POST "https://api.featury.app/v1/ask" \
-H "Authorization: Bearer fk_…" \
-H "Content-Type: application/json" \
-d '{"workspace":"acme","project":"web","question":"How does billing retry failed payments?"}'7. Changelog público (sem chave)
O changelog publicado de cada produto é servido sem login, em quatro formatos, num endereço estável, e responde a qualquer origem, então o seu próprio site pode buscar o JSON e montar uma página com ele. É essa a chamada por trás de featury.app/changelog.
| Endpoint | O que faz |
|---|---|
| GET /feed/{ws}/{proj}.{html|json|md|xml} | O índice, da edição mais recente à mais antiga, 20 por página |
| GET /feed/{ws}/{proj}.{ext}?before={n} | Páginas anteriores; o next do JSON traz o link |
| GET /feed/{ws}/{proj}/{n}.{html|json|md} | O endereço permanente de uma edição |
| GET /feed/{ws}/{proj}/og.png · /{n}/og.png | Cartões de compartilhamento: o do feed e o de uma edição |
curl https://api.featury.app/feed/featury/featury.json8. Bom saber
- BUILDING e SHIPPED são derivados de sinais reais do código e nunca podem ser definidos manualmente: a mesma regra do app.
- Cite o refCode de um request em um commit ou PR ("Closes idea/dark-mode", "Fixes bug/login-white-screen") e o ticket é entregue automaticamente, avisando quem pediu.
- As mutações se comportam exatamente como as ações no app (eventos de jornada, notificações) e são atribuídas a você.
- Quer que o seu agente de código use tudo isso sem escrever código? Esse é o endpoint MCP. Mesmas chaves, mesmas capacidades, em forma de ferramentas. Docs do MCP →