openapi: 3.2.0
info:
  title: Monocrawl On Page API
  version: 0.1.0
  description: One key, one envelope, one credit meter across social, search, commerce and web data.
  contact:
    name: Monocrawl support
    url: https://www.monocrawl.com/contact
  termsOfService: https://www.monocrawl.com/legal/terms-and-conditions
servers:
- url: https://www.monocrawl.com
security:
- ApiKeyHeader: []
tags:
- name: On-Page
paths:
  /v1/on_page/page:
    get:
      operationId: on_page_page
      tags:
      - On-Page
      summary: On-page SEO audit
      description: 'On-page SEO audit of one URL: title and meta description checks, heading structure, image alt coverage, internal/external links, canonical, robots meta, social tags, HTTPS, word count, and a severity-ranked findings list. Costs 3 credits per successful live response.'
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
        example: https://example.com
        description: Page URL to audit (http/https, public hosts only)
      - name: timeout
        in: query
        required: false
        schema:
          type: string
        example: '10000'
        description: Fetch budget in milliseconds, clamped to 1000-15000
      - name: dry_run
        in: query
        required: false
        schema:
          type: string
          enum:
          - '1'
          - '0'
          - 'true'
          - 'false'
        example: '1'
        description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.'
      - name: X-Max-Credits
        in: header
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        example: 5
        description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs.
      security:
      - ApiKeyHeader: []
      - BearerKey: []
      responses:
        '200':
          description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Success'
                - type: object
                  properties:
                    data:
                      $schema: https://json-schema.org/draft/2020-12/schema
                      $id: https://www.monocrawl.com/schemas/on_page/page.json
                      title: on_page/page data fields
                      description: Optional data supplied by this operation. Null means unknown.
                      type: object
                      properties:
                        canonical:
                          description: Canonical URL returned by this audit when supplied.
                          type:
                          - string
                          - 'null'
                        _warnings:
                          description: Optional  warnings supplied by this operation. Null means unknown.
                          type:
                          - array
                          - 'null'
                          items:
                            description: Optional record supplied by this operation. Null means unknown.
                            type:
                            - string
                            - 'null'
                        final_url:
                          description: Optional final url supplied by this operation. Null means unknown.
                          type:
                          - string
                          - 'null'
                        findings:
                          description: Optional findings supplied by this operation. Null means unknown.
                          type:
                          - array
                          - 'null'
                          items:
                            description: Optional record supplied by this operation. Null means unknown.
                            type:
                            - object
                            - 'null'
                            properties:
                              id:
                                description: Source identifier. Preserve the supplied type and exact value.
                                type:
                                - string
                                - 'null'
                              message:
                                description: Optional message supplied by this operation. Null means unknown.
                                type:
                                - string
                                - 'null'
                              severity:
                                description: Optional severity supplied by this operation. Null means unknown.
                                type:
                                - string
                                - 'null'
                            additionalProperties: true
                        headings:
                          description: Optional headings supplied by this operation. Null means unknown.
                          type:
                          - object
                          - 'null'
                          properties:
                            counts:
                              description: Optional counts supplied by this operation. Null means unknown.
                              type:
                              - object
                              - 'null'
                              properties:
                                h1:
                                  description: Optional h1 supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                h2:
                                  description: Optional h2 supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                h3:
                                  description: Optional h3 supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                h4:
                                  description: Optional h4 supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                h5:
                                  description: Optional h5 supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                h6:
                                  description: Optional h6 supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                              additionalProperties: true
                            h1_count:
                              description: Optional h1 count supplied by this operation. Null means unknown.
                              type:
                              - number
                              - 'null'
                            outline:
                              description: Optional outline supplied by this operation. Null means unknown.
                              type:
                              - array
                              - 'null'
                              items:
                                description: Optional record supplied by this operation. Null means unknown.
                                type:
                                - object
                                - 'null'
                                properties:
                                  level:
                                    description: Optional level supplied by this operation. Null means unknown.
                                    type:
                                    - number
                                    - 'null'
                                  text:
                                    description: Source text when supplied.
                                    type:
                                    - string
                                    - 'null'
                                additionalProperties: true
                            structure_ok:
                              description: Optional structure ok supplied by this operation. Null means unknown.
                              type:
                              - boolean
                              - 'null'
                          additionalProperties: true
                        https:
                          description: Optional https supplied by this operation. Null means unknown.
                          type:
                          - boolean
                          - 'null'
                        images:
                          description: Optional images supplied by this operation. Null means unknown.
                          type:
                          - object
                          - 'null'
                          properties:
                            total:
                              description: Source-reported total; null is unknown.
                              type:
                              - number
                              - 'null'
                            with_alt:
                              description: Optional with alt supplied by this operation. Null means unknown.
                              type:
                              - number
                              - 'null'
                            without_alt:
                              description: Optional without alt supplied by this operation. Null means unknown.
                              type:
                              - number
                              - 'null'
                          additionalProperties: true
                        language:
                          description: Optional language supplied by this operation. Null means unknown.
                          type:
                          - string
                          - 'null'
                        links:
                          description: Optional links supplied by this operation. Null means unknown.
                          type:
                          - object
                          - 'null'
                          properties:
                            external:
                              description: Optional external supplied by this operation. Null means unknown.
                              type:
                              - number
                              - 'null'
                            internal:
                              description: Optional internal supplied by this operation. Null means unknown.
                              type:
                              - number
                              - 'null'
                            total:
                              description: Source-reported total; null is unknown.
                              type:
                              - number
                              - 'null'
                          additionalProperties: true
                        meta_description:
                          description: Optional meta description supplied by this operation. Null means unknown.
                          type:
                          - object
                          - 'null'
                          properties:
                            length:
                              description: Optional length supplied by this operation. Null means unknown.
                              type:
                              - number
                              - 'null'
                            present:
                              description: Optional present supplied by this operation. Null means unknown.
                              type:
                              - boolean
                              - 'null'
                          additionalProperties: true
                        open_graph:
                          description: Optional open graph supplied by this operation. Null means unknown.
                          type:
                          - object
                          - 'null'
                          properties:
                            complete:
                              description: Optional complete supplied by this operation. Null means unknown.
                              type:
                              - boolean
                              - 'null'
                            missing:
                              description: Optional missing supplied by this operation. Null means unknown.
                              type:
                              - array
                              - 'null'
                              items:
                                description: Optional record supplied by this operation. Null means unknown.
                                type:
                                - string
                                - 'null'
                            present:
                              description: Optional present supplied by this operation. Null means unknown.
                              type:
                              - number
                              - 'null'
                          additionalProperties: true
                        redirected:
                          description: Optional redirected supplied by this operation. Null means unknown.
                          type:
                          - boolean
                          - 'null'
                        robots:
                          description: Optional robots supplied by this operation. Null means unknown.
                          type:
                          - object
                          - 'null'
                          properties:
                            nofollow:
                              description: Optional nofollow supplied by this operation. Null means unknown.
                              type:
                              - boolean
                              - 'null'
                            noindex:
                              description: Optional noindex supplied by this operation. Null means unknown.
                              type:
                              - boolean
                              - 'null'
                          additionalProperties: true
                        status:
                          description: Optional status supplied by this operation. Null means unknown.
                          type:
                          - number
                          - 'null'
                        title:
                          description: Source title when supplied.
                          type:
                          - object
                          - 'null'
                          properties:
                            length:
                              description: Optional length supplied by this operation. Null means unknown.
                              type:
                              - number
                              - 'null'
                            present:
                              description: Optional present supplied by this operation. Null means unknown.
                              type:
                              - boolean
                              - 'null'
                            text:
                              description: Source text when supplied.
                              type:
                              - string
                              - 'null'
                          additionalProperties: true
                        twitter_card:
                          description: Optional twitter card supplied by this operation. Null means unknown.
                          type:
                          - object
                          - 'null'
                          properties:
                            complete:
                              description: Optional complete supplied by this operation. Null means unknown.
                              type:
                              - boolean
                              - 'null'
                            missing:
                              description: Optional missing supplied by this operation. Null means unknown.
                              type:
                              - array
                              - 'null'
                              items:
                                description: Optional record supplied by this operation. Null means unknown.
                                type:
                                - string
                                - 'null'
                            present:
                              description: Optional present supplied by this operation. Null means unknown.
                              type:
                              - number
                              - 'null'
                          additionalProperties: true
                        url:
                          description: Original source URL when supplied.
                          type:
                          - string
                          - 'null'
                        viewport_meta:
                          description: Optional viewport meta supplied by this operation. Null means unknown.
                          type:
                          - boolean
                          - 'null'
                        word_count:
                          description: Optional word count supplied by this operation. Null means unknown.
                          type:
                          - number
                          - 'null'
                      additionalProperties: true
                      allOf:
                      - anyOf:
                        - required:
                          - canonical
                          properties:
                            canonical:
                              description: Canonical URL returned by this audit when supplied.
                              type:
                              - string
                              minLength: 1
                        - required:
                          - final_url
                          properties:
                            final_url:
                              description: Optional final url supplied by this operation. Null means unknown.
                              type:
                              - string
                              minLength: 1
                        - required:
                          - findings
                          properties:
                            findings:
                              description: Optional findings supplied by this operation. Null means unknown.
                              type:
                              - array
                              items:
                                description: Optional record supplied by this operation. Null means unknown.
                                type:
                                - object
                                - 'null'
                                properties:
                                  id:
                                    description: Source identifier. Preserve the supplied type and exact value.
                                    type:
                                    - string
                                    - 'null'
                                  message:
                                    description: Optional message supplied by this operation. Null means unknown.
                                    type:
                                    - string
                                    - 'null'
                                  severity:
                                    description: Optional severity supplied by this operation. Null means unknown.
                                    type:
                                    - string
                                    - 'null'
                                additionalProperties: true
                        - required:
                          - headings
                          properties:
                            headings:
                              description: Optional headings supplied by this operation. Null means unknown.
                              type:
                              - object
                              properties:
                                counts:
                                  description: Optional counts supplied by this operation. Null means unknown.
                                  type:
                                  - object
                                  - 'null'
                                  properties:
                                    h1:
                                      description: Optional h1 supplied by this operation. Null means unknown.
                                      type:
                                      - number
                                      - 'null'
                                    h2:
                                      description: Optional h2 supplied by this operation. Null means unknown.
                                      type:
                                      - number
                                      - 'null'
                                    h3:
                                      description: Optional h3 supplied by this operation. Null means unknown.
                                      type:
                                      - number
                                      - 'null'
                                    h4:
                                      description: Optional h4 supplied by this operation. Null means unknown.
                                      type:
                                      - number
                                      - 'null'
                                    h5:
                                      description: Optional h5 supplied by this operation. Null means unknown.
                                      type:
                                      - number
                                      - 'null'
                                    h6:
                                      description: Optional h6 supplied by this operation. Null means unknown.
                                      type:
                                      - number
                                      - 'null'
                                  additionalProperties: true
                                h1_count:
                                  description: Optional h1 count supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                outline:
                                  description: Optional outline supplied by this operation. Null means unknown.
                                  type:
                                  - array
                                  - 'null'
                                  items:
                                    description: Optional record supplied by this operation. Null means unknown.
                                    type:
                                    - object
                                    - 'null'
                                    properties:
                                      level:
                                        description: Optional level supplied by this operation. Null means unknown.
                                        type:
                                        - number
                                        - 'null'
                                      text:
                                        description: Source text when supplied.
                                        type:
                                        - string
                                        - 'null'
                                    additionalProperties: true
                                structure_ok:
                                  description: Optional structure ok supplied by this operation. Null means unknown.
                                  type:
                                  - boolean
                                  - 'null'
                              additionalProperties: true
                        - required:
                          - https
                          properties:
                            https:
                              description: Optional https supplied by this operation. Null means unknown.
                              type:
                              - boolean
                        - required:
                          - images
                          properties:
                            images:
                              description: Optional images supplied by this operation. Null means unknown.
                              type:
                              - object
                              properties:
                                total:
                                  description: Source-reported total; null is unknown.
                                  type:
                                  - number
                                  - 'null'
                                with_alt:
                                  description: Optional with alt supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                without_alt:
                                  description: Optional without alt supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                              additionalProperties: true
                        - required:
                          - language
                          properties:
                            language:
                              description: Optional language supplied by this operation. Null means unknown.
                              type:
                              - string
                              minLength: 1
                        - required:
                          - links
                          properties:
                            links:
                              description: Optional links supplied by this operation. Null means unknown.
                              type:
                              - object
                              properties:
                                external:
                                  description: Optional external supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                internal:
                                  description: Optional internal supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                total:
                                  description: Source-reported total; null is unknown.
                                  type:
                                  - number
                                  - 'null'
                              additionalProperties: true
                        - required:
                          - meta_description
                          properties:
                            meta_description:
                              description: Optional meta description supplied by this operation. Null means unknown.
                              type:
                              - object
                              properties:
                                length:
                                  description: Optional length supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                present:
                                  description: Optional present supplied by this operation. Null means unknown.
                                  type:
                                  - boolean
                                  - 'null'
                              additionalProperties: true
                        - required:
                          - open_graph
                          properties:
                            open_graph:
                              description: Optional open graph supplied by this operation. Null means unknown.
                              type:
                              - object
                              properties:
                                complete:
                                  description: Optional complete supplied by this operation. Null means unknown.
                                  type:
                                  - boolean
                                  - 'null'
                                missing:
                                  description: Optional missing supplied by this operation. Null means unknown.
                                  type:
                                  - array
                                  - 'null'
                                  items:
                                    description: Optional record supplied by this operation. Null means unknown.
                                    type:
                                    - string
                                    - 'null'
                                present:
                                  description: Optional present supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                              additionalProperties: true
                        - required:
                          - redirected
                          properties:
                            redirected:
                              description: Optional redirected supplied by this operation. Null means unknown.
                              type:
                              - boolean
                        - required:
                          - robots
                          properties:
                            robots:
                              description: Optional robots supplied by this operation. Null means unknown.
                              type:
                              - object
                              properties:
                                nofollow:
                                  description: Optional nofollow supplied by this operation. Null means unknown.
                                  type:
                                  - boolean
                                  - 'null'
                                noindex:
                                  description: Optional noindex supplied by this operation. Null means unknown.
                                  type:
                                  - boolean
                                  - 'null'
                              additionalProperties: true
                        - required:
                          - title
                          properties:
                            title:
                              description: Source title when supplied.
                              type:
                              - object
                              properties:
                                length:
                                  description: Optional length supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                                present:
                                  description: Optional present supplied by this operation. Null means unknown.
                                  type:
                                  - boolean
                                  - 'null'
                                text:
                                  description: Source text when supplied.
                                  type:
                                  - string
                                  - 'null'
                              additionalProperties: true
                        - required:
                          - twitter_card
                          properties:
                            twitter_card:
                              description: Optional twitter card supplied by this operation. Null means unknown.
                              type:
                              - object
                              properties:
                                complete:
                                  description: Optional complete supplied by this operation. Null means unknown.
                                  type:
                                  - boolean
                                  - 'null'
                                missing:
                                  description: Optional missing supplied by this operation. Null means unknown.
                                  type:
                                  - array
                                  - 'null'
                                  items:
                                    description: Optional record supplied by this operation. Null means unknown.
                                    type:
                                    - string
                                    - 'null'
                                present:
                                  description: Optional present supplied by this operation. Null means unknown.
                                  type:
                                  - number
                                  - 'null'
                              additionalProperties: true
                        - required:
                          - url
                          properties:
                            url:
                              description: Original source URL when supplied.
                              type:
                              - string
                              minLength: 1
                        - required:
                          - viewport_meta
                          properties:
                            viewport_meta:
                              description: Optional viewport meta supplied by this operation. Null means unknown.
                              type:
                              - boolean
                        - required:
                          - word_count
                          properties:
                            word_count:
                              description: Optional word count supplied by this operation. Null means unknown.
                              type:
                              - number
                      x-contract-version: '2026-09-22'
                      x-validation-scope: Required success payload structure; optional fields and source completeness remain separate.
                      examples:
                      - _warnings:
                        - example
                        final_url: https://example.com/example
                        findings:
                        - id: example
                          message: example
                          severity: example
                        headings:
                          counts:
                            h1: 0
                            h2: 0
                            h3: 0
                            h4: 0
                            h5: 0
                            h6: 0
                          h1_count: 0
                          outline:
                          - level: 0
                            text: example
                          structure_ok: false
                        https: false
                        images:
                          total: 0
                          with_alt: 0
                          without_alt: 0
                        language: example
                        links:
                          external: 0
                          internal: 0
                          total: 0
                        meta_description:
                          length: 0
                          present: false
                        open_graph:
                          complete: false
                          missing:
                          - example
                          present: 0
                        redirected: false
                        robots:
                          nofollow: false
                          noindex: false
                        status: 0
                        title:
                          length: 0
                          present: false
                          text: example
                        twitter_card:
                          complete: false
                          missing:
                          - example
                          present: 0
                        url: https://example.com/example
                        viewport_meta: false
                        word_count: 0
        default:
          description: The error envelope — the same shape for every non-2xx status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-credits: 3
      x-production-available: true
      x-capacity:
        status: not_assessed
        message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee.
      x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes.
      x-live-proven: true
