API Reference

Markprompt exposes the following endpoints at https://api.markprompt.com:

  • /train: turn your content into embeddings
  • /chat: get chat completions for user prompts
  • /sections: get sections matching a prompt
  • /search: get instant search results
  • /feedback: attach feedback to a chat response
  • /threads: get threads
  • /threads/<thread_id>/messages: get messages in a thread
  • /threads/<thread_id>/metadata: attach metadata to a thread

The /train, /sections and /threads endpoint requires authorization using a bearer token. This token can be found in your project settings in the dashboard, and should never be shared publicly. If you suspect that your token has been compromised, you can generate a new one in the dashboard. The /chat, /search and /feedback endpoints can be accessed either from a server using the bearer token, or from a client using a development key (for non-public testing) or a production key from a whitelisted domain (for public sharing). See below for more details.

Train

Using the training endpoint is relevant if you want to programmatically index your content, for instance in a GitHub action. If you don't need this level of automation, we recommend that you use the Markprompt dashboard, which offers simple tools such as GitHub sync to make the process easy and setup-free.

http
1POST https://api.markprompt.com/train

Creates and indexes embeddings for your content.

The endpoint accepts two types of payloads:

  • A JSON payload.
  • A file payload, for uploading a zip file or a plain text file.

Request body (JSON)

In the case of a JSON payload, the content type header must be application/json. The JSON payload must be of the form:

KeyTypeDescription
filesarray (optional)A set of objects with the keys:
  • id a unique identifier for your file, for instance its path in a file system.
  • content the textual content of the file.

Example request:

bash
1curl https://api.markprompt.com/train \
2  -X POST \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-Type: application/json" \
5  -H "X-Markprompt-API-Version: 2023-12-01" \
6  -d '{
7    "files": [
8      { "path": "file_path_1", "content": "..." },
9      { "path": "file_path_2", "content": "..." },
10    ]
11  }'

Request body (file)

In the case of a file payload, the content type header must be application/zip or application/octet-stream.

Example request:

bash
1curl "https://api.markprompt.com/train" \
2  -X POST \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-Type: application/zip" \
5  -H "X-Markprompt-API-Version: 2023-12-01" \
6  --data-binary @data.zip

Here is an example in JavaScript that reads a file from disk and sends it to the /train endpoint:

js
1const fs = require('fs')
2
3const file = fs.createReadStream('data.zip');
4
5await fetch('https://api.markprompt.com/train', {
6  method: 'POST',
7  body: file,
8  headers: {
9    'Authorization': 'Bearer <TOKEN>',
10    'Content-Type': 'application/zip',
11    'X-Markprompt-API-Version': '2023-12-01',
12  },
13});

Request headers

  • Authorization

    The authorization header, carrying the bearer token.

  • Content-Type

    The content type of the payload. Currently supported values are application/json, application/zip and application/octet-stream.

  • x-markprompt-force-retrain

    By default, if a file has been trained, sending it again with the same content will not retrain the file. If for some reason you want to force a retraining, you can pass a long this header with the value set to true.

Chat

http
1POST https://api.markprompt.com/chat

Creates a chat completion for the provided prompt, taking into account the content you have trained your project on.

Request body

