> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run SEO scan

> <Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Scans the app for SEO problems and returns the [score and checklist](/developers/references/apps-api/sections/seo#the-score-and-the-checklist) in two parts. The score is a single 0-100 number with a letter grade. The checklist is the individual checks, each pass, warn, or fail, that produced the score.

The scan reads the app's own configuration and also fetches the live site over HTTP to check what it really serves for `robots.txt`, `sitemap.xml` and the home page. Those three run in parallel with a five-second timeout each and one retry, so expect a few seconds, and up to about ten when the live site is slow to answer.

An app that isn't published yet still scans, but its live checks have nothing to fetch. Rather than reporting every check that fails as a result, Base44 reports only the root cause and drops the downstream failures that just restate it, in this case that the app isn't published. The same collapsing applies when the live site's host can't be reached at all. Instead of one warning per probe, you get a single row for the host being unreachable.

Base44 also stores the result, so [Get SEO score](/api-reference/get-seo-score) and [Get last SEO scan](/api-reference/get-last-seo-scan) return this same scan until the next one runs, without needing to scan again. Storing the result is best-effort and can't fail the scan itself, so a successful call here only promises the scan that just ran, not that the two report endpoints already reflect it. Read them back if you need to be sure they're in sync.

The score and the checklist are stored separately, and two scans running at once can interleave those two writes. So if you read both report endpoints, compare their `scanned_at` before treating the numbers as one scan's.

Each check that Base44 can act on carries a `fix_action`, which you can apply with [Apply SEO fix](/api-reference/apply-seo-fix).

The overall score isn't a simple tally of passing and failing checks. Category scores are weighted differently, and some critical checks can further cap the overall score when they fail. That's why `score.overall` doesn't add up to a plain count of failing checks, even though the `passed`, `warnings` and `failures` counts inside each category are exact. Use `failures` from [Get SEO score](/api-reference/get-seo-score) if you need the exact total across every category.

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time.</Warning>



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/seo/scan
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - PersonalAccessTokenAuth: []
paths:
  /api/apps/{app_id}/seo/scan:
    post:
      summary: Run SEO scan
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Scans the app for SEO problems and returns the [score and
        checklist](/developers/references/apps-api/sections/seo#the-score-and-the-checklist)
        in two parts. The score is a single 0-100 number with a letter grade.
        The checklist is the individual checks, each pass, warn, or fail, that
        produced the score.


        The scan reads the app's own configuration and also fetches the live
        site over HTTP to check what it really serves for `robots.txt`,
        `sitemap.xml` and the home page. Those three run in parallel with a
        five-second timeout each and one retry, so expect a few seconds, and up
        to about ten when the live site is slow to answer.


        An app that isn't published yet still scans, but its live checks have
        nothing to fetch. Rather than reporting every check that fails as a
        result, Base44 reports only the root cause and drops the downstream
        failures that just restate it, in this case that the app isn't
        published. The same collapsing applies when the live site's host can't
        be reached at all. Instead of one warning per probe, you get a single
        row for the host being unreachable.


        Base44 also stores the result, so [Get SEO
        score](/api-reference/get-seo-score) and [Get last SEO
        scan](/api-reference/get-last-seo-scan) return this same scan until the
        next one runs, without needing to scan again. Storing the result is
        best-effort and can't fail the scan itself, so a successful call here
        only promises the scan that just ran, not that the two report endpoints
        already reflect it. Read them back if you need to be sure they're in
        sync.


        The score and the checklist are stored separately, and two scans running
        at once can interleave those two writes. So if you read both report
        endpoints, compare their `scanned_at` before treating the numbers as one
        scan's.


        Each check that Base44 can act on carries a `fix_action`, which you can
        apply with [Apply SEO fix](/api-reference/apply-seo-fix).


        The overall score isn't a simple tally of passing and failing checks.
        Category scores are weighted differently, and some critical checks can
        further cap the overall score when they fail. That's why `score.overall`
        doesn't add up to a plain count of failing checks, even though the
        `passed`, `warnings` and `failures` counts inside each category are
        exact. Use `failures` from [Get SEO score](/api-reference/get-seo-score)
        if you need the exact total across every category.


        <Warning>The response includes fields beyond the ones documented here.
        Don't rely on undocumented response fields, as they can change at any
        time.</Warning>
      operationId: run_seo_scan_api_apps__app_id__seo_scan_post
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the app to scan.
            title: App Id
          description: ID of the app to scan.
          example: 6820f3a4e7b91d003c45a1f2
        - name: include_ai_visibility
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Include Ai Visibility
      responses:
        '200':
          description: The scan Base44 just ran.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SEOScanReportResponse'
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            You don't have access to this app, or your token or key is
            read-only. These endpoints accept a personal access token or a
            workspace API key, and this one refuses a read-only credential.
        '404':
          description: App not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            Rate limit exceeded. The base limit is 30 requests per minute for
            each app, counted across the workspace rather than per caller, and
            shared with the app's other SEO endpoints. See [Rate
            limits](/developers/references/apps-api/get-started/rate-limits) for
            the multiplier your plan gets.
        '503':
          description: >-
            Database temporarily unavailable (`database_unavailable`): the data
            cluster did not answer in time. Retry after the `Retry-After`
            seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
              examples:
                database_unavailable:
                  summary: database_unavailable
                  value:
                    error:
                      code: database_unavailable
                      message: Database temporarily unavailable, please retry
                      details: {}
      security:
        - PersonalAccessTokenAuth:
            - full_access
        - WorkspaceApiKeyAuth:
            - full_access
        - WorkspaceApiKeyBearerAuth:
            - full_access
components:
  schemas:
    SEOScanReportResponse:
      properties:
        result:
          $ref: '#/components/schemas/SEOScanReport'
          description: The scan Base44 just ran.
      type: object
      required:
        - result
      title: SEOScanReportResponse
      description: A scan Base44 just ran.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StandardErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
          description: What went wrong.
      type: object
      required:
        - error
      title: StandardErrorEnvelope
      description: The error body returned in the standard envelope.
    SEOScanReport:
      properties:
        score:
          $ref: '#/components/schemas/SEOOverallScore'
          description: The score this scan produced.
        checks:
          items:
            $ref: '#/components/schemas/SEOCheckResult'
          type: array
          title: Checks
          description: >-
            The checks behind the score, in the order Base44 reports them. Not
            every check it ran appears here. A failure that only restates an
            upstream one is dropped in favour of the root cause, so an
            unpublished or login-gated app returns the one gating failure rather
            than the dozen findings that follow from it.
          example:
            - category: ai_discoverability
              description: Turn on the AI site guide so AI engines can understand your app.
              id: llms_txt
              status: warn
              title: AI-readable site guide is off
        scanned_at:
          type: string
          title: Scanned At
          description: When the scan ran, as an ISO 8601 UTC timestamp.
          example: '2026-09-03T09:15:00+00:00'
      type: object
      required:
        - score
        - scanned_at
      title: SEOScanReport
      description: 'An SEO scan: its score and every check behind it.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    StandardError:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable machine-readable cause of the failure. Match on this, not on
            `message`.
          example: not_found
        message:
          type: string
          title: Message
          description: Human-readable explanation. It isn't a stable contract.
          example: App not found
        details:
          additionalProperties: true
          type: object
          title: Details
          description: >-
            Structured context for the failure, or an empty object when there's
            none.
          example: {}
      type: object
      required:
        - code
        - message
      title: StandardError
    SEOOverallScore:
      properties:
        overall:
          type: integer
          title: Overall
          description: Overall SEO score for the app, 0 to 100.
          example: 82
        grade:
          type: string
          title: Grade
          description: 'Letter grade for `overall`: `A`, `B`, `C`, `D` or `F`.'
          example: B
        categories:
          additionalProperties:
            $ref: '#/components/schemas/SEOCategoryScore'
          type: object
          title: Categories
          description: >-
            Per-category breakdown, keyed by the same category names the checks
            carry: `meta_tags`, `crawlability`, `structured_data`,
            `ai_discoverability` and `content_quality`, plus
            `indexing_performance` when Google Search Console integration is
            enabled for you. Base44 can add another category, so read the map
            rather than assuming this list is complete. Every category in the
            map is scored, including one this scan ran no checks for, which
            scores 100 with all three counts at zero.
          example:
            meta_tags:
              failures: 0
              passed: 4
              score: 80
              warnings: 1
      type: object
      required:
        - overall
        - grade
      title: SEOOverallScore
      description: The scan's score, overall and per category.
    SEOCheckResult:
      properties:
        id:
          type: string
          title: Id
          description: >-
            Identifier of the check. Stable across scans, but a check can be
            missing from a later scan rather than change status, because Base44
            collapses cascading failures into their root cause.
          example: llms_txt
        category:
          type: string
          title: Category
          description: >-
            Which part of the score this check feeds: `meta_tags`,
            `crawlability`, `structured_data`, `ai_discoverability`,
            `content_quality`, or `indexing_performance` when Google Search
            Console integration is enabled for you.
          example: ai_discoverability
        title:
          type: string
          title: Title
          description: >-
            Short name of the check, phrased for the finding rather than the
            subject, so it changes with `status`.
          example: AI-readable site guide is off
        status:
          type: string
          enum:
            - pass
            - warn
            - fail
          title: Status
          description: >-
            Outcome of the check. A `warn` scores 50 against the category and a
            `fail` scores 0. Not every check can return all three.
          example: warn
        description:
          type: string
          title: Description
          description: What the check found, written for the app's owner.
          example: Turn on the AI site guide so AI engines can understand your app.
        details:
          items: {}
          type: array
          title: Details
          description: >-
            Supporting detail for the finding, usually one object per page or
            entity involved. The keys differ per check, so treat the entries as
            opaque.
          example:
            - issue: Duplicate title
              page: Pricing
        fix_action:
          anyOf:
            - $ref: '#/components/schemas/SEOFixAction'
            - type: 'null'
          description: >-
            The remedy the Base44 app editor offers, or `null` when the check
            passed or can't be fixed in-app.
        info_only:
          type: boolean
          title: Info Only
          description: >-
            Environmental findings, such as DNS or hosting issues that can't be
            resolved from inside the app, set this to `true`. Everything else is
            `false`.
          default: false
          example: false
      type: object
      required:
        - id
        - category
        - title
        - status
        - description
      title: SEOCheckResult
      description: One check from the SEO scan.
    SEOCategoryScore:
      properties:
        score:
          type: integer
          title: Score
          description: >-
            Score for this category, 0 to 100. A passing check counts 100, a
            warning 50 and a failure 0, averaged over the category's checks.
          example: 80
        passed:
          type: integer
          title: Passed
          description: >-
            Checks in this category that passed. A plain count, so the three
            counts add up to the category's checks in `checks`.
          default: 0
          example: 4
        warnings:
          type: integer
          title: Warnings
          description: Checks in this category that returned a warning.
          default: 0
          example: 1
        failures:
          type: integer
          title: Failures
          description: Checks in this category that failed.
          default: 0
          example: 0
      type: object
      required:
        - score
      title: SEOCategoryScore
      description: One category's slice of the overall score.
    SEOFixAction:
      properties:
        type:
          type: string
          title: Type
          description: >-
            Identifier of the action that fixes this check. Apply it with [Apply
            SEO fix](/api-reference/apply-seo-fix). See [Fix
            actions](/developers/references/apps-api/sections/seo#fix-actions)
            for what each one does.
          example: enable_llms_txt
        label:
          type: string
          title: Label
          description: Label the app editor shows on the button for this action.
          example: Enable AI site guide
        params:
          additionalProperties: true
          type: object
          title: Params
          description: >-
            Arguments to send with the action to [Apply SEO
            fix](/api-reference/apply-seo-fix). Most actions carry none. The
            keys differ per action, so send them as they are.
          example: {}
      type: object
      required:
        - type
        - label
      title: SEOFixAction
      description: The remedy Base44 offers for a check.
  securitySchemes:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token, sent as `Authorization: Bearer <token>`. Each
        operation lists the permission it needs: `read_only` or `full_access`. A
        full-access token can call every operation. A read-only token can call
        only the operations that list `read_only`; anything else returns 403
        `read_only_credential_route_not_allowed`.
    WorkspaceApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: >-
        Workspace API key, sent as `api_key: <key>`. Each operation that accepts
        one lists what the key needs: a permission, `read_only` or
        `full_access`, like a personal access token, or a scope. A key without
        the scope gets 403 `workspace_api_key_scope_required`.
    WorkspaceApiKeyBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key, sent as `Authorization: Bearer <key>`. Accepted
        wherever `api_key` is, with the same permission.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.