Hello World (of Arboretum)

To start leveraging Arboretum as a developer you need to make sure that Arboretum is installed and configured on your Contentful space & environment (if in doubt, check Installation and Configuration).

Getting the Arboretum API key

Once Arboretum is ready in your Contentful environment, you can navigate to Arboretum settings in Contentful (Apps > Manage Apps > three dots next to the Arboretum app). You need to scroll to the bottom of the settings page to find your Arboretum API key and additional information about your installation (like your tenant ID).

Testing Arboretum API

With the API key and the tenant ID in your hands, you can test the API endpoint for converting Contentful's entry ID (of your page) to a full path.

curl -X 'GET' \
  'https://arboretumapp.com/tenants/[YOUR-TENANT-ID]/sitemap/node/by-id?id=[ENTRY_ID]&localeCode=en' \
  -H 'accept: application/json' \
  -H 'x-arboretum-api-key: [YOUR-API-KEY]'

Please remember that for pages, Arboretum uses the Compose: Page content type (make sure you provide the entry ID of this content type).

If you are lucky (and made no mistakes when copying the API keys and the tenant ID to your request), you will get a response similar to this:

  "id": "[ENTRY_ID]",
  "type": "page",
  "localeCode": "en",
  "slug": "hello-world-of-arboretum",
  "path": "/en/docs/hello-world-of-arboretum",
  "totalDirectChildrenCount": 0

Using JavaScript/TypeScript SDK (pre-release)

While you could use the Arboretum API directly in the programming language of your choice, for JavaScript/TypeScript we recommend using our JavaScript SDK. This will save you the burden of manually wrapping the API calls yourself.

Because `@arboretum-app/sdk` is still in a pre-release version, there might be incompatible changes even between minor releases. Use with care!

Add the Arboretum JS SDK to your project

The Arboretum SDK is a npm package. After adding an SDK package as a dependency in package.json, you can import it anywhere in your code:

import { ArboretumClientFactory } from '@arboretum-app/sdk';

Creating the Arboretum Client

// Arboretum client is completely stateless and created synchronously.
// You can safely create it only once per app and reuse.
export const arboretumClient = ArboretumClientFactory.create({
  apiHost: "...",
  tenantId: "YOUR_TENANT_ID",
  apiKey: "YOUR_API_KEY",
  contentMode: "published", // or "preview"

Using the Arboretum Client

const arboretumPage = arboretumClient.getPageByFullPathWithAlternativeUrls({
    fullPath: context.resolvedUrl,

arboretumPage is an ExtendedArboretumPage type which conforms to the interface:

type ExtendedArboretumPage = {
  page: ArboretumPage;
  locales: NonEmptyArray<string>;
  alternativePaths: Array<{ path: string; localeCode: string }>;

What's next?

You decide! ArboretumPage contains all the required information to query Contentful about your page content: UI components, layout type, SEO metadata, and everything else.

In specific, it contains:

  id: string;
  localeCode: string;
  path: string;

so you can send your GraphQL query for a specific page.

Want to stay in the loop?

Follow us on Twitter @arboretumapp