blawgy-com Support API

openapi: 3.2.0
info:
  title: Blawgy Support API
  version: 1.0.0
  description: 'The Blawgy API: everything the Blawgy dashboard and MCP server can do, over HTTPS. Every endpoint is also an MCP tool (`x-mcp-tool`); both transports share keys, site scoping, plan gating, rate limits and the audit log.


    **Authentication.** `Authorization: Bearer blk_live_...` with an API key from Settings > Account > AI agents in the Blawgy dashboard (or an OAuth access token issued for this host). Keys are server-side only: there is no CORS on /v1, except the keyless public content endpoints under `/public`.


    **Arguments.** GET endpoints take theirs as query parameters; POST, PATCH, PUT and DELETE take a JSON body (`Content-Type: application/json`), and their query string carries only `dryRun`. Unknown arguments are a 400, never silently dropped.


    **Errors.** Every non-2xx answer is `{ "error": { "code", "message", "details"?, "requestId" } }`. Every response carries `Request-Id`.


    **Pagination.** Lists answer `{ data, nextCursor, total? }` and take `?limit=` and `?cursor=` (the previous page''s `nextCursor`). `limit` is capped per endpoint (never above 200); a larger value is clamped to the cap.


    **Idempotency.** Send `Idempotency-Key` on POST, PATCH, PUT or DELETE to make a retry safe for 24 hours: the same key and request replays the stored answer (`Idempotent-Replayed: true`); the same key with a different request is a 422.


    **Dry runs.** `?dryRun=true` on any write runs every gate (auth, scope, plan, validation) and returns a one-line summary without doing anything.


    **Rate limits.** 240 calls a minute and 6,000 a day per key, shared with MCP. Responses carry `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`; a 429 adds `Retry-After`. The public content endpoints need no key and are limited per client IP instead.


    **Async work.** Research, writing, scans and syncs return as soon as the job is queued; poll `GET /sites/{site}/jobs/{kind}`.


    **Versioning.** `/v1` is frozen for breaking changes; additive changes ship freely.'
  termsOfService: https://blawgy.com/terms
  contact:
    url: https://blawgy.com/developers
servers:
- url: https://app.blawgy.com/v1
security:
- bearerAuth: []
tags:
- name: Support
  description: Help search and support requests.
paths:
  /help/search:
    get:
      operationId: search_help
      summary: Ask the help centre
      description: Answers a how-does-Blawgy-work question from the public help docs and cites the matching articles. Costs one LLM call and is rate limited; keep questions specific. Read only.
      tags:
      - Support
      x-mcp-tool: search_help
      x-access: read
      x-min-plan: null
      x-partner-only: false
      security:
      - bearerAuth: []
      parameters:
      - name: question
        in: query
        required: true
        schema:
          type: string
          minLength: 3
          maxLength: 1000
      responses:
        '200':
          description: The result, exactly what the matching MCP tool returns.
          headers:
            Request-Id:
              $ref: '#/components/headers/Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /sites/{site}/support/requests:
    post:
      operationId: file_support_request
      summary: File a support request
      description: 'Files a support request with the Blawgy team about this site: a subject, the full message, and an optional category (bug, question, billing, feature_request, other). A snapshot of the account (plan, platform, cadence, recent failures) is attached automatically, so the message only needs to say what happened and what the customer wants. The team replies by email to the account address. Use when something is broken, when the help docs (search_help) cannot answer, or when the customer asks to talk to a person. Works on a frozen site too. At most a few per hour.'
      tags:
      - Support
      x-mcp-tool: file_support_request
      x-access: write
      x-min-plan: null
      x-partner-only: false
      security:
      - bearerAuth: []
      parameters:
      - name: site
        in: path
        required: true
        schema:
          type: string
          minLength: 1
        description: The site, as its domain (example.com). See GET /sites.
      - $ref: '#/components/parameters/IdempotencyKey'
      - $ref: '#/components/parameters/DryRun'
      responses:
        '200':
          description: The result, exactly what the matching MCP tool returns.
          headers:
            Request-Id:
              $ref: '#/components/headers/Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  additionalProperties: true
                - type: object
                  description: 'With ?dryRun=true: every gate passed, nothing ran.'
                  properties:
                    dryRun:
                      type: boolean
                      const: true
                    tool:
                      type: string
                    summary:
                      type: string
                    valid:
                      type: boolean
                  required:
                  - dryRun
                  - summary
                  - valid
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subject:
                  type: string
                  minLength: 3
                  maxLength: 150
                  description: 'One line: what this is about.'
                message:
                  type: string
                  minLength: 10
                  maxLength: 4000
                  description: 'Everything the team needs: what was expected, what happened, which article or setting, and what the customer wants done.'
                category:
                  type: string
                  enum:
                  - bug
                  - question
                  - billing
                  - feature_request
                  - other
                  description: Defaults to other.
              required:
              - subject
              - message
              additionalProperties: false
components:
  responses:
    '429':
      description: Rate limited; `Retry-After` says when to try again.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '422':
      description: '`idempotency_key_reused`: the Idempotency-Key was used for a different request.'
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '402':
      description: The site is read-only until its billing is sorted out.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: The bearer token is missing, unknown, expired or revoked.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Something failed on our side. The `requestId` finds it in our logs.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '409':
      description: Conflict, including `idempotency_in_progress` and `idempotency_secret_not_replayable` (a retry of a call that returned a one-time secret).
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: 'The credential may not do this: read-only key, wrong scope, plan too low (`upgrade_required`), owner only.'
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: 'Not found: the route, the site (`site_not_found`) or the thing inside it.'
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '400':
      description: The request is malformed or the arguments failed validation (`details.issues` lists them).
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: Any unique string (a UUID works). A retry with the same key and request inside 24 hours replays the stored answer instead of running again.
    DryRun:
      name: dryRun
      in: query
      required: false
      schema:
        type: boolean
      description: 'true: run every gate and validation, return a summary, change nothing.'
  headers:
    Request-Id:
      schema:
        type: string
      description: Identifies this request in our logs and audit trail. Quote it to support.
    RateLimit-Remaining:
      schema:
        type: integer
      description: Calls left in the current window.
    RateLimit-Reset:
      schema:
        type: integer
      description: Seconds until the window resets.
    Idempotent-Replayed:
      schema:
        type: boolean
      description: true when this answer was replayed from an earlier request with the same Idempotency-Key.
    RateLimit-Limit:
      schema:
        type: integer
      description: Calls allowed in the current window.
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - requestId
          properties:
            code:
              type: string
              description: Stable machine-readable reason (site_not_found, invalid_request, upgrade_required, rate_limited, ...).
            message:
              type: string
            details:
              type: object
              additionalProperties: true
              description: 'Extra context; validation errors carry `issues: [{ path, code, message }]`.'
            requestId:
              type: string
              description: Same as the Request-Id header.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: blk_live_... API key or OAuth access token
      description: An API key from Settings > Account > AI agents in the Blawgy dashboard. Read keys may only call GET endpoints; keys scoped to specific sites cannot reach other sites or change the account.