Developer API Overview

Overview of the Mulaichat REST API Gateway, authentication, scopes, response format, and error handling.

Welcome to the Mulaichat Developer Guide. This section provides everything you need to start integrating programmatic publishing, analytics, and messaging into your applications.

Base URL

All requests must be directed to the global production API gateway over HTTPS:

https://api.mulaichat.com

Authentication

Every request to the Mulaichat REST API must include your secret API key in the Authorization HTTP header:

Authorization: Bearer mc_live_••••••••••••••••

You can create, roll, and revoke API keys from your workspace dashboard under Settings > API Keys.

[!IMPORTANT] Keep your API keys confidential. Do not expose keys with write or admin scopes in client-side code or public repositories.

API Scopes

Mulaichat uses granular scopes to limit token access:

Scope	Description
`read`	Read connected accounts, scheduled posts, comments, follower stats, and analytics.
`write`	Create and schedule posts, upload media, post comments, and reply to direct messages.
`admin`	Manage workspace settings, rotate API keys, configure webhooks, and disconnect accounts.

Request & Response Format

All request bodies must be sent as application/json with UTF-8 encoding.

Successful responses return standard JSON structures with an HTTP 2xx status code:

{
  "success": true,
  "data": {
    "id": "post_9c7f18e2",
    "status": "scheduled",
    "scheduled_at": "2026-11-05T14:30:00.000Z"
  }
}

Error Handling

When an error occurs, Mulaichat returns a standard JSON error envelope:

{
  "error": {
    "code": "invalid_contact_id",
    "message": "The platform_id parameter must be a numeric Instagram ID.",
    "status": 400
  }
}

Common HTTP Status Codes

Code	Error Type	Description
`200`	OK	The request succeeded.
`201`	Created	Resource created successfully (e.g. post, media, webhook).
`400`	Bad Request	Missing required parameters or invalid syntax.
`401`	Unauthorized	Missing, invalid, or expired Bearer token.
`403`	Forbidden	Insufficient scope or feature unavailable on current plan.
`404`	Not Found	Requested resource ID does not exist.
`422`	Unprocessable	Validation error (e.g. missing Instagram messaging permissions).
`429`	Rate Limited	Request quota exceeded. Retry after delay.
`500`	Internal Error	Unexpected server error.

Rate Limits

General REST API: 60 requests per minute per workspace API key.
Instagram Contacts & Direct Messages: Up to 300 live lookups per hour per connected Instagram account.
Webhook Retries: Automatically retried up to 5 times with exponential backoff if your endpoint returns 5xx or times out.

Developer API Overview

Base URLCopy Anchor Link

AuthenticationCopy Anchor Link

API ScopesCopy Anchor Link

Request & Response FormatCopy Anchor Link

Error HandlingCopy Anchor Link

Common HTTP Status CodesCopy Anchor Link

Rate LimitsCopy Anchor Link