cURL
curl -X POST "https://api.fitsociety.io/public/v1/conversations" \
-H "Authorization: Bearer <access_token>" \
-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" }
}'const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
conversationType: 'group',
participants: [{userId: '66f7b8b1e13c8d25f4d3d90c', role: 'Client'}]
})
};
fetch('https://api.fitsociety.io/public/v1/conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.fitsociety.io/public/v1/conversations"
payload = {
"conversationType": "group",
"participants": [
{
"userId": "66f7b8b1e13c8d25f4d3d90c",
"role": "Client"
}
]
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"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
}
}
}
Conversation records
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.
POST
/
public
/
v1
/
conversations
cURL
curl -X POST "https://api.fitsociety.io/public/v1/conversations" \
-H "Authorization: Bearer <access_token>" \
-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" }
}'const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
conversationType: 'group',
participants: [{userId: '66f7b8b1e13c8d25f4d3d90c', role: 'Client'}]
})
};
fetch('https://api.fitsociety.io/public/v1/conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.fitsociety.io/public/v1/conversations"
payload = {
"conversationType": "group",
"participants": [
{
"userId": "66f7b8b1e13c8d25f4d3d90c",
"role": "Client"
}
]
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"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
}
}
}
Authorizations
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.
Headers
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.
Required string length:
1 - 200Example:
"booking-create-20260714-001"
Body
application/json
Available options:
direct, group Example:
"group"
Required array length:
2 - 100 elementsShow child attributes
Show child attributes
Required for group conversations.
Example:
"Nutrition follow-up"
Example:
"Coach team and member chat."
Optional coach creator. Defaults to the requesting coach when available and must match it when provided.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Group setting; defaults to true.
Example:
true