API

JSON document store API with optional encryption

Store JSON documents in tenant-scoped collections with search, indexes and optional encryption you choose.

What it does

The Data Warehouse Collections API is a document store for your app's JSON. Create a collection, add documents to it, search by title, tags, dates or your own indexed fields, and read them back. Every collection belongs to your tenant and nobody else can see it.
It solves the "we need a database for this one thing" problem. Settings, form submissions, audit snapshots, customer notes and import results all need a home, but a new table and a new service for each is too much. A collection takes a name and a slug, and you are writing documents in a minute.
You choose how each collection is protected, once, when you create it. With no encryption, documents are stored as plain JSON and are fully searchable. With managed encryption, Takelan generates a key, keeps it in the Secrets service and encrypts documents on the server, so you do not handle keys, and indexed fields still work. With client-side encryption, your app encrypts each document before sending it, so the server only ever stores ciphertext. Client-side mode is the zero-knowledge option, and you give up server-side reading of the content in return. The mode cannot be changed later. For managed collections there is a key-rotation call that re-encrypts documents under a new key.
Documents carry a data id, an optional sub-id, a title, description, tags, a public flag and a schema version. Add up to 500 records per bulk request. Large bodies move to object storage for you once they pass a size threshold that you can set per collection, or you can attach a file you uploaded earlier.
Search is a POST with filters for title, description, tags, created and updated dates, and indexed fields, with paging and sorting. You can add indexes to a collection, retry an index that failed, and read an optimization summary that suggests what to index.
The older Data Warehouse endpoints (JSON entries with schemas and validation) are still there for schema-checked records, along with an access log that shows who touched what.
Authenticate with an X-API-Key header or a Bearer token from Takelan SSO. Over the limit you get a 429 with a Retry-After header. Exact numbers vary by environment, so none are quoted.
Affordable by design. Start free* inside platform limits. *Free within platform limits; usage beyond limits may be charged to maintain the platform. Connected ShadowCradle organizations can switch on Takelan SSO and these free* services with one switch. Airgap licences work without any Takelan connection.

See how it works

One collection, three ways to protect it

You pick the protection once, when the collection is created, and it cannot be changed later. Client-side mode is zero-knowledge: the server cannot read the content, so it gives up server-side reading.

Example use cases

App settings and customer records

A developer keeps per-customer settings as JSON documents in a "customer-settings" collection and finds them by tag or indexed field, with no schema migration.

Sensitive notes the server cannot read

A support team stores private notes in a client-encrypted collection. The server holds ciphertext only, and each user unlocks the key with the vault passphrase.

Encryption without key handling

A small business wants data encrypted at rest but has nobody to manage keys. It picks managed encryption, and indexed fields keep working.

Bulk import from an old system

An IT admin loads exported records 500 at a time with the bulk endpoint, then searches them by date and tag to check the import.

Attach large files to a record

A form app stores each submission as a small JSON document and points it at an uploaded PDF, so big files stay in object storage.

Who looked at this data

A compliance-minded team reads the access log to see which user read or changed which entry, and when.

Try it

Create a managed-encryption collection and add a document

curl -X POST https://app.takelan.com/api/v1/data/collections \
  -H "X-API-Key: $TAKELAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "my-app",
    "slug": "customer-notes",
    "name": "Customer notes",
    "encryption_mode": "managed"
  }'

# Response (abridged, fictional)
# { "id": "0a9c...42", "slug": "customer-notes", "encryption_mode": "managed", "is_active": true }

curl -X POST https://app.takelan.com/api/v1/data/collections/0a9c...42/documents \
  -H "X-API-Key: $TAKELAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data_id": "cust-1042", "title": "Renewal call", "tags": ["renewal"],
        "data": { "note": "Wants a 3-year term", "owner": "alex" } }'

Encryption mode is set at creation and is immutable. Slugs use lowercase letters, digits and single hyphens.

Search a collection

