Documentation

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.

Base URL
https://your-domain/api/v1

Every response uses the same envelope:

json · success
{
  "success": true,
  "message": "Request successful",
  "data": {},
  "meta": { "timestamp": "2026-01-01T00:00:00Z" }
}
Open API Reference openapi.json

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.

http
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.

PrefixEnvironmentUse for
ayk_test_DevelopmentLocal development, staging, CI
ayk_live_ProductionProduction traffic

Permissions

PermissionGrants
readGET /example, GET /records, GET /records/{id}
writePOST /records, PATCH /records/{id}
deleteDELETE /records/{id}
analyticsGET /analytics/*
profileGET /profile
adminEverything 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

MethodPathAuthDescription
GET/exampleKey · readVerify a key and see its metadata
GET/recordsKey · readList JSON records (?collection=&page=&per_page=)
POST/recordsKey · writeCreate a record {"collection","data"}
GET/records/{id}Key · readFetch a record
PATCH/records/{id}Key · writeReplace a record's data
DELETE/records/{id}Key · deleteDelete a record
GET/analytics/overviewKey · analytics / SessionTotals, success/error rate, latency, peak (?range=24h|7d|30d|90d|custom&start=&end=&api_key_id=)
GET/analytics/requestsKey · analytics / SessionTime series and status-code breakdown
GET/analytics/endpointsKey · analytics / SessionTop endpoints
GET/analytics/keysKey · analytics / SessionTop API keys
GET/analytics/response-timesKey · analytics / SessionAverage, max and p95 latency
GET/analytics/realtimeKey · analytics / SessionPer-minute traffic for the last hour
GET/profileKey · profile / SessionAccount profile
GET/keys, /keys/{id}Key · admin / SessionList / inspect API keys (never returns secrets)
POST/keys/{id}/revokeKey · admin / SessionRevoke a key
GET/health, /health/databasePublicService and database health

Dashboard API (session + CSRF)

MethodPathDescription
POST/auth/register, /auth/login, /auth/logout, /auth/refreshAccount & session lifecycle
GET/auth/me, /auth/sessionsCurrent user, active sessions
POST/auth/sessions/{id}/revoke, /auth/logout-allSession management
POST/keysCreate a key (returns the secret once)
PATCH/keys/{id}Rename, permissions, limits, expiry, enable/disable
POST/keys/{id}/regenerateIssue a new secret
DELETE/keys/{id}Delete a key
GET/dashboard/overview, /dashboard/recent-activityDashboard data
GET/activity, /activity/exportAudit log and CSV export
PATCH/profile, /settingsUpdate profile / preferences
POST/profile/change-passwordChange password
Try an endpoint
Read-only requests from your browser. Your key stays in memory on this page and is never stored.

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.

HeaderMeaning
X-RateLimit-LimitRequests allowed in the current window
X-RateLimit-RemainingRequests left in the window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds to wait (only on 429)
json · 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.

HTTPCodeWhen
401AUTHENTICATION_REQUIREDNo API key or session provided
401INVALID_API_KEYKey is malformed or unknown
401API_KEY_EXPIREDKey passed its expiration date
401API_KEY_REVOKEDKey was revoked
403API_KEY_DISABLEDKey is temporarily disabled
403PERMISSION_DENIEDKey lacks the permission or endpoint is not allowed
404RESOURCE_NOT_FOUNDUnknown endpoint or resource
422VALIDATION_ERRORInvalid input — see error.details[] (field, message)
429RATE_LIMIT_EXCEEDEDToo many requests
500INTERNAL_SERVER_ERRORUnexpected server error (include request_id when reporting)
503DATABASE_UNAVAILABLE / DATABASE_NOT_CONFIGUREDDatabase 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"

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"

Handle rate limits

python
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 r

Help & support

  • Check API Status for service and database health.
  • Include the request_id from the error response (or the X-Request-ID header) 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.