> ## Documentation Index > Fetch the complete documentation index at: https://docs.helloannie.com/llms.txt > Use this file to discover all available pages before exploring further. # Create conversation > Create a new conversation with the specified medium and bot. An anonymous user is automatically created for the conversation. Optionally seed the conversation with initial messages that will be attached in order. ## OpenAPI ````yaml /openapi/openapi.yaml post /conversations openapi: 3.0.3 info: title: Annie API description: > ### Overview The Annie API is a (mostly) RESTful API. Typically, both POST bodies and responses are JSON-encoded. Note: The documenation is Work In Progress and is subject to change. ### Base URL The base URL for the Annie API is https://api.helloannie.com/. Examples in this document may abbreviate this to `/`. ### Versioning Routes are prefixed with a version number i.e. `v1`. The version will change when there is a non-backwards compatible or other significant change to the api. ### Authentication The Annie API supports two authentication methods API Keys and OAuth Access Tokens: #### API Keys API Keys are long-lived tokens that can be generated from the Developer Portal on your organization page. API keys are prefixed with `annie-sk-v2-` and can be used directly in the `Authorization` header. ``` curl -H "Authorization: Bearer annie-sk-xxxxx" https://api.helloannie.com/... ``` #### OAuth Tokens OAuth tokens are short-lived access tokens generated using the OAuth 2.0 Client Credentials flow (Machine-to-Machine). OAuth clients provide scoped permissions and are ideal for server-to-server integrations. **Creating an OAuth Client** OAuth clients can be created in the Developer Portal on your organization page. When creating a client, you'll receive: - `client_id`: Your OAuth client identifier - `client_secret`: Your OAuth client secret (store this securely) **Generating an OAuth Token** To generate an OAuth access token, make a POST request to the Annie OAuth token endpoint: **Endpoint:** `https://annie-external-api.us.auth0.com/oauth/token` **Example Request:** ```bash curl -X POST https://annie-external-api.us.auth0.com/oauth/token \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "your-client-id", "client_secret": "your-client-secret", "audience": "https://api.helloannie.com" }' ``` The `access_token` from the response should be used in the `Authorization` header when making requests to the Annie API: ``` curl -H "Authorization: Bearer eyJhbGciOiJSUzI..." https://api.helloannie.com/v1/... ``` ### API Response Structure The Annie API returns status codes consistent with standard HTTP conventions. Success and Error responses follow the below structure: ``` { "success": boolean "data": {} "message": string // optional } ``` ### Rate Limiting The Annie API enforces rate limits to ensure stability and fair usage. The default rate limit is **60 requests per minute** per organization. This limit is applied per endpoint pattern (e.g. `GET /v1/bots/:id`). When the rate limit is exceeded, the API responds with HTTP `429 Too Many Requests`. Response headers include: - `X-RateLimit-Limit`: The maximum number of requests allowed in the current window. - `X-RateLimit-Remaining`: The number of requests remaining in the current window. - `X-RateLimit-Reset`: The time at which the current rate limit window resets (in UTC epoch seconds). If you exceed the limit, the response will contain a `Retry-After` header indicating how many seconds to wait before retrying. ### Pagination The Annie API does not currently support pagination. All results are returned at once. version: v1 servers: - url: https://api.helloannie.com/v1 security: [] paths: /conversations: post: tags: - Conversations summary: Create conversation description: >- Create a new conversation with the specified medium and bot. An anonymous user is automatically created for the conversation. Optionally seed the conversation with initial messages that will be attached in order. operationId: postV1Conversations requestBody: description: Request body for creating a new conversation required: true content: application/json: schema: $ref: '#/components/schemas/CreateConversationRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CreateConversationRequest' multipart/form-data: schema: $ref: '#/components/schemas/CreateConversationRequest' responses: '200': description: Response returned when creating a new conversation content: application/json: schema: $ref: '#/components/schemas/CreateConversationResponse' '400': description: The request was invalid or malformed content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' components: schemas: CreateConversationRequest: additionalProperties: false type: object required: - medium - botId properties: medium: type: string enum: - CHAT - SMS botId: format: uuid description: The ID of the bot to use for this conversation type: string toNumber: description: The phone number the conversation is to type: string messages: description: Initial messages to seed the conversation. Order is preserved. type: array items: additionalProperties: false description: A message input with role and content type: object required: - role - input properties: role: type: string enum: - user - assistant input: description: The content of the message type: string idleTimeoutMinutes: minimum: 1 multipleOf: 1 description: >- Optional. Auto-close the conversation after this many minutes with no inbound or outbound activity. Omit to disable the idle timeout (the conversation will remain open until the platform max is reached). Values larger than the platform max are clamped to the platform max. type: number maxOpenMinutes: minimum: 1 multipleOf: 1 description: >- Optional. Hard maximum for how long the conversation can stay open, measured from creation. Omit to allow the conversation to stay open up to the platform max. Values larger than the platform max are clamped to the platform max. type: number CreateConversationResponse: additionalProperties: false type: object required: - success - data properties: success: enum: - true type: boolean data: additionalProperties: false description: >- High-level information about a conversation including summary metadata type: object required: - conversationId - conversationTags - orgId - medium - botId - toNumber - fromNumber - summary - billed - actionsNeeded - topic - duration - startTime - endTime - status properties: conversationId: format: uuid type: string conversationTags: type: array items: type: string orgId: format: uuid type: string medium: type: string enum: - CHAT - PHONE - SMS botId: format: uuid type: string nullable: true toNumber: type: string nullable: true fromNumber: type: string nullable: true summary: type: string nullable: true billed: description: Whether this conversation has been counted as billable. type: boolean actionsNeeded: description: Follow-up actions needed after the conversation type: array items: type: string topic: type: string nullable: true duration: description: Duration of the conversation in milliseconds example: 1500 type: number nullable: true startTime: type: string format: date-time nullable: true endTime: type: string format: date-time nullable: true status: type: string enum: - OPEN - CLOSED BadRequestResponse: additionalProperties: false type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string ````