curl -X POST https://app.takelan.com/api/v1/data/collections/0a9c...42/documents/search \
  -H "X-API-Key: $TAKELAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["renewal"], "created_after": "2026-10-01T00:00:00Z", "page": 1, "page_size": 20 }'

Endpoints

POST /api/v1/data/collections Create a collection. Set encryption_mode to none, managed or client.
GET /api/v1/data/collections List collections.
GET /api/v1/data/collections/{collection_id} One collection.
PUT /api/v1/data/collections/{collection_id} Rename, change the large-body threshold or deactivate.
DELETE /api/v1/data/collections/{collection_id} Delete a collection.
POST /api/v1/data/collections/{collection_id}/documents Add a document (inline JSON, a ciphertext envelope, or a file reference).
POST /api/v1/data/collections/{collection_id}/documents/bulk Add up to 500 documents at once.
GET /api/v1/data/collections/{collection_id}/documents/{document_id} Read a document.
PUT /api/v1/data/collections/{collection_id}/documents/{document_id} Replace a document.
DELETE /api/v1/data/collections/{collection_id}/documents/{document_id} Delete a document.
POST /api/v1/data/collections/{collection_id}/documents/search Search by title, tags, dates and indexed fields, with paging.
POST /api/v1/data/collections/{collection_id}/indexes Add an index.
GET /api/v1/data/collections/{collection_id}/indexes List indexes and their build state.
POST /api/v1/data/collections/{collection_id}/indexes/{index_id}/retry Retry an index that failed.
GET /api/v1/data/collections/{collection_id}/optimization/summary Index suggestions from your search patterns.
POST /api/v1/data/collections/{collection_id}/encryption/register-key Client mode: register the wrapped collection key once.
POST /api/v1/data/collections/{collection_id}/encryption/unlock Client mode: recover the key with the vault passphrase part.
POST /api/v1/data/collections/{collection_id}/encryption/rotate Managed mode: rotate the key and re-encrypt documents.
POST /api/v1/data/entries Schema-checked JSON entry (older warehouse API).
POST /api/v1/data/schemas Define a schema.
POST /api/v1/data/validate Validate data against a schema.
POST /api/v1/data/search Search entries.
GET /api/v1/data/access-logs Who accessed which entry, and when.

MCP

Available as tools through /mcp/utils. Listing and searching collections and documents works with a read-only key. Creating, changing and deleting are writes, so they are off by default and need the tenant's writes switch plus a key that is not read-only. Key registration, unlock and rotation are marked sensitive, and raw document content downloads are not exposed as tools. About MCP

Common questions

how to store json documents with an api

Create a collection with POST /api/v1/data/collections, then POST documents to /collections/{id}/documents with a data_id and a JSON data object. Search them later by tags, dates or indexed fields.

what is the difference between managed and client-side encryption

In managed mode Takelan creates the key, keeps it in the Secrets service and encrypts on the server, so indexed fields still work. In client mode your app encrypts first, so the server stores ciphertext only. That is the zero-knowledge option. The choice is fixed when you create the collection.

is client-side encrypted data readable by Takelan

Not in client mode: the server receives and stores ciphertext produced by your app. This applies only to client-mode collections. Managed and unencrypted collections are readable by the service.

can I bulk import records into a collection

Yes. The bulk endpoint takes up to 500 documents per request.

how do I search documents by field

Add an index on the field, supply indexed_values when you write, then use indexed_filters in the search request. The optimization summary suggests indexes worth adding.

can I change a collection's encryption later

No. Encryption mode and the zero-knowledge flag are immutable after creation. Create a new collection and move the documents if you need a different mode. Managed collections can have their key rotated.

can I see who read my data

Yes. The access-logs endpoint lists access events for warehouse entries, and the user-activity API shows a person's own recent warehouse actions.

is there a free tier for the data warehouse api

It is affordable by design: start free* within platform limits. *Free within platform limits; usage beyond limits may be charged to maintain the platform.

All API families | Takelan Utilities & APIs | Pricing