> ## Documentation Index > Fetch the complete documentation index at: https://docs.parley.so/llms.txt > Use this file to discover all available pages before exploring further. # Start a session > 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. ## OpenAPI ````yaml https://api.parley.so/openapi.json post /sessions openapi: 3.1.1 info: title: Parley API version: 1.0.0 description: >- Manage Parley's projects (matters or cases), accounts (client organizations), contacts (people), tasks, custom fields, notes, files, activity, automations, and skills. Records refer to each other as { type, id, name } references; writes take IDs. Errors are { error: { code, message, details } }, where code names what went wrong and each operation lists the codes it can return. In a query string, write a timestamp's offset as Z or %2B, because a raw + arrives as a space. The MCP server at /mcp offers the same data as a smaller set of tools. servers: - url: https://api.parley.so/v1 security: - bearerAuth: [] tags: - name: Projects description: >- A project is a matter or case: it groups the files, notes, activity, and tasks for one engagement, and links to the accounts and contacts it involves. - name: Accounts description: >- An account is a client organization. Contacts belong to it, and projects link to it. - name: Contacts description: >- A contact is a person, optionally belonging to one account and linked to projects. - name: Tasks description: >- A task is a to-do with a status, assignee, and due date, optionally about one project, account, or contact. - name: Fields description: >- Custom fields defined for projects, accounts, contacts, or tasks. Records carry their values in fields, keyed by field name. - name: Notes description: >- Markdown notes on a project, account, or contact. Updates take the version you last read, so concurrent edits fail with 409 VERSION_CONFLICT instead of overwriting. - name: Files description: >- Files and folders of a project, account, contact, or intake, or the organization's Library. Add a file by creating an upload, PUTting its bytes, and adding the upload to a location. - name: Activity description: >- What happened across the organization or on one record: changes, links, notes, files, USCIS case updates, and synced emails and meetings. Each item's kind says which details it carries. - name: Sessions description: >- Conversations with Parley's assistant, from the web app, Word, Outlook, automation runs, and the API. Start one with a message, follow up or steer it while it works, and read its replies. - name: Automations description: >- Instructions Parley's assistant carries out on a schedule, as the person who created them, with nobody present. - name: Skills description: >- Reusable playbooks for Parley's assistant: a SKILL.md plus optional bundled documents, addressed by slug. - name: Users description: The people in your organization, and the caller. paths: /sessions: post: tags: - Sessions summary: Start a session description: >- 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. operationId: createSession requestBody: required: true content: application/json: schema: type: object properties: message: type: string minLength: 1 maxLength: 100000 description: >- The first message to Parley's assistant, up to 100,000 characters. The assistant starts on it right away. projectId: type: string minLength: 1 description: >- 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. required: - message additionalProperties: false responses: '201': description: Created. content: application/json: schema: type: object properties: id: type: string minLength: 1 description: The session ID. title: anyOf: - type: string - type: 'null' description: >- The session's title, written by Parley after the first reply unless someone named it, or null until then. status: enum: - working - idle type: string description: >- 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: enum: - web - word - outlook - automation - api type: string description: >- 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: anyOf: - $ref: '#/components/schemas/ProjectRef' - type: 'null' description: >- The project the session works in, with that project's files, notes, and linked records as its context, or null for a session across the organization. automation: anyOf: - type: object properties: type: const: automation id: type: string description: Its ID. name: type: string description: The automation name. required: - type - id - name description: The automation's type, ID, and name. - type: 'null' description: The automation whose run started the session, or null. lastRun: anyOf: - type: object properties: status: enum: - running - completed - interrupted - failed type: string description: >- running: in progress. completed: the assistant finished. interrupted: someone stopped it. failed: it ended with an error. startedAt: type: string format: date-time description: When the assistant started. endedAt: anyOf: - type: string format: date-time - type: 'null' description: >- When the assistant stopped, or null while it is running. error: anyOf: - type: object properties: code: anyOf: - type: string - type: 'null' description: >- Machine-readable reason, such as CONTEXT_WINDOW_EXCEEDED, or null. message: type: string description: Human-readable description. required: - code - message - type: 'null' description: Why a failed run failed, or null. required: - status - startedAt - endedAt - error - type: 'null' description: >- The assistant's most recent pass over the session's messages, or null before it starts. url: type: string format: uri description: Where to open the session in Parley. createdAt: type: string format: date-time description: When the session was started. updatedAt: type: string format: date-time description: When the session last changed, such as by a new message. required: - id - title - status - origin - project - automation - lastRun - url - createdAt - updatedAt headers: Location: description: The URL of the created resource. schema: type: string '400': description: The request was invalid. VALIDATION_FAILED, INVALID_REFERENCE. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationFailedError' - $ref: '#/components/schemas/InvalidReferenceError' '401': description: Missing or invalid credentials. UNAUTHORIZED. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: You don't have permission. FORBIDDEN. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: >- Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS, USAGE_LIMIT_REACHED. content: application/json: schema: oneOf: - $ref: '#/components/schemas/TooManyRequestsError' - $ref: '#/components/schemas/UsageLimitReachedError' components: schemas: ProjectRef: type: object properties: type: const: project id: type: string description: Its ID. name: type: string description: The project name. required: - type - id - name description: The project's type, ID, and name. ValidationFailedError: type: object properties: error: type: object properties: code: type: string const: VALIDATION_FAILED message: type: string examples: - The request is invalid. details: type: object properties: issues: type: array items: type: object properties: path: type: string description: >- Where the problem is, as a dotted path into the input such as accountIds.add.0 or reminder.remindAt. Empty for the input as a whole. message: type: string description: What is wrong with the value. required: - path - message description: Each problem with the input. required: - issues required: - code - message - details required: - error InvalidReferenceError: type: object properties: error: type: object properties: code: type: string const: INVALID_REFERENCE message: type: string examples: - >- The request refers to a record or user that doesn't exist or that you can't use. details: type: object properties: field: type: string description: The input that holds the reference, such as accountIds. ids: type: array items: type: string description: The IDs that could not be used. required: - field - ids required: - code - message - details required: - error UnauthorizedError: type: object properties: error: type: object properties: code: type: string const: UNAUTHORIZED message: type: string examples: - Missing or invalid credentials. required: - code - message required: - error ForbiddenError: type: object properties: error: type: object properties: code: type: string const: FORBIDDEN message: type: string examples: - You don't have permission to do this. required: - code - message required: - error TooManyRequestsError: type: object properties: error: type: object properties: code: type: string const: TOO_MANY_REQUESTS message: type: string examples: - Too many requests. required: - code - message required: - error UsageLimitReachedError: type: object properties: error: type: object properties: code: type: string const: USAGE_LIMIT_REACHED message: type: string examples: - The organization has reached its usage limit. required: - code - message required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: A Parley API key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.