> ## Documentation Index > Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt > Use this file to discover all available pages before exploring further. # Create conversation > Requires `conversations:write`. Creates a group conversation, or finds/creates a direct one-to-one conversation. The creator must match the requesting coach. Direct conversations remain one-to-one; add another coach through a group conversation. ## OpenAPI ````yaml /openapi/public-v1.json post /public/v1/conversations openapi: 3.1.0 info: title: FITsociety Public API v1 version: 1.0.0 description: >- Developer Public API endpoints under `/public/v1`. This reference is filtered to OAuth/Bearer Public API resources and excludes provider callback receivers, storefront routes, public widgets, wishlist routes, and access-device validation endpoints. contact: name: FITsociety Engineering servers: - url: https://api.fitsociety.io description: Production security: [] tags: - name: OAuth description: Public API OAuth endpoints for server-to-server client credentials. - name: Health description: Public API token health checks. - name: Platform description: >- Inspect Public API client context, capabilities, scopes, and redacted audit logs. - name: Company Catalog description: Read and manage company profile metadata and locations. - name: Clients description: >- Create and manage clients through the Public API using Bearer access tokens. - name: Coaches description: Retrieve coaches for the authenticated company via integrations. - name: Calendar Events description: Read Public API calendar events. - name: Calendar Templates description: >- Read and manage event types and event templates used by calendar availability and bookings. - name: Calendar Extensions description: >- Read recurring bookings, booking requests, calendar tasks, and availability closure metadata. - name: Availability description: Read bookable availability slots and signed availability tokens. - name: Availability Management description: >- Manage coach and location availability templates used to derive bookable slots. - name: Bookings description: Read and manage Public API bookings. - name: Finance description: >- Read invoices, transactions, products, subscriptions, and memberships with guarded finance writes. - name: Credits description: >- Read company-wide and client-scoped credit allocations, mutations, and guarded credit adjustments. - name: Exports description: >- Create and monitor asynchronous company exports through Public API Bearer endpoints. - name: Webhooks description: >- Manage outbound webhook subscriptions and inspect delivery attempts through Public API Bearer endpoints. - name: Measurements description: Read and write client measurement entries. - name: Progress Photos description: Read client progress photo metadata and short-lived signed media URLs. - name: Forms description: Read, create, update, and archive company form templates. - name: Intakes description: Assign intake forms and read client intake assignments and submissions. - name: Check-ups description: >- Schedule and cancel client check-ups and read their status and submissions. - name: Documents description: >- Read client document and folder metadata, register external document links, update metadata, and archive documents from Public API listings. Binary upload, permanent deletion, and company-wide document management are not exposed. - name: Habits description: Read habits and habit entries. - name: Goals description: Read client goal summaries. - name: Conversations description: >- Read and manage direct and group chat conversations through the Public API. - name: Reports description: Read aggregate attendance, revenue, and retention summaries. paths: /public/v1/conversations: post: tags: - Conversations summary: Create conversation description: >- Requires `conversations:write`. Creates a group conversation, or finds/creates a direct one-to-one conversation. The creator must match the requesting coach. Direct conversations remain one-to-one; add another coach through a group conversation. operationId: postPublicV1Conversations parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 200 example: booking-create-20260714-001 description: >- Required for Public API write requests. Reusing the same key with the same method, path, and body replays the stored successful response; reusing it with a different request returns `409 idempotency.conflict`. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - conversationType - participants properties: conversationType: type: string enum: - direct - group example: group name: type: string description: Required for group conversations. example: Nutrition follow-up description: type: string example: Coach team and member chat. participants: type: array minItems: 2 maxItems: 100 items: type: object additionalProperties: false required: - userId - role properties: userId: type: string example: 66f7b8b1e13c8d25f4d3d90c role: type: string enum: - Coach - Client example: Client createdBy: type: object additionalProperties: false required: - userId - role properties: userId: type: string example: 66f7b8b1e13c8d25f4d3d90b role: type: string enum: - Coach example: Coach description: >- Optional coach creator. Defaults to the requesting coach when available and must match it when provided. context: type: object additionalProperties: false properties: type: type: string enum: - none - client - company - lesson - calendar_event - booking example: client id: type: string example: 66f7b8b1e13c8d25f4d3d90c occurrenceStart: type: string format: date-time example: '2026-09-01T10:00:00.000Z' label: type: string maxLength: 160 example: Intake follow-up isClientReplyAllowed: type: boolean description: Group setting; defaults to true. example: true responses: '201': description: Conversation created content: application/json: schema: allOf: - $ref: '#/components/schemas/PublicApiWriteSuccessResponse' - type: object properties: data: type: object required: - created - conversation properties: created: type: boolean conversation: $ref: '#/components/schemas/Conversation' examples: success: summary: Successful response value: data: created: true conversation: conversationId: 66f7b8b1e13c8d25f4d3d90a conversationType: direct context: type: none id: 66f7b8b1e13c8d25f4d3d90a occurrenceStart: '2026-07-14T10:00:00.000Z' label: string title: string description: Example description participantCount: 1 participants: - userId: 66f7b8b1e13c8d25f4d3d90a role: Coach name: Example name isActive: true joinedAt: '2026-07-14T10:00:00.000Z' removedAt: '2026-07-14T10:00:00.000Z' capabilities: canSendMessages: true canEditOwnMessages: true canDeleteOwnMessages: true canListParticipants: true canAddParticipants: true canRemoveParticipants: true supportsFutureContexts: - none lastMessage: messageId: 66f7b8b1e13c8d25f4d3d90a conversationId: 66f7b8b1e13c8d25f4d3d90a conversationType: direct sender: userId: 66f7b8b1e13c8d25f4d3d90a role: Coach name: Example name type: text text: string hasMedia: true fileName: Example name sentAt: '2026-07-14T10:00:00.000Z' editedAt: '2026-07-14T10:00:00.000Z' isDeleted: true createdAt: '2026-07-14T10:00:00.000Z' updatedAt: '2026-07-14T10:00:00.000Z' meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 idempotency: replayed: false '400': description: >- Bad request. The request shape, query, path parameter, or idempotency header is invalid. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: invalidRequest: summary: Invalid request value: error: code: 400 key: request.invalid message: The request is invalid. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 idempotencyRequired: summary: Missing Idempotency-Key value: error: code: 400 key: idempotency.required message: >- Idempotency-Key header is required for Public API write requests. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 idempotencyInvalid: summary: Invalid Idempotency-Key value: error: code: 400 key: idempotency.invalid message: Idempotency-Key header must be 200 characters or fewer. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '401': description: >- Unauthorized. The Bearer token is missing, invalid, expired, or belongs to an inactive Public API client. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: missingBearer: summary: Missing Bearer token value: error: code: 401 key: auth.missing_bearer message: Authorization Bearer token is required. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 invalidToken: summary: Invalid or expired token value: error: code: 401 key: auth.invalid_token message: The access token is invalid or expired. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 invalidClient: summary: Inactive or revoked client value: error: code: 401 key: auth.invalid_client message: The Public API client is inactive or revoked. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '403': description: >- Forbidden. The token is valid but does not include the required scope. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: insufficientScopes: summary: Missing required scope value: error: code: 403 key: scopes.insufficient message: The access token does not include the required scope. details: requiredScopes: - conversations:write meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '404': description: >- Not found. The requested company-scoped resource does not exist or is not accessible to this token. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: notFound: summary: Resource not found value: error: code: 404 key: resource.not_found message: The requested Public API resource was not found. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '409': description: >- Conflict. The write request conflicts with idempotency or current resource state. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: idempotencyConflict: summary: Idempotency-Key conflict value: error: code: 409 key: idempotency.conflict message: >- Idempotency-Key was already used with a different request. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 idempotencyInProgress: summary: Idempotency-Key in progress value: error: code: 409 key: idempotency.in_progress message: >- Idempotency-Key is already processing for this Public API client. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '422': description: >- Unprocessable content. The request body is empty or is not a JSON object. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: emptyBody: summary: Empty or invalid JSON object body value: error: code: 422 key: EMPTY_BODY message: Request body must be a non-empty JSON object. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 '429': description: >- Too many requests. The Public API client or caller IP exceeded the rate limit. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: rateLimitExceeded: summary: Rate limit exceeded value: error: code: 429 key: rate_limit.exceeded message: Too many Public API requests. Retry later. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 0 resetSeconds: 1 retryAfterSeconds: 1 '500': description: >- Server error. The request could not be completed because of an unexpected Public API server failure. content: application/json: schema: $ref: '#/components/schemas/PublicApiError' examples: serverInternalError: summary: Unexpected server error value: error: code: 500 key: server.internal_error message: An unexpected Public API server error occurred. meta: requestId: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: limit: 10 remaining: 9 resetSeconds: 1 security: - PublicBearerAuth: [] x-codeSamples: - lang: cURL label: cURL source: |- curl -X POST "https://api.fitsociety.io/public/v1/conversations" \ -H "Authorization: Bearer " \ -H "Idempotency-Key: conversation-create-001" \ -H "Content-Type: application/json" \ -d '{ "conversationType": "group", "name": "Nutrition follow-up", "participants": [ { "userId": "66f7b8b1e13c8d25f4d3d90b", "role": "Coach" }, { "userId": "66f7b8b1e13c8d25f4d3d90c", "role": "Client" } ], "createdBy": { "userId": "66f7b8b1e13c8d25f4d3d90b", "role": "Coach" }, "context": { "type": "client", "id": "66f7b8b1e13c8d25f4d3d90c" } }' components: schemas: PublicApiWriteSuccessResponse: type: object additionalProperties: false required: - data - meta properties: data: type: object meta: $ref: '#/components/schemas/PublicApiWriteMeta' Conversation: type: object additionalProperties: false required: - conversationId - conversationType - context - title - description - participantCount - participants - capabilities - lastMessage - createdAt - updatedAt properties: conversationId: type: string conversationType: type: string enum: - direct - group context: type: object additionalProperties: false required: - type - id - occurrenceStart - label properties: type: type: string enum: - none - client - company - lesson - calendar_event - booking id: type: - string - 'null' occurrenceStart: type: - string - 'null' format: date-time label: type: string title: type: string description: type: string participantCount: type: integer participants: type: array items: type: object additionalProperties: false required: - userId - role - name - isActive - joinedAt - removedAt properties: userId: type: string role: type: string enum: - Coach - Client name: type: string isActive: type: boolean joinedAt: type: - string - 'null' format: date-time removedAt: type: - string - 'null' format: date-time capabilities: type: object additionalProperties: false required: - canSendMessages - canEditOwnMessages - canDeleteOwnMessages - canListParticipants - canAddParticipants - canRemoveParticipants - supportsFutureContexts properties: canSendMessages: type: boolean canEditOwnMessages: type: boolean canDeleteOwnMessages: type: boolean canListParticipants: type: boolean canAddParticipants: type: boolean canRemoveParticipants: type: boolean supportsFutureContexts: type: array items: type: string enum: - none - client - company - lesson - calendar_event - booking lastMessage: oneOf: - $ref: '#/components/schemas/ConversationMessage' - type: 'null' createdAt: type: - string - 'null' format: date-time updatedAt: type: - string - 'null' format: date-time PublicApiError: type: object additionalProperties: false required: - error - meta properties: error: type: object additionalProperties: false required: - code - key - message properties: code: type: integer example: 401 key: type: string example: auth.invalid_token message: type: string example: The access token is invalid. details: type: object additionalProperties: true meta: $ref: '#/components/schemas/PublicApiMeta' PublicApiWriteMeta: type: object additionalProperties: false required: - requestId properties: requestId: type: string description: Stable request correlation id. Mirrors `X-Request-Id` when supplied. example: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: $ref: '#/components/schemas/PublicApiRateLimitMeta' idempotency: type: object additionalProperties: false properties: replayed: type: boolean description: >- True when the response was replayed from a previous request with the same `Idempotency-Key`. example: true ConversationMessage: type: object additionalProperties: false required: - messageId - conversationId - conversationType - sender - type - text - hasMedia - fileName - sentAt - editedAt - isDeleted properties: messageId: type: string conversationId: type: string conversationType: type: string enum: - direct - group sender: type: object additionalProperties: false required: - userId - role - name properties: userId: type: string role: type: string enum: - Coach - Client name: type: string type: type: string enum: - text text: type: string hasMedia: type: boolean fileName: type: string sentAt: type: - string - 'null' format: date-time editedAt: type: - string - 'null' format: date-time isDeleted: type: boolean PublicApiMeta: type: object additionalProperties: false required: - requestId properties: requestId: type: string description: Stable request correlation id. Mirrors `X-Request-Id` when supplied. example: 4f849d7d-f4f1-45cc-b4b7-3984a3d17f83 rateLimit: $ref: '#/components/schemas/PublicApiRateLimitMeta' PublicApiRateLimitMeta: type: object additionalProperties: false properties: limit: type: integer example: 10 remaining: type: integer example: 9 resetSeconds: type: integer description: Seconds until the current rate limit window resets. example: 1 retryAfterSeconds: type: integer description: Present when the request was rate limited. example: 1 securitySchemes: PublicBearerAuth: type: http scheme: bearer bearerFormat: Opaque description: >- Public API access token issued by `/public/v1/oauth/token`. Example: `Authorization: Bearer fspt_...`. Each resource request rechecks the token company's current provider access. Disabling access blocks existing tokens with `403 auth.provider_unavailable`. ````