openapi: 3.2.0
info:
  title: PageAudit Audits API
  version: f5ac3ca0
  description: 'Technical SEO auditor that ships the fix. Main client: AI agents. Browsable index at GET /api/.'
servers:
- url: https://pageaudit.online
tags:
- name: Audits
paths:
  /api/audits/{id}:
    get:
      operationId: get_audit
      summary: Re-reads an audit already made, in full, without re-auditing the page
      description: 'Re-reading costs nothing and does not count against the allowance — the page''s HTML is not kept, but the report is.

        Returns: { audit_id, url, score, summary{finalUrl,status,contentType,title,metaDescription,canonical,robots,viewport,charset,lang,favicon,faviconSource,h1s,openGraph,twitter,jsonLdCount,jsonLdBlocks,jsonLdDropped,jsonLdTypes,images,links,words,hreflang,legacy,redirects,robotsTxt,sitemap}, counts{errors,warnings,info}, issues[{severity,code,message}], fixes[{code,severity,classe,alvo,snippet,arquivo,fonte,nota}], jsonLd, headers, truncated, share_slug, created_at }'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ audit_id, url, score, summary{finalUrl,status,contentType,title,metaDescription,canonical,robots,viewport,charset,lang,favicon,faviconSource,h1s,openGraph,twitter,jsonLdCount,jsonLdBlocks,jsonLdDropped,jsonLdTypes,images,links,words,hreflang,legacy,redirects,robotsTxt,sitemap}, counts{errors,warnings,info}, issues[{severity,code,message}], fixes[{code,severity,classe,alvo,snippet,arquivo,fonte,nota}], jsonLd, headers, truncated, share_slug, created_at }'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditGravado'
        '401':
          description: No credential, or an invalid one. See this endpoint's auth.
        '404':
          description: The resource does not exist (or is not yours — the API does not tell the two apart on purpose).
      tags:
      - Audits
  /api/audits/{id}/patch:
    get:
      operationId: get_patch
      summary: 'The consolidated patch of an audit: the block ready to paste, the files to…'
      description: 'Each finding becomes a fix in one of three classes: `deterministico` (comes whole from what the page declares: final URL, title, description, OG), `molde` (a tag with a marked placeholder, like `{{TITULO}}`, and the suggested source) or `sem_patch` (a decision or infrastructure, with the instruction). Nothing is invented by a model.

        Returns: { url, audit, head, arquivos[{code,path,conteudo}], moldes[{code,alvo,snippet,fonte,nota}], sem_patch[{code,nota}], resumo{deterministicos,moldes,sem_patch,total}, como_aplicar, _links }'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ url, audit, head, arquivos[{code,path,conteudo}], moldes[{code,alvo,snippet,fonte,nota}], sem_patch[{code,nota}], resumo{deterministicos,moldes,sem_patch,total}, como_aplicar, _links }'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patch'
        '401':
          description: No credential, or an invalid one. See this endpoint's auth.
        '404':
          description: The resource does not exist (or is not yours — the API does not tell the two apart on purpose).
      tags:
      - Audits
  /api/audits/{id}/share:
    post:
      operationId: post_api_audits_by_id_share
      summary: Publishes the audit under a non-enumerable slug.
      description: 'Returns: { ok, shared, slug, path, badge, _links }'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ ok, shared, slug, path, badge, _links }'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Compartilhamento'
        '401':
          description: No credential, or an invalid one. See this endpoint's auth.
        '404':
          description: The resource does not exist (or is not yours — the API does not tell the two apart on purpose).
      tags:
      - Audits
    delete:
      operationId: delete_api_audits_by_id_share
      summary: Revokes the share; the slug stops serving the report
      description: 'The badge keeps answering 200 with the grey `n/a` SVG — same box, so the layout of whoever pasted it in a README does not break.

        Returns: { ok, shared }'
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ ok, shared }'
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    description: Always `true`.
                  shared:
                    type: boolean
                    description: Always `false` at the end of this call.
                required:
                - ok
                - shared
        '401':
          description: No credential, or an invalid one. See this endpoint's auth.
        '404':
          description: The resource does not exist (or is not yours — the API does not tell the two apart on purpose).
      tags:
      - Audits
