SunflareSunflare/Documentation
Back to site

title: "Public API" lastUpdated: 2026-04-20

Sunflare Public API

Sunflare exposes a public REST API so you can hand your AI agents, scripts, or integrations a key and let them manage your CMS directly — SEO at scale, image alt text, translations, and publish-to-live.

Base URL: https://sc-api.sunflare.app Current version: v1 Machine-readable spec: /.well-known/openapi.json

1. Create an API key

Go to Dashboard → Settings → Developer → API Keys, click Create key, choose a label and the scopes you need, then copy the full key that appears once. The key looks like:

sk_live_{keyId}_{secret}

Store the key immediately — the full value is shown once. If you lose it, revoke and create a new one.

2. Authenticate

Send the key on every request as a bearer token:

curl -H "Authorization: Bearer sk_live_{keyId}_{secret}" \
  https://sc-api.sunflare.app/v1/whoami

A successful response returns the account ID, key ID, and granted scopes:

{ "accountId": "…", "keyId": "…", "scopes": ["cms:read", "cms:write"] }

3. Scopes

| Scope | What it grants | |-------|----------------| | cms:read | All GET endpoints | | cms:write | SEO, alt text, translations, manual snapshots | | cms:publish | Restore a previous version, publish draft to live |

The API key implies the account — you never pass an accountId argument. Using a key minted for account A against account B's resources returns 404.

4. What you can do

  • SEO at scale — List pages, patch single or bulk SEO fields (title, description, keywords, robots).
  • Image alt text — Filter photos missing alt, write individually or in batches.
  • Versioning — List history, inspect any version, take manual snapshots, restore, publish.
  • Translations — Read/write per-language page overlays against the latest site version.

5. Safety (server-enforced)

  • The server automatically snapshots before your first write in any 15-minute window. The response includes X-Sunflare-Snapshot-Version: <n> so you always know the restore point.
  • Publish and restore create their own checkpoints before applying.
  • Bulk endpoints accept an optional Idempotency-Key header — safe to retry on timeouts.

6. Errors

All error responses use RFC 7807 application/problem+json:

{
  "type": "https://sunflare.app/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This endpoint requires the cms:publish scope",
  "requestId": "01KPN..."
}

Every response — success or error — carries X-Sunflare-Request-Id (a ULID). Include it when reporting problems.

7. For AI agents

If you're pointing an agent (Claude Desktop, Cursor, custom) at this API, the agent-readable skill file is at:

https://sunflare.app/.well-known/agent-skills/sunflare-cms/SKILL.md

It's indexed in the discovery manifest at /.well-known/agent-skills/index.json with a sha256 digest so the agent can verify integrity.

The full machine contract is the OpenAPI 3.1 spec linked at the top of this page.

8. Quick reference

# Read
GET  /v1/whoami
GET  /v1/pages                           ?cursor=&limit=
GET  /v1/pages/{path}                    # URL-encode slashes: %2F
GET  /v1/images                          ?missingAlt=true
GET  /v1/images/{imageId}
GET  /v1/versions
GET  /v1/versions/{n}
GET  /v1/locales
GET  /v1/translations                    ?language=es
GET  /v1/translations/{language}/{path}

# Write (cms:write)
PATCH /v1/pages/{path}/seo               {seoTitle?, seoDescription?, keywords?, robots?}
POST  /v1/pages/bulk-seo                 {items: [...]}
PATCH /v1/images/{imageId}/alt           {alt}
POST  /v1/images/bulk-alt                {items: [...]}
PATCH /v1/translations/{lang}/{path}     {overlay, staleness?}
POST  /v1/versions/snapshot              {label?, changesSummary?}

# Publish (cms:publish)
POST  /v1/versions/publish               {versionNumber?}    # omit to publish latest draft
POST  /v1/versions/{n}/restore

See the OpenAPI spec for full request and response schemas.

title: "API pública" lastUpdated: 2026-04-20

API pública de Sunflare

Sunflare expone una API REST pública para que puedas dar a tus agentes de IA, scripts o integraciones una clave y dejarles gestionar tu CMS directamente — SEO a escala, texto alternativo de imágenes, traducciones y publicación en vivo.

URL base: https://sc-api.sunflare.app Versión actual: v1 Especificación legible por máquina: /.well-known/openapi.json

1. Crea una clave de API

Ve a Panel → Ajustes → Desarrollador → Claves de API, haz clic en Crear clave, elige una etiqueta y los ámbitos que necesites, y copia la clave completa que aparece una sola vez. La clave tiene este aspecto:

