API GraphQL

Usa la API GraphQL para solicitar contenido de Contismo fuera del Studio, por ejemplo en un sitio web, una aplicación u otro sistema externo.

Extremo

Cada entorno del proyecto tiene su propio extremo de GraphQL.

Para encontrar el extremo correcto:

1. Abre tu proyecto en el Studio.
2. Ve a Configuración y busca el extremo de GraphQL del entorno que quieres consultar.
3. Usa esa URL al configurar tu cliente o integración.

Autenticación

Autentica las solicitudes enviando tu clave de API en el encabezado Authorization:

Authorization: Bearer <your-api-key>

Asegúrate de que la clave que uses tenga acceso al proyecto y al entorno que estás consultando.

Consulta de ejemplo

El ejemplo siguiente solicita una lista de entradas de un modelo BlogPost (campo plural blogPosts):

query {
  blogPosts(limit: 10, offset: 0) {
    metadata {
      pagination {
        total
        limit
        offset
        hasNextPage
        hasPreviousPage
      }
    }
    items {
      _id
      title
      body
    }
  }
}

Esto devuelve hasta 10 elementos en items, más los metadatos de paginación en metadata.pagination. Solicita los campos de la entrada en items; los metadatos de la lista son independientes de los campos de sistema de la entrada, como _id.

Consultar una sola entrada

Para solicitar una sola entrada, consulta el campo singular del modelo e indica el ID de la entrada:

query {
  blogPost(id: "entry-id-here") {
    _id
    title
    body
  }
}

Esto es útil cuando ya sabes qué entrada necesitas recuperar.

Consultar traducciones de la interfaz

Usa el campo uiTranslations cuando tu sitio web o aplicación necesite textos reutilizables de la interfaz administrados en el Studio.

El campo devuelve una lista de pares clave-valor de una configuración regional:

query {
  uiTranslations {
    key
    value
  }
}

De forma predeterminada, esto devuelve los valores de la configuración regional predeterminada del proyecto.

Cuando tu esquema expone enumeraciones de configuración regional, también puedes pasar el argumento opcional locale para solicitar otra configuración regional.

Esto es útil para textos de la interfaz, como etiquetas de navegación, botones, avisos y mensajes compartidos.

Para más detalles sobre cómo administrar estos valores en el Studio, consulta Traducciones de la interfaz.

Mutaciones (claves de lectura y escritura)

Las mutaciones de GraphQL requieren una clave de API GraphQL - Lectura y escritura (prefijo gqlw_). Las claves de solo lectura pueden consultar contenido, pero no pueden ejecutar mutaciones.

Las mutaciones se generan a partir de tus modelos de contenido. Para un modelo con ID de API BlogPost, las operaciones disponibles incluyen:

• createBlogPost — crea una entrada
• updateBlogPost — actualiza campos, estado, fechas de programación o asignaciones de taxonomía
• deleteBlogPost — elimina una entrada de forma lógica

También hay mutaciones globales para recursos, administración del esquema y traducciones de entradas:

• createAsset / deleteAsset
• createContentModel / updateContentModel / deleteContentModel
• createComponent / updateComponent / deleteComponent
• linkEntryTranslation / disconnectEntryTranslation

Las mutaciones de creación de cada modelo aceptan el argumento opcional linkToEntryId para crear una variante vinculada de configuración regional en un solo paso.

Ejemplo: crear una entrada

mutation {
  createBlogPost(
    locale: "en"
    status: DRAFT
    input: {
      title: "Hello world"
      body: "First post"
    }
  ) {
    _id
    _status
    title
  }
}

Ejemplo: publicar una entrada

mutation {
  updateBlogPost(
    id: "entry-id-here"
    status: PUBLISHED
    input: {
      title: "Hello world"
    }
  ) {
    _id
    _status
  }
}

Taxonomías en las entradas

Cuando una taxonomía se aplica a un modelo de contenido, cada tipo Entry_* expone un campo de lista cuyo nombre sale del ID de API plural de la taxonomía (camelCase), por ejemplo tags cuando el ID de API plural es Tags. El campo devuelve [Taxonomy_{apiId}!]! y queda vacío cuando no hay nada asignado.

Filtra las colecciones de entradas en las consultas plurales con where, usando el ID de API singular de la taxonomía (por ejemplo where: { tag: { key: name, value: ["News"] } } cuando el ID de API singular es Tag).

Asigna o reemplaza términos al crear o actualizar con el argumento opcional taxonomies ({Model}TaxonomiesInput), por ejemplo:

mutation {
  updateBlogPost(
    id: "entry-id-here"
    taxonomies: {
      tags: ["term-entry-id-1", "term-entry-id-2"]
    }
  ) {
    _id
    tags {
      _id
    }
  }
}

Ejemplo: subir un recurso

Las cargas de recursos usan el contenido del archivo codificado en base64:

