Hapi API documentation

1. Start a 15-day trial. Your workspace comes with labelled demo data and sandbox accounts so you can call the API right away.
2. Create an API key in Dashboard → API keys. The secret is shown once — store it in an environment variable.
3. Connect social accounts in Dashboard → Social accounts (OAuth, credentials, or a sandbox account).
4. List your accounts, then publish with one request.

curl -X GET "https://hapi.tools/v1/accounts" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx"

Authenticate every request with a bearer token. Keys look like hapi_live_… and belong to one organization.

curl https://hapi.tools/v1/accounts \
  -H "Authorization: Bearer hapi_live_xxxxxxxx"

• Scopes. READ keys can only call GET endpoints. READ_WRITE keys can create, update and delete.
• Profile restrictions. A key can be limited to specific profiles; it then only sees accounts and posts within them.
• Storage. We store a peppered SHA-256 hash of each key — never the key itself. Lost keys can't be recovered, only revoked and replaced.
• Never call the API from a browser or mobile app with a secret key. Proxy requests through your backend.

Sandbox accounts let you build and test without platform credentials. They run every request through the same validation as live accounts (character limits, media rules, required options), but never contact the platform.

• Sandbox targets finish with status sandbox_published and "sandbox": true. They are never reported as real publishes.
• Include [sandbox:fail] in the content to force a failure and test your error handling.
• Sandbox accounts count toward your plan's account limit and can be removed at any time.

A post has one piece of content and one or more targets — the social accounts it goes to. Pass accountIds, platforms, or both (platforms then filters the accounts). Each target is validated against its platform's real limits before anything is published.

• Omit scheduledAt (or send null) to publish immediately — the response contains the final per-target result.
• Override text or supply required fields per platform with platformOptions, e.g. {"reddit": {"subreddit": "webdev", "title": "…"}}.
• Attach media by mediaIds (from POST /v1/media) or public mediaUrls.
• Send an Idempotency-Key header to make retries safe — the same key returns the original post.
• firstComment is posted as a comment or self-reply on platforms that support it.

curl -X POST "https://hapi.tools/v1/posts" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "accountIds": [
    "account_123"
  ],
  "content": "Our new product is live!",
  "platforms": [
    "instagram",
    "linkedin"
  ],
  "mediaUrls": [
    "https://example.com/image.jpg"
  ],
  "scheduledAt": null
}'

Set scheduledAt to an ISO-8601 timestamp with an offset (for example 2026-11-20T09:00:00-05:00). The post is stored with status scheduled and published by Hapi's scheduler within about 15 seconds of that time. Pass timezone (IANA name) to record the author's intent for display.

Scheduled posts can be edited or rescheduled with PATCH /v1/posts/:id until they start publishing. Drafts ("draft": true) are never published automatically.

curl -X POST "https://hapi.tools/v1/posts" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "platforms": [
    "linkedin",
    "x"
  ],
  "content": "Webinar starts in one hour 👋",
  "scheduledAt": "2026-11-20T09:00:00-05:00",
  "timezone": "America/New_York"
}'

Analytics are normalized into impressions, reach, likes, comments, shares, clicks and followers. Values come from each platform's API where it exposes them; some (Slack, Discord webhooks, LinkedIn member profiles) expose none, and Bluesky exposes followers and per-post counts only. Demo data is flagged so it's never mistaken for live numbers.

curl -X GET "https://hapi.tools/v1/analytics?from=2026-10-01&to=2026-10-31&platform=x" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx"

Register an HTTPS endpoint to receive events as they happen. Each delivery is a JSON POST with these headers:

Respond with any 2xx within 10 seconds. Failed deliveries are retried with exponential backoff (30s, 1m, 2m, 4m…) for up to 6 attempts, and can be retried manually from the dashboard or the API. Verify the signature before trusting a payload:

import crypto from "node:crypto";

export function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

// Express: app.post("/hooks/hapi", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verify(req.body.toString(), req.get("hapi-signature"), process.env.HAPI_WEBHOOK_SECRET)) return res.sendStatus(400);
//   res.sendStatus(200);
// });

Hapi runs a remote Model Context Protocol server at https://hapi.tools/mcp. Any MCP-capable agent (Claude, Codex, Gemini CLI, Cursor, VS Code Copilot, Windsurf) can publish, schedule and analyze with no code: add the server with your API key and ask in plain language. The fastest path is Dashboard → AI agents, which creates a key and fills it into these snippets.

claude mcp add --transport http hapi https://hapi.tools/mcp \
  --header "Authorization: Bearer YOUR_HAPI_API_KEY"

Transport is stateless Streamable HTTP; authenticate with the same Authorization: Bearer key as the REST API. Rate limits, plan limits, profile restrictions and the audit log all apply. Write tools need a READ_WRITE key, so give reporting agents a READ key.

No MCP support? Point the agent at /llms.txt, a plain-text guide to the REST API written for LLMs, or define your own tools over the endpoints below. ChatGPT and claude.ai web connectors need OAuth sign-in, which is coming soon.

All endpoints accept and return JSON (except media upload, which takes multipart/form-data). Timestamps are ISO-8601 in UTC. List endpoints paginate with page and limit.

