Python

This is the whole read, with the standard library:

import json
import os
from urllib.parse import urlencode
from urllib.request import urlopen

params = urlencode({
    "read_key": os.environ["BUCKET_READ_KEY"],
    "query": json.dumps({"type": "posts"}),
})
slug = os.environ["BUCKET_SLUG"]
with urlopen(f"https://api.cosmicjs.com/v3/buckets/{slug}/objects?{params}") as res:
    objects = json.load(res)["objects"]

The cosmicjs package is a thin wrapper around the same endpoints:

pip install git+https://github.com/cosmicjs/cosmic-sdk-py.git
from cosmicjs import Bucket

cosmic = Bucket(
    bucket_slug="your-bucket-slug",
    read_key="your-read-key",
    write_key="your-write-key",
)

posts = cosmic.find({"type": "posts"}, props="title,slug,metadata", limit=20)
one = cosmic.find_one({"type": "posts", "slug": "hello-world"})
created = cosmic.insert_one({
    "title": "Hello",
    "type": "posts",
    "metadata": {"content": "Body"},
})
cosmic.update_one(created["object"]["id"], {"title": "Hello again"})
cosmic.delete_one(created["object"]["id"])

Django setup is on the Django page. FastAPI can call Bucket inside a normal async route via asyncio.to_thread, because the client uses urllib.

Media upload is not in this client. Use @cosmicjs/sdk media.insertOne or the media endpoint. The upload host is https://workers.cosmicjs.com/v3, and the form field name is media.

FAQ

What is the pip package name?

cosmicjs, imported as cosmicjs. The name cosmic-sdk on PyPI is a different project. Install this client with pip install git+https://github.com/cosmicjs/cosmic-sdk-py.git.

Which methods exist?

find, find_one, insert_one, update_one, and delete_one. find takes a query dict and optional limit, skip, props, depth, locale, and status.

Where do writes send the key?

Authorization: Bearer and the write key. insert_one, update_one, and delete_one raise if write_key was not set.

How much does Cosmic cost?

Project plans are Free ($0), Builder ($99/mo), Team ($299/mo), Business ($499/mo), Enterprise (custom pricing). Yearly billing saves 10%. Workspace plans are Small Workspace ($999/mo) and Large Workspace ($2,999/mo), and they start with a 30-day free trial. Allowances, add-on rates, and the rest of the pricing FAQ are plain text at https://www.cosmicjs.com/pricing.md.

Are API keys required, and is content private?

Each Bucket has a read key and a write key in Bucket Settings > API Access. GET requests use the read key. POST, PATCH, and DELETE use the write key as Authorization: Bearer. Do not put the write key in a browser bundle, a mobile app, or a NEXT_PUBLIC_ variable. SAML single sign-on is on Large Workspace and Enterprise. The audit log is append-only. Text versions: https://www.cosmicjs.com/security.md and https://www.cosmicjs.com/docs/dashboard/audit-log.md.

Can an agent create a Cosmic project without an existing account?

Yes. POST https://dapi.cosmicjs.com/v3/agents/sign-up provisions a free-tier project and bucket tied to a human email, with no existing Cosmic account. The human claims it with the emailed one-time code. The playbook is https://www.cosmicjs.com/docs/ai-onboarding.md.