canonical: https://jentic.com/apis/googleapis.com/firestore # Google Cloud Firestore API The Cloud Firestore API provides programmatic access to Google's serverless NoSQL document database. It supports document reads and writes, transactions, structured queries, listen streams, and administrative operations on databases, indexes, and backups. Firestore is designed for automatic scaling and strong consistency at any scale, making it a fit for both mobile apps and server-side workloads. ## For AI agents Read, write, query, and stream document data in Cloud Firestore, plus manage databases, indexes, and backups. Suited for agents that need a scalable NoSQL store with transactional guarantees. ## Scope Does not handle SQL queries, relational joins, or analytics aggregation - use BigQuery for analytics and Spanner for SQL workloads; this API is for document storage and queries only. ## Capabilities - Read documents by name with strong or eventual consistency via documents.get - Run structured queries against a collection with documents:runQuery - Commit batched writes atomically with documents:commit and documents:batchWrite - Begin and roll back multi-document transactions - Manage Firestore databases, indexes, and field configurations - Schedule and restore backups for disaster recovery - Listen for realtime document changes via documents:listen ## Use cases ### Server-Side Document Reads and Writes Backend services need a scalable NoSQL store for user profiles, orders, or session state. Cloud Firestore exposes commit, batchWrite, and runQuery endpoints that give server code transactional document access without managing database servers. Reads return strongly consistent results within a region, and the API scales automatically with traffic. Example prompt: Call POST /v1/projects/{project}/databases/{database}/documents:commit with a write that creates a user document at users/{uid} and verify the commit time. ### Run Structured Queries from a Service Reporting jobs and back-office tools need to query Firestore by field equality, ranges, and ordering. The runQuery endpoint accepts a structured query proto and streams matching documents back, supporting both ad-hoc reports and scheduled extraction jobs. Composite indexes are managed via the same API so the query plan can be guaranteed. Example prompt: Call POST /v1/projects/{project}/databases/{database}/documents:runQuery with a structured query that selects orders where status equals 'paid' in the last 24 hours. ### Backup and Restore Firestore Databases Operators need scheduled backups for disaster recovery and point-in-time recovery options. The Firestore API exposes backup schedules and restore operations on the database resource so backups can be created, listed, and used to restore a new database. This supports compliance retention policies and rollback after data corruption. Example prompt: Call POST /v1/projects/{project}/databases/{database}/backupSchedules to create a daily backup schedule and confirm the schedule id. ### Agent-Driven Document Updates An AI agent acting on a user instruction can read or update a Firestore document through Jentic. The agent searches for the right operation by intent, loads the request schema, and executes commit or runQuery without holding a service account key. This makes Firestore a viable agent-native datastore for application memory or task state. Example prompt: Use Jentic to search 'update a firestore document', load the documents:commit schema, and execute it to set the status field on a specific document. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v1/{+database}/documents:commit | Commit a batch of writes atomically | | POST | /v1/{+database}/documents:batchGet | Read multiple documents in one call | | POST | /v1/{+database}/documents:beginTransaction | Start a Firestore transaction | | POST | /v1/{+database}/documents:rollback | Roll back a transaction | | POST | /v1/{+database}/documents:listen | Listen for realtime document changes | | GET | /v1/{+name} | Get a single Firestore document | | PATCH | /v1/{+name} | Update fields on a Firestore document | ## Key resources - **documents** — Read, write, query, listen, and transact over Firestore documents. - **databases** — Create and manage Firestore databases within a project. - **indexes** — Manage composite indexes for query performance. - **backupSchedules** — Schedule and list Firestore backups. ## Why Jentic - **Setup:** Wiring the Cloud Firestore API by hand means standing up Google OAuth 2.0 with a service account, choosing the datastore or cloud-platform scope, and managing transactions, commits, and batch reads yourself. Through Jentic you install once, import the Cloud Firestore API from the API Directory, store the service-account credential once, and your agent calls it. - **Permission scoping:** Firestore puts the database and document resource in the URL path (/v1/{database}/documents:commit, /v1/{name}), so a rule can pin your agent to one database: it can read and write documents there and nothing else. You choose the operations it may call, so a document patch is not included unless you add it. - **Credential handling:** Your Google service-account 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. - **Discovery method:** Agents search Jentic by intent such as 'commit a Firestore write' or 'query Firestore documents', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Cloud Datastore API** — The legacy Datastore mode of the same backend, with a different query model. - **Firebase Realtime Database API** — Firebase's older JSON tree database, optimised for low-latency sync. - **Cloud Spanner API** — Globally distributed relational database with SQL and strong consistency. - **BigQuery API** — Analytical data warehouse often loaded from Firestore exports. ## FAQ ### What authentication does the Cloud Firestore API use? It uses Google OAuth 2.0 with the cloud-platform or datastore scope. Through Jentic, service account credentials are stored encrypted in the vault and the agent gets a scoped bearer token rather than the raw key. ### Can I run transactions across multiple documents with this API? Yes. Begin a transaction with documents:beginTransaction, perform reads, then send writes through documents:commit referencing the transaction id. Use documents:rollback to abort cleanly. ### What are the rate limits for the Cloud Firestore API? Firestore enforces per-database write limits (around 10,000 writes per second per database) and per-document write limits (1 per second sustained). Read throughput scales much higher. Quota errors return HTTP 429 and should be retried with backoff. ### How do I query Firestore from an agent through Jentic? Search Jentic for 'query firestore documents', load the schema for POST /v1/{database}/documents:runQuery, and execute it with a structuredQuery payload describing the from, where, and orderBy clauses. ### Does Firestore support realtime updates over this REST API? Yes, through the documents:listen endpoint, which streams document change events. For most clients the official SDKs are simpler, but the REST listen channel is available for custom integrations. ### Is the Cloud Firestore API free? Firestore has a free daily quota of reads, writes, deletes, and storage. Beyond that it bills per operation and per GB stored. Pricing details are in the Firestore documentation. ### Can I limit what my agent is allowed to do with the Cloud Firestore API? Yes. Because you run Jentic One yourself, your own rules decide which Firestore operations and which service-account credential the agent may use. Firestore carries the database and document resource in the URL path (for example /v1/{database}/documents:commit and /v1/{name}), so you can pin the agent to a single database where it may read and query documents while excluding write paths like documents:commit or a document PATCH unless you explicitly allow them. Nothing outside the operations you approve is callable.