API Overview

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)

Recently added (May 2026)

The following capabilities are live in the dashboard and on the internal API. They will be promoted to the public v1 surface in the next release, with versioning notes recorded here.

When promoted, each will follow the same response envelope, idempotency header, and rate-limit policy as the rest of v1. Until then, integrate via the dashboard or wait for the public release — internal routes are not backwards-compatibility guaranteed.