Use these curl, JavaScript, and Python examples to integrate with the Deck Public API.

Examples

Use these examples as starting points for your own scripts and integrations.

Set base variables

Shell

export DECK_API_BASE="https://api.getdeck.io/api/v1"
export DECK_API_KEY="YOUR_KEY"

JavaScript helper

const baseUrl = "https://api.getdeck.io/api/v1";
const apiKey = process.env.DECK_API_KEY!;

async function deckFetch(path: string) {
  const response = await fetch(`${baseUrl}${path}`, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });

  const body = await response.json();

  if (!response.ok) {
    throw new Error(`${body?.error?.code ?? "UNKNOWN"}: ${body?.error?.message ?? "Request failed"}`);
  }

  return body;
}

Verify your key

curl --request GET \
  --url "$DECK_API_BASE/me" \
  --header "Authorization: Bearer $DECK_API_KEY"

List themes

curl --request GET \
  --url "$DECK_API_BASE/themes?limit=10" \
  --header "Authorization: Bearer $DECK_API_KEY"

Paginate through themes

async function listAllThemes() {
  let cursor: string | null = null;
  const allThemes = [];

  while (true) {
    const query = new URLSearchParams({ limit: "100" });
    if (cursor) query.set("cursor", cursor);

    const page = await deckFetch(`/themes?${query.toString()}`);
    allThemes.push(...page.data);

    if (!page.pagination.has_more || !page.pagination.next_cursor) {
      break;
    }

    cursor = page.pagination.next_cursor;
  }

  return allThemes;
}

Fetch negative insights for a theme

curl --request GET \
  --url "$DECK_API_BASE/insights?theme_id=THEME_ID&sentiment=NEGATIVE&limit=20" \
  --header "Authorization: Bearer $DECK_API_KEY"

Get insight detail

curl --request GET \
  --url "$DECK_API_BASE/insights/INSIGHT_ID" \
  --header "Authorization: Bearer $DECK_API_KEY"

List active initiatives

curl --request GET \
  --url "$DECK_API_BASE/initiatives?status=building&limit=10" \
  --header "Authorization: Bearer $DECK_API_KEY"

Get initiative sections

curl --request GET \
  --url "$DECK_API_BASE/initiatives/INITIATIVE_ID" \
  --header "Authorization: Bearer $DECK_API_KEY"

Search subthemes

curl --request GET \
  --url "$DECK_API_BASE/subthemes?q=onboarding&limit=10&offset=0" \
  --header "Authorization: Bearer $DECK_API_KEY"

Paginate subthemes

async function listAllSubthemes() {
  const pageSize = 50;
  let offset = 0;
  const allSubthemes = [];

  while (true) {
    const page = await deckFetch(`/subthemes?limit=${pageSize}&offset=${offset}`);
    allSubthemes.push(...page.data);

    if (!page.pagination.has_more) {
      break;
    }

    offset += page.pagination.limit;
  }

  return allSubthemes;
}

Get a full subtheme

curl --request GET \
  --url "$DECK_API_BASE/subthemes/PATTERN_ID" \
  --header "Authorization: Bearer $DECK_API_KEY"

Download the OpenAPI spec

curl --request GET \
  --url "$DECK_API_BASE/openapi"

Python example

import os
import requests

base_url = "https://api.getdeck.io/api/v1"
api_key = os.environ["DECK_API_KEY"]

response = requests.get(
    f"{base_url}/themes?limit=5",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30,
)
response.raise_for_status()

for theme in response.json()["data"]:
    print(theme["id"], theme["name"], theme["insight_count"])

Common error handling

All error responses use:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key."
  }
}

Useful client behavior:

401 errors: verify the key and header format
403 errors: verify org settings, role access, or subthemes entitlement
400 errors: fix invalid filters or cursors
500 and 503 errors: retry with backoff and surface the failure

Examples

On this page