Frase Rules API

openapi: 3.2.0
info:
  title: Frase Rules API
  version: 1.0.0
  description: 'The Frase API provides programmatic access to your SEO content platform. Use it to manage content, research, audits, AI visibility tracking, and more. ## Authentication


    All API requests require authentication using an API key. Include your key in the `X-API-KEY` header:


    ```

    X-API-KEY: sk_live_your_api_key_here

    ```


    For legacy compatibility, the `token` header is also supported. ## Rate Limits


    Three independent limits apply, each with its own headers and error code. Headers are returned on `429` responses, not on successful ones. **Per-minute burst** - 60/min on trial and Starter, 120 Professional, 300 Scale, 1,000 Enterprise. Error code `rate_limit_exceeded`. - `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (epoch seconds)


    **Sustained hourly ceiling** - 2,000/hour trial, 3,000 Starter, 5,000 Professional, 15,000 Scale, 50,000 Enterprise. Error code `hourly_limit_exceeded`. - `X-RateLimit-Hourly-Limit`, `X-RateLimit-Hourly-Remaining`, `X-RateLimit-Hourly-Reset` (epoch seconds)


    **Monthly request budget** - error code `monthly_budget_exceeded`, headers `X-Monthly-Limit`, `X-Monthly-Used`, `X-Monthly-Remaining`. Every `429` carries `Retry-After` in seconds. On the hourly ceiling this can be up to 3,600, so clients should honour it rather than retrying on a short fixed backoff - a retry sooner than `Retry-After` cannot succeed. ## Errors


    The API uses standard HTTP status codes and returns errors in a consistent format:


    ```json

    {

    "error": {

    "type": "authentication_error",

    "code": "invalid_api_key",

    "message": "Invalid API key provided.",

    "doc_url": "https://docs.frase.io/api/errors#invalid_api_key"

    }

    }

    ```


    ## Changelog


    Breaking changes are listed here, newest first. "Breaking" means a field that was always present with a value can now be `null`, or an existing value now means something different — not that a field was removed or renamed. Additive fields are not listed. ### 2026-08-31 — Fact `sources[]` may omit `url`, and minted facts default to `approved`


    - `GET /briefs/{id}/facts`, `PATCH /briefs/{id}/facts/{factId}` → a `sources[]` entry may now carry only `title`, with no `url` or `domain`. Research names a publisher far more often than it captures a link (793 of 801 plan-evidence items in production), and those names were previously discarded rather than returned. Read `url` defensively. - `GET /briefs/{id}/facts` → `approval` on a newly minted fact is now `approved` rather than `pending`. A client polling for `pending` facts to review will see far fewer; rejection is unchanged and remains permanent. Facts the writer asserted in its own output (`provenance: generated`) are still minted `pending`. ### 2026-08-24 — Content Guard''s hasPublishedUrl is now recoverability, not the stored URL


    - `GET /content/{id}/monitoring` → `hasPublishedUrl`: was a judgment on the STORED URL (false for a relative path even when the page was live). It now answers "could Guard watch this article right now" — the stored URL when absolute, or an address the server recovers (CMS inventory; FraseCMS re-derivation from current settings when a live published post exists). `true` no longer implies the stored URL itself is absolute, and a FraseCMS article published before domain setup flips to `true` when setup finishes, with no re-publish. It remains exactly the condition enabling enforces. - `publishedUrlIssue` is now the RESIDUAL after recovery failed, not a raw-column classification — "not_absolute" can also mean the FraseCMS post is not live or FraseCMS is disabled for the site. - `POST /content/{id}/publish` → `url` (frase_cms): now derived from the site''s current CMS settings rather than the adapter''s host-of-the-moment value; the same URL is stored on the content row and sent in the content.published webhook.'
  contact:
    name: Frase Support
    url: https://frase.io
    email: support@frase.io
  license:
    name: Proprietary
    url: https://www.frase.io/company/terms
servers:
- url: https://next.frase.io/api/v1
  description: Production
- url: /api/v1
  description: This host
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Rules
  description: Content rules for automated quality checks
paths:
  /content/{id}/evaluate-rules:
    post:
      operationId: evaluateContentRules
      summary: Evaluate every enabled rule set against a content row
      description: 'Run every enabled rule set (org-wide plus the content''s site) against an existing Frase content row, mirroring the in-app governance agent. Unlike the stateless `POST /rules/evaluate`, this endpoint persists the outcome by default so the content''s governance status stays current; pass `save_results: false` to evaluate without writing.'
      tags:
      - Rules
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Content ID to evaluate
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                site_id:
                  type: string
                  format: uuid
                  description: Optional. Scopes site-scoped rule sets and score computation.
                save_results:
                  type: boolean
                  description: Persist the evaluation to the content's governance status. Defaults to true; pass false for a preview.
      responses:
        '200':
          description: Evaluation result across every applied rule set
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      content_id:
                        type: string
                        format: uuid
                      overall_status:
                        type: string
                        enum:
                        - pass
                        - warning
                        - fail
                      rule_set_results:
                        type: array
                        items:
                          type: object
                          properties:
                            rule_set_id:
                              type: string
                              format: uuid
                            rule_set_name:
                              type: string
                            overall_status:
                              type: string
                              enum:
                              - pass
                              - warning
                              - fail
                            summary:
                              nullable: true
                            results:
                              type: array
                              items:
                                type: object
                                properties:
                                  rule_id:
                                    type: string
                                    format: uuid
                                  rule_name:
                                    type: string
                                  condition_type:
                                    type: string
                                  severity:
                                    type: string
                                    enum:
                                    - error
                                    - warning
                                    - info
                                  passed:
                                    type: boolean
                                  skipped:
                                    type: boolean
                                    description: The rule could not run (e.g. a score_threshold rule with no target keywords). A skipped rule is neither a pass nor a failure - never read it as a genuine pass.
                                  value:
                                    nullable: true
                                  threshold:
                                    nullable: true
                                  message:
                                    type: string
                                    nullable: true
                                  fix_hint:
                                    type: string
                                    nullable: true
                  request_id:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)
  /rules/evaluate:
    post:
      operationId: evaluateRuleSets
      summary: Evaluate rule sets against content, a CMS post, or raw text
      description: 'Run content rules against exactly one subject: an existing Frase content row (`content_id`), a FraseCMS post (`post_id`), or raw text (`content`). Omit `rule_set_id` to evaluate every enabled rule set (org-wide plus the subject''s site), matching the in-app agent. This is a **read:content** endpoint: results are never persisted (the `save_results` field is accepted for back-compat but ignored). Provide `target_keywords` (post/raw subjects) to compute real SEO/GEO/EEAT scores for score_threshold rules; without it those rules report `skipped` rather than failing.'
      tags:
      - Rules
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content_id:
                  type: string
                  format: uuid
                  description: 'Subject: an existing Frase content row.'
                post_id:
                  type: string
                  format: uuid
                  description: 'Subject: a FraseCMS post.'
                content:
                  type: object
                  description: 'Subject: raw text (e.g. a pre-publish preflight).'
                  required:
                  - body
                  properties:
                    title:
                      type: string
                    body:
                      type: string
                      description: Required. Sanitized exactly as a publish would before evaluation.
                    seo_title:
                      type: string
                    seo_description:
                      type: string
                rule_set_id:
                  type: string
                  format: uuid
                  description: Optional. Omit to evaluate every enabled rule set in scope.
                site_id:
                  type: string
                  format: uuid
                  description: Optional. Scopes site-scoped rule sets and score computation.
                target_keywords:
                  type: array
                  items:
                    type: string
                  description: Optional (post/raw subjects). Enables real score computation for score_threshold rules.
                save_results:
                  type: boolean
                  description: Accepted for back-compat but IGNORED — this read-scope endpoint never persists.
      responses:
        '200':
          description: Evaluation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      content_id:
                        type: string
                        format: uuid
                        description: Echoed when the subject was a content row.
                      post_id:
                        type: string
                        format: uuid
                        description: Echoed when the subject was a FraseCMS post.
                      overall_status:
                        type: string
                        enum:
                        - pass
                        - warning
                        - fail
                      no_rules_configured:
                        type: boolean
                        description: true when no rule set applied — a 'pass' here means governance was never set up, not that anything was checked.
                      site_scoped_sets_skipped:
                        type: integer
                        description: Count of site-scoped rule sets not evaluated (no site in scope). A verdict with this > 0 is weaker than the publish gate.
                      rule_set_results:
                        type: array
                        items:
                          type: object
                          properties:
                            rule_set_id:
                              type: string
                              format: uuid
                            rule_set_name:
                              type: string
                            overall_status:
                              type: string
                              enum:
                              - pass
                              - warning
                              - fail
                            summary:
                              nullable: true
                            results:
                              type: array
                              items:
                                type: object
                                properties:
                                  rule_id:
                                    type: string
                                    format: uuid
                                  rule_name:
                                    type: string
                                  condition_type:
                                    type: string
                                  severity:
                                    type: string
                                    enum:
                                    - error
                                    - warning
                                    - info
                                  passed:
                                    type: boolean
                                  skipped:
                                    type: boolean
                                    description: The rule could not run (e.g. a score_threshold rule with no target_keywords). A skipped rule is neither a pass nor a failure — never read it as a genuine pass.
                                  value:
                                    nullable: true
                                  threshold:
                                    nullable: true
                                  message:
                                    type: string
                                    nullable: true
                                  fix_hint:
                                    type: string
                                    nullable: true
                  request_id:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: Rate limited, or the org's monthly brief limit blocked minting the refreshed brief (only the FIRST supersession of a brief is billing-exempt; repeats meter normally)
  /rules:
    get:
      operationId: listRules
      summary: List rules
      description: Retrieve all content rules for your organization, including system rules and custom rules.
      tags:
      - Rules
      security:
      - ApiKeyAuth: []
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: page_size
        in: query
        schema:
          type: integer
          default: 20
          maximum: 100
      responses:
        '200':
          description: List of rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRules'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /rules/{id}:
    get:
      operationId: getRule
      summary: Get rule
      description: Retrieve a single content rule by ID.
      tags:
      - Rules
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Rule ID
      responses:
        '200':
          description: Rule details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RuleDetail'
                  request_id:
                    type: string
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      operationId: deleteRule
      summary: Delete rule
      description: Delete a rule. System rules cannot be deleted.
      tags:
      - Rules
      security:
      - ApiKeyAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Rule ID
      responses:
        '200':
          description: Rule deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                  request_id:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: System rule cannot be deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: resource_not_found
              message: The requested resource was not found.
              doc_url: https://docs.frase.io/api/errors#resource_not_found
            request_id: req_abc123
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: authentication_error
              code: invalid_api_key
              message: Invalid API key. Check that you are using the correct key.
              doc_url: https://docs.frase.io/api/errors#invalid_api_key
            request_id: req_abc123
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until rate limit resets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: rate_limit_error
              code: rate_limit_exceeded
              message: Rate limit exceeded. Please retry after 60 seconds.
              doc_url: https://docs.frase.io/api/errors#rate_limit_exceeded
            request_id: req_abc123
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: validation_error
              message: The request body is invalid.
              param: prompt_text
              doc_url: https://docs.frase.io/api/errors#validation_error
            request_id: req_abc123
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            param:
              type: string
            doc_url:
              type: string
        request_id:
          type: string
    PaginatedRules:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Rule'
        pagination:
          $ref: '#/components/schemas/Pagination'
        request_id:
          type: string
    RuleDetail:
      type: object
      description: Rule with additional detail fields including updated_at
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        condition_type:
          type: string
          enum:
          - score_threshold
          - term_compliance
          - verify_chips
          - word_count
          - meta_required
          - link_count
          - section_required
          - regex_pattern
          - competitor_filter
        config:
          type: object
          description: Rule configuration object, structure varies by condition_type
        severity:
          type: string
          enum:
          - error
          - warning
          - info
        fix_hint:
          type: string
          nullable: true
        is_system:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
    Rule:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        condition_type:
          type: string
          enum:
          - score_threshold
          - term_compliance
          - verify_chips
          - word_count
          - meta_required
          - link_count
          - section_required
          - regex_pattern
          - competitor_filter
        config:
          type: object
          description: Rule configuration object, structure varies by condition_type
        severity:
          type: string
          enum:
          - error
          - warning
          - info
        fix_hint:
          type: string
          nullable: true
        is_system:
          type: boolean
        created_at:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        page:
          type: integer
        page_size:
          type: integer
        total:
          type: integer
        has_more:
          type: boolean
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: 'API key for authentication. Get your key from Settings > API Keys. You may also send the same key as `Authorization: Bearer <key>` — see BearerAuth.'
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Frase API key (sk_live_* / sk_test_*) or MCP access token (mcp_at_*)
      description: 'Send either your API key or an MCP access token as `Authorization: Bearer <token>`. An API key sent this way is exactly equivalent to sending it in X-API-KEY — same identity, same scopes, same rate limits — so use whichever your HTTP client makes natural. X-API-KEY takes precedence if you somehow send both. Cookie/session auth is intentionally NOT supported on /api/v1/* endpoints.'