API reference

Base URL https://hawcast.ialae.com/v1. New to connecting an account? Start with the Meta setup guide.

Authentication

Every request needs your project API key, as a bearer token or X-API-KEY header. Find it in the dashboard under API keys.

curl https://hawcast.ialae.com/v1/usage \
  -H "Authorization: Bearer hc_live_your_key"

Rate limits & quota

• Up to 60 requests/minute per API key (429 if exceeded).
• Each successfully published post counts against your monthly plan quota. At the limit, publishing returns 402 until the next cycle or an upgrade.

Publish a post

POST /v1/posts — publish immediately. kind is image, carousel, or reel. media_urls must be durable, publicly fetchable URLs.

# curl
curl -X POST https://hawcast.ialae.com/v1/posts \
  -H "Authorization: Bearer hc_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 42,
    "kind": "carousel",
    "media_urls": ["https://cdn.you.com/1.jpg", "https://cdn.you.com/2.jpg"],
    "caption": "Launch day"
  }'

# python
import requests
requests.post("https://hawcast.ialae.com/v1/posts",
  headers={"Authorization": "Bearer hc_live_your_key"},
  json={"account_id": 42, "kind": "image",
        "media_urls": ["https://cdn.you.com/a.jpg"], "caption": "Hello"})

// javascript
await fetch("https://hawcast.ialae.com/v1/posts", {
  method: "POST",
  headers: { Authorization: "Bearer hc_live_your_key", "Content-Type": "application/json" },
  body: JSON.stringify({ account_id: 42, kind: "image",
    media_urls: ["https://cdn.you.com/a.jpg"], caption: "Hello" })
});

Returns 201 with {id, status, external_id} on success, 502 if the platform rejected it, 402 if over quota.

Schedule a post

POST /v1/schedule — publish later. publish_at is ISO 8601 (include an offset). kind is image or carousel.

curl -X POST https://hawcast.ialae.com/v1/schedule \
  -H "Authorization: Bearer hc_live_your_key" -H "Content-Type: application/json" \
  -d '{"account_id":42,"kind":"carousel","image_urls":["https://cdn.you.com/1.jpg","https://cdn.you.com/2.jpg"],"caption":"Tuesday","publish_at":"2026-11-01T09:00:00+01:00"}'

Manage scheduled posts:

• GET /v1/schedule — list (filter with ?status=pending).
• GET /v1/schedule/{id} — one scheduled post.
• DELETE /v1/schedule/{id} — cancel a pending post.

Read endpoints

• GET /v1/accounts — connected accounts in the project (and their id for account_id).
• GET /v1/posts — published/failed history.
• GET /v1/usage — plan, posts published, quota, remaining.

Webhooks

Add a webhook URL in the dashboard to receive post.published and post.failed events. Each delivery is signed with your webhook secret using HMAC-SHA256 in the X-HawCast-Signature header; verify it before trusting the payload.

Errors