Cloudant IBM Cloudant API
Agent-ready OpenAPI document · curated by JenticStorageDatabasebearer, basic, apiKey30 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Read and write JSON documents, run Mango queries and Lucene full-text search, watch change feeds, and replicate data on IBM Cloudant.
Use for: I need to insert a JSON document into a database, Get a document by its ID and current revision, List all databases on the Cloudant account, Run a Mango query for documents where status equals 'active'
Not supported: Does not handle SQL queries, blob storage, or non-Cloudant CouchDB administration - use for managing JSON documents in IBM Cloudant only.
Jentic publishes the only available OpenAPI specification for IBM Cloudant API, keeping it validated and agent-ready. IBM Cloudant is a distributed JSON document database built on Apache CouchDB and offered as a fully managed service. The API exposes database and document CRUD, bulk read and write, the Mango query language via _find, MapReduce and Lucene full-text search via design documents, change feeds, replication, session and IAM authentication, and security configuration. Authentication can be IBM Cloud IAM bearer, CouchDB-compatible basic auth, or an AuthSession cookie.
Install Jentic One Beta
Connect the IBM Cloudant API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the IBM Cloudant 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%2Fcloudant.com%2Fcloudant" | 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%2Fcloudant.com%2Fcloudant" | 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 IBM Cloudant API.
Read and write JSON documents in databases scoped to a Cloudant account
Run bulk read and write batches via _bulk_get and _bulk_docs for high throughput ingestion
Query documents declaratively with Mango selectors via the _find endpoint
Build secondary indexes and aggregations through MapReduce design document views
Run Lucene-backed full-text search with the _search endpoint on design documents
Watch a database change feed via _changes for streaming integrations and replication
Configure replication between Cloudant or CouchDB databases via _replicate and _replicator
Use Cases
Patterns agents use IBM Cloudant API for, with concrete tasks.
★ Mobile Sync With Cloudant
Use Cloudant as the cloud backend for an offline-first mobile or web app. The change feed at /{db}/_changes drives client sync, /{db}/_bulk_docs uploads batches when devices come online, and replication via /_replicator keeps replica databases consistent across regions. CouchDB-compatible semantics mean PouchDB and other clients work directly without translation.
Read /{db}/_changes since the last sequence and apply incoming changes to a local PouchDB store
Document Search and Discovery
Add full-text search over user-generated content stored as JSON. A design document with a Lucene search index, hit through /{db}/_design/{ddoc}/_search/{index}, returns ranked documents matching a free-text query, while Mango selectors via /{db}/_find handle structured filters. Used together they cover both keyword and structured query patterns without a separate search service.
Call /{db}/_design/{ddoc}/_search/{index} with q='product:phone AND price:[100 TO 500]' and return the top 20 hits
Bulk Ingestion Pipelines
Ingest large JSON datasets into Cloudant by batching writes through /{db}/_bulk_docs and reads through /{db}/_bulk_get. Bulk endpoints accept thousands of documents per request and return per-document success or conflict status, which is the recommended throughput pattern for ETL jobs feeding analytics or migration workloads.
Read 5,000 records from a CSV, transform to JSON, and POST to /{db}/_bulk_docs in batches of 1,000
Cross-Region Replication
Set up active replication between Cloudant databases in different regions for disaster recovery or read-locality. POST /_replicate triggers a one-shot replication and POST to /_replicator persists a continuous replication document. Combined with the change feed, this is the standard pattern for multi-region Cloudant deployments.
POST a replication document to /_replicator with source and target URLs and continuous=true, then verify the replication status
Agent-Driven Document Workflows via Jentic
AI assistants that need a flexible JSON store can search Jentic for an intent like 'save document to cloudant' and execute the matching operation without learning CouchDB's auth quirks. Jentic holds the IAM bearer or basic-auth credential in the vault and issues a scoped credential per call, which is essential for multi-tenant agent deployments.
Search Jentic for 'save json document to cloudant', load PUT /{db}/{docId}, and execute with the user-supplied JSON body
Key Endpoints
30 endpoints — jentic publishes the only available openapi specification for ibm cloudant api, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
GET
/_all_dbs
List all databases
PUT
/{db}
Create a database
GET
/{db}/_all_docs
List documents in a database
PUT
/{db}/{docId}
Create or update a document
POST
/{db}/_bulk_docs
Bulk insert or update documents
POST
/{db}/_find
Run a Mango selector query
GET
/{db}/_changes
Read the change feed
POST
/_replicate
Trigger a replication job
GET
/_all_dbs
List all databases
PUT
/{db}
Create a database
GET
/{db}/_all_docs
List documents in a database
PUT
/{db}/{docId}
Create or update a document
POST
/{db}/_bulk_docs
Bulk insert or update documents
POST
/{db}/_find
Run a Mango selector query
GET
/{db}/_changes
Read the change feed
POST
/_replicate
Trigger a replication job
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring IBM Cloudant by hand means choosing among IAM bearer tokens, basic auth, or an AuthSession cookie, putting each in the right header, and resolving the per-account {account}.cloudantnosqldb.appdomain.cloud host yourself. Through Jentic you install once, import the IBM Cloudant API from the API Directory, store the credential once, and your agent calls it.
Permission scoping
Cloudant puts the database and document id in the URL path (/{db}/{docId}), so a rule can pin your agent to one database: it can read and write documents and run queries there and nothing else. You choose the operations it may call, so a replication trigger or a database creation is only in reach if you include it.
Credential isolation
Your Cloudant credential is stored once, encrypted, by your own Jentic One instance and injected into the correct header at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'query a Cloudant database' or 'save a document', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without learning Cloudant's CouchDB-style URL conventions.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using IBM Cloudant API through Jentic.
Why is there no official OpenAPI spec for IBM Cloudant API?
IBM Cloudant does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call IBM Cloudant API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.
What authentication does the IBM Cloudant API use?
Cloudant supports three schemes - IBM Cloud IAM bearer tokens (recommended for production), CouchDB-compatible basic authentication, and an AuthSession cookie obtained from /_session. Through Jentic, the chosen credential is held in the vault and a scoped credential is issued per call so the raw token or password never enters the agent's context.
Can I run full-text search on documents with this API?
Yes. /{db}/_design/{ddoc}/_search/{index} runs a Lucene query against a search index defined in a design document, and /{db}/_find runs structured Mango selector queries. Combine them when both keyword and structured filtering are required.
What are the rate limits for the IBM Cloudant API?
Rate limits depend on the Cloudant plan and are expressed as provisioned throughput capacity (lookups, writes, queries per second). Standard plans purchase capacity in blocks; Lite plans are capped at low single-digit operations per second. Check the IBM Cloud Cloudant pricing page for the exact tier.
How do I save a JSON document through Jentic?
Run pip install jentic, search for 'save json document to cloudant', load the PUT /{db}/{docId} operation, then execute with the database name, document ID, and JSON body. The call returns the assigned revision.
Does this API support replication between databases?
Yes. POST /_replicate runs a one-shot replication job, and writing a replication document to /_replicator persists a continuous replication that survives restarts. Both source and target can be Cloudant or CouchDB databases.
Can I limit what my agent is allowed to do with the IBM Cloudant API?
Yes. Because Jentic One is self-hosted, your own rules decide which operations and credentials the agent may use. Since Cloudant puts the database and document id in the URL path such as /{db}/{docId}, you can pin the agent to a single database where it only reads and writes documents and runs Mango queries via /{db}/_find. Higher-impact operations like triggering replication through POST /_replicate or creating a database with PUT /{db} are reachable only if you explicitly include them.
GET STARTED