# Developer API Overview

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.

## Authentication Methods

### Session Cookies

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.

Session-authenticated endpoints are designed for the HTMX frontend. When called without the `HX-Request` header, they return JSON instead of HTML fragments.

### SyncKit JWT

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.

### No Authentication

Public endpoints that require no auth:
- [License Key API](./license-keys.md): key validation, activation, deactivation
- [OTA update check](./ota.md): Tauri-compatible update endpoint
- [OAuth authorize](./oauth.md): authorization page and code exchange

## Error Format

All API errors return JSON:

```json
{
  "error": "Description of what went wrong"
}
```

| Status | Meaning |
|--------|---------|
| 400 | Invalid request body or parameters |
| 401 | Missing or invalid authentication |
| 403 | Insufficient permissions |
| 404 | Resource not found |
| 413 | File too large |
| 422 | Validation error |
| 429 | Rate limit exceeded |
| 500 | Internal error |

Internal errors return a generic message; no stack traces or database details are exposed.

## Rate Limits

All rate limits are per IP. Check response headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`) for current values. Current limits (subject to change):

| Category | Burst | Sustained | Endpoints |
|----------|-------|-----------|-----------|
| Authentication | 5 | 2/sec | Login, join, OAuth authorize |
| OAuth token exchange | 10 | 2/sec | Token endpoint |
| 2FA verification | 5 | 2/sec | TOTP, passkey verification |
| License key validation | 20 | 5/sec | Validate, activate, deactivate |
| API reads | 60 | 10/sec | GET endpoints |
| API writes | 30 | 2/sec | POST/PUT/DELETE endpoints |
| Data export | 3 | 1/sec | Export endpoints |
| File uploads | 10 | 2/sec | Presign + confirm |
| SyncKit auth | 5 | 1/sec | Sync auth endpoint |
| SyncKit sync | 30 | 10/sec | Push, pull, blobs |
| OTA check | 30 | 10/sec | Update check endpoint |
| OTA publish | 10 | 2/sec | Artifact upload |

Exceeding a limit returns HTTP 429. Implement exponential backoff in your client.

## API Reference

- [SyncKit Cloud Sync](./synckit.md): push/pull encrypted data, device management, blob storage
- [OTA Updates](./ota.md): app auto-update server (Tauri-compatible protocol)
- [OAuth2 PKCE](./oauth.md): "Log in with Makenot.work"
- [License Key API](./license-keys.md): validate, activate, and deactivate license keys
- [Rustdoc API Reference](/rustdoc/synckit_client/): SyncKit client SDK documentation