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](/docs/quickstart).

## Obtaining access
To access the Isaacus API, you must:
1. have an **active, email-verified account** on the [Isaacus Platform](https://platform.isaacus.com/), which you can create [here](https://platform.isaacus.com/accounts/signup);
2. be **subscribed** to our usage-based (no-flat-fee) API plan, which you can do [here](https://platform.isaacus.com/billing) (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](https://platform.isaacus.com/billing); and
4. have an **active API key**, which you can generate [here](https://platform.isaacus.com/users/api-keys).

You can use your [usage dashboard](https://platform.isaacus.com/usage) 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](https://pypi.org/project/isaacus/) and [server-side JavaScript/TypeScript](https://www.npmjs.com/package/isaacus) packages, which can be installed with `pip` and `npm`, respectively.

<DocsCodeGroup>

```bash Python
pip install isaacus
```

```bash JavaScript
npm install isaacus
```

</DocsCodeGroup>

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

```python
from isaacus import Isaacus

client = Isaacus(api_key="PASTE_YOUR_API_KEY_HERE")
```

```javascript
import { Isaacus } from 'isaacus';

// Create an Isaacus API client.
const client = new Isaacus({ apiKey: "PASTE_YOUR_API_KEY_HERE" });
```

</DocsCodeGroup>

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 /enrichments`](/docs/api-reference/enrichments/enrichment) - Enrich documents with an Isaacus enricher.
* [`POST /embeddings`](/docs/api-reference/embeddings/embedding) - Embed queries and documents with an Isaacus embedder.
* [`POST /rerankings`](/docs/api-reference/rerankings/reranking) - Rank documents by their relevance to queries with an Isaacus reranker.
* [`POST /extractions/qa`](/docs/api-reference/extractions/extractive-question-answering) - Extract answers to questions from documents with an Isaacus answer extractor.
* [`POST /classifications/universal`](/docs/api-reference/classifications/universal-classification) - Classify whether a query is true in respect of a document with an Isaacus universal 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.

<DocsCodeGroup>

```python
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
```

```javascript
import { Isaacus } from 'isaacus';

// Create an Isaacus API client.
const client = new Isaacus({ apiKey: "PASTE_YOUR_API_KEY_HERE" });

// Embed queries.
const response = await 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.
const embeddings = response.embeddings;
const firstEmbedding = embeddings[0].embedding;
const usage = response.usage;
```

</DocsCodeGroup>

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 <a href="https://aws.amazon.com/marketplace/seller-profile?id=seller-5e4iuidabgujc" target="_blank" rel="noopener noreferrer external">Amazon SageMaker</a> 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 <a href="https://pypi.org/project/isaacus-sagemaker/" target="_blank" rel="noopener noreferrer external">Isaacus SageMaker Python integration package</a> to automatically proxy requests for you instead of handling this manually. We explain how to get started with that package in our <a href="/docs/integrations/amazon-sagemaker" target="_blank" rel="noopener noreferrer external">SageMaker integration guide</a>.

The complete schema for the Isaacus SageMaker `/invocations` endpoint is as follows:
```python
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."""
```