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

# Stop a session

`POST /api/v1/stop`

## 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/stop`
- Auth: HTTP bearer

Stop the user's open recording session.

Takes the same body as `POST /start`. The user must belong to your
organization; otherwise the request fails with `404 user_not_found` and
nothing is recorded.

`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/stop/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)