Threads

Get threads

1GET https://api.markprompt.com/threads

Retrieves threads in the given time range.

Request body

KeyTypeDescriptionDefault
fromstring

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.

tostring

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
limitnumber

The maximum number of results to return.

20
pagenumber

The page index.

0
answeredStatus"answered" | "unanswered" | "partially_answered"

The answered status.

metadataarray

A list of metadata filters.

tagsarray

A list of tags (case sensitive). Filters the tags on the messages within the thread, not the entire thread.

threadTagsarray

A list of tags (case sensitive). Filters the tags on the thread, not the individual messages.

csat1 | 2 | 3 | 4 | 5

Thread CSAT score.

ces1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10

Thread customer effort score.

sentimentsarray

A list of sentiments (between -2 and 2).

urgenciesarray

A list of urgency scores (from 1 to 4).

escalatedboolean

Whether the thread is escalated or not.

functionNamestring

The name of a function that was called.

expandstring

If set to data.messages, expand the thread object to include associated messages.

includePlaygroundDataboolean

If set to true, include threads that originate from the playground.

false
projectKeystring

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-10-20T00%3A00%3A00&to=2024-10-21T00%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-10-20T22:54:52.000000+00:00",
9      "lastMessageCreatedAt": "2024-10-20T22:54:55.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-10-20T00%3A00%3A00&to=2024-10-21T00%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-10-20T22:54:52.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-10-20T22:54:55.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-10-20T00%3A00%3A00" \
8  -d "to=2024-10-21T00%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-10-20T22:54:52.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-10-20T22:54:55.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

KeyTypeDescriptionDefault
csat1 | 2 | 3 | 4 | 5 | 0

A CSAT score. Set to 0 to clear value.

csatReasonstring

A CSAT reason.

metadataobject

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.