Pinecone

Pinecone stores vectors and returns the nearest ones to a query. Here that lives inside /v1/ai (272 operations) — stores, vectors, and an ingest path that parses, chunks and embeds in one call — with /v1/index (17) as the lexical half and POST /v1/search fusing both by reciprocal rank. The structural difference is where the tenant comes from: Pinecone partitions with a namespace string passed on every data-plane call, so isolation is a discipline your code keeps, while here the org is minted from the validated key's owner claim and no request body can name another one.

Start here

Ingest a document and search it. There is no index to create first — the store is named on the call, and the org it belongs to comes from the key.

# 1. mint a key — sk- belongs on a server, pk- is safe in a browser
curl -sS -X POST https://api.hanzo.ai/v1/account/keys \
  -H "Authorization: Bearer $HANZO_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"type":"secret"}'

# 2. ingest — parse, chunk and embed in one call, no embedding step of your own
curl -sS -X POST https://api.hanzo.ai/v1/ai/rag/ingest \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"store":"docs","text":"Hanzo IAM issues OIDC tokens.","metadata":{"src":"handbook"}}'

# 3. search it — semantic and lexical fused by reciprocal rank
curl -sS -X POST https://api.hanzo.ai/v1/search \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query":"how do tokens get issued","stores":["docs"]}'

Three calls and you have retrieval. Pinecone's equivalent needs an index created on the control plane, its host read back, an embedding model called yourself, and a namespace passed on every data-plane call after that.

Core capabilities

Nouns

The index, and the namespace inside it

/v1/provisioning (28) · /v1/ai (272) · /v1/index (17)

The physical collection name is derived from your slug under an org-namespacing hash, so it is not the slug and two orgs cannot land on one.

Records

/v1/ai (272) · /v1/index (17)

Query, and the inference beside it

/v1/ai (272) · /v1/search (1) · /v1/knowledge (9)

The call

Pinecone, from nothing to a first result:

# 1. create the index — dimension and metric are fixed here, permanently
curl -sS -X POST https://api.pinecone.io/indexes \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H 'X-Pinecone-API-Version: 2025-04' \
  -H 'Content-Type: application/json' \
  -d '{"name":"docs","dimension":1024,"metric":"cosine",
       "spec":{"serverless":{"cloud":"aws","region":"us-east-1"}}}'

# 2. poll until ready, and read back the host this index answers on
HOST=$(curl -sS https://api.pinecone.io/indexes/docs \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H 'X-Pinecone-API-Version: 2025-04' | jq -r .host)

# 3. embed on one hostname, write on the other
curl -sS -X POST https://api.pinecone.io/embed \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H 'X-Pinecone-API-Version: 2025-04' \
  -H 'Content-Type: application/json' \
  -d '{"model":"multilingual-e5-large","inputs":[{"text":"the Q3 roadmap"}]}'

curl -sS -X POST "https://$HOST/vectors/upsert" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"namespace":"acme","vectors":[
        {"id":"doc-1","values":[0.02,0.31],"metadata":{"user":"alice"}}]}'

# 4. query, reusing the vector rather than embedding the text again
curl -sS -X POST "https://$HOST/query" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"namespace":"acme","topK":5,"vector":[0.02,0.31],
       "filter":{"user":{"$eq":"alice"}},"includeMetadata":true}'

Hanzo, the same thing:

curl -sS -X POST https://api.hanzo.ai/v1/ai/rag/ingest \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"source":"upload","store":"docs",
       "documents":[{"id":"doc-1","text":"the Q3 roadmap"}]}'

curl -sS -X POST https://api.hanzo.ai/v1/search \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query":"roadmap","mode":"hybrid","limit":5}'

Five calls across two hostnames become two against one, and it is five only because the query reuses the vector from the upsert instead of embedding the query text again. There is no index host to resolve, because an index is a row rather than an appliance; and no namespace in either body, because the org is minted from the validated bearer's owner claim, so two orgs both holding a docs index have no way to write each other's name down. The write is applied before its response — GET /v1/index/tasks/{uid} reports succeeded on the first poll and isIndexing in GET /v1/index/stats is always false — so the query that follows a write sees it, rather than seeing it soon. Pinecone asks you to keep the index name, the resolved host, the namespace, the record id, the metadata key and the embedding model's output width in step; here it is the store name and the document id.

The metadata filter is the one place that takes two calls, because an attribute has to be declared filterable before a query may constrain it:

curl -sS -X PATCH https://api.hanzo.ai/v1/index/indexes/docs/settings \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"filterableAttributes":["user","conversationId"]}'

curl -sS -X POST https://api.hanzo.ai/v1/index/indexes/docs/search \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"q":"roadmap","filter":"user = alice","limit":20}'

What does not carry

Namespace is not a field, and the one-call namespace drop goes with it. Pinecone puts thousands of end-user partitions in one index and deletes one with a single call. The org here comes from the key, project is the one narrowing coordinate beneath it, and per-end-user scoping is a filterable attribute — a filter, not a partition. Deleting one user's records is a list of keys at POST /v1/index/indexes/{uid}/documents/delete-batch, not a namespace drop.

You cannot query by a vector you computed yourself. Every query endpoint in this document takes text: query on POST /v1/search, q on the index search, query on POST /v1/knowledge/search. If you embed with your own model — images, a fine-tune, anything outside POST /v1/embeddings — the answer is POST /v1/provisioning/vector, which hands back a host, a port and a connection string once, and you speak the backend's own protocol to it.

No sparse values on either side. Pinecone's hybrid is a dense vector and a sparse one you build and send together. Here hybrid is two engines — a lexical index and a semantic one — fused by reciprocal rank at POST /v1/search, which reports each leg's status and timing in backends. That is a different mechanism, not a different spelling: there is nowhere to put a sparse encoding you built.

No dimension and no metric to choose. POST /v1/provisioning/vector takes a name; POST /v1/index/indexes takes a uid and an optional primaryKey. Nothing takes a width or a distance function. The semantic leg is cosine — score on a knowledge hit is documented as cosine similarity from -1 to 1 — and changing embedding model means re-ingesting, because nothing converts vectors of one width into another.

No snapshot and restore. Pinecone backs an index up to a collection or a backup and restores it into a new index. No route here does that. A corpus is rebuilt from its source instead: POST /v1/ai/rag/ingest naming github, crawl or s3, or POST /v1/knowledge/import for an exported vault.

No capacity to size. Pods, replicas, pod_type and configure_index have no equivalent. A create body is a name plus an optional instance binding; a shared-backend create answers ready, and a dedicated one answers 201 while it is still launching and reaches ready only when a later read reconciles it against the operator's live record. Nothing sets throughput.