> ## Documentation Index
> Fetch the complete documentation index at: https://docs.isaacus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Making requests

> The basics of making requests to the Isaacus API

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

<CodeGroup>
  ```bash Python theme={null}
  pip install isaacus
  ```

  ```bash JavaScript theme={null}
  npm install isaacus
  ```
</CodeGroup>

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.

<CodeGroup>
  ```python Python theme={null}
  from isaacus import Isaacus

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

  ```javascript JavaScript theme={null}
  import { Isaacus } from 'isaacus';

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

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

<CodeGroup>
  ```python Python theme={null}
  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 JavaScript theme={null}
  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;
  ```
</CodeGroup>

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](https://aws.amazon.com/marketplace/seller-profile?id=seller-5e4iuidabgujc) 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](https://pypi.org/project/isaacus-sagemaker/) 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](/integrations/amazon-sagemaker).

The complete schema for the Isaacus SageMaker `/invocations` endpoint is as follows:

```python theme={null}
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."""

```