Skip to main content

Create embeddings

POST /projects/:projectid/embeddings

Converts text into numeric vectors for semantic search, similarity, and related applications. It does not store vectors, search a database, or read Library files for you.

Authentication and request​

Use a project key with embeddings.create in Authorization, without Bearer. Replace :projectid with the key's project ID and send Content-Type: application/json.

The required input field accepts:

  • One non-empty string.
  • A non-empty array of non-empty strings, for a batch.

Whitespace-only strings and non-string array entries are rejected. There is no public model-tier, dimension, or encoding-format selection on this endpoint.

Using the Quickstart variables:

curl --include --request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--data '{"input":["Customers can cancel before renewal.","Orders are delivered within five working days."]}' \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/embeddings"

Response​

200 OK returns one embedding per input, in the same order:

{
"data": [
{"embedding": [0.12, -0.03, 0.08]},
{"embedding": [0.04, 0.11, -0.07]}
]
}

The vectors above are shortened illustrative values, not their actual dimension. A single-string request still returns a data array. Pair data[i].embedding with input i; the response does not attach your document IDs.

Vectors are normalised. Inspect the actual vector length when configuring storage, and use a compatible embedding process for both stored documents and search queries.

Prepare useful inputs​

Extract text before calling the endpoint. A file ID, path, or URL sent as input is just text to embed; it does not fetch the document.

Split large documents into meaningful passages and retain their source identifiers separately. Long inputs may be truncated, so do not rely on one request preserving every part of a large document. Use manageable batches and avoid mixing vectors from incompatible embedding spaces.

For a search pipeline, retrieve candidates using your vector store and optionally rerank them before generating an answer.

Errors​

  • 400: missing/empty input or invalid input types, returned as BAD_REQUEST with a message.
  • 401: missing or invalid project credential.
  • 403: missing embeddings.create.
  • 429: request-rate limit reached.
  • 502: embedding generation failed, returned as UPSTREAM_FAILURE.

See Errors, limits and retries. Repeating generation can consume additional service usage.