VitrinaAPI

Help centers

The customer-facing documentation portal: sections, multi-locale articles and their sync into the knowledge base.

Beta
This may change at any time, with a changelog entry and a notice to recent callers — see versioning.

Download the full API pública projection: openapi.json.

Publish your help center explains this resource in prose, with runnable examples.

MethodPathWhat it does
GET/help-centersList the tenant’s help centers
POST/help-centersCreate a help center
DELETE/help-centers/{id}Delete a help center
GET/help-centers/{id}Get one help center
PUT/help-centers/{id}Update a help center
GET/help-centers/{id}/articlesList articles in a help center
POST/help-centers/{id}/articlesCreate an article
DELETE/help-centers/{id}/articles/{articleId}Delete an article
GET/help-centers/{id}/articles/{articleId}Get one article with its translations
PUT/help-centers/{id}/articles/{articleId}Update an article’s placement or status
POST/help-centers/{id}/articles/{articleId}/archiveArchive an article
GET/help-centers/{id}/articles/{articleId}/feedbackSummarise reader feedback for one article
DELETE/help-centers/{id}/articles/{articleId}/lockRelease the editor lock
POST/help-centers/{id}/articles/{articleId}/lockTake the editor lock on an article
POST/help-centers/{id}/articles/{articleId}/preview-linkMint a signed preview token for an unpublished article
POST/help-centers/{id}/articles/{articleId}/publishPublish an article
POST/help-centers/{id}/articles/{articleId}/resync-kbForce a fresh KB chunk + embed pass on a published article
POST/help-centers/{id}/articles/{articleId}/scheduleSchedule an article to publish later
DELETE/help-centers/{id}/articles/{articleId}/translations/{locale}Delete an article translation
PUT/help-centers/{id}/articles/{articleId}/translations/{locale}Create or replace an article translation
POST/help-centers/{id}/articles/{articleId}/translations/{locale}/generateAI-translate one article into one locale
POST/help-centers/{id}/articles/bulk-translateQueue AI translation of every article into target locales
POST/help-centers/{id}/articles/from-fileCreate an article from an uploaded document
GET/help-centers/{id}/feedbackList reader feedback across the help center
GET/help-centers/{id}/localesList the locales a help center publishes in
POST/help-centers/{id}/localesAdd a locale to a help center
DELETE/help-centers/{id}/locales/{locale}Remove a locale from a help center
POST/help-centers/{id}/locales/{locale}/defaultMake a locale the default
GET/help-centers/{id}/mediaList uploaded media
POST/help-centers/{id}/mediaUpload a media asset (multipart/form-data)
DELETE/help-centers/{id}/media/{mediaId}Delete a media asset
GET/help-centers/{id}/sectionsList the section tree
POST/help-centers/{id}/sectionsCreate a section
DELETE/help-centers/{id}/sections/{sectionId}Delete a section
PUT/help-centers/{id}/sections/{sectionId}Update a section’s slug, parent or position
DELETE/help-centers/{id}/sections/{sectionId}/translations/{locale}Delete a section translation
PUT/help-centers/{id}/sections/{sectionId}/translations/{locale}Create or replace a section translation
POST/help-centers/{id}/sections/reorderReorder sections
GET/help-centers/{id}/translation-coverageTranslation coverage matrix
GET/help-centers/articles/allList articles across every help center in the tenant

GET /help-centers

List the tenant’s help centers

Every help center (portal) in the workspace, with its publish state and locales.

curl https://api.vitrinadev.com/api/v1/help-centers \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "id": "a8a8a8a8-0000-4000-8000-000000000001",
      "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
      "slug": "ayuda",
      "name": "Centro de ayuda",
      "brand": null,
      "logo_url": null,
      "primary_color": null,
      "default_locale": "es",
      "supported_locales": [
        "es",
        "en"
      ],
      "custom_subdomain": null,
      "is_published": true,
      "settings": {},
      "created_at": "2026-08-20T12:00:00.000Z",
      "updated_at": "2026-09-10T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers

Create a help center

