Ayaka Sync API
Ayaka Sync API issues and manages REST API keys, enforces per-key permissions and rate limits, and records every request for analytics. All endpoints live under a single versioned base URL and return JSON.
https://your-domain/api/v1Every response uses the same envelope:
{
"success": true,
"message": "Request successful",
"data": {},
"meta": { "timestamp": "2026-01-01T00:00:00Z" }
}Authentication
Developer endpoints authenticate with an API key. Send it in the Authorization header using the Bearer scheme. The X-API-Key header is also accepted.
Authorization: Bearer ayk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX # or X-API-Key: ayk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- Keys are only accepted over headers — never put them in URLs or query strings.
- Call the API from your server. Don't ship production keys in browser or mobile bundles.
- The dashboard itself uses HttpOnly session cookies with CSRF protection; dashboard-only endpoints reject API keys.
API Keys
Create keys in Dashboard → API Keys. The full key is displayed once; only its HMAC-SHA256 hash is stored.
| Prefix | Environment | Use for |
|---|---|---|
ayk_test_ | Development | Local development, staging, CI |
ayk_live_ | Production | Production traffic |
Permissions
| Permission | Grants |
|---|---|
read | GET /example, GET /records, GET /records/{id} |
write | POST /records, PATCH /records/{id} |
delete | DELETE /records/{id} |
analytics | GET /analytics/* |
profile | GET /profile |
admin | Everything above plus GET /keys, GET /keys/{id}, POST /keys/{id}/revoke. Requires your password to grant. |
Optionally restrict a key to specific paths with allowed endpoints, e.g. /api/v1/records/*. Keys can also have an expiration date, a custom rate limit, and can be disabled, regenerated or revoked at any time.
Endpoints
Paths are relative to the base URL. Key = API key with the listed permission; Session = signed-in dashboard session.
Developer API
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /example | Key · read | Verify a key and see its metadata |
| GET | /records | Key · read | List JSON records (?collection=&page=&per_page=) |
| POST | /records | Key · write | Create a record {"collection","data"} |
| GET | /records/{id} | Key · read | Fetch a record |
| PATCH | /records/{id} | Key · write | Replace a record's data |
| DELETE | /records/{id} | Key · delete | Delete a record |
| GET | /analytics/overview | Key · analytics / Session | Totals, success/error rate, latency, peak (?range=24h|7d|30d|90d|custom&start=&end=&api_key_id=) |
| GET | /analytics/requests | Key · analytics / Session | Time series and status-code breakdown |
| GET | /analytics/endpoints | Key · analytics / Session | Top endpoints |
| GET | /analytics/keys | Key · analytics / Session | Top API keys |
| GET | /analytics/response-times | Key · analytics / Session | Average, max and p95 latency |
| GET | /analytics/realtime | Key · analytics / Session | Per-minute traffic for the last hour |
| GET | /profile | Key · profile / Session | Account profile |
| GET | /keys, /keys/{id} | Key · admin / Session | List / inspect API keys (never returns secrets) |
| POST | /keys/{id}/revoke | Key · admin / Session | Revoke a key |
| GET | /health, /health/database | Public | Service and database health |
Dashboard API (session + CSRF)
| Method | Path | Description |
|---|---|---|
| POST | /auth/register, /auth/login, /auth/logout, /auth/refresh | Account & session lifecycle |
| GET | /auth/me, /auth/sessions | Current user, active sessions |
| POST | /auth/sessions/{id}/revoke, /auth/logout-all | Session management |
| POST | /keys | Create a key (returns the secret once) |
| PATCH | /keys/{id} | Rename, permissions, limits, expiry, enable/disable |
| POST | /keys/{id}/regenerate | Issue a new secret |
| DELETE | /keys/{id} | Delete a key |
| GET | /dashboard/overview, /dashboard/recent-activity | Dashboard data |
| GET | /activity, /activity/export | Audit log and CSV export |
| PATCH | /profile, /settings | Update profile / preferences |
| POST | /profile/change-password | Change password |
Usage
Every request authenticated with an API key — successful or not — is recorded with its request ID, endpoint, method, status code, response time, key, IP and user agent. Authorization headers, full keys, passwords and request bodies are never logged.
Usage powers the Overview and Analytics pages. If the usage write fails, your request still succeeds; the event is retried in the background and the failure counter is exposed at GET /health.
Each response carries an X-Request-ID header you can search for in Recent API Activity.
Rate Limits
Each key has its own limit (default 60 requests per minute, configurable per key from 1 to 10,000). Counters are stored in PostgreSQL, so limits hold across serverless instances.
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current window |
X-RateLimit-Remaining | Requests left in the window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Retry-After | Seconds to wait (only on 429) |
{
"success": false,
"message": "Rate limit of 60 requests per minute exceeded",
"error": { "code": "RATE_LIMIT_EXCEEDED" },
"meta": { "timestamp": "2026-01-01T00:00:00Z", "request_id": "req_…" }
}Sign-in is separately protected: repeated failed logins for an account or network are blocked for 15 minutes.
Errors
Errors use the envelope {"success": false, "message", "error": {"code", "details?"}, "meta"}. Branch on error.code, not on the message.
| HTTP | Code | When |
|---|---|---|
| 401 | AUTHENTICATION_REQUIRED | No API key or session provided |
| 401 | INVALID_API_KEY | Key is malformed or unknown |
| 401 | API_KEY_EXPIRED | Key passed its expiration date |
| 401 | API_KEY_REVOKED | Key was revoked |
| 403 | API_KEY_DISABLED | Key is temporarily disabled |
| 403 | PERMISSION_DENIED | Key lacks the permission or endpoint is not allowed |
| 404 | RESOURCE_NOT_FOUND | Unknown endpoint or resource |
| 422 | VALIDATION_ERROR | Invalid input — see error.details[] (field, message) |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests |
| 500 | INTERNAL_SERVER_ERROR | Unexpected server error (include request_id when reporting) |
| 503 | DATABASE_UNAVAILABLE / DATABASE_NOT_CONFIGURED | Database unreachable or DATABASE_URL missing |
Examples
Store your key in an environment variable (AYAKA_API_KEY) — never hard-code it.
Verify a key
curl https://your-domain/api/v1/example \
-H "Authorization: Bearer $AYAKA_API_KEY"
import os
import requests
BASE_URL = "https://your-domain/api/v1"
headers = {"Authorization": f"Bearer {os.environ['AYAKA_API_KEY']}"}
resp = requests.get(f"{BASE_URL}/example", headers=headers, timeout=10)
body = resp.json()
if not body["success"]:
raise RuntimeError(f"{body['error']['code']}: {body['message']}")
print(body["data"]["key"])
const BASE_URL = "https://your-domain/api/v1";
const res = await fetch(`${BASE_URL}/example`, {
headers: { Authorization: `Bearer ${process.env.AYAKA_API_KEY}` },
});
const body = await res.json();
if (!body.success) throw new Error(`${body.error.code}: ${body.message}`);
console.log(body.data.key, res.headers.get("X-RateLimit-Remaining"));
Create and list records
curl -X POST https://your-domain/api/v1/records \ -H "Authorization: Bearer $AYAKA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"collection": "orders", "data": {"id": 1001, "total": 49.9}}' curl "https://your-domain/api/v1/records?collection=orders" \ -H "Authorization: Bearer $AYAKA_API_KEY"
import os
import requests
BASE_URL = "https://your-domain/api/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['AYAKA_API_KEY']}"
created = s.post(f"{BASE_URL}/records", json={"collection": "orders", "data": {"id": 1001, "total": 49.9}}, timeout=10)
created.raise_for_status()
page = s.get(f"{BASE_URL}/records", params={"collection": "orders"}, timeout=10).json()
for record in page["data"]:
print(record["id"], record["data"])
const BASE_URL = "https://your-domain/api/v1";
const headers = {
Authorization: `Bearer ${process.env.AYAKA_API_KEY}`,
"Content-Type": "application/json",
};
await fetch(`${BASE_URL}/records`, {
method: "POST",
headers,
body: JSON.stringify({ collection: "orders", data: { id: 1001, total: 49.9 } }),
});
const list = await (await fetch(`${BASE_URL}/records?collection=orders`, { headers })).json();
console.log(list.data, list.meta.total);
Handle rate limits
import time, requests
def call(url, headers, attempts=3):
for _ in range(attempts):
r = requests.get(url, headers=headers, timeout=10)
if r.status_code != 429:
return r
time.sleep(int(r.headers.get("Retry-After", "1")))
return rHelp & support
- Check API Status for service and database health.
- Include the
request_idfrom the error response (or theX-Request-IDheader) when reporting a problem. - Self-hosting? The README covers Neon setup, environment variables, migrations and Vercel deployment.
- Contact the operator of this deployment for account issues. No support mailbox is configured in this open-source build.