TechPrufer
Get started
Pinecone
Pinecone logoPinecone · Feature trail

API Versioning

5 posts · Mar 2024 – Aug 2026

What this trail covers

Pinecone has introduced a date-based API versioning schema managed via a custom header, allowing for incremental changes and a clear, predictable, and manageable API lifecycle. Stable API versions are supported for a minimum of 12 months. The Global Control Plane API has been launched, using a global URL for all control plane operations, supported within Python, Node, and Java clients, and also via Terraform and Pulumi. This update also includes broader availability with a new serverless region.

All Pinecone trails
  1. Designing Agent-Friendly APIsThis post introduces principles for designing agent-friendly APIs, focusing on how to make APIs more robust and understandable for AI agents. Key contributions include: 1. Error Guidance: Designing errors with clear explanations, concrete fixes, and doc links, using machine-readable error codes (RFC 9457). 2. Context Budgeting: Bounding responses, prioritizing high-signal fields, and ensuring verifiable success in-band. 3. Self-Description: Implementing describe/capabilities endpoints and providing detailed, example-rich OpenAPI specifications. 4. Safe Machine Tempo: Ensuring idempotency, paceable rate limits, predictability, and boundary guardrails (dry-run/preview). It also discusses metrics like Turns-to-First-Successful-Call (TTFSC) and unattended task success rate.
  2. Introducing Pinecone API VersioningThis post details Pinecone's adoption of a date-based API versioning schema, moving away from traditional URL-path versioning. It explains the rationale behind this choice, emphasizing stability, predictability, and the flexibility to innovate. The implementation involves quarterly releases of stable and release candidate API versions, with stable versions supported for a minimum of 12 months. The post also outlines the corresponding updates to SDK client versions.
  3. Going Global: Building the Global Control Plane APIThis post details the engineering effort behind migrating from a regional control plane API to a global control plane API. The new API uses a global URL (`api.pinecone.io`) for all control plane operations, simplifying resource management across multiple environments and regions. The system leverages Google Cloud Spanner for high availability, geographical replication, and ACID-compliant transactions, backed by a globally replicated, highly available Rust API server and Google Cloud's global load balancer. Usability improvements include standardized naming, updated response types, and more accurate error handling.
  4. March Monthly Product UpdateThe Node.js client v2.1.0 now supports listing record IDs with a prefix, which is beneficial for managing RAG applications by enabling querying segments of content. This feature is also available in the Python client (v3.1.0 and later). The Python SDK has been updated to v3.2.0, adding four optional configuration properties for proxy support, allowing users to work within environments with proxy servers or network restrictions. Enterprise customers can now configure self-serve SSO for managing team access to Pinecone via SAML 2.0. The console has been refreshed with features like index shortcuts, an index browser with search and sorting capabilities, and filtering by index type (serverless, pod-based, or starter). A troubleshooting section has been added to the documentation.