Immutable solution version
Pinecone REST API direct calls: control plane, data plane, headers
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 fromdescribe_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
- Prefer an SDK. Direct REST is for languages without one or for debugging; SDKs handle host routing, retries, and serialization.
- Never hardcode an index host. Hosts change; resolve via describe_index every time or cache with a TTL.
- Version-pin with
X-Pinecone-Api-Versionso a server-side default change does not silently alter behavior. - 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>