AstraVerify Report API

openapi: 3.2.0
info:
  description: 'Email Security and Discoverability scores for any domain, with the exact fixes. No account or key is needed. Identical scans inside 15 minutes are served from cache. Budget per caller: 120 requests a minute, 1200 an hour, 10000 a day; assistants share one egress address, so this covers everyone behind it. Fresh DNS-hitting scans are capped at 30 per domain per hour across all clients, and one caller may trigger fresh scans for at most 120 distinct domains an hour. Over a cap, a cached result up to 24 hours old is returned where one exists; otherwise the call returns 429 with code RATE_LIMITED, flagged retryable, carrying a request_id. MCP callers are never IP-blocked.'
  title: AstraVerify Domain Trust Report API
  version: 1.0.0
servers:
- url: https://astraverify.com
security:
- {}
- apiKey: []
tags:
- name: Report
paths:
  /api/v1/report:
    get:
      operationId: getReport
      parameters:
      - description: The domain to check (no scheme, no path)
        in: query
        name: domain
        required: true
        schema:
          type: string
      - description: Force a fresh scan (rate limited)
        in: query
        name: refresh
        required: false
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
          description: Report
        '400':
          $ref: '#/components/responses/InvalidInput'
        '429':
          $ref: '#/components/responses/RateLimited'
      summary: Both scores, open fixes and the report link
      tags:
      - Report
components:
  schemas:
    Component:
      description: One scored area
      properties:
        key:
          type: string
        max:
          type: integer
        name:
          type: string
        points:
          type: integer
        summary:
          type: string
      type: object
    Recommendation:
      properties:
        fix:
          $ref: '#/components/schemas/Fix'
        id:
          type: string
        scan:
          enum:
          - email
          - discoverability
          type: string
        severity:
          enum:
          - critical
          - important
          - info
          type: string
        title:
          type: string
        why:
          type: string
      type: object
    Error:
      properties:
        error:
          properties:
            code:
              description: Stable machine-readable code
              enum:
              - DISABLED
              - DNS_NXDOMAIN
              - DNS_SERVFAIL
              - INTERNAL_ERROR
              - INVALID_INPUT
              - NOT_READY
              - RATE_LIMITED
              - SCAN_TIMEOUT
              - SCHEMA_VIOLATION
              - UPSTREAM_ERROR
              type: string
            domain:
              type: string
            message:
              type: string
            request_id:
              description: Quote this to hi@astraverify.com
              type: string
            retryable:
              description: true when the same call may succeed later
              type: boolean
            stage:
              description: Where it failed, for support
              type: string
          type: object
      required:
      - error
      type: object
    Fix:
      description: The record, tag or file to add
      properties:
        kind:
          type: string
        label:
          type: string
        name:
          type: string
        type:
          type: string
        value:
          type: string
        where:
          type: string
      type: object
    Report:
      properties:
        discoverability:
          $ref: '#/components/schemas/Score'
        discoverability_cache_age_seconds:
          type: integer
        discoverability_error:
          nullable: true
          type: string
        domain:
          type: string
        email_cache_age_seconds:
          type: integer
        email_security:
          $ref: '#/components/schemas/Score'
        live_url:
          description: The live report page, which rescans when stale
          type: string
        recommendations:
          items:
            $ref: '#/components/schemas/Recommendation'
          type: array
        report_url:
          description: Saved snapshot of this report (/r/<id>); opens without a rescan
          type: string
      type: object
    Score:
      properties:
        capped:
          type: boolean
        components:
          items:
            $ref: '#/components/schemas/Component'
          type: array
        grade:
          type: string
        held_back:
          description: Points the cap holds back; components add up to score + held_back
          type: integer
        open_fixes:
          type: integer
        provider:
          type: string
        raw:
          description: Before cap rules
          type: integer
        score:
          description: Out of 100, as shown on the website
          type: integer
        verdict:
          type: string
      type: object
  responses:
    RateLimited:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: 'RATE_LIMITED — over the request budget, or the domain is over its fresh-scan cap. Retryable: back off and repeat. Where a recent result exists this returns 200 with a cached body instead of this error.'
    InvalidInput:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: INVALID_INPUT — the domain is not a domain. Not retryable.
  securitySchemes:
    apiKey:
      description: Optional. An AstraVerify API key (from your /my page) lifts the anonymous fresh-scan limits.
      scheme: bearer
      type: http