mutation {
  createAsset(input: {
    filename: "photo.jpg"
    mimeType: "image/jpeg"
    contentBase64: "<base64-encoded-bytes>"
  }) {
    id
    url
  }
}

Cuando consultas recursos en las entradas, url y thumbnailUrl apuntan a la CDN. Consulta CDN de imágenes para los parámetros de cambio de tamaño, recorte y formato al vuelo.

Encabezados obligatorios

Envía Authorization: Bearer <gqlw_...> y X-Environment: <environment-api-id> con cada solicitud de mutación.

Cómo se nombran los campos y los tipos

Los nombres de tipos y de campos de GraphQL se basan en los ID de API configurados en el Studio.

Eso significa que:

• los ID de API de los modelos determinan los tipos que se pueden consultar
• los ID de API de los campos determinan los campos que puedes solicitar

Si cambias los ID de API en el Studio, es posible que debas actualizar tus consultas para que coincidan.

Buenas prácticas

Al trabajar con la API GraphQL, suele ser buena idea:

• usar limit y offset en las consultas plurales y leer metadata.pagination para los totales y las marcas de página siguiente y anterior
• solicitar solo los campos que realmente necesitas
• revisar con cuidado los ID de API de los modelos y de los campos
• tener en cuenta los argumentos de configuración regional en los proyectos localizados, cuando estén disponibles

Estas prácticas ayudan a que las consultas sean predecibles y eficientes.

Campos de metadatos de la entrada

Los tipos de entrada de contenido y de taxonomía incluyen metadatos con prefijo de guion bajo junto a los campos de tu modelo. Ejemplos habituales:

• _id: el identificador de la entrada
• _status: estado de entrega (por ejemplo, borrador, publicado o programado)
• _locale: la configuración regional de esta entrada
• _localizations: todas las entradas vinculadas como variantes de configuración regional del mismo contenido lógico (el mismo modelo de contenido, distintas configuraciones regionales)
• _workflowStage: cuando hay un flujo de trabajo editorial configurado para el modelo, la etapa del flujo de trabajo actual de la entrada (apiId y name). Esto es independiente de _status: el flujo de trabajo describe el avance editorial (p. ej., revisión, aprobación), mientras que _status describe lo que se entrega a través de la API.

Usa el explorador de esquema para ver el conjunto completo de campos de metadatos de tu proyecto.

Entradas localizadas (grupos de traducción)

Cuando tu proyecto tiene varias configuraciones regionales, las entradas relacionadas se pueden vincular para que representen el mismo contenido en distintos idiomas. La API no expone un tipo separado de «grupo de traducción»; trabajas con entradas y usas _localizations para leer las variantes vinculadas.

Consultar configuraciones regionales vinculadas

query {
  blogPost(id: "en-entry-id") {
    _id
    _localizations {
      _id
      _locale {
        id
      }
    }
  }
}

Crear una variante de configuración regional

Usa linkToEntryId en create{Model} para crear una entrada en otra configuración regional y vincularla a una entrada existente:

mutation {
  createBlogPost(
    locale: "fr"
    linkToEntryId: "en-entry-id"
    input: {
      title: "Bonjour"
    }
  ) {
    _id
    _localizations {
      _id
    }
  }
}

Vincular dos entradas existentes

Usa las mutaciones globales cuando ambas entradas ya existen:

• linkEntryTranslation(entryId, peerEntryId) — mueve entryId al mismo grupo que peerEntryId
• disconnectEntryTranslation(entryId) — quita entryId de su grupo (los demás miembros siguen vinculados)

Ambas devuelven EntryTranslationMutationResult (una unión de tus tipos de entrada). Usa un fragmento en línea para el modelo que esperas:

mutation {
  linkEntryTranslation(
    entryId: "fr-entry-id"
    peerEntryId: "en-entry-id"
  ) {
    ... on Entry_BlogPost {
      _id
      _localizations {
        _id
        _locale {
          id
        }
      }
    }
  }
}

Reemplaza Entry_BlogPost por el nombre del tipo de GraphQL de tu modelo (se muestra en el Explorador GraphQL).

Errores comunes

Situación	Código de error
Las entradas usan modelos de contenido distintos	BAD_REQUEST
Ambas entradas están en la misma configuración regional	CONFLICT
El grupo ya tiene una entrada para esa configuración regional	CONFLICT
No se encontró la entrada	NOT_FOUND

Vincular y desvincular requieren el permiso Actualizar entradas (o Actualizar entradas propias para las entradas que creaste). Si otro usuario está editando una entrada en el Studio, las mutaciones pueden devolver ENTRY_EDIT_LOCK_CONFLICT.

¿No sabes qué consultar?

Abre el Explorador GraphQL en el Studio (Herramientas → Explorador GraphQL) para inspeccionar el esquema, probar consultas y confirmar los nombres de los campos antes de agregarlos a tu aplicación.

Próximos pasos

• Claves de API
• Servidor MCP — conecta clientes de IA al mismo contenido con una clave MCP del proyecto