Get threads
1GET https://api.markprompt.com/threads
Retrieves threads in the given time range.
Request body
| Key | Type | Description |
|---|
| from | string | The start of the range, as an ISO 8601 string. The date comparison is made against the timestamp of the last message in the thread. |
| to | string | The end of the range, as an ISO 8601 string. The date comparison is made against the timestamp of the last message in the thread. |
| limit | number | The maximum number of results to return. Default: 50. |
| page | number | The page index. Default: 0. |
| answeredStatus | "answered" | "unanswered" | "partially_answered" | |
| metadata | array | A list of metadata filters. |
| tags | array | A list of tags (case sensitive). |
| csat | 1 | 2 | 3 | 4 | 5 | |
| sentiments | array | A list of sentiments (between -2 and 2). |
| urgencies | array | A list of urgency scores (from 1 to 4). |
| escalated | boolean | Whether the thread is escalated or not. |
| functionName | string | The name of a function that was called. |
| expand | string | If set to data.messages, expand the thread object to include associated messages. |
Example request
1curl "https://api.markprompt.com/threads?from=2024-04-01T22%3A00%3A00&to=2024-04-15T22%3A00%3A00&limit=3&page=1" \
2 -X GET \
3 -H "Authorization: Bearer <TOKEN>" \
4 -H "Content-type: application/json" \
5 -H "Accept: application/json" \
6 -H "X-Markprompt-API-Version: 2024-05-21"
Response
The response is of the form:
1{
2 "object": "list",
3 "data": [
4 {
5 "id": "id-1",
6 "createdAt": "2023-08-07T22:36:37.728248+00:00",
7 "lastMessageCreatedAt": "2023-08-07T22:38:12.423211+00:00",
8 "answeredStatus": "answered",
9 "firstUserMessage": "How do I process a refund?",
10 "messageCount": 2,
11 "tags": ["Billing", "Platform"],
12 "votes": [1],
13 "sentiments": [0],
14 "urgencies": [0],
15 "metadata": {
16 "sessionId": "sessions-id-1"
17 }
18 }
19 // ...
20 ]
21}
It contains aggregated information about the messages in each thread, such as the average CSAT score and the highest urgency score, as well as a general assessment of whether the conversation can be considered as answered (or unanswered, or partially answered).
Expanded threads
When adding expand=data.messages to the request body, threads are returned together with associated messages.
1curl "https://api.markprompt.com/threads?from=2024-04-01T22%3A00%3A00&to=2024-04-02T22%3A00%3A00&limit=3&page=1&expand=data.messages" \
2 -X GET \
3 -H "Authorization: Bearer <TOKEN>" \
4 -H "Content-type: application/json" \
5 -H "Accept: application/json" \
6 -H "X-Markprompt-API-Version: 2024-05-21"
The response looks like this:
1{
2 "object": "list",
3 "data": [
4 {
5 "id": "id-1",
6 // ...
7 "messages": [
8 {
9 "id": "message-id-1",
10 "createdAt": "2024-04-01T22:36:37.728248+00:00",
11 "role": "user",
12 "content": "How do I process a refund?",
13 "tags": ["Billing"],
14 "sentiment": 0,
15 "urgency": 0
16 },
17 {
18 "id": "message-id-2",
19 "role": "assistant",
20 "createdAt": "2024-04-01T22:36:41.34872+00:00",
21 "config": {
22 "systemPrompt": "You are a helpful AI assistant!",
23 "payloadConfig": {
24 // ...
25 }
26 },
27 "content": "You can create a refund...",
28 "vote": 1,
29 "answered": true,
30 "sentiment": 0,
31 "references": [
32 // ...
33 ]
34 }
35 ]
36 }
37 // ...
38 ]
39}
Filters
Here is an example that filters on metadata and tags:
1curl -X GET -G https://api.markprompt.com/threads \
2 -H "Authorization: Bearer <TOKEN>" \
3 -H "Content-type: application/json" \
4 -H "Accept: application/json" \
5 -H "X-Markprompt-API-Version: 2024-05-21" \
6 -d "limit=10" \
7 -d "from=2024-03-25T00:00:00Z" \
8 -d "to=2024-04-25T23:59:59" \
9 --data-urlencode "tags=[\"Billing\"]" \
10 --data-urlencode "metadata=[{ \"op\": \"eq\", \"field\": \"plan\", \"value\": \"starter\" }]" | jq
Supported metadata filter operators are: eq, neq, gt, lt, gte, lte, like, ilike, in, is, contains, containedBy, overlaps.
Thread messages
1GET https://api.markprompt.com/threads/{thread_id}/messages
Retrieves messages within a thread.
Example request
1curl "https://api.markprompt.com/threads/thread_123/messages" \
2 -X GET \
3 -H "Authorization: Bearer <TOKEN>" \
4 -H "Content-type: application/json" \
5 -H "Accept: application/json" \
6 -H "X-Markprompt-API-Version: 2024-05-21"
Response
The response is of the form:
1{
2 "object": "list",
3 "data": [
4 {
5 "id": "message-id-1",
6 "createdAt": "2024-04-01T22:36:37.728248+00:00",
7 "role": "user",
8 "role": "what is markprompt in three words?",
9 "urgency": 1,
10 "sentiment": 0
11 },
12 {
13 "id": "message-id-2",
14 "createdAt": "2024-04-01T22:36:41.728248+00:00",
15 "response": "AI, support, API",
16 "csat": "4",
17 "systemPrompt": "You are kind AI who loves to help people!",
18 "config": {
19 // ...
20 },
21 "references": [
22 // ...
23 ]
24 }
25 ]
26}
Update a thread
1POST https://api.markprompt.com/threads/{thread_id}
Updates a thread.
Request body
| Key | Type | Description |
|---|
| csat | 1 | 2 | 3 | 4 | 5 | 0 | A CSAT score. Set to 0 to clear value. |
| metadata | object | |
| strategy | "merge" | "overwrite" | The update strategy. If set to merge, it will merge with the existing fields. If set to overwrite, it will replace the existing fields. Default: overwrite. |
Example request
1curl "https://api.markprompt.com/threads/thread_123" \
2 -X POST \
3 -H "Authorization: Bearer <TOKEN>" \
4 -H "Content-type: application/json" \
5 -H "X-Markprompt-API-Version: 2024-05-21" \
6 -d '{
7 "metadata": { "category": "payments" },
8 "csat": 3,
9 "strategy": "merge"
10 }'