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

# Create New Session

> Create a new session for a specific agent and user.
Returns a unique session_id that can be used for subsequent chat interactions.
Optionally accepts metadata (name, description, tags) for the session.

Supports both authenticated users (via bearer token) and agent bots (via API key).
For agent bots, session_id and user_id can be provided in the request body.



## OpenAPI

````yaml /api-reference/openapi/EvoAI-Processor-Service/sessions.yaml post /api/v1/sessions/{agent_id}
openapi: 3.1.0
info:
  title: Evolution Foundation - AI Processor Service - Sessions
  description: AI processing, integrations and sessions
  version: 1.0.0
servers:
  - url: https://api.evoai.app
    description: Production server
  - url: http://localhost:3004
    description: Development server
    variables:
      port:
        default: '3004'
  - url: '{customUrl}'
    description: Custom server
    variables:
      customUrl:
        default: https://your-instance.com
        description: Enter your server URL
security: []
paths:
  /api/v1/sessions/{agent_id}:
    post:
      summary: Create New Session
      description: >-
        Create a new session for a specific agent and user.

        Returns a unique session_id that can be used for subsequent chat
        interactions.

        Optionally accepts metadata (name, description, tags) for the session.


        Supports both authenticated users (via bearer token) and agent bots (via
        API key).

        For agent bots, session_id and user_id can be provided in the request
        body.
      operationId: create_new_session_api_v1_sessions__agent_id__post
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Agent Id
        - name: x-api-key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/Body_create_new_session_api_v1_sessions__agent_id__post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse_SessionWithMetadata_'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: BAD_REQUEST
                  message: Invalid input data
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/sessions/{agent_id}
                  method: POST
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication token
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/sessions/{agent_id}
                  method: POST
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to perform this action
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/sessions/{agent_id}
                  method: POST
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Agent not found
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/sessions/{agent_id}
                  method: POST
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/sessions/{agent_id}
                  method: POST
      security:
        - ApiAccessToken: []
components:
  schemas:
    Body_create_new_session_api_v1_sessions__agent_id__post:
      properties:
        request_data:
          anyOf:
            - 3b9fcfda-6804-4f4d-857a-a5b8ef1d6913
            - type: 'null'
        metadata:
          anyOf:
            - 4121dc50-430e-46fa-9c8e-32cd42a18d1f
            - type: 'null'
      type: object
      title: Body_create_new_session_api_v1_sessions__agent_id__post
    SuccessResponse_SessionWithMetadata_:
      properties:
        success:
          type: boolean
          title: Success
          description: Success indicator
          default: true
        data:
          $ref: 578e98ae-71a6-4bf1-9246-e5a70860c638
          description: Response payload
        meta:
          $ref: 5bc4c43b-167e-462f-8934-13ae1099d48f
          description: Metadata
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Optional success message
      type: object
      required:
        - data
        - meta
      title: SuccessResponse[SessionWithMetadata]
    ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Success indicator
          default: false
        error: 51da5519-eda1-49e7-a0a6-b699da9b410e
        meta:
          $ref: 644ffca8-f3ef-4e5b-9148-ce42bc96ec8e
          description: Metadata
      type: object
      required:
        - error
        - meta
      title: ErrorResponse
      description: |-
        Standard error response schema matching error_response() return format.

        This schema matches the structure returned by error_response() function,
        which always uses ErrorInfo for the error field.
    HTTPValidationError:
      properties:
        detail:
          items: 453ce868-0da7-4326-8d12-6c4ec4b84885
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    ApiAccessToken:
      type: apiKey
      in: header
      name: api_access_token
      description: API Access Token (UUID) for authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.