FOR KIRO CREW AND OTHER CLIENTS

JSON API

A versioned JSON interface over the same catalog, accounts, submissions, claims, moderation and content as the website.

Authentication

Public reads need no authentication. Sign in with POST https://kirocrewapps.com/api/v1/auth/login (email and password) or register with POST https://kirocrewapps.com/api/v1/auth/register. Both return a bearer token:

curl -X POST https://kirocrewapps.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"your-password"}'

Send the token on later requests:

curl https://kirocrewapps.com/api/v1/auth/me \
  -H 'Authorization: Bearer TOKEN'

The API never signs in from a cookie, so cross-site forms cannot act with your session. Tokens are server-side sessions: they expire, are revoked by logout/password changes/access changes, and honour email-verification and role gates.

The full endpoint list is in the OpenAPI document. Mutations accept JSON (Content-Type: application/json); form-encoded bodies also work for the public action endpoints.

Public catalog

Listings: GET /items with q, type, source_type, sort, page, per_page
Listing: GET /items/{slug} including source history and review aggregates
Reviews: GET /items/{slug}/reviews (visible, non-withdrawn only)
Types: GET /types
Editorial: GET /content and GET /content/{kind}/{slug} (published only; raw Markdown plus rendered HTML)

Account actions

Profile: GET /auth/me, POST /auth/password, POST /auth/logout
Library: GET /me/bookmarks, GET /me/reviews, GET /me/votes
Listing actions: POST/DELETE /items/{slug}/bookmark, POST /items/{slug}/vote, POST/DELETE /items/{slug}/reviews, POST /items/{slug}/report
Data: GET /me/export, POST /me/close

Votes are -1, 0 (clear) or 1. Reviews are one per account per listing. Reports and account closure keep the same moderation and audit rules as the website.

Developer and administration

Developer: /developer/submissions, /developer/claims, /developer/claims/{id}/proof, /developer/claims/{id}/verify, /developer/unclaimed
Moderation: /admin/submissions, /admin/reviews, /admin/reports
Catalog: /admin/items, status, merge, permanent deletion, /admin/content
Access: /admin/users, /admin/roles, permission overrides
Operations: /admin/scanner, /admin/analytics, /admin/audit, /admin/settings

These endpoints require the same permissions as the corresponding pages. The first administrator is still granted with the operator CLI; there is no API bootstrap bypass.

Response shape

Successful responses use {"data": ...}. Collections add meta with page, per_page, total and pages. Errors use an HTTP status plus:

{"error": {"code": "invalid_request", "message": "...", "status": 400}}

The API never exposes internal dedupe keys, account hashes, session digests or SMTP credentials.