Centro de ayuda

Gestiona los artículos del centro de ayuda de un proyecto y sus categorías. Requiere que el centro de ayuda esté activado en el proyecto — cuando está desactivado, todos los endpoints de abajo devuelven 404.

El cuerpo de los artículos es Markdown, no HTML. El portal los renderiza con un visor que nunca evalúa HTML sin procesar, así que cualquier HTML que envíes se muestra a los lectores como texto literal.

GET/v1/articles

Parameter	Type	Description
`status`	`string`	Filtrar por estado: draft, published o archived.
`category_id`	`string`	Solo artículos de esta categoría.
`limit`	`integer`	Tamaño de página. Por defecto 25, máximo 100.
`offset`	`integer`	Elementos a omitir. Por defecto 0.

GET/v1/articles/search

Parameter	Type	Description
`q`required	`string`	Consulta de búsqueda. Admite frases entre comillas, OR y -negación.
`limit`	`integer`	Número de resultados. Por defecto 25, máximo 100.

GET/v1/articles/:id

POST/v1/articles

Parameter	Type	Description
`title`required	`string`	Hasta 200 caracteres.
`body`	`string`	Markdown. Hasta 50.000 caracteres.
`excerpt`	`string`	Resumen de una línea, hasta 300 caracteres. Se deriva del cuerpo si se omite.
`slug`	`string`	Segmento de URL, hasta 80 caracteres. Se deriva del título si se omite.
`category_id`	`string`	Categoría en la que archivar el artículo.

PATCH/v1/articles/:id

Parameter	Type	Description
`title`	`string`	Nuevo título.
`body`	`string`	Nuevo cuerpo en Markdown.
`excerpt`	`string`	Nuevo resumen; null lo borra.
`slug`	`string`	Nuevo segmento de URL.
`category_id`	`string`	Nueva categoría; null deja el artículo sin categoría.
`status`	`string`	draft, published o archived.

DELETE/v1/articles/:id

Los artículos se crean siempre como borradores — publicar es un PATCH aparte, para que nada llegue a tu portal por accidente. Crear un artículo requiere acceso de escritura de un plan de pago, igual que cualquier otro método que modifique datos aquí.

Listar artículos


curl "https://api.supdesk.app/v1/articles?status=published&limit=10" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "¿Cómo restablezco mi contraseña?",
      "slug": "como-restablezco-mi-contrasena",
      "body": "Abre **Ajustes** y elige *Restablecer contraseña*.",
      "excerpt": "Abre Ajustes y elige Restablecer contraseña.",
      "status": "published",
      "category_id": "3c2b...",
      "published_at": "2026-07-01T09:12:00Z",
      "helpful_count": 12,
      "not_helpful_count": 1,
      "created_at": "2026-06-28T14:03:00Z",
      "updated_at": "2026-07-01T09:12:00Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "has_more": false }
}

Sin filtro devuelve también borradores y artículos archivados, con la edición más reciente primero. Usa status=published para lo que los clientes ven realmente.

Buscar artículos


curl "https://api.supdesk.app/v1/articles/search?q=restablecer+contraseña&limit=5" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "¿Cómo restablezco mi contraseña?",
      "slug": "como-restablezco-mi-contrasena",
      "category_slug": "primeros-pasos",
      "category_name": "Primeros pasos",
      "snippet": "Abre Ajustes y elige Restablecer contraseña.",
      "rank": 0.6079
    }
  ]
}

Búsqueda de texto completo solo sobre artículos publicados, ordenada por relevancia, con un fragmento de texto plano alrededor de la coincidencia. Los títulos pesan más que los resúmenes, y los resúmenes más que el cuerpo. Una consulta vacía o no interpretable devuelve una lista vacía en lugar de un error.

Obtener un artículo


curl "https://api.supdesk.app/v1/articles/8f7a..." \
  -H "Authorization: Bearer sd_live_..."

Devuelve un único artículo con la misma forma que en la lista, o 404 cuando el id es desconocido en tu proyecto.

Crear un artículo


curl -X POST https://api.supdesk.app/v1/articles \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "¿Cómo restablezco mi contraseña?",
    "body": "Abre **Ajustes** y elige *Restablecer contraseña*.",
    "category_id": "3c2b..."
  }'


{
  "data": {
    "id": "8f7a...",
    "title": "¿Cómo restablezco mi contraseña?",
    "slug": "como-restablezco-mi-contrasena",
    "body": "Abre **Ajustes** y elige *Restablecer contraseña*.",
    "excerpt": "Abre Ajustes y elige Restablecer contraseña.",
    "status": "draft",
    "category_id": "3c2b...",
    "published_at": null,
    "helpful_count": 0,
    "not_helpful_count": 0,
    "created_at": "2026-07-01T09:12:00Z",
    "updated_at": "2026-07-01T09:12:00Z"
  }
}

Devuelve 201. Si omites slug, se deriva del título, con sufijo -2, -3… si esa dirección está ocupada. Si omites excerpt, se deriva del cuerpo.

Tu plan limita cuántos artículos puede mantener un proyecto — Free 5, Pro 50, Team ilimitados. Superado el límite, esto devuelve limit_reached (429). Los artículos archivados no cuentan, así que archivar uno libera un hueco.

Actualizar un artículo


curl -X PATCH https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

Solo se escriben los campos que envías, así que un PATCH nunca vacía algo que has omitido. Poner status en published registra published_at la primera vez y lo conserva después — corregir una errata no hace que un artículo antiguo parezca nuevo. Ponerlo en archived retira el artículo sin borrarlo.

Desarchivar un artículo vuelve a comprobar el límite del plan, y puede devolver limit_reached.

Borrar un artículo


curl -X DELETE https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..."

Borra el artículo y su feedback de lectores de forma permanente, y devuelve 204. Para retirar un artículo conservándolo, pon su estado en archived.

Categorías

GET/v1/article-categories

Parameter	Type	Description
`limit`	`integer`	Tamaño de página. Por defecto 25, máximo 100.
`offset`	`integer`	Elementos a omitir. Por defecto 0.

GET/v1/article-categories/:id

POST/v1/article-categories

Parameter	Type	Description
`name`required	`string`	Hasta 80 caracteres.
`description`	`string`	Se muestra en el portal, hasta 300 caracteres.
`sort_order`	`integer`	Posición de visualización. Por defecto 0.

PATCH/v1/article-categories/:id

Parameter	Type	Description
`name`	`string`	Nuevo nombre.
`description`	`string`	Nueva descripción; null la borra.
`sort_order`	`integer`	Nueva posición de visualización.

DELETE/v1/article-categories/:id


curl -X POST https://api.supdesk.app/v1/article-categories \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Primeros pasos", "sort_order": 1 }'


{
  "data": {
    "id": "3c2b...",
    "name": "Primeros pasos",
    "slug": "primeros-pasos",
    "description": null,
    "sort_order": 1,
    "created_at": "2026-07-01T09:12:00Z"
  }
}

Las categorías se listan por sort_order y luego por nombre. Los slugs se derivan del nombre igual que los slugs de artículo se derivan del título.

Borrar una categoría devuelve 204 y no borra sus artículos — pasan a estar sin categoría y siguen siendo accesibles por búsqueda y desde la portada del centro de ayuda.

Errores

Además de los códigos estándar:

Código	Estado	Cuándo
`not_found`	404	Id desconocido — o el centro de ayuda está desactivado en este proyecto.
`forbidden`	403	Una escritura en un plan sin acceso de escritura a la API.
`limit_reached`	429	El cupo de artículos del plan está agotado.