Get threads
1GET https://api.markprompt.com/threads
Retrieves threads in the given time range.
Request body
| Key | Type | Description | Default |
| 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. | |
| order | "asc" | "desc" | The order of the results based on the date. | asc |
| limit | number | The maximum number of results to return. | 20 |
| page | number | The page index. | 0 |
| answeredStatus | "answered" | "unanswered" | "partially_answered" | The answered status. | |
| metadata | array | A list of metadata filters. | |
| tags | array | A list of tags (case sensitive). Filters the tags on the messages within the thread, not the entire thread. | |
| threadTags | array | A list of tags (case sensitive). Filters the tags on the thread, not the individual messages. | |
| csat | 1 | 2 | 3 | 4 | 5 | Thread CSAT score. | |
| ces | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | Thread customer effort score. | |
| 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. | |
| includePlaygroundData | boolean | If set to true, include threads that originate from the playground. | false |
| projectKey | string | Instead of the API token, use a project key, for instance for client-facing requests. | |
Example request
1curl "https://api.markprompt.com/threads?from=2024-12-11T00%3A00%3A00&to=2024-12-12T00%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": "thread-id-1",
6 "assistantId": "assistant-id-1",
7 "assistantVersionId": "assistant-version-id-1",
8 "createdAt": "2024-12-11T09:52:56.000000+00:00",
9 "lastMessageCreatedAt": "2024-12-11T09:52:59.000000+00:00",
10 "answeredStatus": "answered",
11 "firstUserMessage": "How do I process a refund?",
12 "messageCount": 2,
13 "tags": ["Billing", "Platform"],
14 "threadTag": "Billing",
15 "functionNames": null,
16 "ces": 6,
17 "cesReason": {
18 "reason": "The user was not able to find the refund process in the platform and tried several options before getting assistance."
19 },
20 "csat": 3,
21 "csat_reason": "The agent did not mention the refund process with my processor.",
22 "votes": null,
23 "sentiments": [0],
24 "urgencies": [1],
25 "metadata": {
26 "plan": "business",
27 "userId": "user-id-1"
28 },
29 "extras": {
30 "origin": "https://support.acme.com"
31 }
32 }
33 // ...
34 ]
35}
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-12-11T00%3A00%3A00&to=2024-12-12T00%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-12-11T09:52:56.000000+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-12-11T09:52:59.000000+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-12-11T00%3A00%3A00" \
8 -d "to=2024-12-12T00%3A00%3A00" \
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-12-11T09:52:56.000000+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-12-11T09:52:59.000000+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 | Default |
| csat | 1 | 2 | 3 | 4 | 5 | 0 | A CSAT score. Set to 0 to clear value. | |
| csatReason | string | A CSAT reason. | |
| metadata | object | A 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. | 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 "csatReason": "The agent did not mention the refund process.",
10 "strategy": "merge"
11 }'
Example: tracking escalations
In order to mark a thread as escalated, simply attach a caseNumber to the thread metadata. For instance, you may create a case on Salesforce Case, obtain a case number, and then post it to Markprompt:
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": { "caseNumber": "10238347" }
8 }'
Limits
This API is subject to a limit of 100 requests per minute per project.