> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raccoonai.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# List sessions

> Retrieves a paginated list of sessions.



## OpenAPI

````yaml openapi.yaml get /sessions
openapi: 3.1.0
info:
  title: Raccoon AI API
  description: >
    The Raccoon AI API provides programmatic access to an autonomous AI agent
    platform.


    ## Core Concepts


    ### Sessions


    A **session** is a persistent workspace where the AI agent performs work.
    Sessions maintain

    state across multiple interactions, including conversation history,
    generated files, and context.


    Sessions are identified by a unique ID that you provide via the `session_id`
    parameter.


    ### Turns


    A **turn** is one cycle of: user request → agent execution → response. Each
    turn within a

    session builds on previous context. The agent can see files created in
    earlier turns,

    reference prior conversation, and continue work incrementally.


    To start a new turn in an existing session, simply pass the same
    `session_id` when calling

    the create endpoint. To start a fresh session, generate a new UUID.


    ### Modes


    Modes determine how the agent approaches work:

    - `auto` - General-purpose mode (default)

    - `code` - Software development

    - `deepsearch` - Web research and data analysis

    - `slides` - Presentation generation

    - `plan` - Creates a detailed plan before execution


    ## Authentication


    All requests require a Bearer token:


    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    **API Key Access:** The following endpoints are available with API key
    authentication:

    - `POST /sessions/new` - Start a new session/turn

    - `GET /sessions` - List sessions

    - `GET /sessions/{sessionId}` - Get session details

    - `PUT /sessions/{sessionId}/title` - Update session title

    - `DELETE /sessions/{sessionId}` - Delete session

    - `PUT /media/upload` - Upload files

    - `WS /ws/sessions/{sessionId}` - WebSocket streaming


    ## Execution Flow


    1. **Start a turn** - Call `POST /sessions/new` with your prompt, mode, and
    `session_id`

    2. **Connect to WebSocket** - Subscribe to `/ws/sessions/{sessionId}` for
    real-time updates

    3. **Receive events** - Stream content, tool executions, and progress as the
    agent works

    4. **Turn completes** - Receive final results and any generated files

    5. **Continue session** - Start another turn by calling `POST /sessions/new`
    with the same `session_id`
  version: 1.0.0
  contact:
    name: Raccoon AI Support
    email: team@raccoonai.tech
    url: https://raccoonai.tech
servers:
  - url: https://api.raccoonai.tech
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Turns
    description: Start and manage agent execution turns
  - name: Sessions
    description: Retrieve and manage session history
  - name: Media
    description: Upload files to include with turns
paths:
  /sessions:
    get:
      tags:
        - Sessions
      summary: List sessions
      description: Retrieves a paginated list of sessions.
      operationId: listSessions
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: query
          in: query
          description: Search filter
          schema:
            type: string
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - updatedAt
              - createdAt
              - title
            default: updatedAt
        - name: sortOrder
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Sessions retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSessionsResponse'
components:
  schemas:
    ListSessionsResponse:
      type: object
      properties:
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/Session'
          description: List of sessions
        meta:
          type: object
          properties:
            total_count:
              type: integer
            total_pages:
              type: integer
            current_page:
              type: integer
    Session:
      type: object
      description: A persistent workspace containing turns and files
      properties:
        id:
          type: string
          description: MongoDB ObjectID
        sessionId:
          type: string
          format: uuid
          description: Session ID
        title:
          type: string
          description: Session title (auto-generated or user-set)
        userId:
          type: string
        createdAt:
          type: integer
          description: Unix timestamp (ms)
        updatedAt:
          type: integer
          description: Unix timestamp (ms)
        deleted:
          type: boolean
        isPinned:
          type: boolean
        sandboxImage:
          type: string
          description: Docker image used for sandbox
        fileSnapshot:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FileInfo'
          description: Current state of files in the session
    FileInfo:
      type: object
      properties:
        key:
          type: string
        name:
          type: string
        size:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key from Raccoon AI

````