Getting Started

To call the Shapecaster API you need a client and the administrator token it carries. There is no signup page and no console — clients are provisioned by hand, so getting one means asking for one. You will be handed a single token that looks like this:

adtk_c1f4e2a7-9b3d-4e6a-8f21-0a5c7d9e1b34

That is the whole credential. There is no second key and no separate secret — one token, sent as a Bearer token on every request, which Authenticating covers.

Save it when you receive it. The token is shown once at provisioning and never again, because only a hash of it is stored — so a token that gets lost cannot be looked up or resent, and the only way back is a fresh client with a new token.

Your first API requests

Before you can do much else you'll need to have a frame to orient your shapecasts. A frame names four values and, for each one, the question a person answers and a word at each end of the scale they answer it on. To create a frame, send a new frame request:

curl

curl -i "https://api.cxipgroup.com/frames" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer adtk_c1f4e2a7-9b3d-4e6a-8f21-0a5c7d9e1b34" \
  -d '{
    "name": "Deliberation",
    "val1": "Dialectic",
    "val2": "Wellness",
    "val3": "Reasoning",
    "val4": "Desirability",
    "val1_question": "How well does this hold up under argument?",
    "val1_min_label": "Falls apart",
    "val1_max_label": "Holds firm",
    "val2_question": "How much does this affect your wellbeing?",
    "val2_min_label": "No impact",
    "val2_max_label": "Strong impact",
    "val3_question": "How much have you thought about this?",
    "val3_min_label": "Quick reaction",
    "val3_max_label": "Well reasoned",
    "val4_question": "How much do you want this?",
    "val4_min_label": "Not at all",
    "val4_max_label": "Very much"
  }'

JavaScript

const response = await fetch("https://api.cxipgroup.com/frames", {
  method: "POST",
  body: JSON.stringify({
    name: "Deliberation",
    val1: "Dialectic",
    val2: "Wellness",
    val3: "Reasoning",
    val4: "Desirability",
    val1_question: "How well does this hold up under argument?",
    val1_min_label: "Falls apart",
    val1_max_label: "Holds firm",
    val2_question: "How much does this affect your wellbeing?",
    val2_min_label: "No impact",
    val2_max_label: "Strong impact",
    val3_question: "How much have you thought about this?",
    val3_min_label: "Quick reaction",
    val3_max_label: "Well reasoned",
    val4_question: "How much do you want this?",
    val4_min_label: "Not at all",
    val4_max_label: "Very much"
  }),
  headers: {
    "Content-type": "application/json; charset=UTF-8",
    "Authorization": "Bearer adtk_c1f4e2a7-9b3d-4e6a-8f21-0a5c7d9e1b34"
  },
});

You'll get a JSON response that includes the frame's identifier.

{
  "id": "b9cdcd91-8fe8-41dc-9b46-ae6eb5e3c751",
  "name": "Deliberation",
  "val1": "Dialectic",
  "val2": "Wellness",
  "val3": "Reasoning",
  "val4": "Desirability",
  "val1_question": "How well does this hold up under argument?",
  "val1_min_label": "Falls apart",
  "val1_max_label": "Holds firm",
  "val2_question": "How much does this affect your wellbeing?",
  "val2_min_label": "No impact",
  "val2_max_label": "Strong impact",
  "val3_question": "How much have you thought about this?",
  "val3_min_label": "Quick reaction",
  "val3_max_label": "Well reasoned",
  "val4_question": "How much do you want this?",
  "val4_min_label": "Not at all",
  "val4_max_label": "Very much"
}

Creating a frame and successfully receiving a response means you are ready to continue. Your First Table picks up here and walks the rest of the way — a user tag, a session for it, and a table on this frame with positions plotted against it.