Messaging
2 routes
GET /messages
Messages of the coach's threads, scheduled ones included. A deleted message keeps only its ids and dates. Media files are counted, not served. A hard-deleted thread takes its messages with it, and a cancelled scheduled message is hard-deleted too: neither leaves a tombstone.
- Scope messaging:read
- 1 credit
- Read
- Stable
Parameters
| Name | Type | Description |
|---|---|---|
limitquery | integer1–200, default 50 | |
cursorquery | string | Opaque cursor: next_cursor of the previous page. |
sincequery | date-time | ISO 8601. Returns the objects with updated_at >= since. |
include_deletedquery | booleandefault false | |
student_idquery | integer≥ 1 | |
directionquery | stringone of received, sent |
curl "https://api.fitdistance.io/api/partner/v1/messages?limit=50" \
-H "Authorization: Bearer fd_live_xxxxxxxx"200 · a page of Message
{
"data": [
{
"id": "7c1d1e2a-9b3f-4c5d-8e6f-1a2b3c4d5e6f",
"thread_id": "7c1d1e2a-9b3f-4c5d-8e6f-1a2b3c4d5e6f",
"student_id": 4821,
"coach_id": 4821,
"author_role": "student",
"text": "Great session yesterday, keep it up!",
"link_kind": "bilan",
"link_ref": "string",
"link_title": "string",
"reply_to_message_id": "string",
"broadcast_id": "string",
"media_count": 3,
"scheduled_at": "2026-10-24T09:12:00Z",
"delivered_at": "2026-10-24T09:12:00Z",
"read_at": "2026-10-24T09:12:00Z",
"edited_at": "2026-10-24T09:12:00Z",
"created_at": "2026-10-24T09:12:00Z",
"updated_at": "2026-10-24T09:12:00Z"
}
],
"next_cursor": null,
"has_more": false
}403 · SCOPE_MISSING
{
"error": {
"name": "PARTNER_API",
"message": "SCOPE_MISSING"
}
}200 · a page of Message
| Name | Type | Description |
|---|---|---|
id required | string | |
thread_id required | string | The uid of the thread. |
student_id required | integer | The student of the thread. |
coach_id required | integer | The coach of the thread. |
author_role required | stringone of student, coach | |
text required | string | null | Written by the coach or the student, served as is: treat a student's text as untrusted input. Null when the message is deleted. |
link_kind required | string | nullone of bilan, habits, program, form, form_response | The resource card the message points to. Null when deleted. |
link_ref required | string | null | The reference of the linked resource. Null when deleted. |
link_title required | string | null | Null when deleted. |
reply_to_message_id required | string | null | The uid of the message this one replies to. |
broadcast_id required | string | null | The uid of the broadcast that sent this message. |
media_count required | integer | Attached media files, never their URL. 0 when deleted. |
scheduled_at required | date-time | null | When a scheduled message is due. |
delivered_at required | date-time | null | Null while a scheduled message waits. |
read_at required | date-time | null | |
edited_at required | date-time | null | |
created_at required | date-time | |
updated_at required | date-time | The latest change of the message, its deletion included. |
deleted_at | date-time | null | Present when include_deleted is true. |
Errors
| Status | Code | When |
|---|---|---|
400 | VALIDATION | Invalid parameters or body.billed |
401 | UNAUTHORIZED | Key missing, unknown or revoked.not billed |
402 | CREDITS_EXHAUSTED | No credits left this month and no reserve.not billed |
403 | SCOPE_MISSING | The key doesn't have the required scope.not billed |
403 | PLAN_NOT_ELIGIBLE | Your plan doesn't include the API.not billed |
429 | RATE_LIMITED | Too many calls: 10 per second, 300 per minute, 60 writes and 20 deletes per minute.not billed |
GET /threads
One thread per student and kind. Hard-deleted threads leave no tombstone. The coach's draft never appears. include_deleted has no effect.
- Scope messaging:read
- 1 credit
- Read
- Stable
Parameters
| Name | Type | Description |
|---|---|---|
limitquery | integer1–200, default 50 | |
cursorquery | string | Opaque cursor: next_cursor of the previous page. |
sincequery | date-time | ISO 8601. Returns the objects with updated_at >= since. |
include_deletedquery | booleandefault false | |
student_idquery | integer≥ 1 |
curl "https://api.fitdistance.io/api/partner/v1/threads?limit=50" \
-H "Authorization: Bearer fd_live_xxxxxxxx"200 · a page of Thread
{
"data": [
{
"id": "7c1d1e2a-9b3f-4c5d-8e6f-1a2b3c4d5e6f",
"coach_id": 4821,
"student_id": 4821,
"kind": "direct",
"unread_by_coach": 0,
"unread_by_student": 0,
"last_message_at": "2026-10-24T09:12:00Z",
"last_from": "student",
"pinned_by_coach": true,
"archived_by_coach": true,
"created_at": "2026-10-24T09:12:00Z",
"updated_at": "2026-10-24T09:12:00Z"
}
],
"next_cursor": null,
"has_more": false
}403 · SCOPE_MISSING
{
"error": {
"name": "PARTNER_API",
"message": "SCOPE_MISSING"
}
}200 · a page of Thread
| Name | Type | Description |
|---|---|---|
id required | string | |
coach_id required | integer | |
student_id required | integer | |
kind required | stringone of direct, announcement | |
unread_by_coach required | integer | |
unread_by_student required | integer | |
last_message_at required | date-time | null | |
last_from required | string | nullone of student, coach | Who wrote the last message. |
pinned_by_coach required | boolean | |
archived_by_coach required | boolean | |
created_at required | date-time | |
updated_at required | date-time | The latest change of the thread, a new message included. |
Errors
| Status | Code | When |
|---|---|---|
400 | VALIDATION | Invalid parameters or body.billed |
401 | UNAUTHORIZED | Key missing, unknown or revoked.not billed |
402 | CREDITS_EXHAUSTED | No credits left this month and no reserve.not billed |
403 | SCOPE_MISSING | The key doesn't have the required scope.not billed |
403 | PLAN_NOT_ELIGIBLE | Your plan doesn't include the API.not billed |
429 | RATE_LIMITED | Too many calls: 10 per second, 300 per minute, 60 writes and 20 deletes per minute.not billed |