KeyTypeDescription
messagesarrayA list of user and assistant messages to complete.
projectKeystringThe API key associated to your project. If shared publicly, use the production key from a whitelisted domain. If not, for instance on localhost, use the development key.
modelgpt-4 | gpt-4-32k | gpt-4-1106-preview | gpt-4-turbo-preview | gpt-3.5-turbo | text-davinci-003 | text-davinci-002 | text-curie-001 | text-babbage-001 | text-ada-001 | davinci | curie | babbage | adaThe completions model to use.
systemPromptstringCustom system prompt that wraps prompt and context.
streambooleanIf true, return the response as a Readable Stream. Otherwise, return as a plain JSON object. Default: true.
doNotInjectContextbooleanIf true, do not inject the context in the full prompt unless the context tag is present in the template. Default false.
allowFollowUpQuestionsbooleanIf true, the bot may encourage the user to ask a follow-up question, for instance to gather additional information. Default true.
doNotInjectPromptbooleanIf true, do not inject the prompt in the full prompt unless the prompt tag is present in the template. Default false.
excludeFromInsightsbooleanIf true, exclude the prompt from insights. Default false.
redactbooleanIf true, redact sensitive data from prompt and response. Default false.
outputFormat"markdown" | "slack"Output format, e.g. Slack-flavored Markdown. Default markdown.
conversationIdstringIf provided, the prompt and response will be tracked as part of the same conversation in the insights.
conversationMetadataobjectAn arbitrary JSON payload to attach to a conversation, available in the insights.
temperaturenumberThe model temperature. Default: 0.1.
topPnumberThe model top P. Default: 1.
frequencyPenaltynumberThe model frequency penalty. Default: 0.
presencePenaltynumberThe model presence penalty. Default: 0.
maxTokensnumberThe max number of tokens to include in the response.
maxContextTokensnumberThe max number of tokens to include as part of the context. Default: 10000. Note that this value will automatically be adjusted to fit within the context window allowed by the model.
sectionsMatchCountnumberThe number of sections to include in the prompt context.
sectionsMatchThresholdnumberThe similarity threshold between the input question and selected sections. The higher the threshold, the more relevant the sections. If it's too high, it can potentially miss some sections.
toolsOpenAI.ChatCompletionTool[]A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for.
tool_choiceOpenAI.ChatCompletionToolChoiceOptionControls which (if any) function is called by the model. none means the model will not call a function and instead generates a message. auto means the model can pick between generating a message or calling a function. Specifying a particular function via {"type: "function", "function": {"name": "my_function"}} forces the model to call that function. none is the default when no functions are present. auto is the default if functions are present.
debugbooleanIf set to true, the response will contain additional metadata, such as the full prompt, for debug or other purposes.

Example request

bash
1curl https://api.markprompt.com/chat \
2  -X POST \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-Type: application/json" \
5  -H "X-Markprompt-API-Version: 2023-12-01" \
6  -d '{
7    "messages": [
8      {
9        "role": "user",
10        "content": "What is Markprompt?"
11      },
12      {
13        "role": "assistant",
14        "content": "Markprompt is ..."
15      },
16      {
17        "role": "user",
18        "content": "Explain this to me as if I was a 3 year old."
19      }
20    ],
21    "model": "gpt-4"
22  }'

Response

By default, the response is returned as a ReadableStream of the form:

1So imagine a robot that can answer all the questions you have...

In addition to the stream, the response includes a header named x-markprompt-data, which is an encoded (Uint8Array) JSON object of the form:

json
1{
2  references: [
3    reference1,
4    reference2,
5    ...
6  ],
7  promptId: "...",
8  conversationId: "...",
9  debugInfo: { ... }
10}

It consists of the following:

  • The references (see below) used to generate the answer.
  • A promptId, which is a unique ID representing the message/answer pair.
  • A conversationId, which is a unique ID which can be passed on subsequent requests and represents a multi-message conversation.
  • If the debug parameter is set to true, a debugInfo object containing information about the query, such as the full prompt that was built for the query.

The reference object

A reference is an object of the form:

ts
1type FileSectionReference = {
2  file: {
3    title?: string;
4    path: string;
5    meta?: any;
6    source: Source;
7  },
8  meta?: {
9    leadHeading?: {
10      id?: string;
11      depth?: number;
12      value?: string;
13      slug?: string;
14    };
15  };
16}

and is meant to provide enough information for the client to be able to generate descriptive links to cited sources, including section slugs.

Parsing the header

Here is some example code in JavaScript to decode the references from the response header:

js
1const res = await fetch(
2  'https://api.markprompt.com/chat',
3  { /*...*/ }
4);
5
6// JSON payload
7const encodedPayload = res.headers.get('x-markprompt-data');
8const headerArray = new Uint8Array(encodedPayload.split(',').map(Number));
9const decoder = new TextDecoder();
10const decodedValue = decoder.decode(headerArray);
11const payload = JSON.parse(decodedValue);
12// ...

If the stream flag is set to false, the response is returned as a plain JSON object with a text field containing the completion, and a references field containing the list of references used to create the completion:

json
1{
2  "text": "Completion response...",
3  "references": [reference1, reference2, ...]
4}

