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.