| 1 |
# Developer API Overview |
| 2 |
|
| 3 |
Makenot.work 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. 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 |
|
| 24 |
## Error Format |
| 25 |
|
| 26 |
All API errors return JSON: |
| 27 |
|
| 28 |
```json |
| 29 |
{ |
| 30 |
"error": "Description of what went wrong" |
| 31 |
} |
| 32 |
``` |
| 33 |
|
| 34 |
|
| 35 |
|
| 36 |
| 400 | Invalid request body or parameters | |
| 37 |
| 401 | Missing or invalid authentication | |
| 38 |
| 403 | Insufficient permissions | |
| 39 |
| 404 | Resource not found | |
| 40 |
| 413 | File too large | |
| 41 |
| 422 | Validation error | |
| 42 |
| 429 | Rate limit exceeded | |
| 43 |
| 500 | Internal error | |
| 44 |
|
| 45 |
Internal errors return a generic message; no stack traces or database details are exposed. |
| 46 |
|
| 47 |
## Rate Limits |
| 48 |
|
| 49 |
All rate limits are per IP. Check response headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`) for current values. Current limits (subject to change): |
| 50 |
|
| 51 |
|
| 52 |
|
| 53 |
| Authentication | 5 | 2/sec | Login, join, OAuth authorize | |
| 54 |
| OAuth token exchange | 10 | 2/sec | Token endpoint | |
| 55 |
| 2FA verification | 5 | 2/sec | TOTP, passkey verification | |
| 56 |
| License key validation | 20 | 5/sec | Validate, activate, deactivate | |
| 57 |
| API reads | 60 | 10/sec | GET endpoints | |
| 58 |
| API writes | 30 | 2/sec | POST/PUT/DELETE endpoints | |
| 59 |
| Data export | 3 | 1/sec | Export endpoints | |
| 60 |
| File uploads | 10 | 2/sec | Presign + confirm | |
| 61 |
| SyncKit auth | 5 | 1/sec | Sync auth endpoint | |
| 62 |
| SyncKit sync | 30 | 10/sec | Push, pull, blobs | |
| 63 |
| OTA check | 30 | 10/sec | Update check endpoint | |
| 64 |
| OTA publish | 10 | 2/sec | Artifact upload | |
| 65 |
|
| 66 |
Exceeding a limit returns HTTP 429. Implement exponential backoff in your client. |
| 67 |
|
| 68 |
## API Reference |
| 69 |
|
| 70 |
- [SyncKit Cloud Sync](./synckit.md): push/pull encrypted data, device management, blob storage |
| 71 |
- [OTA Updates](./ota.md): app auto-update server (Tauri-compatible protocol) |
| 72 |
- [OAuth2 PKCE](./oauth.md): "Log in with Makenot.work" |
| 73 |
- [License Key API](./license-keys.md): validate, activate, and deactivate license keys |
| 74 |
- [Rustdoc API Reference](/rustdoc/synckit_client/): SyncKit client SDK documentation |
| 75 |
|