sk_live_{keyId}_{secret}

Guarda la clave inmediatamente — el valor completo solo se muestra una vez. Si la pierdes, revócala y crea una nueva.

2. Autentícate

Envía la clave en cada solicitud como token tipo bearer:

curl -H "Authorization: Bearer sk_live_{keyId}_{secret}" \
  https://sc-api.sunflare.app/v1/whoami

Una respuesta correcta devuelve el ID de la cuenta, el ID de la clave y los ámbitos concedidos:

{ "accountId": "…", "keyId": "…", "scopes": ["cms:read", "cms:write"] }

3. Ámbitos

| Ámbito | Qué permite | |--------|-------------| | cms:read | Todos los endpoints GET | | cms:write | SEO, texto alternativo, traducciones y snapshots manuales | | cms:publish | Restaurar una versión anterior, publicar el borrador en vivo |

La clave de API ya implica la cuenta — nunca tienes que pasar un argumento accountId. Usar una clave emitida para la cuenta A contra recursos de la cuenta B devuelve 404.

4. Qué puedes hacer

  • SEO a escala — Lista páginas, edita campos SEO individualmente o en lotes (título, descripción, palabras clave, robots).
  • Texto alternativo de imágenes — Filtra fotos sin alt, escríbelo individualmente o en lotes.
  • Versionado — Lista el historial, inspecciona cualquier versión, crea snapshots manuales, restaura, publica.
  • Traducciones — Lee y escribe superposiciones de página por idioma contra la versión más reciente del sitio.

5. Seguridad (aplicada por el servidor)

  • El servidor crea automáticamente un snapshot antes de tu primera escritura dentro de cualquier ventana de 15 minutos. La respuesta incluye X-Sunflare-Snapshot-Version: <n> para que siempre conozcas el punto de restauración.
  • Publicar y restaurar crean sus propios puntos de control antes de aplicar los cambios.
  • Los endpoints en lote aceptan una cabecera opcional Idempotency-Key — seguro para reintentar ante timeouts.

6. Errores

Todas las respuestas de error usan RFC 7807 application/problem+json:

{
  "type": "https://sunflare.app/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This endpoint requires the cms:publish scope",
  "requestId": "01KPN..."
}

Cada respuesta — correcta o de error — incluye X-Sunflare-Request-Id (un ULID). Inclúyelo al reportar problemas.

7. Para agentes de IA

Si apuntas un agente (Claude Desktop, Cursor, personalizado) a esta API, el archivo de skill legible por el agente está en:

https://sunflare.app/.well-known/agent-skills/sunflare-cms/SKILL.md

Está indexado en el manifiesto de descubrimiento en /.well-known/agent-skills/index.json con un digest sha256 para que el agente pueda verificar la integridad.

El contrato completo para máquinas es la especificación OpenAPI 3.1 enlazada al principio de esta página.

8. Referencia rápida

# Lectura
GET  /v1/whoami
GET  /v1/pages                           ?cursor=&limit=
GET  /v1/pages/{path}                    # codifica las barras: %2F
GET  /v1/images                          ?missingAlt=true
GET  /v1/images/{imageId}
GET  /v1/versions
GET  /v1/versions/{n}
GET  /v1/locales
GET  /v1/translations                    ?language=es
GET  /v1/translations/{language}/{path}

# Escritura (cms:write)
PATCH /v1/pages/{path}/seo               {seoTitle?, seoDescription?, keywords?, robots?}
POST  /v1/pages/bulk-seo                 {items: [...]}
PATCH /v1/images/{imageId}/alt           {alt}
POST  /v1/images/bulk-alt                {items: [...]}
PATCH /v1/translations/{lang}/{path}     {overlay, staleness?}
POST  /v1/versions/snapshot              {label?, changesSummary?}

# Publicación (cms:publish)
POST  /v1/versions/publish               {versionNumber?}    # omítelo para publicar el último borrador
POST  /v1/versions/{n}/restore

Consulta la especificación OpenAPI para los esquemas completos de solicitud y respuesta.

title: "API pública" lastUpdated: 2026-04-20

API pública de Sunflare

Sunflare exposa una API REST pública perquè puguis donar a les teves agents d'IA, scripts o integracions una clau i deixar-los gestionar directament el teu CMS — SEO a escala, text alternatiu d'imatges, traduccions i publicació en viu.

