> ## Documentation Index > Fetch the complete documentation index at: https://quintus.tec.br/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a conversation > Create a new conversation with an agent and receive a session token. ## OpenAPI ````yaml /public/api/openapi.json post /v1/public/agents/conversations openapi: 3.1.0 info: title: Quintus Public Chat API description: >- Quintus Public Chat API - for embedding agent conversations in customer-facing front-ends (websites, apps). **Authentication.** Two schemes: 1. **API Key** (`X-API-Key` header) - used to **start** a conversation and to **refresh** its session token. Scoped per agent via `api_key.resources["agents"]`. 2. **Session Token** (`Authorization: Bearer ...`) - short-lived JWT returned by `POST /conversations`. Used for everything inside an existing conversation (send messages, upload files, fetch state, terminate). **Rate limiting.** Requests are rate-limited per API key and per session token. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header. Limits and headers are subject to change - clients should always honor `Retry-After`. **Errors.** All non-2xx responses use the standard `ErrorEnvelope` shape with a stable `error.code` for programmatic handling. contact: name: Quintus Support email: support@quintus.tec.br license: name: Proprietary - Quintus url: https://quintus.tec.br/ version: 1.0.0 servers: - url: https://api.quintus.tec.br security: [] tags: - name: Conversations description: Conversation lifecycle and tokens. - name: Messages description: Send and read messages within a conversation. - name: Files description: Upload and list files attached to a conversation. - name: Feedback description: Conversation-level feedback (NPS-style). paths: /v1/public/agents/conversations: post: tags: - Conversations summary: Create a conversation description: Create a new conversation with an agent and receive a session token. operationId: createConversation requestBody: content: application/json: schema: $ref: '#/components/schemas/ConversationCreateRequest' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ConversationCreateResponse' '401': description: Authentication missing or invalid content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded - see Retry-After header content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - ApiKey: [] components: schemas: ConversationCreateRequest: properties: agent_id: type: string title: Agent Id description: ID of the agent to converse with. user_data: anyOf: - additionalProperties: true type: object - type: 'null' title: User Data description: >- End-user identification stored on the conversation (e.g. {name, email, external_id}). Visible in the dashboard and available to the agent runtime when looking up user history. Not injected verbatim into the LLM context. context: anyOf: - additionalProperties: true type: object - type: 'null' title: Context description: >- Free-form key/value pairs injected into the agent's system context for this conversation. Use for page URL, plan tier, language, etc. Keys and values must be JSON-serializable; keep payload small. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: >- Free-form storage for the integrator. Saved with the conversation and returned on read. Not seen by the agent. Use for your own tracking IDs, campaign tags, audit fields, etc. type: object required: - agent_id title: ConversationCreateRequest example: agent_id: f3a1... context: page: /pricing metadata: campaign: spring-2026 user_data: email: a@example.com name: Andre ConversationCreateResponse: properties: id: type: string title: Id description: Conversation identifier. agent_id: type: string title: Agent Id session_token: type: string title: Session Token description: Bearer token to authenticate subsequent calls in this conversation. expires_at: type: string format: date-time title: Expires At expires_in: type: integer title: Expires In description: Seconds until session_token expires. created_at: type: string format: date-time title: Created At type: object required: - id - agent_id - session_token - expires_at - expires_in - created_at title: ConversationCreateResponse ErrorEnvelope: example: error: code: session_token_expired context: {} message: Session token has expired. Refresh to continue. name: SessionTokenExpiredError request_id: 5f0c-... timestamp: '2026-04-27T12:00:00Z' properties: error: $ref: '#/components/schemas/ErrorBody' request_id: anyOf: - type: string - type: 'null' default: null description: Request ID for support correlation. title: Request Id timestamp: anyOf: - type: string - type: 'null' default: null description: ISO-8601 server timestamp when the error occurred. title: Timestamp required: - error title: ErrorEnvelope type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ErrorBody: properties: code: type: string title: Code description: Stable machine-readable error code (snake_case). name: type: string title: Name description: Error class name (PascalCase). message: type: string title: Message description: Human-readable explanation. context: additionalProperties: true type: object title: Context description: Error-specific structured context (ids, limits, hints). type: object required: - code - name - message title: ErrorBody ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key ````