---
title: "Start a session"
method: POST
path: "/api/v1/start"
tags: ["Start / Stop"]
---

# Start a session

`POST /api/v1/start`

## Request

- Base URL: `https://api.neosapien.xyz` (the document declares no server; this is the origin it was published from)
- URL: `https://api.neosapien.xyz/api/v1/start`
- Auth: HTTP bearer

Start a recording session for a user in your organization.

The user is identified by `user_id`, interpreted according to `id_type`
(`phone`, `email`, or `neosapien_uid`). The user must belong to your
organization; otherwise the request fails with `404 user_not_found` and
nothing is recorded.

A start for a user who already has an open session with a different
`context_id` closes that session first. If no stop arrives, the session
ends automatically after the organization's auto stop timeout (set by an
admin), or after the organization's maximum session length when no
timeout is set.

`queued: false` means the event was accepted but could not be queued for
session processing.

## Request body

- StartStopRequest: Request body for `POST /start` and `POST /stop`.
  - `user_id` string, required: Identifier of the user in your organization. Interpreted according to `id_type`.
  - `id_type` 'phone' | 'email' | 'neosapien_uid', required: How `user_id` identifies the NeoSapien user.
  - `timestamp` string, date-time, required: When the session started or stopped. ISO 8601 with a timezone offset, e.g. '2026-10-05T09:30:00Z' or '2026-10-05T15:00:00+05:30'.
  - `context_id` string, nullable: Your identifier for where or what the session is about (a store, site, customer, job...). A start with a different `context_id` closes the user's open session.
  - `latitude` string, nullable: Latitude as a decimal string, e.g. '12.9716'. -90 to 90.
  - `longitude` string, nullable: Longitude as a decimal string, e.g. '77.5946'. -180 to 180.
  - `metadata` object, nullable: Flat key/value pairs stored with the event. At most 20 keys; keys 1-64 characters without null bytes; values are strings (up to 256 characters), finite numbers (integers within 64 bits), or booleans; at most 4096 bytes as compact JSON.

## Response `200`

Successful Response

- StartStopResponse: Response for `POST /start` and `POST /stop`.
  - `success` boolean, required: The request was accepted.
  - `neo_user_id` string, required: The resolved NeoSapien user ID.
  - `queued` boolean, required: The event was queued for session processing. `false` means it was accepted but could not be queued.
  - `event_id` string, nullable: ID of the stored event record, or null if it was not stored.

## Other responses

- `404`: No user in your organization matches `user_id`.
- `422`: The request body failed validation.
- `503`: Users could not be looked up. Retry later.

## Changes

- **2026-10-07** `c4a9f2c4a121`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/neosapien/apis/neocore/changes/api/v1/start/post.md)

---

[API](https://skmtc.dev/neosapien/apis/neocore.md) - [All operations](https://skmtc.dev/neosapien/apis/neocore/llms.txt) - [OpenAPI document](https://skmtc.dev/neosapien/apis/neocore/revisions/a42bfdafa6fe?raw)