A new help center starts unpublished — set is_published via PUT once its content is ready. slug is unique per tenant; a collision is a 409.

Body

FieldTypeRequiredConstraints
slugstringyespatrón ^[a-z0-9](?:[a-z0-9-]{0,118}[a-z0-9])?$
namestringyesmín. 1, máx. 160
brandstring—máx. 120
logo_urlstring—uri, máx. 2048
primary_colorstring—patrón ^#[0-9A-Fa-f]{6}$
default_localestring—patrón ^[a-z]{2}(-[A-Z]{2})?$, por defecto "en"
supported_localesstring[]—por defecto []
custom_subdomainstring—patrón ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
curl -X POST https://api.vitrinadev.com/api/v1/help-centers \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Centro de ayuda",
    "slug": "ayuda"
  }'

Example response (201)

{
  "data": {
    "id": "a8a8a8a8-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "slug": "ayuda",
    "name": "Centro de ayuda",
    "brand": null,
    "logo_url": null,
    "primary_color": null,
    "default_locale": "es",
    "supported_locales": [
      "es",
      "en"
    ],
    "custom_subdomain": null,
    "is_published": false,
    "settings": {},
    "created_at": "2026-08-20T12:00:00.000Z",
    "updated_at": "2026-09-10T12:00:00.000Z"
  }
}

Answers: 201 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /help-centers/{id}

Delete a help center

Removes the portal and everything under it — sections, articles and translations.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl -X DELETE https://api.vitrinadev.com/api/v1/help-centers/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /help-centers/{id}

Get one help center

The full portal row: branding, locales configuration, publish state.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl https://api.vitrinadev.com/api/v1/help-centers/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "id": "a8a8a8a8-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "slug": "ayuda",
    "name": "Centro de ayuda",
    "brand": null,
    "logo_url": null,
    "primary_color": null,
    "default_locale": "es",
    "supported_locales": [
      "es",
      "en"
    ],
    "custom_subdomain": null,
    "is_published": true,
    "settings": {},
    "created_at": "2026-08-20T12:00:00.000Z",
    "updated_at": "2026-09-10T12:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

PUT /help-centers/{id}

Update a help center

Partial update — at least one field is required. Nullable fields (brand, logo_url, primary_color, custom_subdomain) are cleared by sending null; omitting them leaves them untouched. is_published is what makes the portal reachable on the public reader.

ParameterInTypeRequiredConstraints
idpathuuidyes

Body

FieldTypeRequiredConstraints
slugstring—patrón ^[a-z0-9](?:[a-z0-9-]{0,118}[a-z0-9])?$
namestring—mín. 1, máx. 160
brandstring | null—máx. 120
logo_urlstring | null—uri, máx. 2048
primary_colorstring | null—patrón ^#[0-9A-Fa-f]{6}$
default_localestring—patrón ^[a-z]{2}(-[A-Z]{2})?$
supported_localesstring[]—
custom_subdomainstring | null—patrón ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
is_publishedboolean—
settingsobject—
curl -X PUT https://api.vitrinadev.com/api/v1/help-centers/<id> \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_published": true,
    "primary_color": "#0EA5E9"
  }'

Example response (200)

