API GraphQL

Use a API GraphQL para solicitar conteúdo do Contismo fora do Studio, por exemplo em um site, um aplicativo ou outro sistema externo.

Endpoint

Cada ambiente do projeto tem o próprio endpoint GraphQL.

Para encontrar o endpoint correto:

1. Abra seu projeto no Studio.
2. Vá em Configurações e encontre o endpoint GraphQL do ambiente que você quer consultar.
3. Use essa URL ao configurar seu cliente ou integração.

Autenticação

Autentique as solicitações enviando sua chave de API no cabeçalho Authorization:

Authorization: Bearer <your-api-key>

Confira se a chave que você usa tem acesso ao projeto e ao ambiente que está consultando.

Consulta de exemplo

O exemplo a seguir solicita uma lista de entradas de um modelo BlogPost (campo plural blogPosts):

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

Isso retorna até 10 itens em items, mais os metadados de paginação em metadata.pagination. Solicite os campos da entrada em items; os metadados da lista são separados dos campos de sistema da entrada, como _id.

Consultar uma única entrada

Para solicitar uma única entrada, consulte o campo singular do modelo e informe o ID da entrada:

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

Isso é útil quando você já sabe qual entrada precisa recuperar.

Consultar traduções da interface

Use o campo uiTranslations quando seu site ou aplicativo precisar de textos reutilizáveis da interface gerenciados no Studio.

O campo retorna uma lista de pares chave-valor de uma localidade:

query {
  uiTranslations {
    key
    value
  }
}

Por padrão, isso retorna os valores da localidade padrão do projeto.

Quando o esquema expõe enumerações de localidade, você também pode passar o argumento opcional locale para solicitar outra localidade.

Isso é útil para textos da interface, como rótulos de navegação, botões, avisos e mensagens compartilhadas.

Para detalhes sobre como gerenciar esses valores no Studio, consulte Traduções da interface.

Mutações (chaves de leitura e gravação)

As mutações GraphQL exigem uma chave de API GraphQL - Leitura e gravação (prefixo gqlw_). Chaves somente leitura podem consultar conteúdo, mas não podem executar mutações.

As mutações são geradas a partir dos seus modelos de conteúdo. Para um modelo com ID de API BlogPost, as operações disponíveis incluem:

• createBlogPost — cria uma entrada
• updateBlogPost — atualiza campos, status, datas de agendamento ou atribuições de taxonomia
• deleteBlogPost — exclui uma entrada de forma lógica

Também há mutações globais para recursos, gerenciamento do esquema e traduções de entradas:

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

As mutações de criação de cada modelo aceitam o argumento opcional linkToEntryId para criar uma variante vinculada de localidade em uma única etapa.

Exemplo: criar uma entrada

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

Exemplo: publicar uma entrada

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

Taxonomias nas entradas

Quando uma taxonomia aplica-se a um modelo de conteúdo, cada tipo Entry_* expõe um campo de lista cujo nome vem do ID de API plural da taxonomia (camelCase), por exemplo tags quando o ID de API plural é Tags. O campo retorna [Taxonomy_{apiId}!]! e fica vazio quando nada está atribuído.

Filtre as coleções de entradas nas consultas plurais com where, usando o ID de API singular da taxonomia (por exemplo where: { tag: { key: name, value: ["News"] } } quando o ID de API singular é Tag).

Atribua ou substitua termos ao criar ou atualizar com o argumento opcional taxonomies ({Model}TaxonomiesInput), por exemplo:

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

Exemplo: enviar um recurso

Os envios de recursos usam o conteúdo do arquivo codificado em base64:

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

Quando você consulta recursos nas entradas, url e thumbnailUrl apontam para a CDN. Consulte CDN de imagens para os parâmetros de redimensionamento, recorte e formato na hora.

Cabeçalhos obrigatórios

Envie Authorization: Bearer <gqlw_...> e X-Environment: <environment-api-id> em toda solicitação de mutação.

Como campos e tipos são nomeados

Os nomes de tipos e de campos do GraphQL se baseiam nos IDs de API configurados no Studio.

Isso significa que:

• os IDs de API dos modelos determinam os tipos que podem ser consultados
• os IDs de API dos campos determinam os campos que você pode solicitar

Se você alterar os IDs de API no Studio, talvez precise atualizar suas consultas para que coincidam.

Boas práticas

Ao trabalhar com a API GraphQL, em geral é uma boa ideia:

• usar limit e offset nas consultas plurais e ler metadata.pagination para os totais e os indicadores de página seguinte e anterior
• solicitar só os campos de que você realmente precisa
• conferir com cuidado os IDs de API dos modelos e dos campos
• considerar os argumentos de localidade em projetos localizados, quando estiverem disponíveis

Essas práticas ajudam a manter as consultas previsíveis e eficientes.

Campos de metadados da entrada

Os tipos de entrada de conteúdo e de taxonomia incluem metadados com prefixo de sublinhado junto dos campos do seu modelo. Exemplos comuns:

• _id: o identificador da entrada
• _status: status de entrega (por exemplo, rascunho, publicado ou agendado)
• _locale: a localidade desta entrada
• _localizations: todas as entradas vinculadas como variantes de localidade do mesmo conteúdo lógico (o mesmo modelo de conteúdo, localidades diferentes)
• _workflowStage: quando um fluxo de trabalho editorial está configurado para o modelo, a etapa do fluxo de trabalho atual da entrada (apiId e name). Isso é separado de _status: o fluxo de trabalho descreve o andamento editorial (ex.: revisão, aprovação), enquanto _status descreve o que é entregue pela API.

Use o explorador de esquema para ver o conjunto completo de campos de metadados do seu projeto.

Entradas localizadas (grupos de tradução)

Quando o projeto tem várias localidades, entradas relacionadas podem ser vinculadas para representar o mesmo conteúdo em idiomas diferentes. A API não expõe um tipo separado de “grupo de tradução”; você trabalha com entradas e usa _localizations para ler as variantes vinculadas.

Consultar localidades vinculadas

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

Criar uma variante de localidade

Use linkToEntryId em create{Model} para criar uma entrada em outra localidade e vinculá-la a uma entrada existente:

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

Vincular duas entradas existentes

Use as mutações globais quando as duas entradas já existem:

• linkEntryTranslation(entryId, peerEntryId) — move entryId para o mesmo grupo de peerEntryId
• disconnectEntryTranslation(entryId) — remove entryId do grupo (os outros membros continuam vinculados)

As duas retornam EntryTranslationMutationResult (uma união dos seus tipos de entrada). Use um fragmento inline para o modelo esperado:

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

Substitua Entry_BlogPost pelo nome do tipo GraphQL do seu modelo (mostrado no Explorador GraphQL).

Erros comuns

Situação	Código de erro
As entradas usam modelos de conteúdo diferentes	BAD_REQUEST
As duas entradas estão na mesma localidade	CONFLICT
O grupo já tem uma entrada para essa localidade	CONFLICT
Entrada não encontrada	NOT_FOUND

Vincular e desvincular exigem a permissão Atualizar entradas (ou Atualizar as próprias entradas para as entradas que você criou). Se outro usuário estiver editando uma entrada no Studio, as mutações podem retornar ENTRY_EDIT_LOCK_CONFLICT.

Não sabe o que consultar?

Abra o Explorador GraphQL no Studio (Ferramentas → Explorador GraphQL) para inspecionar o esquema, testar consultas e confirmar os nomes dos campos antes de adicioná-los ao seu aplicativo.

Próximos passos

• Chaves de API
• Servidor MCP — conecte clientes de IA ao mesmo conteúdo com uma chave MCP do projeto