curl -X GET "https://hapi.tools/v1/accounts" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "id": "account_123",
      "platform": "linkedin",
      "username": "acme-inc",
      "displayName": "Acme Inc.",
      "avatarUrl": null,
      "status": "active",
      "sandbox": false,
      "profileId": "prof_1",
      "connectedAt": "2026-10-02T10:00:00.000Z"
    }
  ]
}

curl -X POST "https://hapi.tools/v1/posts" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "accountIds": [
    "account_123"
  ],
  "content": "Our new product is live!",
  "platforms": [
    "instagram",
    "linkedin"
  ],
  "mediaUrls": [
    "https://example.com/image.jpg"
  ],
  "scheduledAt": null
}'

{
  "id": "cmh2k8x0p0001",
  "content": "Our new product is live!",
  "status": "published",
  "scheduledAt": null,
  "publishedAt": "2026-11-01T14:02:11.000Z",
  "timezone": "UTC",
  "firstComment": null,
  "source": "api",
  "isDemo": false,
  "media": [
    {
      "id": "cmh2k7q1z0000",
      "url": "https://example.com/image.jpg",
      "kind": "image"
    }
  ],
  "targets": [
    {
      "accountId": "account_123",
      "platform": "linkedin",
      "username": "acme-inc",
      "status": "published",
      "sandbox": false,
      "platformPostId": "urn:li:share:7251…",
      "url": "https://www.linkedin.com/feed/update/urn:li:share:7251…/",
      "error": null,
      "publishedAt": "2026-11-01T14:02:11.000Z"
    },
    {
      "accountId": "account_456",
      "platform": "instagram",
      "username": "@instagram_sandbox",
      "status": "sandbox_published",
      "sandbox": true,
      "platformPostId": "sbx_instagram_9fK2…",
      "url": null,
      "error": null,
      "publishedAt": "2026-11-01T14:02:10.000Z"
    }
  ],
  "createdAt": "2026-11-01T14:02:09.000Z",
  "updatedAt": "2026-11-01T14:02:11.000Z"
}

curl -X GET "https://hapi.tools/v1/posts?status=scheduled&limit=20" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx"

{
  "data": [
    "…post objects…"
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "hasMore": true
  }
}

curl -X PATCH "https://hapi.tools/v1/posts/cmh2k8x0p0001" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduledAt": "2026-11-21T15:00:00Z"
}'

curl -X POST "https://hapi.tools/v1/posts/cmh2k8x0p0001/retry" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx"

curl -X POST "https://hapi.tools/v1/media" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx" \
  -F "file=@./launch.jpg"

{
  "id": "cmh2k7q1z0000",
  "url": "https://hapi.tools/api/media/…/a1b2.jpg",
  "kind": "image",
  "mimeType": "image/jpeg",
  "sizeBytes": 482113
}

curl -X GET "https://hapi.tools/v1/analytics?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx"

{
  "data": {
    "isDemo": false,
    "totals": {
      "impressions": 48210,
      "reach": 34711,
      "likes": 2169,
      "comments": 289,
      "shares": 193,
      "clicks": 578,
      "followers": 12840,
      "engagement": 2651,
      "engagementRate": 0.055
    },
    "series": [
      "…daily rows…"
    ],
    "platforms": [
      "…per platform…"
    ]
  }
}

curl -X GET "https://hapi.tools/v1/platforms" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx"

curl -X POST "https://hapi.tools/v1/webhooks" \
  -H "Authorization: Bearer hapi_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/hapi",
  "events": [
    "post.published",
    "post.failed"
  ]
}'

{
  "id": "wh_1",
  "url": "https://example.com/hooks/hapi",
  "events": [
    "post.published",
    "post.failed"
  ],
  "enabled": true,
  "secret": "whsec_…"
}

Platforms don't all support the same things. Hapi enforces each platform's actual rules instead of pretending otherwise.

Limits apply per API key over a one-minute window and depend on your plan:

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). Over the limit you'll get 429 rate_limited with a Retry-After header. Platforms also enforce their own quotas (for example, Instagram's 100 API posts per 24 hours); those surface as target errors with code platform_rate_limited.

Errors use one envelope. details is present for validation errors and lists each problem.

{
  "error": {
    "code": "validation_error",
    "message": "Post failed platform validation",
    "details": [
      {
        "accountId": "account_789",
        "platform": "x",
        "message": "X: 312/280 characters"
      }
    ]
  }
}

BetaNot yet available in the public API. Contact sales@hapi.tools to join the beta.

Send and receive direct messages on platforms with messaging APIs (Instagram, Facebook Messenger, WhatsApp Cloud API).

BetaNot yet available in the public API. Contact sales@hapi.tools to join the beta.

Read, reply to, hide and delete comments on published posts.

BetaNot yet available in the public API. Contact sales@hapi.tools to join the beta.

A unified, normalized stream of comments, mentions and messages across accounts.

BetaNot yet available in the public API. Contact sales@hapi.tools to join the beta.

Boost posts and read paid performance alongside organic analytics.

OAuth tokens and platform credentials are encrypted at rest with AES-256-GCM and only decrypted server-side at publish time. API keys are stored as peppered hashes. Webhook payloads are HMAC-signed. All tenant data is isolated per organization and every privileged action is written to an audit log. Report vulnerabilities to support@hapi.tools.

Placeholder — the full terms of service will be published here before general availability. You remain responsible for complying with each social platform's developer terms.

Placeholder — the full privacy policy will be published here. We only request the platform permissions needed to publish and read analytics, and you can disconnect accounts at any time.