Skip to main content
This guide covers everything you need to know to be able to make requests to the Isaacus API. For a less technical walkthrough of the Isaacus API, please consult our quickstart guide.

​
Obtaining access

To access the Isaacus API, you must:
  1. have an active, email-verified account on the Isaacus Platform, which you can create here;
  2. be subscribed to our usage-based (no-flat-fee) API plan, which you can do here (if you’ve unsubscribed from that plan, you can use that same link to resubscribe);
  3. not have any overdue invoices, which you can pay here; and
  4. have an active API key, which you can generate here.
You can use your usage dashboard to monitor your API usage.

​
Accessing the API

The Isaacus API is a RESTful API that can be accessed using any tool or programming language that supports HTTP requests. To make interfacing with the Isaacus API easier than using raw HTTP requests, we also offer and recommend using our Python and server-side JavaScript/TypeScript packages, which can be installed with pip and npm, respectively. 
pip install isaacus
The current base URL of the Isaacus API is https://api.isaacus.com/v1. You don’t need to manually set this URL as your base URL when using our SDKs.

​
Authentication

If you are using one of our SDKs, you can authenticate with the Isaacus API by either setting the ISAACUS_API_KEY environment variable or by passing your API key directly to your client constructor. 
from isaacus import Isaacus

client = Isaacus(api_key="PASTE_YOUR_API_KEY_HERE")
If you are making raw HTTP requests to the Isaacus API, then you must include an Authorization header in the format Bearer PASTE_YOUR_API_KEY_HERE.

​
Endpoints

The Isaacus API currently offers the following endpoints:
  • POST /embeddings - Embed legal queries and documents with an Isaacus legal AI embedder.
  • POST /rerankings - Rerank legal documents by their relevance to a query with an Isaacus legal AI reranker.
  • POST /extractions/qa - Extract answers to questions from legal documents with an Isaacus legal AI answer extractor.
  • POST /classifications/universal - Classify the relevance of a legal document to a query with an Isaacus universal legal AI classifier.
When using our SDKs, you can access these endpoints by translating them into method calls, with POST requests using the create() method and GET requests using the get() method. For example, to call POST /embeddings, you would use the method client.embeddings.create().

​
Requests and responses

Our SDKs accept request parameters in the form of function arguments and they return responses in the form of objects, as shown below. 
from isaacus import Isaacus

# Create an Isaacus API client.
client = Isaacus(api_key="PASTE_YOUR_API_KEY_HERE")

# Embed queries.
response = client.embeddings.create(
    model="kanon-2-embedder",
    texts=[
        "Are restraints of trade enforceable under English law?",
        "What is a non-compete clause?",
    ],
    task="retrieval/query",
)

# Unpack the results.
embeddings = response.embeddings
first_embedding = embeddings[0].embedding
usage = response.usage
When making raw HTTP requests to the Isaacus API, you must ensure that all request bodies (e.g., POST requests) are formatted as JSON and that the Content-Type header is set to application/json. The response will also be formatted as JSON.

​
Amazon SageMaker

All private deployments of Isaacus models on Amazon SageMaker offer feature parity with the Isaacus API. The only difference is that, due to SageMaker constraints, requests must be proxied through the /invocations endpoint. Also, since SageMaker deployments are private to your AWS account, Isaacus API keys are not required when making requests to them (if passed, they will simply be ignored). For example, if you wanted to send a POST request to /v1/embeddings with the data {"model": "kanon-2-embedder", "texts": ["This is a confidentiality clause."], "task": "retrieval/query"}, you could do so by sending /invocations the payload {"path": "/v1/embeddings","data": {"model": "kanon-2-embedder", "texts": ["This is a confidentiality clause."], "task": "retrieval/query"}}. Assuming the model being invoked supports the endpoint being used, you should receive the exact same response the online Isaacus API would have returned (allowing for slight numerical differences due to different hardware being used). When an error occurs, SageMaker will wrap the original Isaacus API error message with its own message. To find the original error message and status code, check the OriginalMessage and OriginalStatusCode keys. We recommend using the Isaacus SageMaker Python integration package to automatically proxy requests for you instead of handling this manually. We explain how to get started with that package in our SageMaker integration guide. The complete schema for the Isaacus SageMaker /invocations endpoint is as follows: 
class SageMakerInvocationRequest(Struct):
    path: str
    """
    The path of the API endpoint being invoked (e.g., `/v1/embeddings`).
    """

    method: str = "POST"
    """
    The HTTP method used for the invocation (e.g., `POST`). Defaults to `POST`.
    """

    headers: dict[str, str] | None = None
    """
    The HTTP headers to include in the invocation request. \
    Defaults to `null`/`None`, in which case no additional headers are sent.
    """

    data: Any = None
    """
    The data to be sent as the body of the invocation request. \
    This can be any Python-serializable object. \
    Defaults to `null`/`None`, in which case no body is sent."""