Threads

Get threads

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

Retrieves threads in the given time range.

Request body

KeyTypeDescription
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.

limitnumber

The maximum number of results to return. Default: 20.

pagenumber

The page index. Default: 0.

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

The answered status.

metadataarray

A list of metadata filters.

tagsarray

A list of tags (case sensitive).

csat1 | 2 | 3 | 4 | 5

Thread CSAT 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.

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

KeyTypeDescription
csat1 | 2 | 3 | 4 | 5 | 0

A CSAT score. Set to 0 to clear value.

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. 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    }'

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.