URL base

http://localhost:3001/api

Autenticación

Los endpoints de la API requieren autenticación via cookie de sesión o header de API key:

# Usando API key
curl -H "Authorization: Bearer sk_..." http://localhost:3001/api/observations

# Usando cookie de sesión (después de login)
curl --cookie "authjs.session-token=..." http://localhost:3001/api/observations

Observaciones

Listar observaciones

GET /api/observations

Parámetros de consulta:

Parámetro	Tipo	Descripción
project	string	Filtrar por proyecto
type	string	Filtrar por tipo
limit	number	Máximo de resultados (default: 50)
offset	number	Offset de paginación
sort	string	created_at o updated_at

Respuesta:

{
  "observations": [
    {
      "id": 42,
      "title": "Corregido N+1 en UserList",
      "type": "bug",
      "content": "What: Agregada carga batch...",
      "topic_key": "bugfix/n1-userlist",
      "project_id": "mi-app"
    }
  ],
  "total": 342,
  "limit": 50,
  "offset": 0
}

Crear observación

POST /api/observations

Obtener observación

GET /api/observations/:id

Actualizar observación

PATCH /api/observations/:id

Eliminar observación

DELETE /api/observations/:id

Búsqueda

GET /api/search?q=elección+base+datos&type=decision&limit=10

Usa búsqueda FTS5 de texto completo en todas las observaciones.

Sesiones

Iniciar sesión

POST /api/sessions

Finalizar sesión

POST /api/sessions/:id/end

Respuestas de error

Todos los errores siguen este formato:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Observación 999 no encontrada"
  }
}

Código	HTTP Status	Descripción
NOT_FOUND	404	Recurso no encontrado
VALIDATION_ERROR	400	Body de request inválido
UNAUTHORIZED	401	Auth faltante o inválida
RATE_LIMITED	429	Demasiadas solicitudes
INTERNAL_ERROR	500	Error del servidor