| 1 |
# Developer API Overview |
| 2 |
|
| 3 |
Makenotwork provides four APIs for building integrations, desktop applications, and developer tools: session-based (web dashboard), SyncKit JWT (cloud sync and OTA), OAuth2 PKCE (third-party apps), and a public License Key API. Public [RSS feeds](./feeds.md) are documented separately. This page covers authentication methods, error handling, and rate limits shared across all endpoints. |
| 4 |
|
| 5 |
## Authentication Methods |
| 6 |
|
| 7 |
### Session Cookies |
| 8 |
|
| 9 |
The primary authentication for the web dashboard. Set via `/login`, required for all creator-facing endpoints (projects, items, files, analytics). Write operations require a CSRF token in the `_csrf` form field or `X-CSRF-Token` header. |
| 10 |
|
| 11 |
Session-authenticated endpoints are designed for the HTMX frontend. When called without the `HX-Request` header, they return JSON instead of HTML fragments. |
| 12 |
|
| 13 |
### SyncKit JWT |
| 14 |
|
| 15 |
Used by [SyncKit](./synckit.md) cloud sync and [OTA updates](./ota.md). Obtain a token via `POST /api/sync/auth` (email + password + API key) or the [OAuth2 PKCE flow](./oauth.md). Pass it as `Authorization: Bearer <token>`. Tokens expire after 7 days. |
| 16 |
|
| 17 |
### No Authentication |
| 18 |
|
| 19 |
Public endpoints that require no auth: |
| 20 |
- [License Key API](./license-keys.md): key validation, activation, deactivation |
| 21 |
- [OTA update check](./ota.md): Tauri-compatible update endpoint |
| 22 |
- [OAuth authorize](./oauth.md): authorization page and code exchange |
| 23 |
- [Public Feeds](./feeds.md): RSS feeds for creators, projects, and blog posts |
| 24 |
|
| 25 |
## Error Format |
| 26 |
|
| 27 |
All API errors return JSON: |
| 28 |
|
| 29 |
```json |
| 30 |
{ |
| 31 |
"error": "Description of what went wrong" |
| 32 |
} |
| 33 |
``` |
| 34 |
|
| 35 |
|
| 36 |
|
| 37 |
| 400 | Invalid request body or parameters | |
| 38 |
| 401 | Missing or invalid authentication | |
| 39 |
| 403 | Insufficient permissions | |
| 40 |
| 404 | Resource not found | |
| 41 |
| 413 | File too large | |
| 42 |
| 422 | Validation error | |
| 43 |
| 429 | Rate limit exceeded | |
| 44 |
| 500 | Internal error | |
| 45 |
|
| 46 |
Internal errors return a generic message; no stack traces or database details are exposed. |
| 47 |
|
| 48 |
## Rate Limits |
| 49 |
|
| 50 |
All rate limits are per IP. Check response headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`) for current values. Current limits (subject to change): |
| 51 |
|
| 52 |
|
| 53 |
|
| 54 |
| Authentication | 5 | 2/sec | Login, join, OAuth authorize | |
| 55 |
| OAuth token exchange | 10 | 2/sec | Token endpoint | |
| 56 |
| 2FA verification | 5 | 2/sec | TOTP, passkey verification | |
| 57 |
| License key validation | 20 | 5/sec | Validate, activate, deactivate | |
| 58 |
| API reads | 60 | 10/sec | GET endpoints | |
| 59 |
| API writes | 30 | 2/sec | POST/PUT/DELETE endpoints | |
| 60 |
| Data export | 3 | 1/sec | Export endpoints | |
| 61 |
| File uploads | 10 | 2/sec | Presign + confirm | |
| 62 |
| SyncKit auth | 5 | 1/sec | Sync auth endpoint | |
| 63 |
| SyncKit sync | 30 | 10/sec | Push, pull, blobs | |
| 64 |
| OTA check | 30 | 10/sec | Update check endpoint | |
| 65 |
| OTA publish | 10 | 2/sec | Artifact upload | |
| 66 |
|
| 67 |
Exceeding a limit returns HTTP 429. Implement exponential backoff in your client. |
| 68 |
|
| 69 |
## OpenAPI Spec |
| 70 |
|
| 71 |
A machine-readable OpenAPI 3 spec is served at: |
| 72 |
|
| 73 |
``` |
| 74 |
GET /api/openapi.json |
| 75 |
``` |
| 76 |
|
| 77 |
An interactive Swagger UI viewer for the same spec is available at [`/api/docs`](/api/docs): send test requests, browse schemas, and copy example payloads without leaving the browser. |
| 78 |
|
| 79 |
The spec covers the SyncKit and License Key endpoints (the surfaces with frozen request/response shapes). Point any OpenAPI-aware client generator, Postman-style tool, or IDE plugin at the JSON URL. The spec's `version` matches the server version, so a hard-refresh after a deploy picks up any schema changes. |
| 80 |
|
| 81 |
OAuth, OTA, and RSS feeds are documented on their own pages rather than in the spec: OAuth is fully described by [discovery metadata](./oauth.md#discovery-metadata), OTA follows Tauri's protocol, and RSS is an XML surface. |
| 82 |
|
| 83 |
## API Reference |
| 84 |
|
| 85 |
- [SyncKit Cloud Sync](./synckit.md): push/pull encrypted data, device management, blob storage |
| 86 |
- [OTA Updates](./ota.md): app auto-update server (Tauri-compatible protocol) |
| 87 |
- [OAuth2 PKCE](./oauth.md): "Log in with Makenotwork" |
| 88 |
- [License Key API](./license-keys.md): validate, activate, and deactivate license keys |
| 89 |
- [Public Feeds](./feeds.md): RSS feeds for creators, projects, blogs, and the changelog |
| 90 |
|