mindthread.tw

MindThread runs a brand's Threads presence for you. Daily loop: 1) get_me, list_accounts → pick account_id. 2) update_account_settings → persona (voice), schedule_times ("12:30,16:30" Asia/Taipei), content_rules {max_chars, min_chars, forbid_cta, forbid_hashtags, facts[], forbid_causal_claims, enforce:"block"}. facts = the ONLY numbers the AI may use; the server checks every number, remembers which facts the last 5 posts used (repeated_fact), and regenerates up to 3 times. 2b) build_material (account_id, urls of the brand's own pages, notes with real cases) → get_material to read it. Without material the AI only has the persona and writes generic content; with it, posts and patrol replies draw on real experiences, FAQs and sourced numbers. 3) generate_posts (topic + account_id) → read rule_violations → add_library status queued. list_library shows position and next_publish_at; update_library_item moves / archives; bulk_library handles 50 at once. Old scripts that write the library directly are checked at publish time too (block → moved to draft). 4) set_cloud_patrol (1-10 keywords, 3-5 works best; "#tag" entries for topic tags, enabled, review_before_reply:true for the first week) → list_pending_replies → approve_pending_reply (optionally edited) / reject_pending_reply. 5) cloud_patrol_stats, browser_patrol_stats, analytics_insights daily; list_events (since=latest_at) or a webhook for patrol.pending / post.failed / token.expiring. With facts + forbid_causal_claims + judge_claims + one_fact_per_post + mention_limits + enforce:block set, the server rejects invented numbers, recycled numbers, unsupported conclusions, multi-topic posts, over-mentioned brands and "N people saw this" wording. What is left for you: tone drift and whether the post is worth posting at all. mt_test_ keys return mock data, set test_mode:true and persisted:false on writes, and never mutate live account state (an endpoint that is not sandboxed yet returns test_mode_unsupported instead of writing). Sandbox events and usage (1.8.2): In the sandbox, publishing now (POST /content/publish or POST /content/generate-and-schedule with publish_now, POST /content/publish-thread, POST /experiments) records post.published, approving a pending cloud reply records patrol.reply, and an approval this key created records approval.decided when it is decided, cancelled or expires (tools: publish or generate-and-schedule with publish_now, REST publish-thread, experiments, approve_pending_reply). list_events with a mt_test_ key returns only these events of that key (data carries test_mode:true, key_id, persisted:false, request_id; an empty list comes with data.note), never mock data. Sandbox events are never delivered to webhooks and never shown to live keys. From 1.8.2, publishing now with a live key through POST /content/publish or POST /content/generate-and-schedule (publish_now) also emits post.published or post.failed (source api_publish or api_generate_and_schedule); webhook deliveries can repeat, so dedupe by post_id. latest_at moves past events you did not ask for (types), so polling never sticks. get_my_usage returns this key's own usage (summary calls / units / errors / by_endpoint and recent calls with request_id and status, newest first; days 1..30, limit 1..100, cursor = next_cursor of the previous page); it consumes no daily quota, at most 10 requests per minute per key on this endpoint, on top of the usual per-minute limit; only this key's records. Not recorded: 401 unauthorized, 401 key_disabled, answers given before the key is checked (405 method_not_allowed, 401 session_required), and the validation run before an approval is created. 429 answers and refusals made before the quota check (400 invalid_idempotency_key, 403 scope_unmapped) are recorded about once per key per minute on each server, so those counts are a lower bound. Records are written after the answer is sent, best effort: one can occasionally be missing, so summary and recent may differ slightly. Scheduling time field is publish_at everywhere (schedule_at / scheduled_at are deprecated aliases). Tool results: read structuredContent first (the REST JSON as an object); content[].text carries the same JSON as a string. Every REST response has request_id (body) and X-Request-Id (header); quote it when reporting a problem. Quotas: a mt_live_ key has its plan's daily limit plus 120 calls/minute; all mt_test_ keys of one member share a sandbox pool of 500 units/day (not charged to the plan) plus 30 calls/minute per member. Each successful tool result that consumed quota carries it in _meta["mindthread.tw/rate_limit"] (limit, remaining, reset, retry_after_seconds); disable_this_key and 401 results have none. A 429 (error.code rate_limit_exceeded) is a tool result with isError:true whose structuredContent.error carries window (daily | minute | global_sandbox | concurrency), limit, used, reset_at and retry_after_seconds: wait that long, do not retry in a loop. get_me returns data.key { id, label, prefix, last4, kind, status, scopes, legacy, scopes_enforced, agent_name, agent_url, created_at, last_used_at } and actor { type, key_id, label }; write results carry a top-level actor { type: "key", key_id } (no label). Permissions (1.8.0): every non-legacy key has allow | ask | deny per permission (data.key.scopes, scopes_enforced:true); legacy:true keys allow everything. deny returns 403 insufficient_scope (message, required, mode, have, fix; the permission is error.required[0], same as the REST header X-Required-Scope that MCP clients cannot see): stop and tell the human, do not retry. fix names this key (mt_live_...<last4>), the permission and the steps in Settings → API keys (Edit permissions and name, then Advanced); no new key is needed, and only a signed-in human can change permissions (there is no tool for it). ask returns 403 approval_required with message, scope, approval_id and approval { id, status, scope, key_id, test_mode, action { method, route, account_id, account_username, summary }, created_at, expires_at, decided_at, decision, result, human_url, human_message, poll, event, execution }: hand human_url or human_message to the human verbatim, never open the link yourself, never resend the request (you get the same approval back while it is pending, which is also how to recover a lost approval_id), then poll get_approval (the full result is only there; list_events types=approval.decided carries a summary, and for mt_test_ keys list_events returns only that key's sandbox events). The server executes the request after the owner confirms and puts the outcome in approval.result; if the status is denied, expired, cancelled or failed, stop and ask the human (a cancelled approval has cancel_reason: key_revoked, key_disabled_self, or permission_set_to_deny when the owner set that permission to deny; other values are support cancellations. Once a permission is deny, a pending approval for it can no longer be approved: the owner gets 409 approval_permission_denied and the approval turns cancelled). content:publish_now also covers REST POST /experiments and any publish_at less than 30 minutes away; add_library without status draft and update_library_item text on a queued item need content:schedule. Other codes: 409 approval_already_executed (this exact request was already confirmed and run within 24h; read error.approval.result, do not resend) · 409 approval_in_progress (confirmed, still running) · 409 approval_denied (the owner denied this exact request within 24h) · 400 approval_unsupported_field · 413 approval_payload_too_large · 400 invalid_idempotency_key (keys starting with approval: are reserved) · 403 approval_not_supported (REST POST /content/generate-and-schedule never waits for approval: use generate_posts, then publish with the text). result.error.code approval_payload_changed means the library items changed after the owner was asked (nothing ran); approval_base_changed (1.8.3) means a settings field the request touches changed after the owner was asked (nothing ran; read get_account_settings again and resend, which asks the owner again); execution_unknown means the outcome was not recorded (check before retrying). scope_unmapped is a server bug: report it with the request_id. Key metadata lives only on get_me (agent_name and agent_url are what the owner entered in Settings): GET /keys, PATCH /keys/{id} and /usage are for the web app session and answer 401 session_required to an API key. Kill switch: disable_this_key permanently disables the key you are using (no quota, works after a 429, cannot be undone); the next call is rejected, within 5 seconds at most; calls already in progress are not interrupted. Disabling stops API requests only; webhooks, queued posts and cloud patrol settings created with this key keep running. Review them in Settings. 401 key_disabled means this key was disabled (by you or by the human in Settings): stop and tell the human, do not look for another key; 401 unauthorized means the key is wrong. analytics_insights needs account_id (or "all" for the organization view). Spec: https://mindthread.tw/api/v1/openapi.json · Human docs: https://mindthread.tw/developers Content rules and settings approvals (1.8.3): From 1.8.3, content_rules are checked on every API path that writes or schedules text: POST /content/generate, /content/publish, /content/schedule, /content/generate-and-schedule, /content/publish-thread, /content/generate-thread, /experiments, POST /library and PATCH /library/{id}. With enforce:block a violation answers 422 content_rules_violated and nothing is written, scheduled or published; with enforce:warn (the default) the request succeeds and carries rule_violations (/experiments does not report them). Every path checks the fixed rules (max_chars, min_chars, forbid_cta, forbid_hashtags, banned_phrases, facts, forbid_causal_claims, one_fact_per_post, mention_limits). The model review (judge_claims) and the recently used numbers check (repeated_fact) run only on POST /content/generate, POST /library and PATCH /library/{id}; every other path, including the check right before a scheduled post publishes, runs the fixed rules only. Matching ignores invisible format characters such as zero-width spaces, compares banned_phrases and mention_limits after Unicode NFKC and case folding, and skips a number written next to - : / only when it is part of a date, time or range such as 2026-09-25, 12:30 or 5-10 (so 100000/month now counts). A topic_tag is checked against banned_phrases too; forbid_hashtags covers #hashtags in the text, not the Threads topic tag. Stored banned phrases are normalized the same way and capped at 100 characters, and invisible characters are removed from facts. error.violations is RuleViolation[] ({ rule, detail }) for one text (/content/publish, /content/schedule, /content/generate-and-schedule, PATCH /library/{id}); one RuleViolation[] per post for /content/generate; [{ index, rule_violations }] for /library and /content/publish-thread (index counts from 0 in the request array) and for /content/generate-thread (index is the thread_parts[].index of the answer, from 1); [{ formula, rule_violations }] for /experiments. Test keys get the same 422: /content/schedule and /content/publish-thread check the submitted text, and the two generating paths check their mock text, which contains the topic, so a banned phrase in the topic rehearses the refusal. The mock text is checked only against banned_phrases, forbid_cta and forbid_hashtags, because length and number rules need real text: a test key can still rehearse a successful call, and an ask permission on /content/generate-thread still creates its approval. /content/generate-and-schedule and /content/generate-thread now put the rules in the prompt and regenerate a violating draft (up to 3 model calls with enforce:block, 2 with warn), like /content/generate; model_calls says how many were made. Posts scheduled through the API are checked again right before they publish, against the rules in force at that moment: with enforce:block a violating post is not published but moved to draft with held_reason and rule_violations (GET /schedules?status=draft), the owner is notified in the web app, and post.failed with error content_rules_violated is emitted; with warn it publishes and the violations are recorded. Not checked: posts written in the web app's compose page and cloud patrol replies. Behavior change: scheduling or threading text that violates an enforce:block account through these paths used to succeed and now answers 422, and such a post already in the queue is held as a draft instead of published. Also a behavior change: PATCH /accounts/{id}/settings with a live key (legacy keys included) used to merge content_rules key by key and now replaces the object, so rules left out of the body are removed, and the stricter matching above can refuse text that used to pass. PATCH /accounts/{id}/settings now really replaces content_rules as a whole on live keys, as documented: before 1.8.3 a live write merged the object key by key, so rules left out of the body silently stayed. A settings approval (PATCH /accounts/{id}/settings waiting for the owner) now shows the owner every field the body touches as current and proposed value, using the value the server would actually write, including fields that are not guardrails such as persona and schedule_times; content_rules is itemized down to the added and removed facts and banned phrases and the enforce change. A fact that differs only in spaces is listed too, with the numbers the change newly allows. The comparison is capped at 60,000 characters: long current values are shortened (truncated:true), and a request whose comparison still does not fit answers 413 approval_payload_too_large. A facts change counts as loosening (accounts:guardrails) when a fact is new ignoring spaces, when the set of numbers the facts allow grows (a space inside 101563 allows 10 and 1563), or when a new Chinese quantity phrase appears. Such an approval also records the current value of every field the body touches. If any of those fields changes before the request runs, it is not run: the approval turns failed with result.error.code approval_base_changed as soon as it is read, listed or decided (deciding answers 409 approval_base_changed, checked in the same transaction, and always is not applied), or right before it runs. Changes to fields the body does not touch do not matter. Read the settings again and resend: the same body then gets a new approval. Settings approvals created before 1.8.3 have no recorded values and end the same way when read, listed or decided. In MCP a 422 is a tool result with isError:true; structuredContent.error.violations says which rule broke. update_account_settings: send the full content_rules object; an approval that failed with approval_base_changed means read get_account_settings again and resend.