components:
  schemas:
    Error:
      type: object
      required:
      - success
      - error
      - credits_used
      - request_id
      properties:
        success:
          const: false
        error:
          type: object
          required:
          - type
          - message
          - status
          properties:
            type:
              type: string
              enum:
              - UNAUTHORIZED
              - KEY_REVOKED
              - KEY_LIMIT_EXCEEDED
              - RATE_LIMITED
              - INSUFFICIENT_CREDITS
              - RESOURCE_NOT_FOUND
              - INVALID_PARAMETERS
              - TARGET_ACCESS_DENIED
              - UPSTREAM_ERROR
              - UPSTREAM_TIMEOUT
              - FREE_CAPACITY_UNAVAILABLE
              - CAPACITY_UNAVAILABLE
              - ENDPOINT_NOT_FOUND
              - ENDPOINT_NOT_AVAILABLE
              - FAIR_USE_EXCEEDED
              - INTERNAL_ERROR
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              description: Deep link to the exact section of the errors guide for this type.
            details:
              type: object
        credits_used:
          type:
          - integer
          - 'null'
          description: Confirmed net charge; null when billing is pending reconciliation. Inspect error.details.billing_status and retain request_id.
        credits_remaining:
          type: integer
        request_id:
          type: string
    Success:
      type: object
      required:
      - success
      - platform
      - endpoint
      - data
      - credits_used
      - credits_remaining
      - request_id
      properties:
        _completeness:
          type: object
          description: Reported response completeness, not a guarantee of complete platform history. Missing source assertions remain unknown.
          properties:
            state:
              type: string
              enum:
              - complete
              - partial
              - unknown
            scope:
              type: string
            inspection_limited:
              type: boolean
        success:
          const: true
        platform:
          type: string
        endpoint:
          type: string
          description: The resolved path, e.g. `/v1/github/profile`.
        data:
          description: Amazon responses include marketplace.country and marketplace.domain (resolved request marketplace, UK by default). X profiles preserve location, bio_link and cover_url when supplied. TikTok profiles preserve commerce_user, seller, region, location and business_category when supplied; region identifies the account region rather than personal residence. TikTok comments use platform_default selection, which can change between fetches; keep the same video and options when following cursors. Amazon review variant is readable text. Facebook profiles preserve cover_url, following and created_at when supplied; likes_count and followers are distinct and follower totals may be rounded. Endpoint-specific normalized payload, not one universal post/profile schema. Many lists use items/count/cursor; a null cursor means no usable next cursor was supplied, not proof that all history was retrieved. Check has_more and warnings where present. Social full-profile bundles use posts_cursor and posts_pagination.next_params; retain all returned next parameters. YouTube channel bundles instead use recent_videos, cursor and recent_videos_pagination. Inspect complete/partial/legs where supplied for bounded or failed components. Optional model-derived fields are labelled, not source facts.
        credits_used:
          type: integer
        credits_remaining:
          type: integer
        request_id:
          type: string
        cached:
          type: boolean
        stale:
          type: boolean
          description: True only for an explicitly labelled, zero-credit reference snapshot served after a temporary upstream failure.
        age_seconds:
          type: integer
          minimum: 0
          description: Age of a stale snapshot since its original retrieval; not reset by outage recovery.
        fetched_at:
          type: string
          format: date-time
          description: Original retrieval time of a stale snapshot, in UTC.
        synthetic:
          type: boolean
          description: Present and true only on the explicitly requested /sandbox surface. Synthetic responses are representative and charged 0 credits; production /v1 never returns them.
        degraded:
          type: boolean
          description: Reserved for sandbox compatibility. Production /v1 reports upstream failure as an error and never serves a representative fallback.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Your API key (`mn_…`), from the console. The recommended style.
    BearerKey:
      type: http
      scheme: bearer
      description: The same key as a Bearer token, for clients that only expose an Authorization field. Keys are never accepted in the query string — URLs leak into logs and referrers.
x-provenance:
  method: harvested
  publisher: Monocrawl
  source: https://www.monocrawl.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)