API REST: JSON por HTTPS con token bearer

Una visión general de la API REST de Feedjolt: JSON sobre HTTPS con token bearer. Cubre la URL base, la referencia interactiva, convenciones y versión v1.

La API de Feedjolt es una API REST sobre JSON. La referencia completa de endpoints está en progreso; esta sección cubre los comportamientos que se aplican a través de todos los endpoints.

URL base

https://api.feedjolt.com/api/v1

Referencia interactiva

La referencia completa de endpoints, con try-it, vive en:

https://api.feedjolt.com/docs

Se autogenera desde el servicio FastAPI - siempre actualizada. El JSON OpenAPI 3.x está en https://www.feedjolt.com/openapi.json (también en https://api.feedjolt.com/openapi.json). YAML: https://www.feedjolt.com/api/openapi.yaml.

Lo que hay en estas páginas

Los comportamientos transversales que se aplican a cada endpoint:

Autenticación - claves API, dónde poner el bearer token.
Límites de peticiones - cabeceras, 429 y Retry-After.
Errores - forma del error, códigos, qué reintentar.
Paginación - basada en página, con totales.

Para el detalle por endpoint (forma del cuerpo de petición, parámetros de query, esquema de respuesta), la referencia interactiva de arriba es la fuente de verdad.

Lo que viene

SDKs propios - TypeScript y Python.

Vota en la hoja de ruta pública si te desbloquearía.

Cata rápida

Una llamada típica:

curl -H "Authorization: Bearer fjk_TU_CLAVE" \
     -H "Content-Type: application/json" \
     "https://api.feedjolt.com/api/v1/boards/feature-requests/posts?per_page=10"

Respuesta:

{
  "items": [
    { "id": "post_abc", "title": "Add dark mode", "votes": 42, "status": "Planeado" }
  ],
  "page": 1,
  "per_page": 10,
  "total": 213,
  "total_pages": 22
}

Estado

Recurso	CRUD	Notas
Posts	✅	List, get, create, update, delete, merge.
Comentarios	✅	List, get, create, update, delete. Scope de comentario interno requerido para internos.
Votos	✅	List, cast (toggle).
Tableros	✅ read, ⚠️ write	Crear/editar tableros vía panel por ahora.
Estados	✅
Etiquetas	✅
Miembros	✅	List, invite, change role, remove.
Webhooks	✅	Endpoints, entregas, replay.
Claves API	✅	List + revoke (creación es solo del panel).
Espacios	⚠️ read	Ajustes del espacio vía panel.
Facturación	❌	Solo panel.

Convenciones

Tiempos son ISO 8601, UTC, sufijo Z.
IDs son strings cortos con prefijo: post_abc, cmt_xyz, evt_qrs. Nunca enteros.
Slugs son identificadores estables aptos para URL (espacio, tablero, etiqueta). Prefiérelos para URLs visibles.
Booleans son JSON true/false, no strings.
Nullables usan null, no claves omitidas, cuando se documenta.
Listas vacías son [], no null.

/api/v1 es la versión actual. No romperemos v1 - lanzaremos v2 en una nueva ruta cuando necesitemos hacer cambios rompientes. Las adiciones de campos a v1 son no-rompientes y pueden ocurrir en cualquier momento.

API