Google Cloud Spanner API
Browse all Google APIsOfficial vendor OpenAPI document · agent-readyStorageDatabaseoauth250 EndpointsREST
For Agents
Run SQL queries and DML against globally distributed Cloud Spanner databases, manage schemas and instances, and orchestrate backups and restores. Sessions and transactions are first-class.
Use for: I want to run a SQL query against a Cloud Spanner database, Create a new Spanner instance with 3 nodes, List all databases in a Spanner instance, Take a backup of a Spanner database
Not supported: Does not handle ETL pipelines, BI dashboards, or Postgres-compatible drivers - use for Spanner instance, database, session, and backup management only.
The Cloud Spanner API exposes Google's globally distributed, strongly consistent relational database as REST operations. It covers instance and database lifecycle (create, list, update, drop), schema management via DDL, session-based read and write transactions, partitioned reads for parallel scans, and backup, restore, and point-in-time database operations. Long-running operations for backups, restores, and database moves are tracked through standard operations endpoints.
Install Jentic One Beta
Connect the Cloud Spanner API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Cloud Spanner API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fgoogleapis.com%2Fspanner" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fgoogleapis.com%2Fspanner" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Cloud Spanner API.
Provision Spanner instances and databases with chosen node counts and configurations
Apply DDL changes to evolve a database schema online
Open sessions, run SQL or partitioned reads, and commit or rollback transactions
Execute batched DML statements for high-throughput writes within a transaction
Take, list, and restore from backups, including copying backups across instances
Move a database between instance configurations or change quorum for regional failover
Use Cases
Patterns agents use Cloud Spanner API for, with concrete tasks.
★ Provision Spanner for a New Service
When a team launches a new globally distributed service, automation creates a Spanner instance, then a database with an initial DDL script defining tables and indexes. The Cloud Spanner API exposes instance creation as a long-running operation and database creation with extraStatements for first-pass schema, so a service can be storage-ready in minutes.
POST /v1/{+parent}/instances with config 'regional-us-central1' and nodeCount=3, then POST /v1/{+parent}/databases with createStatement and the initial DDL extraStatements.
Read-Only Analytics Query
Issue a read-only SQL query against a Spanner database from a reporting agent. The flow opens a session, executes the SQL with single-use bounded staleness for cheaper reads, and returns rows. Cloud Spanner's strong consistency makes this safe for cross-region analytics.
POST /v1/{+database}/sessions to open a session, POST sessions/{session}:executeSql with sql='SELECT name, count FROM Metrics WHERE day=@d' and a 60-second staleness.
Scheduled Backup and Restore Drill
Run a nightly backup of a production Spanner database and periodically test the restore path into a staging instance. The API supports POST /v1/{+parent}/backups for take, GET listing, and POST /v1/{+parent}/databases:restore for the restore path. Each is a long-running operation trackable via the operations endpoint.
Create a backup of database prod-db with expireTime=now+30d, then poll the returned operation until done; in staging, POST databases:restore with the backup name.
AI Agent Schema Evolution
An AI agent reviewing a feature request decides a new column is needed on a Spanner table. The agent searches Jentic for the DDL update operation, loads the schema, and submits an updateDdl request. Jentic returns a long-running operation handle so the agent can poll for completion before proceeding.
Search Jentic for 'apply DDL to a Spanner database', execute PATCH /v1/{+database}/ddl with statements=['ALTER TABLE Orders ADD COLUMN region STRING(2)'].
Key Endpoints
50 endpoints — the cloud spanner api exposes google's globally distributed, strongly consistent relational database as rest operations.
METHOD
PATH
DESCRIPTION
POST
/v1/{+database}/sessions
Create a session for executing reads and transactions
POST
/v1/{+database}/sessions:batchCreate
Create multiple sessions in one call
PATCH
/v1/{+database}/ddl
Apply DDL statements to evolve a database schema
GET
/v1/{+name}
Get an instance, database, backup, or operation by resource name
POST
/v1/{+name}:cancel
Cancel a long-running operation
POST
/v1/{+name}:move
Move a database between instance configurations
POST
/v1/{+name}:changequorum
Change the quorum configuration of a database
POST
/v1/{+database}/sessions
Create a session for executing reads and transactions
POST
/v1/{+database}/sessions:batchCreate
Create multiple sessions in one call
PATCH
/v1/{+database}/ddl
Apply DDL statements to evolve a database schema
GET
/v1/{+name}
Get an instance, database, backup, or operation by resource name
POST
/v1/{+name}:cancel
Cancel a long-running operation
POST
/v1/{+name}:move
Move a database between instance configurations
POST
/v1/{+name}:changequorum
Change the quorum configuration of a database
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Cloud Spanner API by hand means configuring a service account, minting OAuth access tokens against spanner.googleapis.com, and managing sessions and long-running operations yourself. Through Jentic you install once, import the Cloud Spanner API from the API Directory, store the OAuth credential once, and your agent calls it.
Permission scoping
Spanner puts the database or instance in the URL path (/v1/{database}/sessions, /v1/{name}:move), so a rule can pin your agent to one database: it can create sessions and apply DDL there and nothing else. You choose the operations it may call, so instance moves or changequorum are not included unless you add them.
Credential isolation
Your Spanner OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'run a SQL query against a Spanner database' or 'back up a Spanner database', and Jentic returns the matching Spanner operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Cloud Spanner API through Jentic.
What authentication does the Cloud Spanner API use?
The Cloud Spanner API uses OAuth 2.0 with the cloud-platform or spanner.data scope. Through Jentic, OAuth credentials are stored in your Jentic One instance and exchanged for short-lived access tokens, so service-account JSON keys never enter the agent context.
Can I run arbitrary SQL against a Spanner database with the API?
Yes. Open a session under POST /v1/{+database}/sessions, then call POST .../sessions/{session}:executeSql with the SQL string and any parameters. For DML, wrap the call in a transaction by including a transaction selector with begin or id fields.
What are the rate limits for the Cloud Spanner API?
Cloud Spanner enforces per-instance throughput limits scaled by node count rather than per-call quotas. There are also admin-API quotas (default ~5 requests per second for instance and database admin calls). Heavy DML or large reads should be chunked across sessions to fit within node throughput.
How do I take a Spanner backup through Jentic?
Search Jentic for 'back up a Cloud Spanner database', load the backups.create schema, then execute POST /v1/{+parent}/backups with the source database name and an expireTime. The response returns a long-running operation that Jentic surfaces so the agent can poll for completion.
Is the Cloud Spanner API free?
Cloud Spanner itself is billed per node hour and per GB of storage, with backup storage charged separately. The API surface has no per-call charge - costs come from the underlying instance running the queries.
Can I run a partitioned read for a large scan?
Yes. Call POST .../sessions/{session}:partitionRead or partitionQuery to get partition tokens, then issue parallel POST .../sessions/{session}:streamingRead calls - one per partition - to scan the table in parallel.
Can I limit what my agent is allowed to do with the Cloud Spanner API?
Yes. Because you run Jentic One yourself, your own rules decide which Spanner operations and which OAuth credential the agent can use. Since Spanner puts the database or instance in the URL path, such as /v1/{database}/sessions, you can pin the agent to a single database so it may only open sessions, run SQL, and apply DDL there. Destructive operations like moving a database or changing quorum stay off limits unless you explicitly add them.
GET STARTED