where references are objects of the form described above.

When querying chat completions, do not use the bearer token if the code is exposed publicly, for instance on a public website. Instead, use the project production key, and make the request from a whitelisted domain. Obtaining the project production key and whitelisting the domain is done in the project settings.

Here is a working example of how to consume the stream in JavaScript. Note the use of projectKey and no authorization header: this code can be shared publicly, and will work from a domain you have whitelisted in the project settings.

js
1const res = await fetch('https://api.markprompt.com/chat', {
2  method: 'POST',
3  headers: {
4    'Content-Type': 'application/json',
5    'X-Markprompt-API-Version': '2023-12-01',
6  },
7  body: JSON.stringify({
8    messages: [
9      {
10        role: "user",
11        content: "What is Markprompt?"
12      }
13    ],
14    projectKey: 'YOUR-PROJECT-KEY',
15    model: 'gpt-4'
16  }),
17});
18
19if (!res.ok || !res.body) {
20  console.error('Error:', await res.text());
21  return;
22}
23
24// JSON payload
25const encodedPayload = res.headers.get('x-markprompt-data');
26const headerArray = new Uint8Array(encodedPayload.split(',').map(Number));
27const decoder = new TextDecoder();
28const decodedValue = decoder.decode(headerArray);
29const { references } = JSON.parse(decodedValue);
30
31const reader = res.body.getReader();
32const decoder = new TextDecoder();
33let response = '';
34
35while (true) {
36  const { value, done } = await reader.read();
37  const chunk = decoder.decode(value);
38  response = response + chunk;
39  if (done) {
40    break;
41  }
42}
43
44console.info('Answer:', response);

Sections

http
1GET https://api.markprompt.com/sections

Retrieves a list of sections that match a prompt.

The /sections endpoint is available as part of the Enterprise plan.

Request body

KeyTypeDescription
promptstringThe input prompt.
sectionsMatchCountnumberThe number of sections to retrieve. Default: 10.
sectionsMatchThresholdnumberThe similarity threshold between the input prompt and selected sections. The higher the threshold, the more relevant the sections. If it's too high, it can potentially miss some sections. Default: 0.5.
maxContextTokensnumberThe maximum number of tokens that the returned sections fill. Default: 10000.
ragTypebasic | smallToBigThe RAG strategy. If set to basic, sections whose embeddings satisfy the minimum similarity score against the input prompt are returned. If set to smallToBig, search for section matches is extended to include neighboring content, as long as it fits within the maxContentTokens constraint. Note that smallToBig RAG type is an enterprise-only feature. Default: basic.

Example request

bash
1curl "https://api.markprompt.com/sections?prompt=what%20is%20a%20component%3F&sectionsMatchCount=20&sectionsMatchThreshold=0.4" \
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: 2023-12-01"

Response

The response is of the form:

json
1{
2  data: [
3    {
4      path: "/path/to/section/1",
5      content: "Section 1 content...",
6      similarity: 0.89
7    },
8    {
9      path: "/path/to/section/2",
10      content: "Section 2 content...",
11      similarity: 0.72
12    },
13    ...
14  ]
15}
http
1GET https://api.markprompt.com/search

Retrieves a list of search result that match a query.

Request body

KeyTypeDescription
querystringThe search query string.
projectKeystringOptional, if not using an bearer token. The project key associated to your project. If shared publicly, use the production key from a whitelisted domain. If not, for instance on localhost, use the development key.
limitnumberThe maximum number of results to return. Default: 10.
includeSectionContentbooleanWhether to return the full content of matching sections, in addition to snippets. Default: false.

Example request

bash
1curl "https://api.markprompt.com/search?query=react&limit=4" \
2  -X GET \
3  -H "Authorization: Bearer <TOKEN>"
4  -H "Content-type: application/json" \
5  -H "Accept: application/json"

Response

The response is of the form:

json
1{
2  data: [
3    searchResult1,
4    searchResult2,
5    ...
6  ]
7}

A search result is similar to a reference object used in completions references, with an additional field describing the match type:

ts
1type SearchResult = {
2  matchType: 'title' | 'leadHeading' | 'content',
3  file: {
4    title?: string;
5    path: string;
6    meta?: any;
7    source: Source;
8  },
9  meta?: {
10    leadHeading?: {
11      id?: string;
12      depth?: number;
13      value?: string;
14      slug?: string;
15    };
16  };
17}

