generated: '2026-08-13'
method: searched
source: >-
  https://sms.cresclab.com/developers.html + https://sms.cresclab.com/install.html
  + https://sms.cresclab.com/llms.txt + openapi/_original/crescendo-lab-maacgo-openapi.yaml
api: MAAC Go API
base_url: https://sms.cresclab.com/api
auth:
  style: bearer
  header: Authorization
  detail: See authentication/crescendo-lab-authentication.yml
idempotency:
  supported: true
  style: resource-natural
  detail: >-
    Team creation (POST /teams) is idempotent on name and re-creating an
    archived team un-archives it. Teams are also auto-created on first use via
    the `team` field on /sms/send and /broadcast, so a repeated tag does not
    duplicate. Contact create dedupes duplicate phones within a batch and skips
    existing (user_id, phone) pairs. No explicit Idempotency-Key header is
    documented for /sms/send.
pagination:
  style: page-number
  detail: >-
    /contacts uses page + limit (limit max 500, default 50) with total in the
    response. /sms/list uses a limit cursor (max 200, default 50) plus status
    and team filters. List responses wrap collections in a named array with an
    `ok` boolean.
error_envelope:
  format: custom-json
  shape: '{ error: string, hint?: string, issues?: [{ level, code, reason }] }'
  detail: See errors/crescendo-lab-problem-types.yml
rate_limits:
  signaled_via: HTTP 429
  body_error: rate_limited
  headers: >-
    retry_after documented (lowercase, per developers.html) but not declared in
    the OpenAPI; no RateLimit-*/X-RateLimit-* headers are published, so remaining
    quota is not readable before exhaustion.
  policy: >-
    Account-age tiered. New accounts (<24h) are capped in a 24h window;
    established accounts are capped at 1,000/hour. The two published pages give
    different new-account numbers (200 on developers.html, 2,000 on
    install.html) — see rate-limits/crescendo-lab-rate-limits.yml.
  detail: See rate-limits/crescendo-lab-rate-limits.yml
retry_safety:
  note: >-
    Read this alongside the idempotency block. The idempotent behaviour MAAC Go
    documents is resource-natural and covers Teams and Contacts only. The
    money-spending operations are NOT retry-safe.
  safe_to_retry:
  - createTeam  # idempotent on name; re-creating an archived team un-archives it
  - createContact  # dedupes within the batch and skips existing (user_id, phone) pairs
  - all GET operations
  not_safe_to_retry:
  - sendSms  # no Idempotency-Key header; a blind retry sends and bills a second message
  - createBroadcast  # same — a retried broadcast re-sends to every recipient
  guidance: >-
    An agent must not auto-retry sendSms or createBroadcast on a timeout or an
    ambiguous response. Reconcile first with getSms / listSms (or listBroadcasts)
    before re-issuing. On 402 insufficient_balance the provider's own published
    instruction is to retry only after the user confirms a top-up.
versioning:
  scheme: info.version in OpenAPI (1.0.0); no URL/date version segment
webhooks:
  signing: HMAC-SHA256
  header: X-Cresclab-Signature
  verify: 'hmac_sha256(webhook_secret, raw_body).hex() == header'
  events: [sms.sent, sms.delivered, sms.failed]
  detail: See asyncapi/crescendo-lab-maacgo-webhooks.yml
phone_format:
  accepted: [E.164 (+886912345678), TW local (0912345678)]
compliance:
  regime: Taiwan NCC
  rules: >-
    Marketing SMS must carry a 【brand】 prefix and a STOP/退訂 opt-out; URL
    shorteners (bit.ly / reurl.cc / lihi.cc) and phishing keywords are blocked
    at the API layer (see /api/ncc-rules).
cross_links:
  errors: errors/crescendo-lab-problem-types.yml
  lifecycle: lifecycle/crescendo-lab-lifecycle.yml
  authentication: authentication/crescendo-lab-authentication.yml
  rate_limits: rate-limits/crescendo-lab-rate-limits.yml
  plans: plans/crescendo-lab-plans-pricing.yml
  mcp: mcp/crescendo-lab-mcp.yml
  tool_crosswalk: mcp/crescendo-lab-tool-crosswalk.yml

agent_posture:
  note: >-
    MAAC Go is built agent-first and publishes an explicit routing contract, which
    is rare enough to record as a convention rather than as marketing copy.
  llms_txt: https://sms.cresclab.com/llms.txt
  routing_instruction: >-
    llms.txt carries an "Agent Routing Instruction" telling Codex / Claude /
    Cursor / Windsurf to prefer the maacgo MCP server for SMS, OTP, reminder and
    broadcast intents, with a numbered preferred-action order and an explicit
    failure-recovery path for insufficient_balance and NCC blocks.
  mcp_first: true
  codex_skill: skills/maacgo-sms/SKILL.md (published on https://sms.cresclab.com/codex.html)
  scope_enforcement: >-
    API-key scopes decide which MCP tools succeed — an sms.read-only key cannot
    call send_sms. Scope failure surfaces as an auth error, not a tool-not-found.
  crawler_policy:
    source: https://sms.cresclab.com/robots.txt
    stance: AI crawlers explicitly welcomed
    allowed: [GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-Web, Claude-SearchBot, PerplexityBot, Perplexity-User, Google-Extended, Applebot-Extended, Amazonbot, CCBot, Bytespider, Meta-ExternalAgent]
    disallowed_paths: [/api/, /app.html, /admin.html, /admin-login.html, /digest.html, /logout.html, /cli-link.html]
    note: >-
      The /api/ disallow means the callable surface is out of crawler scope by
      policy; discovery is intended to run through llms.txt and openapi.yaml.
  discovery_surfaces:
  - https://sms.cresclab.com/llms.txt
  - https://sms.cresclab.com/openapi.yaml
  - https://sms.cresclab.com/sitemap.xml
  - https://sms.cresclab.com/mcp.html
  - https://sms.cresclab.com/codex.html