Django

REST works today, with no extra package:

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"}),
    "limit": "20",
})
slug = os.environ["BUCKET_SLUG"]
with urlopen(f"https://api.cosmicjs.com/v3/buckets/{slug}/objects?{params}") as res:
    posts = json.load(res)["objects"]

The same calls wrapped as Bucket live in the cosmicjs package:

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

cosmic = Bucket(
    bucket_slug=os.environ["BUCKET_SLUG"],
    read_key=os.environ["BUCKET_READ_KEY"],
    write_key=os.environ["BUCKET_WRITE_KEY"],
)
posts = cosmic.find({"type": "posts"}, limit=20)["objects"]
cosmic.insert_one({"title": "Hello", "type": "posts", "metadata": {"content": "Body"}})

See Python for the client methods. Do not pip install cosmic-sdk.

FAQ

How do I install the Python client?

The package name is cosmicjs. It is not the PyPI project named cosmic-sdk, which is unrelated. Install it with pip install git+https://github.com/cosmicjs/cosmic-sdk-py.git. The REST examples on this page use urllib and need no package.

Where do keys go in Django?

settings.py reads BUCKET_SLUG, BUCKET_READ_KEY, and BUCKET_WRITE_KEY from the environment. Do not commit them.

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.