docs(api): document canonical v1 routes

[DarrenBaldwin07]

Summary

• advertise https://api.tembo.io/v1/ as the canonical hosted API base
• advertise /api/public-api/v1/ as the canonical self-hosted API base
• update curl, SDK, OpenAPI, and Snowflake examples to use the versioned routes
• correct the self-hosted follow-up-message sample so it uses the self-hosted host

Validation

• parsed both OpenAPI YAML files successfully
• confirmed hosted and self-hosted specs expose matching operation paths
• scanned the API docs for stale versionless public endpoint URLs
• ran git diff --check

Rollout

This documentation should merge after the API /v1 routing change is deployed. Hosted versionless URLs remain backward-compatible, but /v1 is the canonical documented contract.

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

    

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tembo	🟢 Ready	View Preview	Aug 22, 2026, 3:54 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[tembo]

Recommendation: close this PR without merging.

The proposed /v1 prefix is not implemented for the legacy session, repository, agent, or MCP routes in published releases v0.2.826 through v0.2.828, and current main still mounts those routes without /v1. No published or draft release contains the routing change described here.

The ongoing resource API rollout does use /public-api/v1, but with different plural routes and contracts (for example, /public-api/v1/agents and /public-api/v1/repositories). Therefore paths such as /v1/session/list, /v1/agent, and /v1/mcp will not become correct merely when that rollout finishes.

The self-hosted hostname correction is valid and can be preserved in a separate focused change, but the versioned route replacements and the OpenAPI/Snowflake examples should not ship as written.