{
  "data": {
    "id": "a8a8a8a8-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "slug": "ayuda",
    "name": "Centro de ayuda",
    "brand": null,
    "logo_url": null,
    "primary_color": "#0EA5E9",
    "default_locale": "es",
    "supported_locales": [
      "es",
      "en"
    ],
    "custom_subdomain": null,
    "is_published": true,
    "settings": {},
    "created_at": "2026-08-20T12:00:00.000Z",
    "updated_at": "2026-09-10T12:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /help-centers/{id}/articles

List articles in a help center

Articles in this ONE portal — see GET /help-centers/articles/all for the tenant-wide list. Filter by section_id or status.

ParameterInTypeRequiredConstraints
idpathuuidyes
section_idqueryuuidno
statusquerydraft \published \scheduled \
limitqueryintegerno≥ 1, ≤ 200
curl https://api.vitrinadev.com/api/v1/help-centers/<id>/articles \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "id": "b2b2b2b2-0000-4000-8000-000000000001",
      "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
      "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
      "slug": "garantia-de-fabrica",
      "status": "published",
      "position": 0,
      "scheduled_publish_at": null,
      "translations": [
        {
          "locale": "es",
          "title": "Garantía de fábrica",
          "body": "Todos los vehículos nuevos incluyen 3 años o 100.000 km de garantía."
        }
      ],
      "created_at": "2026-08-21T12:00:00.000Z",
      "updated_at": "2026-09-10T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/articles

Create an article

An empty translation.title is allowed on purpose: the editor opens the new article immediately and the title is typed inline. New articles are always created internal — publish them with the publish route.

ParameterInTypeRequiredConstraints
idpathuuidyes

Body

FieldTypeRequiredConstraints
slugstringyespatrón ^[a-z0-9](?:[a-z0-9-]{0,118}[a-z0-9])?$
section_idstring | null—
positioninteger—≥ 0, ≤ 10000
translationobjectyes
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/articles \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "translation": {
      "locale": "es",
      "title": ""
    }
  }'

Example response (201)

{
  "data": {
    "id": "b2b2b2b2-0000-4000-8000-000000000001",
    "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
    "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
    "slug": "garantia-de-fabrica",
    "status": "internal",
    "position": 0,
    "scheduled_publish_at": null,
    "translations": [
      {
        "locale": "es",
        "title": "",
        "body": ""
      }
    ],
    "created_at": "2026-08-21T12:00:00.000Z",
    "updated_at": "2026-09-10T12:00:00.000Z"
  }
}

Answers: 201 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /help-centers/{id}/articles/{articleId}

Delete an article

Removes the article and every locale’s translation. A published article is un-published and its KB chunks are removed first, so the agent stops quoting it.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
curl -X DELETE https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /help-centers/{id}/articles/{articleId}

Get one article with its translations

The full article row, every locale’s translation included.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
curl https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "id": "b2b2b2b2-0000-4000-8000-000000000001",
  "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
  "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
  "slug": "garantia-de-fabrica",
  "status": "published",
  "position": 0,
  "scheduled_publish_at": null,
  "translations": [
    {
      "locale": "es",
      "title": "Garantía de fábrica",
      "body": "Todos los vehículos nuevos incluyen 3 años o 100.000 km de garantía."
    }
  ],
  "created_at": "2026-08-21T12:00:00.000Z",
  "updated_at": "2026-09-10T12:00:00.000Z"
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

PUT /help-centers/{id}/articles/{articleId}

Update an article’s placement or status

Structure and lifecycle only — the prose lives in translations. Prefer the publish / archive / schedule routes over setting status here: they run the side effects (KB sync on publish, scheduling on schedule) that a bare status write does not.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes

Body

FieldTypeRequiredConstraints
slugstring—patrón ^[a-z0-9](?:[a-z0-9-]{0,118}[a-z0-9])?$
section_idstring | null—
positioninteger—≥ 0, ≤ 10000
statusdraft \published \scheduled \
visibilitypublic \internal—
scheduled_publish_atstring | null—
curl -X PUT https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id> \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
    "position": 1
  }'

Example response (200)