Search results are ranked depending on the match type: higher weights are put on title matches, then section lead headings, and finally on content.

Threads

Get threads

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

Retrieves threads in the given time range.

Request body

KeyTypeDescription
fromstringThe start of the range, as an ISO 8601 string.
tostringThe end of the range, as an ISO 8601 string.
limitnumberThe maximum number of results to return. Default: 50.
pagenumberThe page index. Default: 0.
expandstringIf set to data.messages, expand the thread object to include associated messages.

Example request

bash
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: 2023-12-01"

Response

The response is of the form:

json
1{
2  "object": "list",
3  "data": [
4    {
5      "id": "id-1",
6      "created_at": "2023-08-07T22:36:37.728248+00:00",
7      "metadata": {
8        "sessionId": "sessions-id-1"
9      }
10    },
11    {
12      "id": "id-2",
13      "created_at": "2023-08-07T22:40:04.527411+00:00",
14      "metadata": null
15    }
16  ]
17}

Expanded threads

When adding expand=data.messages to the request body, threads are returned together with associated messages.

bash
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: 2023-12-01"

The response looks like this:

json
1{
2  "object": "list",
3  "data": [
4    {
5      "id": "id-1",
6      "created_at": "2023-08-07T22:36:37.728248+00:00",
7      "metadata": {
8        "sessionId": "sessions-id-1"
9      },
10      "messages": [
11        {
12          "id": "message-id-1",
13          "createdAt": "2023-08-07T22:36:37.728248+00:00",
14          "prompt": "what is markprompt in three words?",
15          "response": "Markprompt can be described as...",
16          "systemPrompt": "You are kind AI who loves to help people!",
17          "config": {
18            // ...
19          },
20          "references": [
21            // ...
22          ]
23        }
24      ]
25    },
26    // ...
27  ]
28}

Thread messages

http
1GET https://api.markprompt.com/threads/{thread_id}/messages

Retrieves messages within a thread.

Example request

bash
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: 2023-12-01"

Response

The response is of the form:

json
1{
2  "object": "list",
3  "data": [
4    {
5      "id": "message-id-1",
6      "config": {
7        "modelId": "gpt-4-turbo-preview",
8      },
9      "feedback": null,
10      "createdAt": "2023-12-21T18:27:25.068349+00:00",
11      "prompt": "How does Markprompt work in one sentence?",
12      "systemPrompt": "You reply in Portuguese",
13      "response": "Markprompt é uma ferramenta poderosa e fácil...",
14      "references": []
15    }
16  ]
17}

Update a thread

http
1POST https://api.markprompt.com/threads/{thread_id}

Updates a thread.

Request body

KeyTypeDescription
metadataobjectAn metadata object.
strategymerge | overwriteThe 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

bash
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: 2023-12-01" \
6  -d '{"metadata": { "category": "payments" } }'

Feedback

http
1POST https://api.markprompt.com/feedback

Attach feedback to a chat response.

Request body

KeyTypeDescription
messageIdstringThe ID of the prompt, as returned from the chat endpoint.
feedbackobjectAn object of the form { vote: "1" | "-1" | "escalated" }.

Example request

bash
1curl https://api.markprompt.com/feedback \
2  -X POST \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-Type: application/json" \
5  -H "X-Markprompt-API-Version: 2023-12-01" \
6  -d '{
7    "messageId": <MESSAGE_ID>
8    "feedback": { "vote": "1" }
9  }'

Legacy

Train

Using the training endpoint is relevant if you want to programmatically index your content, for instance in a GitHub action. If you don't need this level of automation, we recommend that you use the Markprompt dashboard, which offers simple tools such as GitHub sync and drag-and-drop to make the process easy and setup-free.

http
1POST https://api.markprompt.com/v1/train

Creates and indexes embeddings for your content.

The endpoint accepts two types of payloads:

  • A JSON payload.
  • A file payload, for uploading a zip file or a plain text file.

Request body (JSON)

In the case of a JSON payload, the content type header must be application/json. The JSON payload must be of the form:

