openapi: 3.0.3
info:
  title: MAAC Go Broadcast Teams API
  version: 1.0.0
  description: "MAAC Go — Taiwan-first self-serve SMS platform. Send transactional (OTP /\norder / reminder) and broadcast SMS with NCC compliance, MAAC delivery\nbackend, and real-time DLR webhooks.\n\n- Base URL: `https://sms.cresclab.com/api`\n- Auth: `Authorization: Bearer <sk_live_... or sk_test_...>`\n- New accounts receive NT$50 trial credit on signup, enough to send real test SMS immediately.\n- API keys are scoped and wallet-backed; sending debits the account balance unless your deployment uses a mock SMS/payment adapter.\n- All phone numbers use E.164 (`+886912345678`). 09xxxxxxxx is also accepted.\n- Cost: NT$0.78 per SMS segment (Chinese: 70 chars/segment · English: 160/segment).\n- Rate-limit errors return `429 rate_limited` with limit/used details and retry guidance when available.\n- Delivery confirmations arrive asynchronously via webhook (`sms.delivered`\n  / `sms.failed`); poll `GET /sms/{id}` as a fallback.\n- MCP clients (Claude / Cursor / Windsurf) can use this spec directly, or\n  connect via `POST /api/mcp` (JSON-RPC 2.0) with the same bearer key.\n"
  contact:
    name: MAAC Go Support
    email: info@cresclab.com
    url: https://sms.cresclab.com
  license:
    name: Commercial
    url: https://sms.cresclab.com/terms.html
servers:
- url: https://sms.cresclab.com/api
  description: Production
security:
- bearerAuth: []
tags:
- name: Teams
  description: Cost-attribution teams. Tag sends with a team to see which team sent/spent how much (shared wallet — reporting only, not a wallet split).
paths:
  /teams:
    get:
      tags:
      - Teams
      summary: List cost-attribution teams (+ lifetime usage)
      operationId: listTeams
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  teams:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        archived:
                          type: boolean
                        created_at:
                          type: string
                          format: date-time
                        msg_count:
                          type: integer
                        cost_cents:
                          type: integer
    post:
      tags:
      - Teams
      summary: Create a team (idempotent on name; re-creates un-archive)
      description: 'Teams are also auto-created on first use via `team` on `/sms/send` or `/broadcast`,

        so calling this explicitly is optional — handy for pre-seeding before you send.

        '
      operationId: createTeam
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  example: 付費會員
      responses:
        '200':
          description: Created (or already existed)
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  team:
                    type: object
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      archived:
                        type: boolean
                      created_at:
                        type: string
                        format: date-time
    delete:
      tags:
      - Teams
      summary: Archive a team (soft-delete; history is retained)
      operationId: deleteTeam
      parameters:
      - in: query
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Archived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <api_key>`. Production keys start with `sk_live_`,

        test keys with `sk_test_` for environment separation. Sending still follows

        the account wallet and deployment adapter settings.

        '