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

# Price audit fixes in AI credits

> With `page_id`: the plan of that page, each applicable fix with its price
and whether the plan pre-selects it. Without it: the price of fixing the
whole site (`bulk`), which is what `fixAuditBulk` debits. `balance` is the
current AI credit balance. Debits nothing.




## OpenAPI

````yaml /api-reference/openapi.yaml get /profiles/{profile_id}/audit/fix-estimate
openapi: 3.1.0
info:
  title: SORANK Public API
  version: 1.2.0
  description: >
    Versioned REST contract for user-delegated SORANK access, served under

    `/api/public/v1`. Contract 1.1 adds products, Search Console and AI traffic

    analytics, extended GEO reads and site settings to the same version path.

    Contract 1.2 adds keyword research and keyword generation runs, the site

    audit with its fixes, product catalog refresh, article indexing status, GEO

    prompt management, backlink exchange settings and quests, invoices, and the

    AI credit wallet in `getQuotas`. Keyword research and audit fixes spend AI

    credits at the application's prices; an insufficient balance returns 402

    `insufficient_credits` with `details.required` and `details.balance`. The
    1.2

    operations need scopes that credentials issued earlier do not hold.

    Keyword research, keyword runs and audit starts run at most once per

    idempotency key: while a request with the key is still running, another one

    answers 409 `operation_in_progress` (retry shortly), and a keyword run or

    audit start whose earlier attempt stopped before reporting its result

    answers 409 `operation_interrupted` (check the current state, then use a

    new key).

    Availability of each operation depends on the deployed backend version and

    the public API feature flag.

    OAuth tokens are resource-bound to the REST API. Personal API keys may use

    REST only when their transport grant permits it. Browser session cookies and

    Supabase tokens are not credentials for this surface.


    Every request is checked against the credential's exact scopes, explicit

    profile allowlist and the actor's current profile access. The resource owner

    and billable account are resolved server-side. A revoked or expired
    credential

    is rejected even on idempotent replay and operation polling.


    Eligibility: the user must have completed Sorank onboarding and the accessed

    site must have a valid subscription (the owner's subscription for an agency

    collaborator; a site without a subscription is not eligible). Eligibility is

    checked at OAuth consent, at personal key creation and replacement, and
    again

    on every REST request and MCP tool call, including idempotent replays and

    operation polling. An incomplete onboarding returns 403

    `onboarding_required`; an ineligible site returns 402
    `subscription_required`

    with `details.reason`. `listProfiles` returns only the eligible sites of the

    grant; operations without a profile require at least one eligible site.


    All mutations require `Idempotency-Key`. Repeating an identical command with

    the same key returns its original receipt after fresh authorization; a
    changed

    command with the same key returns 409. An accepted asynchronous command may

    still fail later. Do not treat an accepted batch as wholly complete: an

    article generation batch returns HTTP 202 with a receipt already `succeeded`

    (the acceptance is the command's outcome), and each generated article is
    then

    followed through `getArticle` or `listArticles` from the receipt's accepted
    IDs.

    Settings commands return the resulting settings and the asynchronous

    `effects` they queued.


    Errors use one envelope everywhere, including authentication and rate-limit

    middlewares: `{"error": {"code", "message", "request_id", "retryable",

    "details"?}}`. MCP tool errors carry the same `code`, `message`,

    `request_id`, `retryable` and `details` in the tool error result. Codes are

    stable snake_case identifiers; each operation lists the codes it can return

    in `x-error-codes`, and REST and MCP return the same code for the same
    cause.


    Error statuses: 400 invalid request (`invalid_request`, `invalid_id`,

    `invalid_idempotency_key` and field-specific validation codes such as

    `invalid_limit`, `invalid_range`, `field_not_writable` for a read-only field

    like `website_url`, `invalid_market`, `invalid_competitor_selection`,

    `too_many_competitors` or `invalid_url`); 401

    missing/invalid/expired/revoked credential (`invalid_credential`, with a

    `WWW-Authenticate` challenge carrying `resource_metadata`); 402

    `subscription_required` (with `details.reason` among `paused`, `past_due`,

    `incomplete`, `inactive` when known) or `insufficient_quota` for business

    quotas; 403 `missing_scope` or `onboarding_required`; 404 `not_found` for an

    inaccessible or unknown resource; 409 conflicts: `idempotency_conflict` (the

    key belongs to a different command), `calendar_busy` (retryable),

    `calendar_changed` (read the current calendar before retrying),

    `publication_busy` (retryable), `resource_busy` (retryable),

    `keyword_already_published`, `article_identity_conflict`,

    `slug_already_exists`, `audit_rewrite_restored` (the audit rewrite was

    restored to the original article; it cannot be pushed live again),

    `product_catalog_cursor_stale` (restart the

    product list from the first page), `business_brief_revision_conflict`

    (read the settings again),

    `youtube_source_replacement_required` (send `replace: true`),

    `youtube_source_purge_in_progress` (retryable, with `Retry-After`);

    `gsc_not_connected`, `ga_not_connected` (connect Google in Sorank); 422
    unsupported provider capability or state

    (`unsupported_capability`, `unsupported_category`, `cms_not_connected`,

    `publication_state_invalid`, `youtube_channel_unsupported`,

    `youtube_channel_not_found`, ...); 403 `google_access_lost` (with

    `details.reason` among `scope_missing`, `property_access_denied`,

    `token_expired`, `ga_permissions_lost`, `ga_property_unavailable`;

    reconnect Google in Sorank); 429 `rate_limited` or `youtube_rate_limited`

    (retryable, with `Retry-After` and `details.retry_after_seconds` when a

    delay is known); 500 `internal_error` for unexpected failures only; 503

    `auth_state_unavailable` or `rate_limit_unavailable` (retryable), with

    access denied until the state recovers, `service_unavailable` (retryable,

    with `Retry-After`: Sorank itself is temporarily unavailable, for example

    its database, or the request exhausted its server time budget),

    `google_unavailable` or

    `youtube_unavailable` (retryable), or `youtube_feature_disabled` (not

    retryable: the integration is disabled on this deployment); 504 `ga_timeout`
    (retryable with a shorter range).


    Each operation has an MCP tool named by `x-mcp-tool`. Tool arguments are

    flat: `profile_id` and `id` for the path parameters, `idempotency_key` for

    the header, plus the query or body fields of the operation; list and batch

    bounds follow the deployment configuration. A tool result carries exactly

    the REST response body (`data` and `meta`).
servers:
  - url: /api/public/v1
security:
  - OAuth2: []
  - PersonalAPIKey: []
tags:
  - name: Profiles
    description: Accessible SEO profiles, capabilities and business quotas.
  - name: Keywords and GEO
    description: >-
      Existing keyword suggestions, GEO analysis results and GEO aggregates as
      shown by the Sorank dashboard.
  - name: Audit
    description: >-
      Site audit (Improvements) of the blog pages, their issues and the fixes
      paid with AI credits.
  - name: Products
    description: Product catalog discovered on the profile's site.
  - name: Backlinks
    description: Backlink exchange participation, backlink credits and quests.
  - name: Billing
    description: Invoices of the site subscription.
  - name: Analytics
    description: |
      Live Google Search Console and Google Analytics 4 reads, as shown by the
      Sorank dashboard. Each call queries Google; it may refresh and store the
      site's Google access token, never forces a cache refresh, and is charged
      to a dedicated analytics rate budget lower than other reads. Google
      Analytics exposure is limited to traffic coming from AI assistants.
  - name: Settings
    description: |
      Site settings as the Sorank settings pages show them to the same user,
      published as an allowlist: no owner identifier, homepage screenshot,
      connection field, storage path, signed URL or technical error.
  - name: Articles
    description: Local article reading, editing and generation.
  - name: Calendar
    description: Automatic editorial calendar and slot management.
  - name: Publication
    description: CMS publication, updates and scheduling.
  - name: Operations
    description: Durable command receipts and outcome polling.
paths:
  /profiles/{profile_id}/audit/fix-estimate:
    get:
      tags:
        - Audit
      summary: Price audit fixes in AI credits
      description: >
        With `page_id`: the plan of that page, each applicable fix with its
        price

        and whether the plan pre-selects it. Without it: the price of fixing the

        whole site (`bulk`), which is what `fixAuditBulk` debits. `balance` is
        the

        current AI credit balance. Debits nothing.
      operationId: estimateAuditFixes
      parameters:
        - $ref: '#/components/parameters/ProfileID'
        - name: page_id
          in: query
          description: >-
            Audit page ID from listAuditPages; without it the read covers the
            whole audit.
          schema:
            $ref: '#/components/schemas/UUID'
      responses:
        '200':
          $ref: '#/components/responses/AuditFixEstimate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        default:
          $ref: '#/components/responses/Error'
      security:
        - OAuth2:
            - audit:read
        - PersonalAPIKey: []
components:
  parameters:
    ProfileID:
      name: profile_id
      in: path
      required: true
      description: >-
        Profile UUID; must be in the grant allowlist and currently accessible to
        the actor.
      schema:
        $ref: '#/components/schemas/UUID'
  schemas:
    UUID:
      type: string
      format: uuid
    AuditFixEstimateEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: '#/components/schemas/AuditFixEstimateData'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      examples:
        - error:
            code: insufficient_quota
            message: The current article generation quota is exhausted.
            request_id: 33333333-3333-4333-8333-333333333333
            retryable: false
    AuditFixEstimateData:
      type: object
      additionalProperties: false
      required:
        - audit_id
        - scope
        - balance
        - total_credits
        - fix_count
        - article_count
        - cms_connected
        - manual_only
        - pages
        - bulk
      properties:
        audit_id:
          $ref: '#/components/schemas/UUID'
        scope:
          type: string
          enum:
            - page
            - site
        balance:
          type: integer
          minimum: 0
          description: Current AI credit balance.
        total_credits:
          type: integer
          minimum: 0
        fix_count:
          type: integer
          minimum: 0
        article_count:
          type: integer
          minimum: 0
        cms_connected:
          type: boolean
        cms_provider:
          type: string
        manual_only:
          type: boolean
          description: >-
            No fix is written to the site automatically; fixes are generated to
            copy.
        cms_unavailable_reason:
          type: string
        pages:
          type: array
          description: Plan of the estimated page; empty for a site estimate.
          items:
            $ref: '#/components/schemas/AuditPageEstimateData'
        bulk:
          $ref: '#/components/schemas/AuditBulkEstimateData'
    Meta:
      type: object
      additionalProperties: false
      required:
        - request_id
      properties:
        request_id:
          $ref: '#/components/schemas/UUID'
        pagination:
          $ref: '#/components/schemas/Pagination'
        catalog:
          $ref: '#/components/schemas/ProductCatalogMeta'
    ErrorBody:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - request_id
        - retryable
      properties:
        code:
          type: string
          description: Stable public error code; never a raw SQL, CMS or provider error.
          examples:
            - insufficient_quota
            - unsupported_capability
        message:
          type: string
        request_id:
          $ref: '#/components/schemas/UUID'
        retryable:
          type: boolean
          description: |
            True when repeating the same request later, unchanged and with the
            same Idempotency-Key, may succeed (transient busy state, rate limit,
            unavailable authorization or rate-limit state). False when the
            request or the resource state must change first.
        details:
          type: object
          additionalProperties: true
          description: >-
            Safe structured details only (for example `reason` for
            `subscription_required`); no tokens, prompts or internal commands.
    AuditPageEstimateData:
      type: object
      additionalProperties: false
      required:
        - page_id
        - plan
        - protected
        - total_credits
        - fixes
        - bulk_fix_count
        - bulk_credits
        - bulk_rewrite
      properties:
        page_id:
          $ref: '#/components/schemas/UUID'
        plan:
          type: string
          enum:
            - rewrite
            - targeted
            - advice
            - ready
        protected:
          type: boolean
          description: The page performs in Search Console; a rewrite is not proposed.
        total_credits:
          type: integer
          minimum: 0
          description: Price of the pre-selected fixes.
        fixes:
          type: array
          items:
            $ref: '#/components/schemas/AuditPlannedFixData'
        bulk_fix_count:
          type: integer
          minimum: 0
        bulk_credits:
          type: integer
          minimum: 0
        bulk_rewrite:
          type: boolean
    AuditBulkEstimateData:
      type: object
      additionalProperties: false
      description: Price of fixAuditBulk over the estimated pages.
      required:
        - article_count
        - targeted_fix_count
        - targeted_credits
        - rewrite_count
        - rewrite_credits
        - total_credits
        - can_afford
      properties:
        article_count:
          type: integer
          minimum: 0
        targeted_fix_count:
          type: integer
          minimum: 0
        targeted_credits:
          type: integer
          minimum: 0
        rewrite_count:
          type: integer
          minimum: 0
        rewrite_credits:
          type: integer
          minimum: 0
        total_credits:
          type: integer
          minimum: 0
        can_afford:
          type: boolean
          description: Whether the balance covers total_credits.
    Pagination:
      type: object
      additionalProperties: false
      required:
        - limit
        - has_more
        - next_cursor
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 100
        has_more:
          type: boolean
        next_cursor:
          type:
            - string
            - 'null'
    ProductCatalogMeta:
      type: object
      additionalProperties: false
      description: Catalog summary returned by list_products only.
      required:
        - available_count
        - enriched_count
        - truncated
      properties:
        available_count:
          type: integer
          minimum: 0
          description: Usable products in the current catalog snapshot.
        enriched_count:
          type: integer
          minimum: 0
          description: Usable products with page evidence (description or image).
        truncated:
          type: boolean
          description: The latest discovery stopped at the configured catalog size.
    AuditPlannedFixData:
      type: object
      additionalProperties: false
      description: One fix the plan of a page offers, with its price.
      required:
        - fix_type
        - credits
        - units
        - applicable
        - delivery
        - selected
        - issue_keys
      properties:
        fix_type:
          type: string
        credits:
          type: integer
          minimum: 0
        units:
          type: integer
          minimum: 0
          description: Billed units, for example images.
        applicable:
          type: boolean
          description: Whether fixAuditPage accepts this fix for the page.
        delivery:
          type: string
          description: apply (written to the CMS), copy (generated to copy) or advice.
        reason_code:
          type: string
          description: Why a fix is not applicable.
        selected:
          type: boolean
          description: Whether the plan pre-selects the fix.
        issue_keys:
          type: array
          items:
            type: string
  responses:
    AuditFixEstimate:
      description: Price of audit fixes in AI credits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuditFixEstimateEnvelope'
    Unauthorized:
      description: Credential missing, invalid, expired or revoked.
      headers:
        WWW-Authenticate:
          description: Bearer challenge with configured resource metadata where applicable.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error:
      description: Error response; see status-to-code mapping in API description.
      headers:
        Retry-After:
          description: >-
            Seconds until retry when HTTP 429 is returned, with 409
            youtube_source_purge_in_progress, or with 503 service_unavailable.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    OAuth2:
      type: oauth2
      description: |
        Authorization-code grant with PKCE S256, exact scopes, explicit resource
        audience and a persisted consent grant. Obtain endpoint URLs from server
        discovery in the target environment. Refresh tokens remain client-bound.
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          refreshUrl: /oauth/token
          scopes:
            profiles:read: Read authorized profiles and CMS capabilities.
            quotas:read: Read business quotas.
            keywords:read: Read existing keyword suggestions.
            geo:read: Read existing GEO analyses.
            articles:read: Read articles and generation results.
            articles:write: Edit allowed local article fields.
            articles:generate: Generate articles.
            articles:delete: Delete eligible local articles.
            calendar:read: Read calendar and slots.
            calendar:write: Manage calendar and slots.
            articles:publish: Schedule and manage CMS publication.
            products:read: Read the product catalog.
            analytics:read: Read Search Console and AI traffic analytics.
            settings:read: Read site, article, visual and YouTube settings.
            settings:write: >-
              Change site, business, competitor, article, visual and YouTube
              settings. Some changes queue asynchronous regeneration or
              synchronization.
            keywords:generate: >-
              Run keyword research and keyword generation runs. Spends the
              site's AI credits.
            audit:read: Read the site audit, its pages, their issues and the fixes.
            audit:write: >-
              Launch audits and page re-checks, create, apply and restore audit
              fixes and rewrites. Spends the site's AI credits and writes to the
              connected CMS.
            products:write: Request a refresh of the product catalog.
            geo:write: Create, edit and delete the AI visibility prompts of the site.
            backlinks:read: Read the backlink exchange state, credits and quests.
            backlinks:write: Turn the backlink exchange on or off and submit quests.
            billing:read: Read the subscription and the invoices of the site.
    PersonalAPIKey:
      type: http
      scheme: bearer
      bearerFormat: Personal API key
      description: >
        Send the one-time personal API key in Authorization: Bearer. Exact
        scopes,

        explicit profiles, expiry, revocation and transport are verified
        server-side.

        This is not an OAuth access token or a browser session.

````

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