# apicraft

> A GitHub release API. Every call needs a personal API key (`ac_...`) and runs on the caller's own saved GitHub token. Base URL: https://api.opencraft.cc

## Start here
- [Full documentation as Markdown](https://api.opencraft.cc/docs.md): every endpoint, parameter, error and example in one file
- [OpenAPI schema](https://api.opencraft.cc/openapi.json): machine-readable contract
- [Docs for humans](https://api.opencraft.cc/docs/): the same content with a live request runner

## Rules for agents
- Send `Authorization: Bearer ac_...` on every `/api/v1/*` call. Never invent a key; ask the user for theirs (dashboard: https://api.opencraft.cc/account/).
- Every error is JSON: `error` (stable code to branch on), `detail`, `status_code`, and often `hint`, `action` and `request_id`. `error: github_token_required` (HTTP 403) means the user has not saved a GitHub token yet: tell them to add one on the dashboard, do not retry. `key_read_only` means the key may only read.
- HTTP 429 means a limit is used up. Wait for `Retry-After` seconds. Limits: 10/s, 80/min, 4000/day per account (read `X-RateLimit-Policy` and `X-RateLimit-Remaining`); batches 15/min, 25 repos, and a batch counts as one call per 5 repositories.
- Prefer `POST /api/v1/check` (up to 25 repositories) over many single checks, and `GET /api/v1/watchlist/summary` over looping the watchlist. Send `If-None-Match` with the last `ETag` when polling; send an `X-Request-ID` to trace a call.
- `GET /api/v1/usage` shows the remaining quota before a big job.
- Account deletion is not available through the API or an API key. Never try to delete an account; the user does it in Settings on the website.
- Versions: tag prefixes such as `app-v` are ignored when comparing; `latest` echoes the raw tag.

## Endpoints
- GET /api/v1/check?owner&repo&current : is a version outdated
- POST /api/v1/check : batch of up to 25
- GET /api/v1/latest : newest release
- GET /api/v1/assets?owner&repo&os&arch : download link for an OS and CPU
- GET /api/v1/changelog?owner&repo&current : notes of every newer release, breaking-change flag
- GET /api/v1/repos/{owner}/{repo}/overview | pulls | issues | compare : repository facts, open work, unreleased commits
- GET|POST|PUT|DELETE /api/v1/watchlist : the user's tracked repositories (label, group, ?group=, ?only=outdated; PUT syncs a whole list with replace=true)
- GET /api/v1/watchlist/summary : counts and `all_current`, the one field a CI gate needs
- POST /api/v1/watchlist/{owner}/{repo}/acknowledge : mark a repository as updated to its newest release
- Automation keys (named, read or full access) are created by the user on the dashboard or with POST /auth/keys from the browser session; a key cannot manage keys
- GET /api/v1/usage : limits and quota left
- GET /api/v1/usage/history?days&limit&via&format=json|csv : every stored call of this account (90 days), totals, errors per day, top endpoints
- GET /api/v1/badge/{owner}/{repo}.svg : public badge, no key, homepage repositories only

## Craft data (credits: Craft Watch by Overprivileged, ArtCraft Contributors, CraftSuite CC BY 4.0)
- GET /api/v1/craft/apps : every Craft app with an update verdict (green, yellow, red, grey), activity numbers, advisories
- GET /api/v1/craft/apps/{slug}/version?tag= : what the public records show for the version the user runs. Never call a version safe or unsafe; quote the verdict text.
- GET /api/v1/craft/events?types=release,advisory&since= : releases, advisories and merged changes, newest first
- GET /api/v1/craft/compare?sort= , /contributors , /contributors/{login} , /stats : comparisons and contributor statistics
- GET /api/v1/craft/tracker : readiness percentages (optional module, CC BY 4.0: credit CraftSuite, craftsuite.net, with a link). `404 module_disabled` means the owner switched a module off; `503 warming_up` means retry after `Retry-After`.
- Atom feed `https://api.opencraft.cc/public/craft/feed.atom`, badge `https://api.opencraft.cc/api/v1/badge/craft/{slug}.svg`, credits `/api/v1/craft/credits`

## Optional
- [Craft Watch page](https://api.opencraft.cc/craft/)
- [Status page](https://api.opencraft.cc/status/) and [JSON](https://api.opencraft.cc/public/status)
- [Homepage as Markdown](https://api.opencraft.cc/index.md)