---
title: "Start a session"
method: POST
path: "/sessions"
tags: ["Sessions"]
---

# Start a session

`POST /sessions`

## Request

- Base URL: `https://api.parley.so/v1`
- URL: `https://api.parley.so/v1/sessions`
- Auth: HTTP bearer

Start a session with Parley's assistant by sending its first message. The assistant works in the background, as you, with the same tools and access it has in the web app, and the session shows up in your Parley chat history. Returns the session as soon as the message is queued, with status working; get the session until its status is idle, then read the reply with GET /sessions/{id}/messages. Returns 429 USAGE_LIMIT_REACHED when the organization has used its Parley AI allowance for the billing period.

## Request body

- object
  - `message` string, required: The first message to Parley's assistant, up to 100,000 characters. The assistant starts on it right away.
  - `projectId` string: A project to work in, with that project's files, notes, and linked records as context. Leave it out for a session across the organization.

## Response `201`

Created.

- object
  - `id` string, required: The session ID.
  - `title` string, nullable, required: The session's title, written by Parley after the first reply unless someone named it, or null until then.
  - `status` 'working' | 'idle', required: working: Parley's assistant is working, a message is waiting for it, or it is waiting on subagents it started in the background. idle: the assistant has stopped and is waiting for the next message.
  - `origin` 'web' | 'word' | 'outlook' | 'automation' | 'api', required: Where the session was started: web (Parley's web app, or an email to Parley's assistant), word or outlook (the add-in), automation (an automation run), or api (the REST API, MCP, or the CLI).
  - `project` ProjectRef, required: The project's type, ID, and name.
    - `type` 'project', required
    - `id` string, required: Its ID.
    - `name` string, required: The project name.
  - `automation` object, nullable, required: The automation's type, ID, and name.
    - `type` 'automation', required
    - `id` string, required: Its ID.
    - `name` string, required: The automation name.
  - `lastRun` object, nullable, required: The assistant's most recent pass over the session's messages, or null before it starts.
    - `status` 'running' | 'completed' | 'interrupted' | 'failed', required: running: in progress. completed: the assistant finished. interrupted: someone stopped it. failed: it ended with an error.
    - `startedAt` string, date-time, required: When the assistant started.
    - `endedAt` string, date-time, nullable, required: When the assistant stopped, or null while it is running.
    - `error` object, nullable, required: Why a failed run failed, or null.
      - `code` string, nullable, required: Machine-readable reason, such as CONTEXT_WINDOW_EXCEEDED, or null.
      - `message` string, required: Human-readable description.
  - `url` string, uri, required: Where to open the session in Parley.
  - `createdAt` string, date-time, required: When the session was started.
  - `updatedAt` string, date-time, required: When the session last changed, such as by a new message.

## Other responses

- `400`: The request was invalid. VALIDATION_FAILED, INVALID_REFERENCE.
- `401`: Missing or invalid credentials. UNAUTHORIZED.
- `403`: You don't have permission. FORBIDDEN.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS, USAGE_LIMIT_REACHED.

---

[API](https://skmtc.dev/parley/apis/parley-api.md) - [All operations](https://skmtc.dev/parley/apis/parley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parley/apis/parley-api/revisions/6b78aeee07bc?raw)