# 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.