TypeScript SDK

The Contismo TypeScript SDK is the official TypeScript client for the Contismo GraphQL Content API. Use it to query content, run mutations, introspect your schema, and generate TypeScript types for your project.

The package is published on npm as @contismo/sdk.

Install

Install the SDK in your application:

pnpm add @contismo/sdk

The SDK requires Node.js 20 or newer.

Authentication

The SDK authenticates with a Contismo GraphQL API key and sends Authorization and the X-Environment header automatically.

API keys are created in the Studio under Settings → API Keys.

Key prefix	Access
gql_	Queries and introspection
gqlw_	Queries, mutations, and introspection

Use a gql_ key for read-only delivery clients. Use a gqlw_ key only where your application needs to create, update, or delete content.

Configuration

Most projects should add a contismo.config.ts file at the project root:

import { defineConfig } from "@contismo/sdk/config";

export default defineConfig({
  client: {
    apiKey: "gql_...",
    endpoint: "https://graphql.contismo.com",
    environment: "production",
  },
});

The required client options are:

Option	Description
apiKey	GraphQL API key from the Studio
endpoint	GraphQL endpoint, usually https://graphql.contismo.com
environment	Environment API ID, sent as X-Environment

Config file discovery

new ContismoClient() looks for contismo.config.ts, contismo.config.mts, contismo.config.js, contismo.config.mjs, contismo.config.cjs, or contismo.config.json from the current working directory.

Quick Start

With contismo.config.ts in place, create a client without arguments:

import { ContismoClient } from "@contismo/sdk";

const client = new ContismoClient();

const posts = await client.fetch("BlogPost", {
  select: {
    _id: true,
    title: true,
  },
  limit: 10,
});

The first argument to fetch is the content model API ID from the Studio.

Explicit Client Setup

If your app does not use a config file, pass credentials directly:

import { ContismoClient } from "@contismo/sdk";

const client = new ContismoClient({
  apiKey: "gql_...",
  endpoint: "https://graphql.contismo.com",
  environment: "production",
});

If your config file lives somewhere else, pass its path:

const client = new ContismoClient({
  config: "./config/contismo.config.ts",
});

Generate TypeScript Types

The SDK includes a contismo CLI that can pull your live GraphQL schema and generate TypeScript types.

1. Add contismo.config.ts to your project.
2. Add optional codegen settings if you want to change the output paths.
3. Run pnpm contismo generate.

import { defineConfig } from "@contismo/sdk/config";

export default defineConfig({
  client: {
    apiKey: "gql_...",
    endpoint: "https://graphql.contismo.com",
    environment: "production",
  },
  codegen: {
    outputDir: "./src/generated",
    outputFile: "contismo.ts",
    schemaDir: "./contismo",
  },
});

pnpm contismo generate

By default, generation writes:

• contismo/schema.json
• src/generated/contismo.ts
• contismo-models.ts

After generating types, use them with fetch and fetchOne:

import { ContismoClient } from "@contismo/sdk";
import type { Entry_BlogPost } from "./generated/contismo";

const client = new ContismoClient();

const posts = await client.fetch<Entry_BlogPost>("BlogPost", {
  select: {
    _id: true,
    title: true,
  },
  limit: 10,
});

Introspection

Use introspect to read the GraphQL schema programmatically. It uses the same credentials as content queries: a GraphQL API key (gql_ or gqlw_) and environment. If the key or environment is wrong, the API returns an authentication error instead of a generic introspection failure.

const schema = await client.introspect();

The SDK also exports writeIntrospectionResult if you want to write the result to disk in a custom workflow.

Query Content

Use fetch to query a list of entries with a Prisma-style select object:

const posts = await client.fetch("BlogPost", {
  select: {
    _id: true,
    title: true,
    author: {
      name: true,
    },
  },
  limit: 10,
});

Use fetchOne when you know the entry ID:

const post = await client.fetchOne("BlogPost", {
  id: "entry-id-here",
  select: {
    _id: true,
    title: true,
  },
});

Nested objects in select become nested GraphQL selections. Use true for scalar fields.

Assets & CDN

Asset fields on entries return CDN URLs. Select url and thumbnailUrl, then use buildCdnUrl to append image transforms:

import { ContismoClient, buildCdnUrl } from "@contismo/sdk";

const client = new ContismoClient();

const posts = await client.fetch("BlogPost", {
  select: {
    _id: true,
    title: true,
    cover: {
      url: true,
      thumbnailUrl: true,
    },
  },
  limit: 10,
});

const cover = posts[0]?.cover;
const previewUrl = cover?.thumbnailUrl ?? cover?.url;
const heroUrl = cover?.url
  ? buildCdnUrl(cover.url, {
      w: 1200,
      fmt: "webp",
      q: 80,
    })
  : null;

CDN delivery is public — GET requests do not need an API key. Prefer thumbnailUrl for list and card previews when it is present. Use the full url with transforms for the main image.

For the full transform parameter reference, see the Image CDN guide.

Raw GraphQL

Use query when you want to provide the GraphQL document yourself:

const data = await client.query(
  `
  query BlogPost($id: ID!) {
    blogPost(id: $id) {
      _id
      title
    }
  }
`,
  { id: "entry-id-here" },
);

This is useful when you want full control over the operation or when copying a query from the GraphQL Explorer.

Mutations

Mutations require a read/write API key with the gqlw_ prefix. The SDK blocks client.mutate() calls before making a network request when the client is configured with a read-only gql_ key. Content entry mutations use {ModelApiId}Input (for example BlogPostInput) for both create and update—not {ModelApiId}CreateInput.

const client = new ContismoClient({
  apiKey: "gqlw_...",
  endpoint: "https://graphql.contismo.com",
  environment: "production",
});

await client.mutate(
  `
  mutation CreatePost($input: BlogPostInput!) {
    createBlogPost(input: $input) {
      _id
      _status
      title
    }
  }
`,
  {
    input: {
      title: "Hello world",
    },
  },
);

For mutation shapes and generated operation names, see the GraphQL API reference.

Error Handling

Missing entries do not throw. Singular reads such as blogPost(id: …) and client.fetchOne() return null when no entry matches (wrong id, locale, or status filters). Check the result instead of using try/catch:

const client = new ContismoClient();

const post = await client.fetchOne("BlogPost", {
  id: entryId,
  select: { _id: true, title: true },
});

if (post == null) {
  // Entry does not exist or does not match filters
}

GraphQL, HTTP, and SDK failures throw. Configuration errors, validation errors, auth failures, rate limits, and other API errors reject the promise as ContismoError (often ContismoGraphQLError). Use isContismoError to handle them:

import {
  ContismoClient,
  ContismoGraphQLError,
  isContismoError,
} from "@contismo/sdk";

const client = new ContismoClient();

try {
  await client.query(`query { blogPostCollection { items { _id } } }`);
} catch (error) {
  if (isContismoError(error) && error instanceof ContismoGraphQLError) {
    console.error(error.code, error.message);
  }
}

This catches request failures from the API—not a null singular field when an id is missing.

Related Docs

• SDKs
• Image CDN
• Managing Assets
• GraphQL API
• GraphQL Explorer
• API Keys