REST API · Para desarrolladores

featury por HTTP puro

Todo lo que featury expone a los agentes también es una REST API versionada: descubre workspaces y proyectos, lee el inventario de funcionalidades y el feed completo de cambios, registra y actualiza solicitudes, y pregúntale al agente del código: una API key personal, un header Bearer, JSON de vuelta.

1. Crea una API key

En la app, ve a Cuenta → API keys → Crear API key. La clave completa se muestra solo una vez. Guárdala en un lugar seguro. En el servidor solo se conserva su hash, así que no se puede recuperar después.

Una clave actúa como tú: el agente trabaja con tu identidad y tus permisos exactos en cada workspace al que perteneces, ni más, ni menos. Revoca la clave desde la misma página en cuanto se filtre.

Abrir configuración de cuenta

2. Convenciones

Todas las URLs son relativas al origen de tu API (¿self-hosted? usa el tuyo):

https://api.featury.app

Las respuestas siempre vienen en un envelope: { "data": … } en el éxito, { "error": { "code", "message" } } en el error. Los códigos de estado son claros: 400 para una llamada malformada, 401 para una clave ausente o revocada, 403 cuando tu rol no alcanza el recurso, 404 cuando no existe.

Cada parámetro workspace y project acepta el slug o el id: los mismos slugs que ves en las URLs de la app. Y una clave actúa como su dueño: cada endpoint ve exactamente lo que tú puedes ver en la app, ni más.

Atribución opcional: envía un encabezado X-Featury-Agent (o vincula un agente a la clave al crearla) y todo lo que haga la clave aparece como “{agent} · vía ti” en lugar de solo tú. Sin ello, featury aun así detecta el nombre del cliente cuando puede.

3. Cambios

El feed interno completo de cambios clasificados: cada item trae visibility: PUBLIC | INTERNAL, incluidas las entradas internas que nunca llegan al changelog público curado en /feed/{workspace}/{project}.json. Por defecto 50 items, máximo 200.

Endpoint	Qué hace
GET /v1/changes	Cambios clasificados, del más reciente al más antiguo. Filtra por kind, impactSurface, fecha from/to; pagina con limit/offset

curl -H "Authorization: Bearer fk_…" \
  "https://api.featury.app/v1/changes?workspace=acme&project=web&limit=50"

4. Solicitudes

Bugs y propuestas, de punta a punta. Sin filtro de status, la lista devuelve solo los carriles vivos; repite el parámetro para filtrar por varios. BUILDING y SHIPPED siguen derivándose de señales reales del código, no se pueden fijar a mano. Es la misma regla que en la app.

Endpoint	Qué hace
GET /v1/requests	Lista solicitudes. Filtros: status, size, impact (cada uno repetible), kind, horizon, search; pagina con limit/offset. Las filas compactas traen updatedAt, shippedAt y area
GET /v1/requests/:id	Detalle completo de una solicitud: recorrido, comentarios, artefactos de spec, reality read
POST /v1/requests	Registra una solicitud ({ workspace, project, kind, title, body?, severity? }). Pasa por el triaje estándar
PATCH /v1/requests/:id	Actualiza una solicitud: title, body, severity y overrides de horizon/size/fit
POST /v1/requests/:id/status	Mueve una solicitud por los carriles manuales. { status, note?, declinedReason? }
POST /v1/requests/:id/comments	Comenta en una solicitud ({ body }). Notifica a los participantes; las menciones @Nombre avisan

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. Funcionalidades y descubrimiento

Empieza aquí: lista tus workspaces, luego los proyectos dentro de uno, luego el inventario vivo de funcionalidades de un proyecto.

Endpoint	Qué hace
GET /v1/workspaces	Los workspaces a los que perteneces: id, nombre, slug, tu rol
GET /v1/projects	Los proyectos a los que tienes acceso en un workspace
GET /v1/features	El inventario vivo de funcionalidades del proyecto

curl -H "Authorization: Bearer fk_…" \
  "https://api.featury.app/v1/features?workspace=acme&project=web"

6. Pregúntale al código

Una pregunta entra, una respuesta fundamentada sale. No hay streaming, así que espera una llamada larga. Devuelve el conversationId recibido para seguir el hilo. Consume el presupuesto de IA del workspace, como un mensaje de chat en la app.

Endpoint	Qué hace
POST /v1/ask	Pregunta al agente del código: { question, conversationId? } → { data: { answer, conversationId, sources } }. `sources` nombra los documentos y funcionalidades que el turno realmente leyó.

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 (sin clave)

El changelog publicado de cada producto se sirve sin iniciar sesión, en cuatro formatos, desde una dirección estable, y responde a cualquier origen, así que tu propio sitio puede obtener el JSON y montar una página con él. Esa es la llamada detrás de featury.app/changelog.

Endpoint	Qué hace
GET /feed/{ws}/{proj}.{html\|json\|md\|xml}	El índice, de la más reciente a la más antigua, 20 por página
GET /feed/{ws}/{proj}.{ext}?before={n}	Páginas anteriores; el next del JSON trae el enlace
GET /feed/{ws}/{proj}/{n}.{html\|json\|md}	La dirección permanente de una edición
GET /feed/{ws}/{proj}/og.png · /{n}/og.png	Tarjetas para compartir: la del feed y la de una edición

curl https://api.featury.app/feed/featury/featury.json

Míralo en vivo: el changelog del propio featury →

8. Bueno saberlo

BUILDING y SHIPPED se derivan de señales reales del código y nunca se pueden fijar a mano: la misma regla que en la app.
Cita el refCode de una solicitud en un commit o PR ("Closes idea/dark-mode", "Fixes bug/login-white-screen") y el ticket se entrega automáticamente y avisa a quien lo pidió.
Las mutaciones se comportan exactamente como las acciones en la app (eventos de recorrido, notificaciones) y se atribuyen a ti.
¿Quieres que tu agente de código use todo esto sin escribir código? Eso es el endpoint MCP. Mismas claves, mismas capacidades, en forma de herramientas. Docs de MCP →