KeyTypeDescription
filesarray (optional)A set of objects with the keys:
  • id a unique identifier for your file, for instance its path in a file system.
  • content the textual content of the file.

Example request:

bash
1curl https://api.markprompt.com/v1/train \
2  -X POST \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "files": [
7      { "path": "file_path_1", "content": "..." },
8      { "path": "file_path_2", "content": "..." },
9    ]
10  }'

Request body (file)

In the case of a file payload, the content type header must be application/zip or application/octet-stream.

Example request:

bash
1curl https://api.markprompt.com/v1/train \
2  -X POST \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-Type: application/zip" \
5  --data-binary @data.zip

Here is an example in JavaScript that reads a file from disk and sends it to the /train endpoint:

js
1const fs = require('fs')
2
3const file = fs.createReadStream('data.zip');
4
5await fetch('https://api.markprompt.com/v1/train', {
6  method: 'POST',
7  body: file,
8  headers: {
9    'Authorization': 'Bearer <TOKEN>',
10    'Content-Type': 'application/zip',
11  },
12});

Request headers

  • Authorization

    The authorization header, carrying the bearer token.

  • Content-Type

    The content type of the payload. Currently supported values are application/json, application/zip and application/octet-stream.

  • x-markprompt-force-retrain

    By default, if a file has been trained, sending it again with the same content will not retrain the file. If for some reason you want to force a retraining, you can pass a long this header with the value set to true.

Create chat completion

http
1POST https://api.markprompt.com/v1/chat

Creates a chat completion for the provided prompt, taking into account the content you have trained your project on.

Request body

KeyTypeDescription
messagesarrayA list of user and assistant messages to complete.
projectKeystringThe API key associated to your project. If shared publicly, use the production key from a whitelisted domain. If not, for instance on localhost, use the development key.
modelgpt-4 | gpt-4-32k | gpt-4-1106-preview | gpt-3.5-turbo | text-davinci-003 | text-davinci-002 | text-curie-001 | text-babbage-001 | text-ada-001 | davinci | curie | babbage | adaThe completions model to use.
systemPromptstringCustom system prompt that wraps prompt and context.
streambooleanIf true, return the response as a Readable Stream. Otherwise, return as a plain JSON object. Default: true.
doNotInjectContextbooleanIf true, do not inject the context in the full prompt unless the context tag is present in the template. Default false.
allowFollowUpQuestionsbooleanIf true, the bot may encourage the user to ask a follow-up question, for instance to gather additional information. Default true.
doNotInjectPromptbooleanIf true, do not inject the prompt in the full prompt unless the prompt tag is present in the template. Default false.
excludeFromInsightsbooleanIf true, exclude the prompt from insights. Default false.
redactbooleanIf true, redact sensitive data from prompt and response. Default false.
outputFormat"markdown" | "slack"Output format, e.g. Slack-flavored Markdown. Default markdown.
conversationIdstringIf provided, the prompt and response will be tracked as part of the same conversation in the insights.
conversationMetadataobjectAn arbitrary JSON payload to attach to a conversation, available in the insights.
temperaturenumberThe model temperature. Default: 0.1.
topPnumberThe model top P. Default: 1.
frequencyPenaltynumberThe model frequency penalty. Default: 0.
presencePenaltynumberThe model presence penalty. Default: 0.
maxTokensnumberThe max number of tokens to include in the response. Default: 500.
sectionsMatchCountnumberThe number of sections to include in the prompt context. Default: 10.
sectionsMatchThresholdnumberThe similarity threshold between the input question and selected sections. The higher the threshold, the more relevant the sections. If it's too high, it can potentially miss some sections. Default: 0.5.
debugbooleanIf set to true, the response will contain additional metadata, such as the full prompt, for debug or other purposes.

Example request

bash
1curl https://api.markprompt.com/v1/chat \
2  -X POST \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "messages": [
7      {
8        "role": "user",
9        "content": "What is Markprompt?"
10      },
11      {
12        "role": "assistant",
13        "content": "Markprompt is ..."
14      },
15      {
16        "role": "user",
17        "content": "Explain this to me as if I was a 3 year old."
18      }
19    ],
20    "model": "gpt-4"
21  }'

Response

