API Reference

The API is served from https://api.algomuse.io/api/v1. The version is pinned in the URL path (/api/v1). Backwards-incompatible changes ship under a new version; additive, non-breaking changes may be made to /api/v1. When we deprecate a version we announce it in advance and support the previous version through a migration window.

API access is available on the Business and Enterprise plans. Authenticate every request with a secret API key sent as a Bearer token: Authorization: Bearer am_live_... (test keys start am_test_). Create, roll, and revoke keys in Dashboard → Developers; a new key is shown once.

Treat keys like passwords: keep them server-side, never embed them in client-side code or commit them to source control. Requests without a valid key return 401 invalid_api_key.

Each key carries the scopes you pick when you create it, and each endpoint below names the scope it needs. A key without it gets 403 insufficient_scope. Available scopes:

• posts:read
• posts:write
• posts:publish
• analytics:read
• conversations:read
• conversations:write
• workspace:read
• templates:read
• templates:write
• calendar:read
• calendar:write
• crisis:read
• crisis:write
• listening:read
• listening:write
• competitors:read
• competitors:write
• linkinbio:read
• linkinbio:write
• influencers:read
• influencers:write
• search:read
• uploads:read
• uploads:write
• media:read

Rate limits are enforced per API key. Each key allows 60 requests a minute and 10,000 a day by default; you can set other limits when you create it, up to 1,000 a minute and 100,000 a day. All /api/v1 traffic is also held to 100 requests a minute per key. Every response includes the current limit state in these headers:

• X-RateLimit-Limit — the ceiling for the current window
• X-RateLimit-Remaining — requests left in the window
• X-RateLimit-Reset — when the window resets

Exceeding a limit returns 429 rate_limit_exceeded with a Retry-After header. Back off and retry after the indicated delay.

Errors use conventional HTTP status codes and a JSON body. The error.code is a stable, machine-readable string; error.message is human-readable and may change.

{
  "success": false,
  "error": {
    "code": "resource_not_found",
    "message": "Post not found"
  }
}

List endpoints accept limit (page size, up to 100) and offset (records to skip) query parameters, and return a pagination object (totalItems, totalPages, hasNextPage) alongside the data array.

You can register webhook endpoints in Dashboard → Developers and send them a test event. Delivery of post, account and analytics events is not live yet; until it is, poll the endpoints above. Each delivery is an HTTP POST with a { id, type, created_at, data } body and these headers:

• X-AlgoMuse-Event — the event type
• X-AlgoMuse-Delivery — the delivery id
• X-AlgoMuse-Signature — formatted t=<unix time>,v1=<hex>

Always verify the signature. Compute an HMAC-SHA256 of <t>.<raw request body> using your endpoint's signing secret and compare it (in constant time) to the v1 value before trusting the payload.