URL base: https://sc-api.sunflare.app Versió actual: v1 Especificació llegible per màquines: /.well-known/openapi.json

1. Crea una clau d'API

Ves a Tauler → Configuració → Desenvolupador → Claus d'API, fes clic a Crea clau, tria una etiqueta i els àmbits que necessites, i copia la clau completa que apareix una sola vegada. La clau té aquest aspecte:

sk_live_{keyId}_{secret}

Guarda la clau immediatament — el valor complet només es mostra una vegada. Si la perds, revoca-la i crea'n una de nova.

2. Autentica't

Envia la clau a cada sol·licitud com a token de tipus bearer:

curl -H "Authorization: Bearer sk_live_{keyId}_{secret}" \
  https://sc-api.sunflare.app/v1/whoami

Una resposta correcta retorna l'ID del compte, l'ID de la clau i els àmbits concedits:

{ "accountId": "…", "keyId": "…", "scopes": ["cms:read", "cms:write"] }

3. Àmbits

| Àmbit | Què permet | |-------|------------| | cms:read | Tots els endpoints GET | | cms:write | SEO, text alternatiu, traduccions i snapshots manuals | | cms:publish | Restaurar una versió anterior, publicar l'esborrany en viu |

La clau d'API ja implica el compte — mai no has de passar un argument accountId. Utilitzar una clau generada per al compte A contra recursos del compte B retorna 404.

4. Què pots fer

  • SEO a escala — Llista pàgines, edita camps SEO individualment o en lots (títol, descripció, paraules clau, robots).
  • Text alternatiu d'imatges — Filtra fotos sense alt, escriu-lo individualment o en lots.
  • Versionat — Llista l'historial, inspecciona qualsevol versió, fes snapshots manuals, restaura, publica.
  • Traduccions — Llegeix i escriu superposicions de pàgina per idioma contra la versió més recent del lloc.

5. Seguretat (aplicada pel servidor)

  • El servidor crea automàticament un snapshot abans de la teva primera escriptura dins de qualsevol finestra de 15 minuts. La resposta inclou X-Sunflare-Snapshot-Version: <n> perquè sempre sàpigues el punt de restauració.
  • Publicar i restaurar creen els seus propis punts de control abans d'aplicar els canvis.
  • Els endpoints de lot accepten una capçalera opcional Idempotency-Key — segur per reintentar en cas de temps d'espera.

6. Errors

Totes les respostes d'error fan servir RFC 7807 application/problem+json:

{
  "type": "https://sunflare.app/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This endpoint requires the cms:publish scope",
  "requestId": "01KPN..."
}

Cada resposta — correcta o d'error — inclou X-Sunflare-Request-Id (un ULID). Inclou-lo quan reportis problemes.

7. Per a agents d'IA

Si apuntes un agent (Claude Desktop, Cursor, personalitzat) a aquesta API, el fitxer de skill llegible per l'agent és a:

https://sunflare.app/.well-known/agent-skills/sunflare-cms/SKILL.md

Està indexat al manifest de descobriment a /.well-known/agent-skills/index.json amb un digest sha256 perquè l'agent pugui verificar-ne la integritat.

El contracte màquina complet és l'especificació OpenAPI 3.1 enllaçada al començament d'aquesta pàgina.

8. Referència ràpida

# Lectura
GET  /v1/whoami
GET  /v1/pages                           ?cursor=&limit=
GET  /v1/pages/{path}                    # codifica les barres: %2F
GET  /v1/images                          ?missingAlt=true
GET  /v1/images/{imageId}
GET  /v1/versions
GET  /v1/versions/{n}
GET  /v1/locales
GET  /v1/translations                    ?language=es
GET  /v1/translations/{language}/{path}

# Escriptura (cms:write)
PATCH /v1/pages/{path}/seo               {seoTitle?, seoDescription?, keywords?, robots?}
POST  /v1/pages/bulk-seo                 {items: [...]}
PATCH /v1/images/{imageId}/alt           {alt}
POST  /v1/images/bulk-alt                {items: [...]}
PATCH /v1/translations/{lang}/{path}     {overlay, staleness?}
POST  /v1/versions/snapshot              {label?, changesSummary?}

# Publicació (cms:publish)
POST  /v1/versions/publish               {versionNumber?}    # omet-ho per publicar l'últim esborrany
POST  /v1/versions/{n}/restore

Consulta l'especificació OpenAPI per a l'esquema complet de sol·licituds i respostes.