> ## 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. # Start a new session/turn > Starts a new turn in a session. If the session doesn't exist, it's created automatically. To continue an existing session, pass the same `session_id` from a previous turn. To start a fresh session, generate a new UUID for `session_id`. After calling this endpoint, connect to the WebSocket at `/ws/sessions/{sessionId}` to receive real-time execution updates. ## OpenAPI ````yaml openapi.yaml post /sessions/new 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/new: post: tags: - Sessions summary: Start a new session/turn description: > Starts a new turn in a session. If the session doesn't exist, it's created automatically. To continue an existing session, pass the same `session_id` from a previous turn. To start a fresh session, generate a new UUID for `session_id`. After calling this endpoint, connect to the WebSocket at `/ws/sessions/{sessionId}` to receive real-time execution updates. operationId: createTurn requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSessionRequest' responses: '200': description: Turn created successfully content: application/json: schema: $ref: '#/components/schemas/CreateSessionResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded headers: X-Rate-Limit-Max-Concurrent: description: Maximum concurrent turns allowed schema: type: integer X-Rate-Limit-Current-Concurrent: description: Current concurrent turns schema: type: integer X-Rate-Limit-Retry-After: description: Seconds until retry schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateSessionRequest: type: object required: - session_id - task - mode properties: session_id: type: string format: uuid description: >- Session ID. Use the same ID to continue an existing session, or generate a new UUID for a fresh session. task: type: string description: Natural language description of what you want the agent to do mode: type: string enum: - auto - plan - deepsearch - slides - code description: | Execution mode: - `auto`: General-purpose mode for any task - `plan`: Creates a detailed plan before execution - `deepsearch`: Optimized for web research and data analysis - `slides`: Generates presentation slides - `code`: Optimized for coding tasks files: type: array items: $ref: '#/components/schemas/FileReference' description: Files from the upload endpoint ace_version: type: string enum: - fast - think description: SDK version (optional) base_prompt: type: string description: Base prompt or system instructions (optional) references: type: array items: type: object description: Reference objects for additional context (optional) history: type: array items: type: object description: Conversation history for continuation (optional) continuation: type: string description: Continuation data as JSON string (optional) CreateSessionResponse: type: object properties: session_id: type: string description: >- Session ID (same as the `session_id` you provided). Use for WebSocket connection. user_message_id: type: string description: ID of the user's message agent_message_id: type: string description: >- ID of the agent's response message. Use as `message_id` for WebSocket connection. Error: type: object properties: error: type: string message: type: string details: type: object FileReference: type: object properties: key: type: string description: Storage key from upload name: type: string type: type: string description: MIME type size: type: integer securitySchemes: bearerAuth: type: http scheme: bearer description: API key from Raccoon AI ````