Skip to main content

Subjects

A subject is a person who will be or has been assessed. All assessments and profiles belong to a subject.

Create a subject​

POST /v1/nature/subjects

Consent must be captured at creation time. See Consent for requirements.

const subject = await client.nature.subjects.create({
  external_subject_id: 'user_42',   // optional: your own reference ID
  consent_artifact: {
    consent_text_version: 'v1',
    consented_at: new Date().toISOString(),
    ui_snapshot_hash: 'sha256:abc123...',
  },
  metadata: { department: 'engineering' }, // optional key-value pairs
});
curl -X POST https://api.xavigate.com/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"
    }
  }'

Supports Idempotency-Key — safe to retry on network failure.

List subjects​

GET /v1/nature/subjects

Returns subjects cursor-paginated. See Pagination.

for await (const subject of client.nature.subjects.list({ limit: 50 })) {
  console.log(subject.id);
}

Retrieve a subject​

GET /v1/nature/subjects/{subject_id}

const subject = await client.nature.subjects.get('sub_abc123');

Delete a subject​

DELETE /v1/nature/subjects/{subject_id}

Soft-deletes the subject and cascades deletion of all associated data (assessments, profiles) within 24 hours. This is the right-to-erasure endpoint.

await client.nature.subjects.delete('sub_abc123');
// Returns 204 No Content

Deletion is permanent and non-reversible.

Metadata​

The metadata field stores arbitrary string key-value pairs for your own reference (max 50 keys, 500 chars per value). Metadata is returned on all subject responses but is never used by the scoring engine.

const subject = await client.nature.subjects.create({
  ...,
  metadata: {
    cohort: '2026-q2',
    recruiter_id: 'rec_789',
  },
});