openapi: 3.0.0
info:
  title: Cattive Platform API
  description: |
    Cattive is an AI-First platform for news portals. This API provides public
    endpoints for platform information, newsroom articles, and payable
    commerce operations (legal advertising and niche directory listings).
  version: 1.1.0
  contact:
    name: Cattive
    email: contato@cattive.com
    url: https://cattive.com
  license:
    name: Proprietary
    url: https://cattive.com/terms

# MPP (Machine Payment Protocol) top-level service info — categorises the
# payable operations under this server so agent payers can short-list them.
# https://mpp.dev
x-service-info:
  categories:
    - publishing
    - advertising
    - directory
  payment_methods:
    - card
    - stripe

servers:
  - url: https://cattive.com
    description: Production

paths:
  /cattive-sitemap.xml:
    get:
      operationId: getSitemap
      summary: Get the Cattive sitemap
      description: Returns the XML sitemap with all public URLs, hreflang tags, priorities, and change frequencies.
      responses:
        '200':
          description: XML sitemap
          content:
            application/xml:
              schema:
                type: string

  /cattive-llms.txt:
    get:
      operationId: getLlmsTxt
      summary: Get structured information about Cattive for AI models
      description: Returns a plain text file with structured information about the Cattive platform, products, key facts, and contact details optimized for AI consumption.
      responses:
        '200':
          description: Plain text with platform information
          content:
            text/plain:
              schema:
                type: string

  /.well-known/ai-plugin.json:
    get:
      operationId: getAiPluginManifest
      summary: Get the AI plugin manifest
      description: Returns the AI plugin manifest following the OpenAI plugin specification, including platform name, description, logo, and authentication details.
      responses:
        '200':
          description: JSON manifest
          content:
            application/json:
              schema:
                type: object
                properties:
                  name_for_human:
                    type: string
                  description_for_human:
                    type: string
                  logo_url:
                    type: string

  /api/legal-ads:
    post:
      operationId: createLegalAd
      summary: Publish a legal act with ICP-Brasil certification
      description: |
        Creates a publication request for a legal act (bid notice, balance
        sheet, edict, judicial publication). The published document carries
        ICP-Brasil digital signature (SHA-256) and an RFC 3161 timestamp.
        Returns 402 Payment Required if no payment receipt is presented;
        agent payers fulfill via the linked ACP checkout session.
      x-payment-info:
        intent: charge
        method: card
        amount: 109.90
        currency: BRL
        description: Publication of one legal act (single document).
        checkout_url: https://cattive.com/api/acp/sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegalAdRequest'
      responses:
        '201':
          description: Legal ad created and queued for publication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalAdResponse'
        '402':
          description: Payment required (see x-payment-info)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

  /api/niches/{slug}/listings:
    post:
      operationId: createNicheListing
      summary: Buy a listing in a commercial niche directory
      description: |
        Creates a directory listing for a company in a thematic niche
        (e.g. /api/niches/supermercados-barueri/listings). Plans are
        billed monthly (signature/destaque, minimum 6 months). Returns
        402 Payment Required if no payment receipt is presented.
      parameters:
        - in: path
          name: slug
          required: true
          schema:
            type: string
          description: Niche slug, as listed in the public niche directory.
      x-payment-info:
        intent: session
        method: card
        amount: 0
        currency: BRL
        description: Recurring monthly listing in commercial niche directory. Exact amount depends on selected plan (destaque or signature).
        checkout_url: https://cattive.com/api/acp/sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NicheListingRequest'
      responses:
        '201':
          description: Listing created and pending publication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NicheListingResponse'
        '402':
          description: Payment required (see x-payment-info)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'

components:
  schemas:
    PlatformInfo:
      type: object
      properties:
        name:
          type: string
          example: Cattive
        description:
          type: string
          example: AI-First Platform for News Portals
        founded:
          type: string
          example: "2009"
        headquarters:
          type: string
          example: São Paulo, Brazil
        products:
          type: array
          items:
            type: string
          example:
            - Portal PRO (Smart CMS)
            - Newsletter AI
            - Legal Advertising
            - Monetization System
            - leia.la (Link Shortener)
            - Chama.lá (WhatsApp Links)
        languages:
          type: array
          items:
            type: string
          example:
            - English
            - Portuguese (Brazil)
        website:
          type: string
          example: https://cattive.com

    LegalAdRequest:
      type: object
      required: [portal_id, document_type, content]
      properties:
        portal_id:
          type: string
          description: Portal slug or UUID where the act will be published.
        document_type:
          type: string
          enum: [licitacao, balanco, edital, ata, portaria, outro]
        content:
          type: string
          description: Markdown or HTML body of the legal act.
        publication_date:
          type: string
          format: date
        attachments:
          type: array
          items:
            type: string
            format: uri

    LegalAdResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [queued, processing, published, rejected]
        published_url:
          type: string
          format: uri

    NicheListingRequest:
      type: object
      required: [company_name, plan_id]
      properties:
        company_name:
          type: string
        company_cnpj:
          type: string
          description: Brazilian CNPJ (formatted or numeric).
        plan_id:
          type: string
          description: One of the plans available for this niche.
        contact_email:
          type: string
          format: email
        contact_whatsapp:
          type: string

    NicheListingResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending_payment, active, paused]
        listing_url:
          type: string
          format: uri

    PaymentRequired:
      type: object
      properties:
        error:
          type: string
          example: payment_required
        payment_url:
          type: string
          format: uri
          description: ACP checkout session URL where the agent can pay.
        amount:
          type: number
        currency:
          type: string
          example: BRL
