> ## 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. # Quickstart > Start building awesome applications with the Isaacus API in under 5 minutes Follow this short guide to get up and running with the Isaacus API by embedding your first query and document with [Kanon 2 Embedder](/models#embedding), the world's most accurate legal embedding model. If you're looking to perform tasks other than embedding with the Isaacus API such as [enrichment](/capabilities/enrichment) and [reranking](/capabilities/reranking), follow the first two steps of this guide to set up your account and API client, and then check out the [capabilities](/capabilities/) section of our documentation for information on how to use our API for those tasks. ## 1. Set up your account Head to the [Isaacus Platform](https://platform.isaacus.com/accounts/signup/) to [create a new account](https://platform.isaacus.com/accounts/signup/). Once signed up, [add a payment method](https://platform.isaacus.com/billing/) to claim your [free credits](/pricing/credits). Don't worry, there's no fee for having an account—all of our products are charged solely based on usage. After adding a payment method, [create a new API key](https://platform.isaacus.com/users/api-keys/). Make sure to keep your API key safe. You won't be able to see it again after you create it (you can always revoke it and issue a new one though). ## 2. Install the Isaacus API client Now that your account is set up, install our [Python](https://pypi.org/project/isaacus/) or [server-side JavaScript/TypeScript](https://www.npmjs.com/package/isaacus) API client (or check out our [API reference](/api-reference/) if you're not using either of those languages). If you're a customer of our AWS Marketplace models and are using Python, you should also install the [Isaacus SageMaker Python integration](https://pypi.org/project/isaacus-sagemaker/). ```bash Python theme={null} pip install isaacus // If you're an AWS Marketplace customer, also install our SageMaker integration: pip install isaacus-sagemaker ``` ```bash JavaScript theme={null} npm install isaacus ``` ## 3. Embed a document With our API client installed, let's embed our first query and document. To start, you need to **initialize the client with your API key**. You can do this by setting the `ISAACUS_API_KEY` environment variable or by passing it directly, which is what we're doing in this example. ```python Python theme={null} from isaacus import Isaacus client = Isaacus(api_key="PASTE_YOUR_API_KEY_HERE") # For async usage: # from isaacus import AsyncIsaacus # # aclient = AsyncIsaacus(api_key="...") # For AWS Marketplace customers: # from isaacus_sagemaker import IsaacusSageMakerRuntimeHTTPClient, \ # IsaacusSageMakerRuntimeEndpoint # endpoints = [IsaacusSageMakerRuntimeEndpoint(name="your-endpoint-name")] # http_client = IsaacusSageMakerRuntimeHTTPClient(endpoints=endpoints) # client = Isaacus(http_client=http_client) ``` ```javascript JavaScript theme={null} import { Isaacus } from 'isaacus'; const client = new Isaacus({ apiKey: "PASTE_YOUR_API_KEY_HERE" }); ``` Next, let's grab a document to embed. For this example, we'll use [GitHub's terms of service](https://github.com/terms). ```python Python theme={null} import httpx tos = httpx.get("https://examples.isaacus.com/github-tos.md").text ``` ```javascript JavaScript theme={null} const tos = await client.get("https://examples.isaacus.com/github-tos.md"); ``` We're going to embed the terms of service using [Kanon 2 Embedder](/models#embedding), the [most accurate](https://isaacus.com/blog/introducing-kanon-2-embedder/) legal embedding model. What is an embedder? An [embedder](/capabilities/embedding) is an AI model that converts content into a highly compressed numerical representation, known as an embedding, that can be compared mathematically with other embeddings to quantify how similar they are in meaning. Embeddings are used to power semantic search engines, text classification, and cluster analysis as well as the retrieval component of retrieval-augmented generation (RAG) applications. Right now, we're interested in retrieving the GitHub terms of service given a search query about it. To do that, we'll first embed the document using the `.embeddings.create()` method of our API client. We'll also make sure to flag that we're embedding a document by setting the [`task`](/api-reference/embeddings/embedding#body-task) parameter to `"retrieval/document"`. This will help our embedder produce an embedding that is optimized specifically for being retrieved. We recommend always setting the `task` parameter to either `"retrieval/document"` or `"retrieval/query"` when using our embedders for retrieval tasks, even if the text in question is not strictly a document or a query, so long as one text is being treated as something to be retrieved, and the other as something to retrieve it with. If necessary, you can also request a lower-dimensional embedding using the optional [`dimensions`](/api-reference/embeddings/embedding#body-dimensions) parameter, which can help speed up similarity comparisons and save on vector storage costs at the cost of some diminution in accuracy. The default (and maximum) dimensionality for Kanon 2 Embedder is $1,792$. ```python Python theme={null} document_response = client.embeddings.create( model="kanon-2-embedder", texts=tos, # You can pass a single text or a list of texts here. task="retrieval/document", ) ``` ```javascript JavaScript theme={null} const document_response = await client.embeddings.create({ model: "kanon-2-embedder", texts: tos, // You can pass a single text or an array of texts here. task: "retrieval/document", }); ``` Since we only passed a single document to the embedder, let's unpack the first embedding result, accessible at `document_response.embeddings[0]`, in addition to our usage statistics. ```python Python theme={null} document_embedding_data = document_response.embeddings[0] document_embedding = document_embedding_data.embedding document_index = document_embedding_data.index document_embedding_usage = document_response.usage ``` ```javascript JavaScript theme={null} const document_embedding_data = document_response.embeddings[0]; const document_embedding = document_embedding_data.embedding; const document_index = document_embedding_data.index; const document_embedding_usage = document_response.usage; ``` [`document_response.embeddings`](/api-reference/embeddings/embedding#response-embeddings) is an array of embedding results, sorted in the same order as the input texts. Each embedding result contains [`embedding`](/api-reference/embeddings/embedding#response-embeddings-embedding), which is the actual embedding, and [`index`](/api-reference/embeddings/embedding#response-embeddings-index), which is the index of the input text that the embedding corresponds to (starting from $0$). [`document_response.usage`](/api-reference/embeddings/embedding#response-usage) contains statistics about the usage of resources in the process of generating the embedding. [`document_response.usage.input_tokens`](/api-reference/embeddings/embedding#response-usage-input-tokens) will give you the number of [tokens](/tokenization) inputted into the embedder, which you can cross-reference with our [pricing](/pricing/) to estimate the cost of embedding the document (excluding applicable taxes). Now, let's embed two search queries, one that is clearly relevant to the document and another that is clearly irrelevant. This time we set our `task` parameter to `"retrieval/query"` to indicate that we're embedding a search query. ```python Python theme={null} query_responses = client.embeddings.create( model="kanon-2-embedder", texts=[ "What are GitHub's billing policies?", # This is a relevant query. "What are Microsoft's billing policies?", # This is an irrelevant query. ], task="retrieval/query", ) query_embeddings = query_responses.embeddings relevant_query_embedding = query_embeddings[0].embedding irrelevant_query_embedding = query_embeddings[1].embedding ``` ```javascript JavaScript theme={null} const query_responses = await client.embeddings.create({ model: "kanon-2-embedder", texts: [ "What are GitHub's billing policies?", // This is a relevant query. "What are Microsoft's billing policies?", // This is an irrelevant query. ], task: "retrieval/query", }); const query_embeddings = query_responses.embeddings; const relevant_query_embedding = query_embeddings[0].embedding; const irrelevant_query_embedding = query_embeddings[1].embedding; ``` To assess the relevance of the queries to the document, we can compute the cosine similarity between their embeddings and the document embedding. Cosine similarity measures how similar two sets of numbers are (specifically, the cosine of the angle between two vectors in an inner product space). In theory, it ranges from $-1$ to $1$, with $1$ indicating that the vectors are identical, $0$ indicating that they are orthogonal (i.e., completely dissimilar), and $-1$ indicating that they are diametrically opposed. In practice, however, it tends to range from $0$ to $1$ for text embeddings (since they are usually non-negative). Our embedders have been optimized such that the cosine similarity of the embeddings they produce roughly corresponds to how similar the original texts are in meaning. Unlike our [rerankers](/capabilities/reranking) or [universal classifiers](/capabilities/universal-classification), however, our embedders' scores have not been calibrated to be interpreted as probabilities, only as relative measures of similarity, making them most useful for ranking search results. For the sake of convenience, our Python example uses [`numpy`](https://numpy.org/)'s `dot` function to compute the dot product of our embeddings (which is equivalent to their cosine similarity since all our embeddings are L2-normalized) (you can run `pip install numpy` to install it if you don't have it already). If you prefer, you can use another library to compute the cosine similarity of the embeddings (e.g., [`torch`](https://pytorch.org/) via `torch.nn.functional.cosine_similarity`), or you could write your own implementation (as we do for our JavaScript example). ```python Python theme={null} import numpy as np # NOTE You may need to run `pip install numpy`. relevant_similarity = np.dot(relevant_query_embedding, document_embedding) irrelevant_similarity = np.dot(irrelevant_query_embedding, document_embedding) print(f"Similarity of relevant query to the document: {relevant_similarity * 100:.2f}") print(f"Similarity of irrelevant query to the document: {irrelevant_similarity * 100:.2f}") ``` ```javascript JavaScript theme={null} // Define a function to compute the dot product of two vectors. function dot(a, b) { let sum = 0; for (let i = 0; i < a.length; i++) { sum += a[i] * b[i]; } return sum; } const relevant_similarity = dot(relevant_query_embedding, document_embedding); const irrelevant_similarity = dot(irrelevant_query_embedding, document_embedding); console.log(`Similarity of relevant query to the document: ${(relevant_similarity * 100).toFixed(2)}`); console.log(`Similarity of irrelevant query to the document: ${(irrelevant_similarity * 100).toFixed(2)}`); ``` The output should look something like this: ``` Similarity of relevant query to the document: 52.87 Similarity of irrelevant query to the document: 24.86 ``` As you should see, the relevant query has a much higher similarity score to the document than the irrelevant query, indicating that our embedder has successfully captured the semantic meaning of the texts. And that's it! You've just successfully embedded a document and queries using the Isaacus API. ## 4. Next steps Beyond the examples we've shared here, there's a lot more that you can do with the Isaacus API. To learn how to take full advantage of the API, you can check out our: 1. [Capabilities section](/capabilities/), which covers the full range of tasks the Isaacus API supports, including [embedding](/capabilities/embedding), [enrichment](/capabilities/enrichment), and [reranking](/capabilities/reranking). 2. [API reference](/api-reference/), which documents how to interface with our API and the endpoints and parameters that are available. 3. [Pricing section](/pricing/), which shows just how affordable our API is. If you're ever unsure about how to use the Isaacus API or if you have any other questions, we also encourage you to [reach out](https://isaacus.com/contact) to us. We're always happy to help.