Pagination

Pagination varies by endpoint. Two patterns are used:

Time-based pagination (Posts)

GET /posts uses time filters instead of page offsets:

curl "$AIDELLY_API_BASE/posts?from=2026-02-01T00:00:00Z&to=2026-02-28T23:59:59Z&limit=25" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID"

Parameters:

from (ISO 8601 datetime) — start of time range
to (ISO 8601 datetime) — end of time range
limit (int, default: 25, max: 100) — max items per response
status (optional) — filter by post status
platform (optional) — filter by platform

Response:

{
  "success": true,
  "data": {
    "items": [ ... ],
    "count": 42
  },
  "request_id": "uuid"
}

Offset-based pagination (Approvals)

GET /approvals uses page and limit:

curl "$AIDELLY_API_BASE/approvals?page=1&limit=10" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID"

Parameters:

page (int, default: 1) — 1-indexed page number
limit (int, default: 10, max: 50) — items per page

Response:

{
  "success": true,
  "data": {
    "batches": [ ... ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 42,
      "hasNext": true,
      "hasPrev": false
    }
  },
  "request_id": "uuid"
}

Increment page to fetch the next page. Check hasNext to determine when to stop.

Timestamps

All timestamps are in ISO 8601 format with UTC timezone:

2026-02-18T17:30:00Z

When you send timestamps to the API (e.g., in filter queries), use the same format:

curl "$AIDELLY_API_BASE/posts?scheduled_after=2026-02-01T00:00:00Z" \
  -H "Authorization: Bearer $AIDELLY_API_KEY"

HTTP Methods and Semantics

`POST` — Create or action

Use POST to create a new resource or perform a side-effecting action. The response returns the newly created or modified object.

Example:

curl -X POST "$AIDELLY_API_BASE/posts" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-create-001" \
  -d '{ "platform": "linkedin", "content_text": "Hello world" }'

`PATCH` — Partial update

Use PATCH to update one or more fields of an existing resource. Send only the fields you want to change; omitted fields remain unchanged.

Example:

curl -X PATCH "$AIDELLY_API_BASE/posts/$POST_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-update-001" \
  -d '{ "status": "scheduled" }'

`DELETE` — Remove

Use DELETE to remove a resource. Returns 204 No Content on success.

Example:

curl -X DELETE "$AIDELLY_API_BASE/posts/$POST_ID" \
  -H "Idempotency-Key: post-delete-001"

`GET` — Fetch

Use GET to retrieve data without side effects. Query parameters filter or paginate results.

Deprecation and Versioning Policy

The current API version is v1. Breaking changes follow this policy:

Breaking changes (field removals, enum value removals, required field additions) are released under a new major version (v2, etc.) with a 6-month deprecation notice published in the API reference and changelog.

Non-breaking additions (new optional fields, new endpoints, new enum values) are added to v1 without notice and are safe to use.

Deprecation example:

Once deprecated, a field remains functional for the notice period but may return a deprecation warning header:

Deprecation: true
Sunset: 2026-08-18T00:00:00Z
Link: </docs/api/overview#versioning>; rel="deprecation"

Plan your integration around the Sunset date to migrate before support ends.

Error Handling

All errors use a consistent format:

{
  "success": false,
  "error": {
    "code": "PUBLIC_API_RATE_LIMITED",
    "message": "Rate limit exceeded."
  },
  "request_id": "uuid"
}

Use error.code as the primary signal for branching logic — it is stable across versions and never changes without a major version bump.

error.message is human-readable and may change to improve clarity.

See Error Codes for the complete reference.

API Conventions