Community Open API

1. The community's plan has to include API access

The community owner controls this, not the integrator. The plan needs both the API access feature — otherwise every call returns 22203 — and a non-zero daily quota, otherwise every call returns 22204.

You do not have to discover this by collecting errors: /capabilities/get answers it directly, and still works in both of those states.

2. Create a key in the community admin console

Community admin → Integrations → API Keys → Create. A key is mfk_ followed by 64 hex characters, and the full value is shown exactly once — afterwards only the prefix is visible.

The scopes you tick at creation decide which endpoints the key can call. They cannot be edited afterwards; to change them, create a new key and revoke the old one.

Optionally restrict a key to an IP allowlist (single addresses or CIDR ranges). Requests from anywhere else fail with 10007 — the same code as an invalid key, which is worth remembering when a key that worked yesterday stops working from a new host.

Scopes

So an older key cannot call the newer endpoints — spaces, members and signed-URL reads. Issue a fresh key with those scopes ticked. This is deliberate: nobody should hand over their member directory because the platform shipped a new feature.

X-API-Key: mfk_xxx

Authorization: Bearer mfk_xxx

The key is the credential on its own — keep it server-side. It belongs in neither browser code nor a mobile bundle, where anyone can read it out and post as your members.

• Every endpoint is POST. There is no GET, PUT or DELETE — reads are POST too.
• Send Content-Type: application/json. Endpoints that take no parameters still expect an empty JSON body.
• Every id is a hashid string such as "kZ3mQ9x" — community, user, post, space and media alike. Numeric ids are rejected.
• Timestamps come back as RFC3339, for example 2026-08-18T10:00:00Z.
• Monetary amounts are integers in the smallest currency unit (cents).
• An optional Accept-Language header (zh, en, ja, ko, es, fr, de, pt) localizes error messages.
• The community is derived from your API key. Do not send a site id in the path or the body.

Success and failure share one envelope

{
  "code": 0,
  "msg": "success",
  "data": { }
}

curl -X POST https://api.mateflow.com/site_open_api/v1/capabilities/get \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" -d '{}'

# → data: {
#     "api_version": "v1",
#     "site_id": "kZ3mQ9x",
#     "scopes": ["site.read", "content.read"],
#     "api_access": true,
#     "quota_limit": 5000,     // -1 means unlimited
#     "quota_used": 128,
#     "quota_reset_at": "2026-09-15T00:00:00Z"
#   }

• Reads that take a list of ids cap at 50, and every paginated endpoint caps limit at 50.
• On /space/feed/list the cursor encoding follows sort, so switching sort means restarting pagination. Q&A spaces ignore sort and order by qa_sort instead. New integrations should use /space/feed/list with sort=top rather than /space/feed/top.
• Member responses are a narrow projection: id, username, display_name, avatar_url, status, role and created_at. The email is never returned, even when you looked the member up by it — you already hold that address, and echoing every member's back would turn /member/get into a contact export. Lookup is exact-match only, and a miss is a normal success, not an error, so hits and misses are indistinguishable by status code or by timing. It also has the tightest rate limit on the API.

• author_user_id

  The member a new post is published as. Must already belong to this community, otherwise 20303.

• actor_user_id

  Who performs an edit or delete. Permission is evaluated against this member — a non-author who is not an admin gets 10004.

• viewer_user_id

  Optional on reads. Returns results as that member sees them: private spaces, like and bookmark state. Omit it for the anonymous, public-only view.

• Feeds and lists return their items plus next_cursor. Send next_cursor back untouched to fetch the next page; an empty next_cursor means you reached the end.
• limit caps out at 50 everywhere.
• On /space/feed/list the cursor encodes the current sort. Changing sort mid-listing invalidates the cursor — reset to the first page.

• idempotency_key is required on every write and capped at 190 characters. Reusing one never creates a second post.
• Its scope is the community, the request type and the key together, independent of which API key you used: two different keys on the same community sending the same idempotency_key to the same endpoint means the second call replays the first result.
• The same key with a different body returns a stable conflict error rather than silently passing as a successful retry.
• When a request times out, retry with the same key — never generate a fresh one.

• scheduled_at is an i64 Unix timestamp in seconds — not the RFC3339 string every other timestamp uses.
• On /post/update, omitting scheduled_at leaves the existing schedule alone. It is not a clear.

