1. Create an API key

In the Aidelly dashboard, go to Account Settings → API Keys:

Choose the scopes your integration needs
Save the key immediately — it is shown only once

For a full-access integration, include:

posts:write
posts:read
media:write
connections:read
webhooks:manage

2. Set local environment variables

export AIDELLY_API_BASE="https://app.aidelly.ai/api/public/v1"
export AIDELLY_API_KEY="aidelly_live_xxx"
export WORKSPACE_ID="your-workspace-id"
export BRAND_ID="your-brand-id"

Find your workspace and brand IDs in Account Settings → API Keys.

3. Create a signed upload URL

curl -sS "$AIDELLY_API_BASE/media/upload-url" \
  -X POST \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "Idempotency-Key: media-upload-2026-02-17-001" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID" \
  -H "x-aidelly-brand-id: $BRAND_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "launch-image.png",
    "content_type": "image/png",
    "file_size": 245000,
    "folder": "campaign-assets"
  }'

The response includes a data.upload.signed_url to PUT your file bytes, and a data.read_url to reference in posts:

{
  "success": true,
  "data": {
    "media_id": "45e938be-a4f0-4e4f-a56d-b65c954f8b2e",
    "read_url": "https://app.aidelly.ai/api/media/stream/...",
    "upload": {
      "signed_url": "https://...",
      "token": "...",
      "path": "public-api/..."
    }
  },
  "request_id": "89d33225-0d24-42ea-8f46-3ec5ad777f99"
}

4. Create a scheduled post

curl -sS "$AIDELLY_API_BASE/posts" \
  -X POST \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "Idempotency-Key: post-create-2026-02-17-001" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID" \
  -H "x-aidelly-brand-id: $BRAND_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "account_id": "social-account-id",
    "scheduled_at": "2026-02-18T17:30:00Z",
    "timezone": "UTC",
    "content": {
      "text": "Launching our new feature today.",
      "media": [
        {
          "url": "https://app.aidelly.ai/api/media/stream/...",
          "type": "image"
        }
      ],
      "hashtags": ["#launch", "#product"]
    },
    "metadata": {
      "campaign": "spring-launch",
      "source": "agent"
    }
  }'

A successful response returns the post ID and status:

{
  "success": true,
  "data": {
    "mode": "scheduled",
    "post": {
      "id": "4b557f9b-7f40-40d8-91dc-98c211295d63",
      "platform": "linkedin",
      "status": "scheduled",
      "scheduled_at": "2026-02-18T17:30:00.000Z"
    }
  }
}

5. Check post status

export POST_ID="4b557f9b-7f40-40d8-91dc-98c211295d63"

curl -sS "$AIDELLY_API_BASE/posts/$POST_ID" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID" \
  -H "x-aidelly-brand-id: $BRAND_ID"

List posts with filters:

curl -sS "$AIDELLY_API_BASE/posts?platform=linkedin&status=scheduled&limit=25" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID"

curl -sS "$AIDELLY_API_BASE/webhooks" \
  -X POST \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "Idempotency-Key: webhook-create-2026-02-17-001" \
  -H "x-aidelly-workspace-id: $WORKSPACE_ID" \
  -H "x-aidelly-brand-id: $BRAND_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.example.com/aidelly/webhooks",
    "events": ["post.created", "post.scheduled", "post.published", "post.failed", "post.canceled"],
    "description": "Primary automation endpoint"
  }'

7. Inspect usage and limits

curl -sS "$AIDELLY_API_BASE/usage" \
  -H "Authorization: Bearer $AIDELLY_API_KEY"

Returns your plan tier, read/write rate limits, current window remaining requests, and per-endpoint usage breakdown.

Retry logic

Retryable:

429 PUBLIC_API_RATE_LIMITED — wait for Retry-After value
500 family errors — retry with exponential backoff

Non-retryable without payload changes:

400 PUBLIC_API_BODY_INVALID
403 PUBLIC_API_SCOPE_FORBIDDEN
409 PUBLIC_API_IDEMPOTENCY_CONFLICT

See the full error catalog for all codes and guidance.

Quickstart