{
  "data": {
    "id": "b2b2b2b2-0000-4000-8000-000000000001",
    "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
    "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
    "slug": "garantia-de-fabrica",
    "status": "published",
    "position": 1,
    "scheduled_publish_at": null,
    "translations": [
      {
        "locale": "es",
        "title": "Garantía de fábrica",
        "body": "Todos los vehículos nuevos incluyen 3 años o 100.000 km de garantía."
      }
    ],
    "created_at": "2026-08-21T12:00:00.000Z",
    "updated_at": "2026-09-10T12:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/articles/{articleId}/archive

Archive an article

Withdraws it from the reader without deleting it; can be published again later.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/archive \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "id": "b2b2b2b2-0000-4000-8000-000000000001",
    "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
    "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
    "slug": "garantia-de-fabrica",
    "status": "archived",
    "position": 0,
    "scheduled_publish_at": null,
    "translations": [
      {
        "locale": "es",
        "title": "Garantía de fábrica",
        "body": "Todos los vehículos nuevos incluyen 3 años o 100.000 km de garantía."
      }
    ],
    "created_at": "2026-08-21T12:00:00.000Z",
    "updated_at": "2026-09-10T12:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /help-centers/{id}/articles/{articleId}/feedback

Summarise reader feedback for one article

Aggregate of the helpful / not-helpful votes left by readers on the public portal.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
curl https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/feedback \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "helpful": 12,
    "not_helpful": 1,
    "total": 13
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /help-centers/{id}/articles/{articleId}/lock

Release the editor lock

Only clears the lock if the caller holds it. Requires a Supabase user session for the same reason as taking it.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
curl -X DELETE https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/lock \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/articles/{articleId}/lock

Take the editor lock on an article

Advisory lock so two editors do not overwrite each other. Requires a Supabase user session — an sk_* API key has no user behind it and gets 400, since a lock has to be held by someone. The response reports who holds it, so losing the race is a 200, not an error.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/lock \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "locked": true,
    "locked_by": "11111111-0000-4000-8000-000000000001",
    "locked_at": "2026-09-21T10:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/articles/{articleId}/preview-link

Mint a signed preview token for an unpublished article

Lets a reviewer open a draft on the public reader without publishing it. The token is valid for 24 hours. locale may be sent in the body or as a ?locale= query parameter; neither is a 400.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes

Body

FieldTypeRequiredConstraints
localestringyesmín. 1
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/preview-link \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "es"
  }'

Example response (200)

{
  "data": {
    "token": "ptok_9f1c2e7a8b3d4e5f",
    "locale": "es",
    "expires_in": 86400
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/articles/{articleId}/publish

Publish an article

Makes it visible on the public reader AND syncs its translations into the knowledge base, so the AI agent starts answering from it.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/publish \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "id": "b2b2b2b2-0000-4000-8000-000000000001",
    "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
    "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
    "slug": "garantia-de-fabrica",
    "status": "published",
    "position": 0,
    "scheduled_publish_at": null,
    "translations": [
      {
        "locale": "es",
        "title": "Garantía de fábrica",
        "body": "Todos los vehículos nuevos incluyen 3 años o 100.000 km de garantía."
      }
    ],
    "created_at": "2026-08-21T12:00:00.000Z",
    "updated_at": "2026-09-10T12:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/articles/{articleId}/resync-kb

Force a fresh KB chunk + embed pass on a published article

Publishing already syncs to the KB, so this is the escape hatch for when that sync was lost — after a backfill, an embedding-model change, or an edit made while the background sync was failing. Only published articles can be synced; anything else is a 400.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/resync-kb \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "synced_locales": [
      "es",
      "en"
    ],
    "chunks": 3
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/articles/{articleId}/schedule

Schedule an article to publish later

Moves it to scheduled; a background worker publishes it at scheduled_publish_at, running the same KB sync as a manual publish.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes

Body

FieldTypeRequiredConstraints
scheduled_publish_atstringyesmín. 1
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/schedule \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_publish_at": "2026-09-25T13:00:00.000Z"
  }'

Example response (200)

{
  "data": {
    "id": "b2b2b2b2-0000-4000-8000-000000000001",
    "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
    "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
    "slug": "garantia-de-fabrica",
    "status": "scheduled",
    "position": 0,
    "scheduled_publish_at": "2026-09-25T13:00:00.000Z",
    "translations": [
      {
        "locale": "es",
        "title": "Garantía de fábrica",
        "body": "Todos los vehículos nuevos incluyen 3 años o 100.000 km de garantía."
      }
    ],
    "created_at": "2026-08-21T12:00:00.000Z",
    "updated_at": "2026-09-10T12:00:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /help-centers/{id}/articles/{articleId}/translations/{locale}

Delete an article translation

Removes this ONE locale’s translation. If the article is published and this was the last translation, the article-level KB entry for that locale is removed too.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
localepathstringyespatrón ^[a-z]{2}(-[A-Z]{2})?$
curl -X DELETE https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/translations/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

PUT /help-centers/{id}/articles/{articleId}/translations/{locale}

Create or replace an article translation

Upsert, and the route the editor autosaves through — which is why an empty title is accepted: it bounces 0-length drafts while the author is still typing. If the article is published, saving re-syncs the KB.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
localepathstringyespatrón ^[a-z]{2}(-[A-Z]{2})?$

Body

FieldTypeRequiredConstraints
titlestringyesmáx. 240
body_markdownstringyesmáx. 200000
excerptstring | null—máx. 1000
meta_descriptionstring | null—máx. 320
seo_titlestring | null—máx. 240
seo_imagestring | null—máx. 1024
curl -X PUT https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/translations/<id> \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Factory warranty",
    "body": "Every new vehicle carries 3 years or 100,000 km of factory warranty."
  }'

Example response (200)

{
  "data": {
    "locale": "en",
    "title": "Factory warranty",
    "body": "Every new vehicle carries 3 years or 100,000 km of factory warranty."
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/articles/{articleId}/translations/{locale}/generate

AI-translate one article into one locale

Synchronous single-cell counterpart to bulk-translate — it returns the finished translation rather than a job count, so it blocks for as long as the model takes. Overwrites any existing translation for that locale.

ParameterInTypeRequiredConstraints
idpathuuidyes
articleIdpathuuidyes
localepathstringyespatrón ^[a-z]{2}(-[A-Z]{2})?$
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/<id>/translations/<id>/generate \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "locale": "en",
    "title": "Factory warranty",
    "body": "Every new vehicle carries 3 years or 100,000 km of factory warranty.",
    "generated": true
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/articles/bulk-translate

Queue AI translation of every article into target locales

Asynchronous: enqueues one job per (article, locale) cell that needs work and returns immediately — the translations appear over the following minutes. min_status picks the cells: missing only fills gaps, outdated (the default) also re-translates cells whose source has changed since.

ParameterInTypeRequiredConstraints
idpathuuidyes

Body

FieldTypeRequiredConstraints
target_localesstring[]yes
min_statusmissing \outdated—
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/bulk-translate \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_locales": [
      "en"
    ],
    "min_status": "outdated"
  }'

Example response (202)

{
  "enqueued": 4,
  "target_locales": [
    "en"
  ],
  "articles": 4
}

Answers: 202 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/articles/from-file

Create an article from an uploaded document

Extracts the text of a PDF / DOCX / XLSX / plain-text upload server-side and stores it as one article — no object-storage round trip. The slug and title come from the filename. Rejects with 400 when fewer than 20 characters of usable text come out, which is the usual outcome for a scanned image PDF.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/articles/from-file \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -F "file=@/path/to/file.png"

Example response (201)

{
  "data": {
    "id": "b2b2b2b2-0000-4000-8000-000000000001",
    "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
    "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
    "slug": "garantia-de-fabrica",
    "status": "internal",
    "position": 0,
    "scheduled_publish_at": null,
    "translations": [
      {
        "locale": "es",
        "title": "",
        "body": ""
      }
    ],
    "created_at": "2026-08-21T12:00:00.000Z",
    "updated_at": "2026-09-10T12:00:00.000Z"
  }
}

Answers: 201 · 400 · 401 · 403 · 404 · 409 · 429

GET /help-centers/{id}/feedback

List reader feedback across the help center

Portal-wide feed of reader votes and comments — the per-article view is nested under the article.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl https://api.vitrinadev.com/api/v1/help-centers/<id>/feedback \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "article_id": "b2b2b2b2-0000-4000-8000-000000000001",
      "locale": "es",
      "helpful": true,
      "comment": null,
      "created_at": "2026-09-20T15:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /help-centers/{id}/locales

List the locales a help center publishes in

Every locale this portal publishes, with which one is is_default.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl https://api.vitrinadev.com/api/v1/help-centers/<id>/locales \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "locale": "es",
      "is_default": true
    },
    {
      "locale": "en",
      "is_default": false
    }
  ]
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/locales

Add a locale to a help center

Answers 200, not 201 — an oddity of this route, kept for the clients already relying on it. Adding a locale does not translate anything; it opens the column that bulk-translate then fills.

ParameterInTypeRequiredConstraints
idpathuuidyes

Body

FieldTypeRequiredConstraints
localestringyesmín. 2, máx. 16
display_namestring | null—máx. 120
is_defaultboolean—
rtlboolean—
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/locales \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "en"
  }'

