AuditAE Schema API

openapi: 3.2.0
info:
  title: AuditAE REST Schema API
  version: '1'
  description: 'Check whether AI answer engines (ChatGPT, Perplexity, Gemini, Google AI Overviews and AI Mode) cite a brand, crawl a site, and generate or validate schema.org JSON-LD. Prepaid credit: paid calls draw from the workspace balance, free calls never do. When the balance is too low, a paid call answers 402 with a `top_up` request (POST /api/v1/billing/top-up). Authenticate with an ae_live_… key from https://auditae.app/dashboard/keys. The same tools are on the MCP server at https://auditae.app/api/mcp.'
  contact:
    name: AuditAE support
    email: support@auditae.app
    url: https://auditae.app/docs/api
servers:
- url: https://auditae.app
security:
- bearerAuth: []
tags:
- name: Schema
  description: JSON-LD generation, validation and Wikidata lookups.
paths:
  /api/v1/schema/validate:
    post:
      operationId: validateSchema
      summary: Validate JSON-LD
      description: Checks a JSON-LD object against the rules for its schema.org type and suggests optional properties.
      tags:
      - Schema
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - payload
              properties:
                payload:
                  type: object
                  additionalProperties: true
                  description: The full JSON-LD, including @context and @type.
            example:
              payload:
                '@context': https://schema.org
                '@type': Organization
                name: Acme
                url: https://acme.com
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WorkspaceUnfunded'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-auditae-auth: any
      x-auditae-price: Free
  /api/v1/schema/generate:
    post:
      operationId: generateSchema
      summary: Generate JSON-LD
      description: Builds valid JSON-LD for a supported type from a few fields, and validates it.
      tags:
      - Schema
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - data
              properties:
                type:
                  type: string
                  enum:
                  - Article
                  - BlogPosting
                  - HowTo
                  - FAQPage
                  - Product
                  - Organization
                  - BreadcrumbList
                  - WebSite
                  - SoftwareApplication
                  - Service
                  - LocalBusiness
                data:
                  type: object
                  additionalProperties: true
            example:
              type: Organization
              data:
                name: Acme
                url: https://acme.com
      responses:
        '200':
          description: Generated JSON-LD.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneratedSchema'
        '400':
          description: Unsupported type or bad data.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error'
                - type: object
                  properties:
                    supported:
                      type: array
                      items:
                        type: string
                    problems:
                      type: array
                      items:
                        type: string
                    ignored_fields:
                      type: array
                      items:
                        type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WorkspaceUnfunded'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-auditae-auth: any
      x-auditae-price: Free
  /api/v1/entities/discover:
    post:
      operationId: discoverEntities
      summary: Find a brand on Wikidata and Google's Knowledge Graph
      description: Looks the brand up on Wikidata and returns its entity and the profile URLs to use as sameAs, plus its Google Knowledge Graph entity.
      tags:
      - Schema
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - brand
              properties:
                brand:
                  type: string
                  minLength: 1
                domain:
                  type: string
                qid:
                  type: string
                  pattern: ^Q\d+$
                  description: Pin a Wikidata item.
            example:
              brand: Acme
              domain: acme.com
      responses:
        '200':
          description: The entity, or candidates when none matched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveredEntity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WorkspaceUnfunded'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          description: Wikidata didn't answer.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Error'
                - type: object
                  required:
                  - error_code
                  properties:
                    error_code:
                      type: string
                      const: wikidata_unreachable
      x-auditae-auth: any
      x-auditae-price: Free
