개발자 문서

API keys

Every request carries your key in an X-Api-Key header. Keys look like efy_live_… (or efy_test_… in test mode), are issued per API client from the dashboard, and are shown exactly once at creation or rotation. Keys are secrets: never ship them in client-side code, and rotate immediately if one leaks.

Always send a descriptive User-Agent header (for example YourPlatform/1.0 ([email protected])). Requests carrying default HTTP-library agents (such as python-urllib or python-requests) can be rejected at the edge with a 403 before reaching the API.

curl "https://elefymove.com/api/public/v1/ping" \
  -H "X-Api-Key: efy_live_xxxxxxxxxxxxxxxxxxxxxxxx"

# Response — 200 OK
{ "ok": true, "client": "My booking site", "scopes": ["listings:read", "availability:read"] }

Scopes

Each key carries a set of scopes; a route refuses keys that lack its scope. The available scopes:

• listings:read
• listings:write
• availability:read
• availability:write
• holds:write
• webhooks:manage
• community:read
• community:write
• marketplace:read
• marketplace:write

Rule zero: every operation is scoped to your own data — there is no cross-partner access in either direction, whatever scopes a key holds.

Check your client

Both routes below work with any valid key and need no scope — use /me to read back exactly which scopes, environment, and status your key carries without guessing from a 403:

Errors

Errors use a single JSON envelope with a machine-readable error.code — branch on the code, never on the message text:

# Every error uses one envelope
{
  "success": false,
  "error": {
    "statusCode": 403,
    "code": "MISSING_SCOPE",
    "message": "This key does not carry the listings:write scope.",
    "timestamp": "2026-08-18T09:30:00.000Z",
    "path": "/api/public/v1/listings"
  }
}

• 401 — missing or invalid API key.
• 403 — valid key but missing the required scope.
• 404 — the resource does not exist or is not yours: foreign resources are indistinguishable from missing ones by design.
• 409 — calendar conflict; carries SLOT_TAKEN (see Availability & holds).
• 429 — rate limit exceeded.

Rate limits

The default limit is 120 requests per minute per key (your key’s exact tier is shown in the dashboard). The limiter fails closed: when the limit state cannot be verified, requests are rejected rather than let through. On a 429, back off and retry with jitter — do not tight-loop.

# Over the per-key limit
# Response — 429 Too Many Requests
{
  "success": false,
  "error": { "statusCode": 429, "code": "RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded (120/min). Retry in 30s." }
}