components:
  schemas:
    ArquivoPatch:
      type: object
      properties:
        code:
          type: string
          description: Finding that originated it (`robots_txt_missing`, `sitemap_missing`).
        path:
          type: string
          description: Absolute path on the host, e.g. `/robots.txt`.
        conteudo:
          type: string
          description: Full content of the file.
      required:
      - code
      - path
      - conteudo
      description: A file to create at the host root.
    AuditGravado:
      type: object
      properties:
        audit_id:
          type: string
          description: ID of the audit.
        url:
          type: string
          description: Final audited URL, after following the redirects.
        score:
          type: integer
          description: Score from 0 to 100.
        summary:
          allOf:
          - $ref: '#/components/schemas/ResumoPagina'
          description: What the page declared at the time of the run.
          nullable: true
        counts:
          allOf:
          - $ref: '#/components/schemas/ContagemAchados'
          description: How many findings of each severity.
        issues:
          type: array
          items:
            $ref: '#/components/schemas/Achado'
          description: Everything found in that run.
        fixes:
          type: array
          items:
            $ref: '#/components/schemas/Correcao'
          description: The ready fix of each finding; an audit stored before this existed gets the computation on read.
        jsonLd:
          type: array
          items:
            type: object
          description: The raw JSON-LD blocks stored.
        headers:
          type: object
          description: Headers of the target's response, as they were in the run.
        truncated:
          type: array
          items:
            type: string
          description: What was cut by size when storing.
        share_slug:
          type: string
          description: Public slug, if this audit was shared.
          nullable: true
        created_at:
          type: string
          description: When the run happened (UTC).
      required:
      - audit_id
      - url
      - score
      - summary
      - counts
      - issues
      - fixes
      - jsonLd
      - headers
      - truncated
      - share_slug
      - created_at
      description: The same report re-read from the database. It has no `quota` and no `_links` (it is a read, not a run) and gains the date and the share slug.
    ContagemAchados:
      type: object
      properties:
        errors:
          type: integer
          description: Serious findings.
        warnings:
          type: integer
          description: Findings that deserve attention.
        info:
          type: integer
          description: Observations without severity.
      required:
      - errors
      - warnings
      - info
      description: How many findings of each severity — the summary that fits in a badge.
    SemPatch:
      type: object
      properties:
        code:
          type: string
          description: Source finding.
        nota:
          type: string
          description: What to check or decide.
      required:
      - code
      - nota
      description: 'Finding without an automatic fix: it is a decision or infrastructure.'
    Compartilhamento:
      type: object
      properties:
        ok:
          type: boolean
          description: Always `true`.
        shared:
          type: boolean
          description: Whether the audit is published at the end of the call.
        slug:
          type: string
          description: Public, non-enumerable slug.
        path:
          type: string
          description: Path of the report's HTML page.
        badge:
          type: string
          description: Path of the score badge SVG.
        _links:
          type: object
          description: Report, JSON and badge, as absolute URLs.
      required:
      - ok
      - shared
      - slug
      - path
      - badge
      - _links
      description: The result of publishing an audit under a non-enumerable slug.
    ResumoPagina:
      type: object
      properties:
        finalUrl:
          type: string
          description: URL after following every redirect.
        status:
          type: integer
          description: Final HTTP status of the target.
        contentType:
          type: string
          description: Content-Type of the final response.
          nullable: true
        title:
          type: string
          description: Content of `<title>`.
          nullable: true
        metaDescription:
          type: string
          description: Content of `<meta name=description>`.
          nullable: true
        canonical:
          type: string
          description: Canonical URL declared by the page.
          nullable: true
        robots:
          type: string
          description: Content of `<meta name=robots>`.
          nullable: true
        viewport:
          type: string
          description: Content of `<meta name=viewport>`.
          nullable: true
        charset:
          type: string
          description: Declared encoding.
          nullable: true
        lang:
          type: string
          description: Language declared in `<html lang>`.
          nullable: true
        favicon:
          type: string
          description: URL of the favicon found.
          nullable: true
        faviconSource:
          type: string
          description: 'How the favicon was found: declared or by the default path.'
          nullable: true
        h1s:
          type: array
          items:
            type: string
          description: Every `<h1>` on the page, in order.
        openGraph:
          type: object
          description: The `og:*` tags found, key by key.
        twitter:
          type: object
          description: The `twitter:*` tags found.
        jsonLdCount:
          type: integer
          description: How many JSON-LD nodes the page had.
        jsonLdBlocks:
          type: integer
          description: How many `<script type=application/ld+json>` blocks existed.
        jsonLdDropped:
          type: boolean
          description: '`true` when nodes were dropped for passing the cap.'
        jsonLdTypes:
          type: array
          items:
            type: string
          description: The `@type`s found, e.g. `Organization`, `WebSite`.
        images:
          type: object
          description: Image count and how many have no `alt`.
        links:
          type: object
          description: Count of internal, external and text-less links.
        words:
          type: integer
          description: Words in the visible content.
        hreflang:
          type: array
          items:
            type: object
          description: The declared language alternates.
        legacy:
          type: object
          description: Old markup still present (e.g. `<font>`, layout tables).
        redirects:
          type: array
          items:
            type: object
          description: The redirect chain followed to the final URL.
        robotsTxt:
          type: object
          description: What the origin's `robots.txt` says about this URL.
        sitemap:
          type: object
          description: Whether the URL appears in the sitemap the origin declares.
      required:
      - finalUrl
      - status
      - contentType
      - title
      - metaDescription
      - canonical
      - robots
      - viewport
      - charset
      - lang
      - favicon
      - faviconSource
      - h1s
      - openGraph
      - twitter
      - jsonLdCount
      - jsonLdBlocks
      - jsonLdDropped
      - jsonLdTypes
      - images
      - links
      - words
      - hreflang
      - legacy
      - redirects
      - robotsTxt
      - sitemap
      description: Everything the page declares about itself. It is the most consulted object of the API.
    Patch:
      type: object
      properties:
        url:
          type: string
          description: Final audited URL.
          nullable: true
        audit:
          type: string
          description: Absolute link of the source audit.
          nullable: true
        head:
          type: string
          description: The deterministic tags, one per line, in <head> order (charset first). Empty when there are none.
        arquivos:
          type: array
          items:
            $ref: '#/components/schemas/ArquivoPatch'
          description: Files to create at the host root.
        moldes:
          type: array
          items:
            $ref: '#/components/schemas/MoldePatch'
          description: What only the owner can fill in.
        sem_patch:
          type: array
          items:
            $ref: '#/components/schemas/SemPatch'
          description: What is a decision or infrastructure.
        resumo:
          allOf:
          - $ref: '#/components/schemas/ResumoPatch'
          description: Count per class.
        como_aplicar:
          type: string
          description: One-sentence instruction.
        _links:
          type: object
          description: '`api_index`.'
      required:
      - url
      - audit
      - head
      - arquivos
      - moldes
      - sem_patch
      - resumo
      - como_aplicar
      - _links
      description: The consolidated patch of an audit, ready for the agent that builds the site to apply.
    Achado:
      type: object
      properties:
        severity:
          type: string
          description: Severity of the finding.
        code:
          type: string
          description: Stable check code, e.g. `title_missing`. It is what you filter by.
        message:
          type: string
          description: The finding in one sentence, ready to show a person.
      required:
      - severity
      - code
      - message
      description: A problem (or a pass) found on the page.
    MoldePatch:
      type: object
      properties:
        code:
          type: string
          description: Source finding.
        alvo:
          type: string
          description: '`head`, `corpo` or `img`.'
        snippet:
          type: string
          description: The tag with `{{PLACEHOLDER}}`.
        fonte:
          type: string
          description: Suggestion taken from the page itself (H1, og:description…), if any.
          nullable: true
        nota:
          type: string
          description: What to fill in and the limit.
      required:
      - code
      - alvo
      - snippet
      - fonte
      - nota
      description: 'A tag with a marked placeholder: content missing that only the owner knows.'
    ResumoPatch:
      type: object
      properties:
        deterministicos:
          type: integer
          description: Ready to paste (head + files).
        moldes:
          type: integer
          description: With a placeholder.
        sem_patch:
          type: integer
          description: Instruction only.
        total:
          type: integer
          description: Findings considered.
      required:
      - deterministicos
      - moldes
      - sem_patch
      - total
      description: How many fixes of each class.
    Correcao:
      type: object
      properties:
        code:
          type: string
          description: The same `code` as the finding (`Achado.code`).
        severity:
          type: string
          description: Severity of the source finding.
        classe:
          type: string
          description: '`deterministico` comes whole from the page; `molde` has a `{{…}}` placeholder; `sem_patch` is an instruction.'
        alvo:
          type: string
          description: 'Where to apply: `head`, `corpo`, `img`, `arquivo` or `pagina` (instruction).'
        snippet:
          type: string
          description: The ready tag (or with a placeholder). `null` for files and for `sem_patch`.
          nullable: true
        arquivo:
          type: object
          description: '`path` and `conteudo` when the fix is a file at the host root.'
          nullable: true
        fonte:
          type: string
          description: Where the value came from, or what the page already had (for the template or to check the cut).
          nullable: true
        nota:
          type: string
          description: How to apply, or what to decide.
          nullable: true
      required:
      - code
      - severity
      - classe
      - alvo
      - snippet
      - arquivo
      - fonte
      - nota
      description: The ready fix of one finding. `classe` says whether it is to paste, to fill in or to decide.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Guest token (`POST /api/guest`) in `X-Guest-Token: pa_…`, `Authorization: Bearer pa_…` or `?guest_token=pa_…`. A user session (`sess_…`) also works and takes precedence.'