components:
  schemas:
    GoogleKgEntity:
      type: object
      description: The brand's entity in Google's Knowledge Graph.
      required:
      - kg_id
      - name
      - types
      - description
      - detailed_description_url
      - url
      - result_score
      - domain_matched
      - wikidata_id_matched
      properties:
        kg_id:
          type: string
          description: Knowledge Graph id, e.g. /m/027cz92 or /g/11…
        name:
          type:
          - string
          - 'null'
        types:
          type: array
          items:
            type: string
        description:
          type:
          - string
          - 'null'
        detailed_description_url:
          type:
          - string
          - 'null'
          description: Usually the entity's Wikipedia article.
        url:
          type:
          - string
          - 'null'
          description: The website Google lists for the entity.
        result_score:
          type:
          - number
          - 'null'
          description: Google's relevance score; 0 when found by id.
        domain_matched:
          type:
          - boolean
          - 'null'
          description: url's host is the domain. null without a domain or a url.
        wikidata_id_matched:
          type:
          - boolean
          - 'null'
          description: kg_id is the matched Wikidata item's Google KG (P2671) or Freebase (P646) id. null when there's none.
    TopUpRequest:
      type: object
      description: 'The top-up call to make as-is: it returns a Stripe Checkout URL for the account owner.'
      required:
      - method
      - url
      - body
      - min_usd
      - max_usd
      - note
      properties:
        method:
          type: string
          const: POST
        url:
          type: string
          format: uri
          description: POST /api/v1/billing/top-up on this host.
        body:
          type: object
          required:
          - amount_usd
          properties:
            amount_usd:
              type: integer
              minimum: 5
              maximum: 1000
              description: 'Suggested amount: the shortfall rounded up to whole dollars, within the top-up limits.'
        min_usd:
          type: integer
          const: 5
        max_usd:
          type: integer
          const: 1000
        note:
          type: string
    GeneratedSchema:
      type: object
      required:
      - schema
      - validation
      - ignored_fields
      - notes
      properties:
        schema:
          type: object
          additionalProperties: true
          description: The JSON-LD, ready to paste.
        validation:
          $ref: '#/components/schemas/ValidationResult'
        ignored_fields:
          type: array
          items:
            type: string
        notes:
          type: array
          items:
            type: string
    DiscoveredEntity:
      type: object
      required:
      - found
      - domain_matched
      - matched_by
      - wikidata_qid
      - label
      - description
      - official_site
      - same_as
      - detail
      - candidates
      - google_kg
      - google_kg_status
      properties:
        found:
          type: boolean
        domain_matched:
          type:
          - boolean
          - 'null'
        matched_by:
          type:
          - string
          - 'null'
          enum:
          - domain
          - qid
          - null
        wikidata_qid:
          type:
          - string
          - 'null'
        label:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        official_site:
          type:
          - string
          - 'null'
        same_as:
          type: array
          items:
            type: string
          description: Profile URLs for the Organization's sameAs.
        detail:
          type: object
          additionalProperties:
            type:
            - string
            - 'null'
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/EntityCandidate'
        google_kg:
          oneOf:
          - $ref: '#/components/schemas/GoogleKgEntity'
          - type: 'null'
          description: Matched by domain or by the Wikidata item's KG id, never by name alone.
        google_kg_status:
          type: string
          enum:
          - matched
          - not_confirmed
          - unavailable
          description: 'not_confirmed: no KG result could be tied to the brand by domain or Wikidata id; Google may still have an entity. unavailable: the lookup couldn''t run.'
        site_same_as:
          type: array
          description: 'With a domain: the sameAs URLs the site''s own homepage JSON-LD declares, each checked live. Resolving ones are safe to keep in sameAs.'
          items:
            type: object
            required:
            - url
            - resolves
            - status
            properties:
              url:
                type: string
              resolves:
                type: boolean
                description: It answered, or refused a bot the way profile sites do (401/403/429/999).
              status:
                type:
                - integer
                - 'null'
        next_step:
          type: string
    ValidationResult:
      type: object
      required:
      - valid
      - type
      - issues
      - suggestions
      properties:
        valid:
          type: boolean
        type:
          type:
          - string
          - 'null'
        issues:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
        suggestions:
          type: array
          items:
            type: string
        checked_types:
          type: array
          items:
            type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable reason.
      additionalProperties: true
    EntityCandidate:
      type: object
      required:
      - qid
      - label
      - description
      - official_site
      - domain_matched
      properties:
        qid:
          type: string
        label:
          type: string
        description:
          type:
          - string
          - 'null'
        official_site:
          type:
          - string
          - 'null'
        domain_matched:
          type:
          - boolean
          - 'null'
    ValidationIssue:
      type: object
      required:
      - severity
      - message
      properties:
        severity:
          type: string
          enum:
          - error
          - warning
          - info
        property:
          type: string
        message:
          type: string
    RateLimited:
      type: object
      required:
      - error
      - retry_after
      properties:
        error:
          type: string
          const: rate_limited
        retry_after:
          type: integer
          minimum: 0
          description: Seconds to wait. Also sent as the Retry-After header.
        message:
          type: string
          description: Which limit was hit, when the route says (e.g. a per-site limit).
  responses:
    RateLimited:
      description: 'Too many requests: 60 per 60s per key, and 30 failed authentications per 60s per IP.'
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimited'
    WorkspaceUnfunded:
      description: The key belongs to an agent workspace (created on /api/mcp/pay) that has never been funded. Until it is, the key works only on /api/mcp/pay and the two billing routes (GET /api/v1/billing, POST /api/v1/billing/top-up). Fund it with the `top_up` request, then retry with the same key.
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - code
            - top_up
            properties:
              error:
                type: string
              code:
                type: string
                const: workspace_unfunded
              top_up:
                $ref: '#/components/schemas/TopUpRequest'
    ServerError:
      description: Something failed on our side. Safe to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The body is missing a field or has a bad value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid or revoked key.
      headers:
        WWW-Authenticate:
          $ref: '#/components/headers/WWW-Authenticate'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    WWW-Authenticate:
      description: Bearer challenge.
      schema:
        type: string
        examples:
        - Bearer realm="auditae-v1"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An ae_live_… key from https://auditae.app/dashboard/keys. The same key works with the MCP server at https://auditae.app/api/mcp.
externalDocs:
  url: https://auditae.app/docs/api
  description: REST API and API keys
x-service-info:
  categories:
  - ai
  - seo
  - marketing
  docs:
    homepage: https://auditae.app
    apiReference: https://auditae.app/docs/api
    llms: https://auditae.app/llms.txt