Skip to main content

Quickstart

Get a scored Multiple Natures profile in under 3 minutes.

What you'll do:

  1. Get your sandbox API key from the Xavigate team
  2. Create a subject (with consent artifact)
  3. Submit MNTEST item responses
  4. Retrieve the scored MN + MI profile
Closed beta — current state

Base URL: https://xavigate-api-v2.steven-c8f.workers.dev (the api.xavigate.com domain cuts over at general availability)

Keys: provisioned directly during the closed beta — email team@xavigate.com to request a test_sk_* key.

Scoring: the scoring engine connects in Build-Session 4. Until then, completed assessments return a profile with placeholder scores (all 0.0). The full API flow works end-to-end; real MN + MI scores land in the next build.

1. Get your sandbox key​

Email team@xavigate.com to request closed-beta access. You'll receive a test_sk_* key with nature:read and nature:write scopes.

Self-serve key management (dashboard) lands when the developer portal opens. For now, keys are provisioned directly.

Sandbox keys (test_*) are free and isolated from production data.

2. Create a subject​

A subject represents one person being assessed. Consent must be captured at creation time — the consent_artifact records that the person agreed to the assessment.

curl -X POST https://xavigate-api-v2.steven-c8f.workers.dev/v1/nature/subjects \
  -H "Authorization: Bearer test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_subject_id": "user_42",
    "consent_artifact": {
      "consent_text_version": "v1",
      "consented_at": "2026-04-21T10:30:00Z",
      "ui_snapshot_hash": "sha256:abc123"
    }
  }'
import Xavigate from '@xavigate/node';

const client = new Xavigate({ apiKey: 'test_sk_YOUR_KEY' });

const subject = await client.nature.subjects.create({
  external_subject_id: 'user_42',
  consent_artifact: {
    consent_text_version: 'v1',
    consented_at: new Date().toISOString(),
    ui_snapshot_hash: 'sha256:abc123',
  },
});

console.log(subject.id); // sub_abc123...
import xavigate

client = xavigate.Xavigate(api_key="test_sk_YOUR_KEY")

subject = client.nature.subjects.create(
    external_subject_id="user_42",
    consent_artifact={
        "consent_text_version": "v1",
        "consented_at": "2026-04-21T10:30:00Z",
        "ui_snapshot_hash": "sha256:abc123",
    },
)

print(subject.id)  # sub_abc123...

Response (201):

{
  "id": "sub_abc123def456",
  "object": "subject",
  "external_subject_id": "user_42",
  "livemode": false,
  "created_at": "2026-04-21T10:30:00Z"
}

Save the id — you'll use it in the next two steps.

3. Start and submit an assessment​

Start an MNTEST assessment, then submit the item responses (1–5 rating per item).

Start the assessment:

curl -X POST https://xavigate-api-v2.steven-c8f.workers.dev/v1/nature/subjects/sub_abc123def456/assessments \
  -H "Authorization: Bearer test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "en" }'
const assessment = await client.nature.assessments.start(subject.id, {
  language: 'en',
});
// assessment.id = asm_xyz789...
// assessment.responses_required = 76
assessment = client.nature.assessments.start(subject.id, language="en")
# assessment.id = "asm_xyz789..."
# assessment.responses_required = 76

Submit responses (you can submit incrementally or all at once):

curl -X PATCH https://xavigate-api-v2.steven-c8f.workers.dev/v1/nature/subjects/sub_abc123def456/assessments/asm_xyz789 \
  -H "Authorization: Bearer test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "responses": [
      { "item_id": "mn_001", "value": 4 },
      { "item_id": "mn_002", "value": 2 }
    ]
  }'
// Submit all 76 responses; scoring triggers automatically when the set is complete
await client.nature.assessments.submitResponses(subject.id, assessment.id, {
  responses: itemResponses, // your array of { item_id, value } objects
});
client.nature.assessments.submit_responses(
    subject.id,
    assessment.id,
    responses=item_responses,  # list of {"item_id": str, "value": int}
)

When all 76 responses are received, scoring runs automatically. The assessment status transitions: in_progress → scoring → completed. You'll receive a nature.assessment.completed webhook when done (or poll step 4).

Listen with webhooks

For production integrations, register a webhook endpoint in your dashboard and listen for nature.assessment.completed. Polling is fine for testing. See Webhooks.

4. Retrieve the scored profile​

curl https://xavigate-api-v2.steven-c8f.workers.dev/v1/nature/subjects/sub_abc123def456/profile \
  -H "Authorization: Bearer test_sk_YOUR_KEY"
const profile = await client.nature.profiles.get(subject.id);
console.log(profile.scores.natures);
profile = client.nature.profiles.get(subject.id)
print(profile.scores["natures"])

Response (200):

{
  "id": "prf_qrs456",
  "object": "profile",
  "subject_id": "sub_abc123def456",
  "scores": {
    "natures": {
      "protective": 0.72,
      "educative": 0.45,
      "creative": 0.88,
      "entrepreneurial": 0.78
    },
    "intelligences": {
      "interpersonal": 0.79,
      "logical": 0.81,
      "intrapersonal": 0.83
    }
  },
  "narratives": {
    "primary_natures": [
      { "nature": "creative", "description": "..." }
    ]
  },
  "language": "en",
  "livemode": false
}

That's your first profile. The scores object contains all 9 Natures and 10 Multiple Intelligences, each scored 0.0–1.0.

Next steps​