Graphdocs

Getting started

Quick start

From a new API key to your first entries in a few minutes.

This walks you from an empty project to reading published entries. You need a Graph workspace with at least one content type and a published entry in it.

1. Create an API key

In the dashboard, open Settings → API keys (app.graphcms.io/settings/api-keys) and choose Create API key.

  1. Give it a name you will recognise later, such as Website (production).
  2. Pick its permissions. A site that only displays content needs just View entries (content.view).
  3. Copy the key. It starts with graph_ and is shown once: Graph stores only a hash of it, so if you lose it, create a new one.

You need the Manage API keys permission on your role to do this. The full list of permissions is in Authentication & API keys.

2. Store it as a secret

Keep the key out of your source code. An environment variable is the usual place:

.env.local
GRAPH_API_KEY=graph_YOUR_API_KEY

A key reads (and, with the right permissions, changes) your workspace's content. Call the API from your server, a build step or a serverless function, not from code that ships to the browser.

3. Make your first request

List your content types to check the key works:

curl https://api.graphcms.io/v1/content-types \
  -H "Authorization: Bearer $GRAPH_API_KEY"

A working key returns 200 with your types and their fields:

{
  "success": true,
  "data": [
    {
      "id": "p8d2k4m9x0s1",
      "name": "Blog posts",
      "slug": "blog-posts",
      "description": "Articles for the company blog",
      "icon": null,
      "isPublished": true,
      "fields": [
        { "name": "Excerpt", "slug": "excerpt", "fieldType": "textarea", "isRequired": true },
        { "name": "Body", "slug": "body", "fieldType": "html", "isRequired": true }
      ],
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-09-01T10:00:00.000Z"
    }
  ]
}

(Field objects carry a few more properties than shown here; see Content types.) A 401 means the key is missing or wrong; a 403 names the permission the key lacks.

4. Fetch entries

Use the content type's slug to list its published entries:

curl "https://api.graphcms.io/v1/content/blog-posts?limit=5" \
  -H "Authorization: Bearer $GRAPH_API_KEY"

The same from JavaScript, for example in a server component or an API route:

lib/graphcms.js
1const API_URL = 'https://api.graphcms.io/v1';
2
3export async function getPosts() {
4  const response = await fetch(`${API_URL}/content/blog-posts?limit=5`, {
5    headers: { Authorization: `Bearer ${process.env.GRAPH_API_KEY}` },
6  });
7
8  if (!response.ok) {
9    const { error } = await response.json();
10    throw new Error(`Graph: ${response.status} ${error}`);
11  }
12
13  const { data, pagination } = await response.json();
14  return { posts: data, total: pagination.total };
15}

Each entry's field values are in post.fields, keyed by field slug: post.fields.excerpt, post.fields.body.

5. Or use the SDK

npm install @graphcms/sdk
1import { GraphCMS } from '@graphcms/sdk';
2
3const graph = new GraphCMS({ apiKey: process.env.GRAPH_API_KEY });
4
5const { data: posts } = await graph.content.entries('blog-posts', { limit: 5 });
6const post = await graph.content.entry('blog-posts', 'hello-world');

See JavaScript SDK for everything it does.

Next steps