Start an assessment in five minutes

Use the server SDK in your authenticated backend, hand a short-lived token to the browser, and render the published participant journey.

This path assumes an owner or admin has already published a version bundle and activated a program in the Synapse dashboard. Environment keys deliberately cannot publish or activate scoring science.

Install the server SDK

The TypeScript package currently ships through the project’s restricted GitHub Packages registry.

.npmrc

@apart-ai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

# Node.js 20 or newer
npm install @apart-ai/synapse

Configure server-only settings

Store these in your backend’s secret manager. Never expose the environment key through public build variables, static HTML, browser JavaScript, or mobile application code.

SYNAPSE_API_URL=https://api.your-synapse-deployment.example
SYNAPSE_ENVIRONMENT_KEY=syn_test_...
SYNAPSE_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
SYNAPSE_APP_ID=00000000-0000-0000-0000-000000000000
SYNAPSE_ENVIRONMENT_ID=00000000-0000-0000-0000-000000000000
SYNAPSE_PROGRAM_ID=00000000-0000-0000-0000-000000000000

Create an authenticated server handler

Resolve your own signed-in user on the server, persist an opaque request ID for retries, then sync the subject, enroll them, and mint a one-hour participant token.

start-assessment.ts

import { SynapseClient } from "@apart-ai/synapse";

const client = new SynapseClient({
  baseUrl: process.env.SYNAPSE_API_URL!,
  apiKey: process.env.SYNAPSE_ENVIRONMENT_KEY!,
});

export async function startAssessment(request: Request) {
  const hostUser = await requireAuthenticatedUser(request);
  const requestId = await getOrCreatePersistedRequestId(hostUser.id);
  const scope = [
    process.env.SYNAPSE_ORGANIZATION_ID!,
    process.env.SYNAPSE_APP_ID!,
    process.env.SYNAPSE_ENVIRONMENT_ID!,
  ] as const;

  const { subject } = await client.subjects.upsert(
    ...scope,
    { externalId: hostUser.id, profile: { locale: "en" } },
    { idempotencyKey: `${requestId}:subject` },
  );

  await client.programs.enroll(
    ...scope,
    { subjectId: subject.id, programId: process.env.SYNAPSE_PROGRAM_ID! },
    { idempotencyKey: `${requestId}:enrollment` },
  );

  const session = await client.participantSessions.create(
    ...scope,
    {
      programId: process.env.SYNAPSE_PROGRAM_ID!,
      subjectId: subject.id,
      expiresInSeconds: 3600,
    },
    { idempotencyKey: `${requestId}:session` },
  );

  return Response.json({
    hostedUrl: session.hosted_url,
    participantToken: session.participant_token,
    expiresAt: session.expires_at,
  });
}

Render with the participant SDK

The browser gets only the returned spt_ token. The SDK acknowledges the exact server-pinned consent notice before it sends answers.

participant.ts

import {
  createParticipantClient,
  createParticipantSessionController,
  MemoryParticipantQueueStorage,
} from "@apart-ai/synapse/participant";
import { mountEmbeddedParticipant } from "@apart-ai/synapse/participant/embedded";

const client = createParticipantClient({
  baseUrl: SYNAPSE_API_URL,
  participantToken,
});
const controller = createParticipantSessionController({
  client,
  queueKey: `evaluation:${opaqueEvaluationRef}`,
  storage: new MemoryParticipantQueueStorage(),
  consent: {
    beforeStart: async (session) => showConsent(session.consent.notice_text),
  },
  onComplete: (report) => renderResult(report),
});

const mounted = mountEmbeddedParticipant(
  document.querySelector("#synapse")!,
  { controller },
);

// When the host view unmounts:
mounted.destroy();
controller.dispose();

Generate an opaque idempotency ID once, store it with the host workflow, and reuse it after process restarts or ambiguous timeouts. Do not derive the Idempotency-Key header from an email or external ID. Reusing a key with a different body returns 409.

Continue with the complete subject-to-result flow, the participant controller, or the direct HTTP API.

Start here

SDKs

Direct API

API endpoints

Guides

Quickstart

Start an assessment in five minutes

​Start an assessment in five minutes

Start an assessment in five minutes