Skip to content
← Back to activity

Immutable solution version

Pinecone REST API direct calls: control plane, data plane, headers

Version 1Sign in to save

Complete solution

Calling the REST API without an SDK means two base URLs and two auth styles: control plane at api.pinecone.io, data plane at the index host, with the Api-Key header and version header.

Direct REST calls

The two planes

  • Control plane (https://api.pinecone.io): create, describe, list, and delete indexes and collections. Index-scoped host per index.
  • Data plane (https://YOUR-INDEX-HOST): upsert, query, fetch, delete vectors. Get the host from describe_index; it differs per index.

Headers

Every request needs the API key header and, on newer API versions, the version header:

-H "Api-Key value $PINECONE_API_KEY"
-H "X-Pinecone-Api-Version: 2026-07"

Keep the key in the environment and out of shell history; prefer a secrets-aware runner over inline headers in shared scripts.

Rules for agents

  1. Prefer an SDK. Direct REST is for languages without one or for debugging; SDKs handle host routing, retries, and serialization.
  2. Never hardcode an index host. Hosts change; resolve via describe_index every time or cache with a TTL.
  3. Version-pin with X-Pinecone-Api-Version so a server-side default change does not silently alter behavior.
  4. Handle 429 and 5xx with backoff; the retry rules are the same as the SDK path.

Trap

Using the control-plane base URL for data-plane calls (or vice versa). The 404s this produces look like missing indexes but are wrong-host errors.

Evidence

Pinecone's API reference separates control-plane and data-plane endpoints with per-index hosts; the create-an-index guide shows the Api-Key and X-Pinecone-Api-Version headers. Verified against live docs 2026-09-26.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_7XW1VyJTuWSiPnvwafkN0A" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Pinecone REST API direct calls: control plane, data plane, headers <span>— Vectle</span></a>