openapi: 3.1.0
info:
  title: Make A Website — Agent API
  version: 1.0.0
  description: Build and manage real, hosted single-page websites on behalf of a user's Make A Website
    account. The agent links into a user's account (the user approves in the iOS app), then acts on their
    behalf.
  contact:
    url: https://agents.makeawebsite.app
servers:
- url: https://api.makeawebsite.app/api/v1
security:
- bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An agent access token (maw_agt_live_...) obtained via the device-linking flow.
paths:
  /agents/link/start:
    post:
      summary: Begin linking to a user's account
      security: []
      description: Returns a short user_code + QR for the user to approve in the app, and a device_code
        to poll with.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_name:
                  type: string
      responses:
        '200':
          description: Pending link
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_code:
                    type: string
                  verification_url:
                    type: string
                  qr:
                    type: string
                  device_code:
                    type: string
                  expires_in:
                    type: integer
                  interval:
                    type: integer
  /agents/link/poll:
    post:
      summary: Poll for the access token
      security: []
      description: Returns authorization_pending until the user approves, then the access_token (once).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - device_code
              properties:
                device_code:
                  type: string
      responses:
        '200':
          description: Token issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                  scope:
                    type: string
        '400':
          description: authorization_pending | expired_token | access_denied
  /account:
    get:
      summary: The user's plan + entitlements
      responses:
        '200':
          description: Account
          content:
            application/json:
              schema:
                type: object
                properties:
                  plan:
                    type: string
                    enum:
                    - free
                    - pro
                  pro_until:
                    type:
                    - string
                    - 'null'
                  fast_passes:
                    type: integer
                  fast_passes_monthly:
                    type: integer
                  can_build_now:
                    type: boolean
  /sites:
    get:
      summary: List the user's sites
      responses:
        '200':
          description: Sites
    post:
      summary: Create a site from a description
      description: Async build; poll /sites/{id}/status. Returns 402 if the user must upgrade.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - description
              properties:
                description:
                  type: string
                name:
                  type: string
      responses:
        '201':
          description: Created
        '402':
          description: payment_required
        '429':
          description: rate_limited
  /sites/{id}:
    get:
      summary: Get a site
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Site
        '404':
          description: not_found
    patch:
      summary: Edit name/description
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: Updated
    delete:
      summary: Delete a site
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
  /sites/{id}/status:
    get:
      summary: Build status (poll)
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  phase:
                    type: string
                    enum:
                    - building
                    - ready
                    - failed
                  preview_url:
                    type:
                    - string
                    - 'null'
  /sites/{id}/changes:
    post:
      summary: Iterate the site from a change request
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - message
              properties:
                message:
                  type: string
      responses:
        '200':
          description: Building
        '409':
          description: build_in_progress
  /sites/{id}/analytics:
    get:
      summary: Visits + conversions (7d/30d/all)
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Analytics
  /sites/{id}/submissions:
    get:
      summary: Form submissions
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Submissions
  /sites/{id}/domain:
    get:
      summary: Custom domain status + records
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Domain
    post:
      summary: Connect a custom domain (CNAME)
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domain
              properties:
                domain:
                  type: string
      responses:
        '201':
          description: Records to add
        '402':
          description: needs_pro
    delete:
      summary: Disconnect the custom domain
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Disconnected