By default, the response is returned as a ReadableStream of the form:

1So imagine a robot that can answer all the questions you have...

In addition to the stream, the response includes a header named x-markprompt-data, which is an encoded (Uint8Array) JSON object of the form:

json
1{
2  references: [
3    reference1,
4    reference2,
5    ...
6  ],
7  promptId: "...",
8  conversationId: "...",
9  debugInfo: { ... }
10}

It consists of the following:

  • The references (see below) used to generate the answer.
  • A promptId, which is a unique ID representing the message/answer pair.
  • A conversationId, which is a unique ID which can be passed on subsequent requests and represents a multi-message conversation.
  • If the debug parameter is set to true, a debugInfo object containing information about the query, such as the full prompt that was built for the query.
The reference object

A reference is an object of the form:

ts
1type FileSectionReference = {
2  file: {
3    title?: string;
4    path: string;
5    meta?: any;
6    source: Source;
7  },
8  meta?: {
9    leadHeading?: {
10      id?: string;
11      depth?: number;
12      value?: string;
13      slug?: string;
14    };
15  };
16}

and is meant to provide enough information for the client to be able to generate descriptive links to cited sources, including section slugs.

Parsing the header

Here is some example code in JavaScript to decode the references from the response header:

js
1const res = await fetch(
2  'https://api.markprompt.com/v1/chat',
3  { /*...*/ }
4);
5
6// JSON payload
7const encodedPayload = res.headers.get('x-markprompt-data');
8const headerArray = new Uint8Array(encodedPayload.split(',').map(Number));
9const decoder = new TextDecoder();
10const decodedValue = decoder.decode(headerArray);
11const payload = JSON.parse(decodedValue);
12// ...

If the stream flag is set to false, the response is returned as a plain JSON object with a text field containing the completion, and a references field containing the list of references used to create the completion:

json
1{
2  "text": "Completion response...",
3  "references": [reference1, reference2, ...]
4}

where references are objects of the form described above.

When querying chat completions, do not use the bearer token if the code is exposed publicly, for instance on a public website. Instead, use the project production key, and make the request from a whitelisted domain. Obtaining the project production key and whitelisting the domain is done in the project settings.

Here is a working example of how to consume the stream in JavaScript. Note the use of projectKey and no authorization header: this code can be shared publicly, and will work from a domain you have whitelisted in the project settings.

js
1const res = await fetch('https://api.markprompt.com/v1/chat', {
2  method: 'POST',
3  headers: {
4    'Content-Type': 'application/json',
5  },
6  body: JSON.stringify({
7    messages: [
8      {
9        role: "user",
10        content: "What is Markprompt?"
11      }
12    ],
13    projectKey: 'YOUR-PROJECT-KEY',
14    model: 'gpt-3.5-turbo'
15  }),
16});
17
18if (!res.ok || !res.body) {
19  console.error('Error:', await res.text());
20  return;
21}
22
23// JSON payload
24const encodedPayload = res.headers.get('x-markprompt-data');
25const headerArray = new Uint8Array(encodedPayload.split(',').map(Number));
26const decoder = new TextDecoder();
27const decodedValue = decoder.decode(headerArray);
28const { references } = JSON.parse(decodedValue);
29
30const reader = res.body.getReader();
31const decoder = new TextDecoder();
32let response = '';
33
34while (true) {
35  const { value, done } = await reader.read();
36  const chunk = decoder.decode(value);
37  response = response + chunk;
38  if (done) {
39    break;
40  }
41}
42
43console.info('Answer:', response);

Create completion

This endpoint is being deprecated in favor of the /chat endpoint.

http
1POST https://api.markprompt.com/v1/completions

Creates a completion for the provided prompt, taking into account the content you have trained your project on.

Request body

