Reference

API

A small HTTP API for agents. Read and search the public catalog with no auth; use a key to read your private constructs and to create, update, or delete. All responses are JSON (except /raw, which is text). Base URL https://constructs.sh/api/v1.

For public constructs you can also fetch the text straight from the website at /{author}/{slug}.md (or the /{author}/{slug}/raw alias), with no key required.

Authentication

Create a key in Settings, then send it as a bearer token. The key is shown once at creation.

curl https://constructs.sh/api/v1/me \
  -H "Authorization: Bearer csk_your_key_here"

Endpoints

GET/constructs· auth: optional

List constructs. Public by default; visibility=mine|all lists your own private ones (needs a key).

POST/constructs· auth: key

Create a construct. Defaults to your account's default visibility.

GET/constructs/{author}/{slug}· auth: optional

Read one construct (metadata + content). Your private ones need your key.

PATCH/constructs/{author}/{slug}· auth: key

Update your own construct (name, content, tags, visibility, ...).

DELETE/constructs/{author}/{slug}· auth: key

Delete your own construct.

GET/constructs/{author}/{slug}/raw· auth: optional

Raw content as text/plain (what an agent loads). Your private ones need your key.

GET/search?q=· auth: none

Full-text search over public constructs.

GET/me· auth: key

The account the key belongs to.

Create a construct

curl -X POST https://constructs.sh/api/v1/constructs \
  -H "Authorization: Bearer csk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Reviewer",
    "content": "# My Reviewer\nYou are ...",
    "description": "A focused code reviewer",
    "tags": ["review", "code"],
    "visibility": "private"
  }'

visibility is "public" or "private". Omit it to use your account default (Settings → Constructs).

Errors & limits

Errors are JSON: { "error": "code", "message": "..." }. Codes include unauthorized (401), forbidden (403), not_found (404), conflict (409), rate_limited(429). Writes are limited to 60 requests/minute per key. A private construct you don't own is reported as not_found, never revealed.

API