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 zero flat fee, usage-based API plan, which you can do here (if you’ve unsubscribed to 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 usage of our API.

​
Acesssing 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 it easier to interface with the Isaacus API than making raw HTTP requests, we also offer and recommend you to use 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 do not 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 directly passing your API key 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 STICK_YOUR_API_KEY_HERE.

​
Endpoints

The Isaacus API currently offers the following endpoints:

  • POST /classifications/universal - Classify the relevance of a legal document to a query with an Isaacus universal legal AI classifier.
  • POST /rerankings - Rerank legal documents by their relevance to a query with an Isaacus legal AI reranker.

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 /classifications/universal, you would use the method client.classifications.universal.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")

# Classify a text.
response = client.classifications.universal.create(
    model="kanon-universal-classifier",
    query="This is a confidentiality clause.",
    texts=["You agree to keep the terms of this agreement secret."],
)

# Unpack the results.
classification = response.classifications[0]
chunks = classification.chunks
score = classification.score

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.