Example response (200)

{
  "data": {
    "locale": "en",
    "is_default": false
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /help-centers/{id}/locales/{locale}

Remove a locale from a help center

Drops the locale and every translation filed under it (sections and articles). The default locale cannot be removed — reassign it first.

ParameterInTypeRequiredConstraints
idpathuuidyes
localepathstringyesmín. 2, máx. 16
curl -X DELETE https://api.vitrinadev.com/api/v1/help-centers/<id>/locales/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/locales/{locale}/default

Make a locale the default

The default locale is what a reader gets with no locale preference, and the source language bulk-translate translates from.

ParameterInTypeRequiredConstraints
idpathuuidyes
localepathstringyesmín. 2, máx. 16
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/locales/<id>/default \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "locale": "en",
    "is_default": true
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /help-centers/{id}/media

List uploaded media

Every media asset uploaded to this portal’s article editor.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl https://api.vitrinadev.com/api/v1/help-centers/<id>/media \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "id": "a8a8a8a8-4000-4000-8000-000000000001",
      "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
      "url": "https://cdn.vitrinadev.com/help-centers/ayuda/garantia.png",
      "content_type": "image/png",
      "size_bytes": 48213,
      "created_at": "2026-09-05T09:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/media

Upload a media asset (multipart/form-data)

Accepts images, video and documents for the article editor’s media blocks, up to 50 MB. Host anything larger externally and link to it.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/media \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -F "file=@/path/to/file.png"

Example response (201)

{
  "data": {
    "id": "a8a8a8a8-4000-4000-8000-000000000001",
    "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
    "url": "https://cdn.vitrinadev.com/help-centers/ayuda/garantia.png",
    "content_type": "image/png",
    "size_bytes": 48213,
    "created_at": "2026-09-05T09:00:00.000Z"
  }
}

Answers: 201 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /help-centers/{id}/media/{mediaId}

Delete a media asset

Articles that still embed the asset are not rewritten — their image will 404.

ParameterInTypeRequiredConstraints
idpathuuidyes
mediaIdpathuuidyes
curl -X DELETE https://api.vitrinadev.com/api/v1/help-centers/<id>/media/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

GET /help-centers/{id}/sections

List the section tree

Flat list; nesting is expressed by parent_id, ordering by position.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl https://api.vitrinadev.com/api/v1/help-centers/<id>/sections \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "id": "a9a9a9a9-0000-4000-8000-000000000001",
      "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
      "slug": "garantia",
      "parent_id": null,
      "position": 0,
      "created_at": "2026-08-20T12:10:00.000Z",
      "updated_at": "2026-08-20T12:10:00.000Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/sections

Create a section

A section carries no text of its own — the title and description live in translations, so one is required at create time to name it.

ParameterInTypeRequiredConstraints
idpathuuidyes

Body

FieldTypeRequiredConstraints
slugstringyespatrón ^[a-z0-9](?:[a-z0-9-]{0,118}[a-z0-9])?$
parent_idstring | null—
positioninteger—≥ 0, ≤ 10000
translationobjectyes
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/sections \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "garantia",
    "translation": {
      "locale": "es",
      "title": "Garantía",
      "description": "Todo sobre la garantía de fábrica"
    }
  }'

Example response (201)

{
  "data": {
    "id": "a9a9a9a9-0000-4000-8000-000000000001",
    "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
    "slug": "garantia",
    "parent_id": null,
    "position": 0,
    "created_at": "2026-08-20T12:10:00.000Z",
    "updated_at": "2026-08-20T12:10:00.000Z"
  }
}

Answers: 201 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /help-centers/{id}/sections/{sectionId}

Delete a section

Removes the section and its translations. Articles that were filed under it are not deleted — they lose their section (section_id becomes null).

ParameterInTypeRequiredConstraints
idpathuuidyes
sectionIdpathuuidyes
curl -X DELETE https://api.vitrinadev.com/api/v1/help-centers/<id>/sections/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

PUT /help-centers/{id}/sections/{sectionId}

Update a section’s slug, parent or position

Structure only — title and description are per-locale, see the translation routes. A section cannot be reparented under itself.

ParameterInTypeRequiredConstraints
idpathuuidyes
sectionIdpathuuidyes

Body

FieldTypeRequiredConstraints
slugstring—patrón ^[a-z0-9](?:[a-z0-9-]{0,118}[a-z0-9])?$
parent_idstring | null—
positioninteger—≥ 0, ≤ 10000
curl -X PUT https://api.vitrinadev.com/api/v1/help-centers/<id>/sections/<id> \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 1
  }'