KeyTypeDescription
promptstringThe input prompt to generate completions for.
projectKeystringThe API key associated to your project. If shared publicly, use the production key from a whitelisted domain. If not, for instance on localhost, use the development key.
modelgpt-4 | gpt-4-32k | gpt-4-1106-preview | gpt-4-turbo-preview | gpt-3.5-turbo | text-davinci-003 | text-davinci-002 | text-curie-001 | text-babbage-001 | text-ada-001 | davinci | curie | babbage | adaThe completions model to use.
iDontKnowMessagestringMessage to return when no response is found.
promptTemplatestringCustom system prompt that wraps prompt and context.
streambooleanIf true, return the response as a Readable Stream. Otherwise, return as a plain JSON object. Default: true.
contextTagstringTag used in the prompt template to indicate where the context should be injected. Default {{CONTEXT}}.
promptTagstringTag used in the prompt template to indicate where the prompt should be injected. Default {{PROMPT}}.
idkTagstringTag used in the prompt template to indicate where the "I don't know" message should be injected. Default {{I_DONT_KNOW}}.
doNotInjectContextbooleanIf true, do not inject the context in the full prompt unless the context tag is present in the template. Default false.
allowFollowUpQuestionsbooleanIf true, the bot may encourage the user to ask a follow-up question, for instance to gather additional information. Default true.
doNotInjectPromptbooleanIf true, do not inject the prompt in the full prompt unless the prompt tag is present in the template. Default false.
excludeFromInsightsbooleanIf true, exclude the prompt from insights. Default false.
redactbooleanIf true, redact sensitive data from prompt and response. Default false.
outputFormat"markdown" | "slack"Output format, e.g. Slack-flavored Markdown. Default markdown.
temperaturenumberThe model temperature. Default: 0.1.
topPnumberThe model top P. Default: 1.
frequencyPenaltynumberThe model frequency penalty. Default: 0.
presencePenaltynumberThe model presence penalty. Default: 0.
maxTokensnumberThe max number of tokens to include in the response. Default: 500.
sectionsMatchCountnumberThe number of sections to include in the prompt context. Default: 10.
sectionsMatchThresholdnumberThe similarity threshold between the input question and selected sections. The higher the threshold, the more relevant the sections. If it's too high, it can potentially miss some sections. Default: 0.5.

Example request

bash
1curl https://api.markprompt.com/v1/completions \
2  -X POST \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "prompt": "How do I self-host the database?",
7    "iDontKnowMessage": "Sorry, I do not know.",
8    "model": "gpt-4"
9  }'

Response

By default, the response is returned as a ReadableStream of the form:

1[path1,path2,...]___START_RESPONSE_STREAM___In order to self-host...

The stream is split in two parts, separated by the ___START_RESPONSE_STREAM___ tag:

  • The first part of the stream is the list of references that were used to produce the content. Namely the page IDs containing the sections that were used in the final prompt. This part will be deprecated, in favor of response headers (see below).
  • The second part is the streamed response, which is the actual result that the completions endpoint produced as an answer to the input prompt.

In addition to the stream, full reference objects are returned in the x-markprompt-data header. It is an encoded (Uint8Array) JSON object of the form:

json
1{
2  references: [
3    reference1,
4    reference2,
5    ...
6  ]
7}

If the stream flag is set to false, the response is returned as a plain JSON object with a text field containing the completion, and a references field containing the list of references used to create the completion:

json
1{
2  "text": "Completion response...",
3  "references": [reference1, reference2, ...]
4}

where references are objects of the form described above.

When querying completions, do not use the bearer token if the code is exposed publicly, for instance on a public website. Instead, use the project production key, and make the request from a whitelisted domain. Obtaining the project production key and whitelisting the domain is done in the project settings.

Here is a working example of how to consume the stream in JavaScript. Note the use of projectKey and no authorization header: this code can be shared publicly, and will work from a domain you have whitelisted in the project settings.

js
1const res = await fetch('https://api.markprompt.com/v1/completions', {
2  method: 'POST',
3  headers: {
4    'Content-Type': 'application/json',
5  },
6  body: JSON.stringify({
7    prompt: 'How do I self-host a database?',
8    iDontKnowMessage: 'I don\'t know',
9    projectKey: 'YOUR-PROJECT-KEY',
10    model: 'gpt-3.5-turbo'
11  }),
12});
13
14if (!res.ok || !res.body) {
15  console.error('Error:', await res.text());
16  return;
17}
18
19// JSON payload
20const encodedPayload = res.headers.get('x-markprompt-data');
21const headerArray = new Uint8Array(encodedPayload.split(',').map(Number));
22const decoder = new TextDecoder();
23const decodedValue = decoder.decode(headerArray);
24const { references } = JSON.parse(decodedValue);
25
26const reader = res.body.getReader();
27const decoder = new TextDecoder();
28let response = '';
29
30while (true) {
31  const { value, done } = await reader.read();
32  const chunk = decoder.decode(value);
33  response = response + chunk;
34  if (done) {
35    break;
36  }
37}
38
39const parts = response.split('___START_RESPONSE_STREAM___');
40
41console.info('Answer:', parts[1]);

