Cactal Documentation API

openapi: 3.2.0
info:
  title: Cactal Ai Documentation API
  version: 1.0.0
  description: 'Operations tagged Documentation across 2 of this provider''s published API definitions: openapi.json, cactal-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.cactal.ai/v1
security:
- apiKey: []
tags:
- name: Documentation
  description: Search and read the Cactal product documentation for concepts, guides, agent workflows, platform behavior, and API operations.
paths:
  /docs/search:
    get:
      operationId: docs.search
      summary: Search the Cactal documentation
      description: 'Search the Cactal product documentation: concepts, guides, agent workflows, platform limits, and the API reference. Returns matching Markdown excerpts with page paths; read a full page with the docs read operation. Consult the docs before non-trivial or unfamiliar work such as source-code editing, publishing, or CMS schema changes.'
      tags:
      - Documentation
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 500
          description: Plain-language question or keywords, for example "how does publishing work".
      responses:
        '200':
          description: Matching documentation excerpts in Markdown.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: string
                    description: Up to 5 matching documentation excerpts formatted as Markdown, each naming the page path to pass to the docs read operation for the full page.
                required:
                - content
                additionalProperties: false
        '400':
          description: Validation failed. The response `message` names the first invalid field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '401':
          description: Missing, invalid, expired, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '403':
          description: The authenticated principal lacks the required capability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '404':
          description: The resource does not exist or is outside the principal’s access scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '429':
          description: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
      x-cactal-required-capability: null
      x-cactal-read-only: true
      x-cactal-destructive: false
      x-cactal-idempotent: true
    servers:
    - url: https://api.cactal.ai/v1
  /docs/read:
    get:
      operationId: docs.read
      summary: Read a Cactal documentation page
      description: Read one Cactal documentation page as Markdown. Pass a page path from docs search results, for example "concepts/publishing" or "agents/agent-safe-publishing". Pass "llms.txt" for an index of every page with titles and descriptions.
      tags:
      - Documentation
      parameters:
      - name: path
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 500
          description: Docs page path, for example "concepts/publishing". Pass "llms.txt" for the index of every page.
      responses:
        '200':
          description: The requested documentation page in Markdown.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: string
                    description: The documentation page formatted as Markdown.
                required:
                - content
                additionalProperties: false
        '400':
          description: Validation failed. The response `message` names the first invalid field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '401':
          description: Missing, invalid, expired, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '403':
          description: The authenticated principal lacks the required capability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '404':
          description: The resource does not exist or is outside the principal’s access scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '429':
          description: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
      x-cactal-required-capability: null
      x-cactal-read-only: true
      x-cactal-destructive: false
      x-cactal-idempotent: true
    servers:
    - url: https://api.cactal.ai/v1
  /skills/{skillId}:
    get:
      operationId: skills.read
      summary: Read a Cactal agent skill
      description: 'Read the matching Cactal skill before acting: source-editing-workflow before source edits, design-direction for design, copywriting for words. Required skills are included.


        - analytics: Traffic, visitors, referrers, and other analytics reports

        - assets-and-media: Find, import, or place images, video, fonts, favicons

        - cms-content-editing: Create, edit, publish, schedule, or delete CMS items

        - cms-data-in-pages: Show CMS content on pages with definePage queries

        - cms-item-queries: Filter, search, and sort CMS item lists

        - cms-modeling: Create or change CMS collections and fields

        - copywriting: Write or rewrite website copy

        - design-direction: New visual design or restyling of palette, type, and layout

        - forms: Forms, submissions, and notification recipients

        - image-reforming: Turn found or imperfect photos into better images

        - imports-and-modules: Imports, components, and shared modules

        - logo-design: Design or redraw a logo, brand mark, icon, or favicon

        - npm-packages: Add, upgrade, or debug npm packages

        - page-metadata-and-seo: Page metadata, SEO, social cards, and sitemaps

        - pages-and-routes: Create pages, routes, URL params, and a custom 404

        - publishing-and-recovery: Publish, roll back, restore, or unpublish the website

        - rendering-and-browser-apis: Browser-only APIs, Intl, and server render failures

        - server-functions: Server functions and website secrets

        - shaders: Build GPU effects with Paper Shaders or custom GLSL

        - source-editing-workflow: Read before any page, component, CSS, or config edit

        - source-files-and-naming: Create, delete, or name source files

        - styling-and-css: Global CSS, Tailwind theme, and fonts

        - validate-and-preview: Checks, diagnostics, screenshots, and deployments

        - web-research: Public web facts and studying reference sites

        - website-config: Redirects, response headers, and website_config

        - website-settings-and-domains: Rename the website or slug, hosts, custom domains, DNS'
      tags:
      - Documentation
      parameters:
      - name: skillId
        in: path
        required: true
        schema:
          type: string
          enum:
          - analytics
          - assets-and-media
          - cms-content-editing
          - cms-data-in-pages
          - cms-item-queries
          - cms-modeling
          - copywriting
          - design-direction
          - forms
          - image-reforming
          - imports-and-modules
          - logo-design
          - npm-packages
          - page-metadata-and-seo
          - pages-and-routes
          - publishing-and-recovery
          - rendering-and-browser-apis
          - server-functions
          - shaders
          - source-editing-workflow
          - source-files-and-naming
          - styling-and-css
          - validate-and-preview
          - web-research
          - website-config
          - website-settings-and-domains
          description: Skill to read; the skills it requires come with it.
      responses:
        '200':
          description: The skill and the skills it requires, formatted as Markdown.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: string
                    description: The skill and every skill it requires, dependencies first, as Markdown.
                required:
                - content
                additionalProperties: false
        '400':
          description: Validation failed. The response `message` names the first invalid field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '401':
          description: Missing, invalid, expired, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '403':
          description: The authenticated principal lacks the required capability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '404':
          description: The resource does not exist or is outside the principal’s access scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
        '429':
          description: Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
      x-cactal-required-capability: null
      x-cactal-read-only: true
      x-cactal-destructive: false
      x-cactal-idempotent: true
    servers:
    - url: https://api.cactal.ai/v1
components:
  schemas:
    ServiceError:
      type: object
      required:
      - kind
      - message
      description: Canonical error body returned by every non-2xx response. Extra fields carry error-specific details.
      properties:
        kind:
          type: string
          enum:
          - validation
          - unauthorized
          - forbidden
          - not_found
          - conflict
          - rate_limited
          - internal
          description: Stable, machine-readable error category.
        message:
          type: string
          description: Human-readable explanation of the failure.
        suggestion:
          type: string
          description: What to do next when the failure has a known fix; may name the exact operation to call.
        validValues:
          type: array
          items:
            type: string
          description: The acceptable values for the failing field, when the set is closed.
      additionalProperties: true
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Cactal API key. Create one in the dashboard or via `POST /apiKeys`. The plaintext key is shown once at creation.
x-refined-from:
- openapi.json
- cactal-ai-openapi.json