AstraVerify Fetch As 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 Fetch As API
  version: 1.0.0
servers:
- url: https://astraverify.com
security:
- {}
- apiKey: []
tags:
- name: Fetch As
paths:
  /api/v1/fetch-as:
    get:
      operationId: fetchAsCrawler
      parameters:
      - description: The domain to check (no scheme, no path)
        in: query
        name: domain
        required: true
        schema:
          type: string
      - in: query
        name: agent
        required: true
        schema:
          enum:
          - googlebot
          - bingbot
          - oai-searchbot
          - perplexitybot
          - claudebot
          - gptbot
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrawlerView'
          description: Crawler view
        '400':
          $ref: '#/components/responses/InvalidInput'
        '429':
          $ref: '#/components/responses/RateLimited'
      summary: What a named crawler receives from the root page
      tags:
      - Fetch As
components:
  responses:
    InvalidInput:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: INVALID_INPUT — the domain is not a domain. Not retryable.
    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.'
  schemas:
    CrawlerView:
      properties:
        agent:
          type: string
        blocked:
          type: boolean
        chain:
          description: 'Each hop: url, status'
          items:
            properties:
              status:
                type: integer
              url:
                type: string
            type: object
          type: array
        challenge:
          type: boolean
        content_type:
          type: string
        domain:
          type: string
        error:
          nullable: true
          type: string
        extract:
          description: Text the crawler would index
          type: string
        final_url:
          type: string
        headers:
          additionalProperties:
            type: string
          type: object
        label:
          type: string
        ms:
          type: integer
      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
  securitySchemes:
    apiKey:
      description: Optional. An AstraVerify API key (from your /my page) lifts the anonymous fresh-scan limits.
      scheme: bearer
      type: http