Sections

http
1GET https://api.markprompt.com/v1/sections

Retrieves a list of sections that match a prompt.

The /v1/sections endpoint is available as part of the Enterprise plan.

Request body

KeyTypeDescription
promptstringThe input prompt.
sectionsMatchCountnumberThe number of sections to retrieve. Default: 10.
sectionsMatchThresholdnumberThe similarity threshold between the input prompt and selected sections. The higher the threshold, the more relevant the sections. If it's too high, it can potentially miss some sections. Default: 0.5.

Example request

bash
1curl "https://api.markprompt.com/v1/sections?prompt=what%20is%20a%20component%3F&sectionsMatchCount=20&sectionsMatchThreshold=0.4" \
2  -X GET \
3  -H "Authorization: Bearer <TOKEN>" \
4  -H "Content-type: application/json" \
5  -H "Accept: application/json"

Response

The response is of the form:

json
1{
2  data: [
3    {
4      path: "/path/to/section/1",
5      content: "Section 1 content...",
6      similarity: 0.89
7    },
8    {
9      path: "/path/to/section/2",
10      content: "Section 2 content...",
11      similarity: 0.72
12    },
13    ...
14  ]
15}
http
1GET https://api.markprompt.com/v1/search

Retrieves a list of search result that match a query.

Request body

KeyTypeDescription
querystringThe search query string.
projectKeystringOptional, if not using an bearer token. The API key associated to your project. If shared publicly, use the production key from a whitelisted domain. If not, for instance on localhost, use the development key.
limitnumberThe maximum number of results to return. Default: 10.
includeSectionContentbooleanWhether to return the full content of matching sections, in addition to snippets. Default: false.

Example request

bash
1curl "https://api.markprompt.com/v1/search?query=react&limit=4" \
2  -X GET \
3  -H "Authorization: Bearer <TOKEN>"
4  -H "Content-type: application/json" \
5  -H "Accept: application/json"

Response

The response is of the form:

json
1{
2  data: [
3    searchResult1,
4    searchResult2,
5    ...
6  ]
7}

A search result is similar to a reference object used in completions references, with an additional field describing the match type:

ts
1type SearchResult = {
2  matchType: 'title' | 'leadHeading' | 'content',
3  file: {
4    title?: string;
5    path: string;
6    meta?: any;
7    source: Source;
8  },
9  meta?: {
10    leadHeading?: {
11      id?: string;
12      depth?: number;
13      value?: string;
14      slug?: string;
15    };
16  };
17}

Search results are ranked depending on the match type: higher weights are put on title matches, then section lead headings, and finally on content.

Insights

http
1GET https://api.markprompt.com/v1/insights/queries

Retrieves a list of prompt queries in the given time range.

Request body

KeyTypeDescription
fromstringThe start of the range, as an ISO 8601 string.
tostringThe end of the range, as an ISO 8601 string.
limitnumberThe maximum number of results to return. Default: 50.
pagenumberThe page index. Default: 0.

Example request

bash
1curl "https://api.markprompt.com/v1/insights/queries?from=2023-09-01T22%3A00%3A00&to=2023-12-31T22%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"

Response

The response is of the form:

json
1{
2  "queries": [
3    {
4      "id": "id-1",
5      "created_at": "2023-08-07T22:36:37.728248+00:00",
6      "prompt": "What is Markprompt?",
7      "no_response": null,
8      "feedback": null
9    },
10    {
11      "id": "id-2",
12      "created_at": "2023-08-07T22:40:04.527411+00:00",
13      "prompt": "What is the weather in Menlo Park?",
14      "no_response": true,
15      "feedback": {
16        "vote": "-1"
17      }
18    }
19  ]
20}