Example response (200)

{
  "data": {
    "id": "a9a9a9a9-0000-4000-8000-000000000001",
    "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
    "slug": "garantia",
    "parent_id": null,
    "position": 1,
    "created_at": "2026-08-20T12:10:00.000Z",
    "updated_at": "2026-08-20T12:10:00.000Z"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

DELETE /help-centers/{id}/sections/{sectionId}/translations/{locale}

Delete a section translation

Removes this ONE locale. The section itself, and its other locales, are untouched.

ParameterInTypeRequiredConstraints
idpathuuidyes
sectionIdpathuuidyes
localepathstringyespatrón ^[a-z]{2}(-[A-Z]{2})?$
curl -X DELETE https://api.vitrinadev.com/api/v1/help-centers/<id>/sections/<id>/translations/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

Answers: 204 · 400 · 401 · 403 · 404 · 409 · 429

PUT /help-centers/{id}/sections/{sectionId}/translations/{locale}

Create or replace a section translation

Upsert — the same call creates the locale or overwrites it.

ParameterInTypeRequiredConstraints
idpathuuidyes
sectionIdpathuuidyes
localepathstringyespatrón ^[a-z]{2}(-[A-Z]{2})?$

Body

FieldTypeRequiredConstraints
titlestringyesmín. 1, máx. 200
descriptionstring | null—máx. 4000
curl -X PUT https://api.vitrinadev.com/api/v1/help-centers/<id>/sections/<id>/translations/<id> \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Garantía",
    "description": "Todo sobre la garantía de fábrica"
  }'

Example response (200)

{
  "data": {
    "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
    "locale": "es",
    "title": "Garantía",
    "description": "Todo sobre la garantía de fábrica"
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

POST /help-centers/{id}/sections/reorder

Reorder sections

Atomic: every section_id must belong to this help center, and one that does not fails the whole call rather than reordering the rest.

ParameterInTypeRequiredConstraints
idpathuuidyes

Body

FieldTypeRequiredConstraints
orderobject[]yes
curl -X POST https://api.vitrinadev.com/api/v1/help-centers/<id>/sections/reorder \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "section_ids": [
      "a9a9a9a9-0000-4000-8000-000000000001"
    ]
  }'

Example response (200)

{
  "data": [
    {
      "id": "a9a9a9a9-0000-4000-8000-000000000001",
      "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
      "slug": "garantia",
      "parent_id": null,
      "position": 0,
      "created_at": "2026-08-20T12:10:00.000Z",
      "updated_at": "2026-08-20T12:10:00.000Z"
    }
  ]
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /help-centers/{id}/translation-coverage

Translation coverage matrix

Article × non-default-locale grid, each cell up_to_date | outdated | missing | draft, plus an overall percentage. This is the same computation bulk-translate uses to pick cells, so it doubles as a preview of what a bulk run would do.

ParameterInTypeRequiredConstraints
idpathuuidyes
curl https://api.vitrinadev.com/api/v1/help-centers/<id>/translation-coverage \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": {
    "locales": [
      "en"
    ],
    "overall_pct": 75,
    "articles": [
      {
        "article_id": "b2b2b2b2-0000-4000-8000-000000000001",
        "slug": "garantia-de-fabrica",
        "en": "up_to_date"
      }
    ]
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

GET /help-centers/articles/all

List articles across every help center in the tenant

Tenant-wide article list, not scoped to one portal — drives the admin “all articles” view. Unlike the per-help-center list, this route does not validate status: an unknown value simply matches nothing.

ParameterInTypeRequiredConstraints
statusquerydraft \published \scheduled \
curl https://api.vitrinadev.com/api/v1/help-centers/articles/all \
  -H "Authorization: Bearer $VITRINA_KEY"

Example response (200)

{
  "data": [
    {
      "id": "b2b2b2b2-0000-4000-8000-000000000001",
      "help_center_id": "a8a8a8a8-0000-4000-8000-000000000001",
      "section_id": "a9a9a9a9-0000-4000-8000-000000000001",
      "slug": "garantia-de-fabrica",
      "status": "published",
      "position": 0,
      "scheduled_publish_at": null,
      "translations": [
        {
          "locale": "es",
          "title": "Garantía de fábrica",
          "body": "Todos los vehículos nuevos incluyen 3 años o 100.000 km de garantía."
        }
      ],
      "created_at": "2026-08-21T12:00:00.000Z",
      "updated_at": "2026-09-10T12:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Answers: 200 · 400 · 401 · 403 · 404 · 409 · 429

Add-ons

The add-on catalog, the ones this workspace has ever held and the live usage of the metered ones — and the two self-serve writes to activate or cancel one.

Integrations · Meta Ads

The Meta Ads account connection: start it, resolve the account selection when there is more than one, disconnect it, and read the workspace's click-to-WhatsApp ads.

On this page

GET /help-centersPOST /help-centersDELETE /help-centers/{id}GET /help-centers/{id}PUT /help-centers/{id}GET /help-centers/{id}/articlesPOST /help-centers/{id}/articlesDELETE /help-centers/{id}/articles/{articleId}GET /help-centers/{id}/articles/{articleId}PUT /help-centers/{id}/articles/{articleId}POST /help-centers/{id}/articles/{articleId}/archiveGET /help-centers/{id}/articles/{articleId}/feedbackDELETE /help-centers/{id}/articles/{articleId}/lockPOST /help-centers/{id}/articles/{articleId}/lockPOST /help-centers/{id}/articles/{articleId}/preview-linkPOST /help-centers/{id}/articles/{articleId}/publishPOST /help-centers/{id}/articles/{articleId}/resync-kbPOST /help-centers/{id}/articles/{articleId}/scheduleDELETE /help-centers/{id}/articles/{articleId}/translations/{locale}PUT /help-centers/{id}/articles/{articleId}/translations/{locale}POST /help-centers/{id}/articles/{articleId}/translations/{locale}/generatePOST /help-centers/{id}/articles/bulk-translatePOST /help-centers/{id}/articles/from-fileGET /help-centers/{id}/feedbackGET /help-centers/{id}/localesPOST /help-centers/{id}/localesDELETE /help-centers/{id}/locales/{locale}POST /help-centers/{id}/locales/{locale}/defaultGET /help-centers/{id}/mediaPOST /help-centers/{id}/mediaDELETE /help-centers/{id}/media/{mediaId}GET /help-centers/{id}/sectionsPOST /help-centers/{id}/sectionsDELETE /help-centers/{id}/sections/{sectionId}PUT /help-centers/{id}/sections/{sectionId}DELETE /help-centers/{id}/sections/{sectionId}/translations/{locale}PUT /help-centers/{id}/sections/{sectionId}/translations/{locale}POST /help-centers/{id}/sections/reorderGET /help-centers/{id}/translation-coverageGET /help-centers/articles/all