1. Exchange your API key for a short-lived upload token via /media/get_token.
2. POST the file as multipart to the media service, with the token in a header literally named "token" and file_cate set to one of Media, Avatar, Header, Audio or File.
3. Pass the returned media id in media_ids when you create the post.

# 1. Exchange the API key for a short-lived upload token.
#    Since 2026-09 a token with no explicit scope is upload-only.
curl -X POST https://api.mateflow.com/site_open_api/v1/media/get_token \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" \
  -d '{"author_user_id": "kZ3mQ9x", "scope": "upload"}'

# 2. Upload the file to the media service (token goes in a "token" header)
curl -X POST https://media.mateflow.com/api/v1/media/upload \
  -H "token: <token from step 1>" \
  -F "file_cate=Media" -F "file=@photo.jpg"

# 3. Attach the media id when creating the post
curl -X POST https://api.mateflow.com/site_open_api/v1/post/create \
  -H "X-API-Key: mfk_xxx" -H "Content-Type: application/json" \
  -d '{"author_user_id":"kZ3mQ9x","idempotency_key":"6f1c...","body":"Hi","media_ids":["m8Yq2Lp"]}'

Private media is read through /media/get_signed_urls, which takes the items and an access_level of 1 (public), 2 (semi-private) or 3 (private) and returns URLs with an expiry. Request them on demand instead of storing them, or they will start returning 403.

Attaching media to a post

• Send either medias — a list of media_id and alt pairs — or media_ids, a plain list of ids. Sending both returns 10005.
• alt is optional. An empty string clears the existing alt text; omitting the field leaves it as it was.

Error responses carry a request_id. Quote it when you report a problem — it is how we find your exact call in the logs.

Plan errors carry structured metadata

Both plan errors come back with enough detail to tell the community owner what to do, so you can surface a real message instead of "something went wrong".

// The plan does not include API access
{
  "code": 22203,
  "msg": "...",
  "request_id": "00de5640-8ae5-4a71-aef8-2f2cab0ce8a7",
  "data": {
    "error_code": "feature_not_available",
    "feature": "api_access",
    "required_plan": "Growth"
  }
}

// The community is out of daily quota
{
  "code": 22204,
  "data": {
    "error_code": "quota_exceeded",
    "resource": "api_requests_per_day",
    "current": "5001",
    "limit": "5000",
    "required_plan": "Business"
  }
}

The daily quota counts requests that pass authentication, resets at 00:00 UTC, and reports the ceiling actually in force in data.limit — including any allowance raised for that community specifically. When the counter's backend misbehaves the request is allowed through rather than rejected, so an occasional undercount does not mean the quota stopped working.

Per-key burst budget (new in September 2026)

Previously the only bucket was per IP, so several customers behind one egress address competed with each other while a caller spread across many addresses was barely constrained. The budget is now tiered per key — the thing a community owner issues, can rotate, and is accountable for.

member/lookup is much tighter for security rather than capacity. Its other constraints limit how much a single answer reveals; this one limits how many times you can ask — and that is the step that turns lookup into directory harvesting. Used as designed, resolving addresses you already hold at human pace, ten a minute is plenty.

• Going over returns HTTP 429 with code 10202, plus Retry-After and the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
• Treat these numbers as a starting point, not a measurement — they are tuned from observed traffic. Do not hardcode them into retry logic; honour 429 and Retry-After instead. The rate-limiting layer is off by default and runs in observation mode for a while before it is enforced.
• Implement 429 backoff regardless, and keep read traffic at or below roughly 10 requests per second.

De-duplicate on event_id. A delivery you processed successfully but answered too slowly arrives again with a new delivery_id and the same event_id. When one event goes to both a custom webhook and a Zap, both sides see the same event_id, so you can line them up.

Delivery is at-least-once and may be out of order. Duplicates and late arrivals of older events are both normal; the receiver has to be idempotent.

• The community is derived from your API key. Do not send a site id in the path or the body.
• Scopes are fixed when the key is created. To change them, create a new key and revoke the old one.
• Keep your API keys server-side. A key in client code lets anyone who reads it post as your members.
• The OpenAPI contract covers every path and schema. One caveat: the generator it comes from does not emit required on request bodies, so take required fields from this page rather than from the spec.