Base URL

https://app.aidelly.ai/api/public/v1

All endpoints are HTTPS-only. HTTP requests are rejected.

Authentication

Every request requires a bearer token:

Authorization: Bearer aidelly_live_xxx

See Authentication for key creation and scopes.

Request format

All request bodies are JSON. Include Content-Type: application/json on write requests.

Write endpoints (POST, PATCH) also require an idempotency key:

Idempotency-Key: <unique-string>

See Idempotency for details.

Response envelope

All responses use a consistent envelope:

{
  "success": true,
  "data": { ... },
  "request_id": "uuid"
}

On error:

{
  "success": false,
  "error": {
    "code": "PUBLIC_API_SCOPE_FORBIDDEN",
    "message": "Key does not have posts:write scope."
  },
  "request_id": "uuid"
}

Use error.code as your primary branching signal — it is stable across versions. error.message is human-readable and may change.

Versioning

The current version is v1. Breaking changes (field removals, enum changes, required field additions) will be released under a new version prefix (v2, etc.) with a deprecation notice period.

Non-breaking additions (new optional fields, new endpoints, new enum values) may be added to v1 without notice.

Rate limits

Rate limits are enforced per API key, per method (read vs. write), per rolling minute window. Response headers on every request include:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 2026-02-17T14:00:00Z

On limit exhaustion, the API returns 429 PUBLIC_API_RATE_LIMITED with a Retry-After header.

See Rate Limits for per-plan limits.

API reference

The full interactive reference — endpoint definitions, request/response schemas, and a live Try It console — is available at:

Open API Reference →

You can also download the OpenAPI spec:

OpenAPI spec (YAML)

API Overview