Magisterium AI

Magisterium API

Get up and running with the Magisterium API in a few minutes.

Create an API key

Go to your API Console to create an API Key.

Set up your API key

Configure your API key as an environment variable. This approach streamlines your API usage by eliminating the need to include your API key in each request. Moreover, it enhances security by minimizing the risk of inadvertently including your API key in your codebase.

In your terminal of choice:

export MAGISTERIUM_API_KEY=<your-api-key-here>
bash

Or, in your project’s .env file

MAGISTERIUM_API_KEY=<your-api-key-here>
bash

Make your first chat completion request

Execute this curl command in the terminal of your choice:

curl -X POST https://www.magisterium.com/api/v1/chat/completions \
  -H "Authorization: Bearer $MAGISTERIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "magisterium-1",
    "messages": [
      {
        "role": "user",
        "content": "What is the Magisterium?"
      }
    ]
  }'
bash

Citations

Magisterium AI API conforms to the OpenAI API, with a few additions in the response object. One addition is the citations field.

{
  "object": "chat.completion",
  "created": 1630000000,
  "model": "magisterium-1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The Catholic Church's teaching on faith and morals is deeply rooted in Scripture [...]",
      },
      "finish_reason": "stop",
    },
  ],
  "citations": [
    {
      "cited_text": "34. Church teaching on moral matters is founded not only on reason and argument, but also on Scripture and the Christian tradition [...]",
      "document_title": "Cherishing Life",
      "document_index": 0,
      "document_author": "Catholic Bishops’ Conference of England and Wales",
      "document_reference": "34"
    }
  ]
  // other fields ...
}
json

Streaming

The citations field is also included when stream is enabled, but only on one chunk, which is the last chunk that includes finish_reason.

For example:

{
  "object": "chat.completion.chunk",
  "choices": [
    {
      "index": 0,
      "delta": {},
      "finish_reason": "stop",
    },
  ],
  "citations": [
    {
      "cited_text": "34. Church teaching on moral matters is founded not only on reason and argument, but also on Scripture and the Christian tradition [...]",
      "document_title": "Cherishing Life",
      "document_index": 0,
      "document_author": "Catholic Bishops’ Conference of England and Wales",
      "document_reference": "34"
    }
  ]
  // other fields ...
}
json

Schema

The citations field is an array of objects with the following fields:

FieldTypeDescription
cited_textstringThe text that was cited.
cited_text_headingstring|nullThe nearest heading of the given citation.
document_titlestring|nullThe title of the document.
document_indexintegerThe index of the document in the response object. Index is zero-based, while inline footnotes numbering is one-based.
document_authorstring|nullThe author of the document.
document_yearstring|nullThe year the document was published.
document_referencestring|nullThe reference number of the citation.
source_urlstringThe source URL.

Related Questions

Magisterium AI API can also return related questions in the response object via the related_questions field. This field is optional. In order to return related questions, you must set the return_related_questions parameter to true in your request.

url = "https://www.magisterium.com/api/v1/chat/completions"
headers = {
  "Authorization": f"Bearer {api_key}",
  "Content-Type": "application/json",
}
data = {
  "model": "magisterium-1",
  "messages": [
    {
      "role": "user",
      "content": "What is the Magisterium?",
    }
  ],
  "stream": False,
  "return_related_questions": True
}
python

Related questions will be included in the response object as an array of strings.

{
  "object": "chat.completion",
  "related_questions": [
    "What is the Magisterium's teaching on faith and morals?",
    "What is the Magisterium's teaching on Scripture?",
    "What is the Magisterium's teaching on tradition?",
  ],
  // other fields ...
}
json

Streaming

Like citations, related questions are also included only in the last chunk.

Error handling

Here is an overview of the error codes you may encounter:

CodeMessageDescription
400Token limit exceededPlease ensure you are using the correct API key and sending it properly.
401Incorrect API key providedPlease ensure you are using the correct API key and sending it properly.
401Invalid billingYour billing is not set up properly. Please check your billing in your account dashboard.
401Tier not foundYou are currently on an invalid service tier. Please contact us for assistance.
429Too many requestsYou have exceeded the rate limit. Please check your usage and upgrade to a paid plan if necessary.
500Internal server errorIssue on our end. Please try again later, check our status page, or contact us for assistance.