answer-engine.yaml

openapi: 3.1.0
info:
  title: Answer Engine OSS API
  version: 1.1.2
  summary: Local-first memory, retrieval, and grounded answers for AI agents.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://127.0.0.1:5050
    description: Default local server
security:
  - apiKey: []
  - bearerKey: []
tags:
  - name: System
  - name: Content
  - name: Memory
  - name: Organization
  - name: Workflows
  - name: Operations
paths:
  /health:
    get:
      tags: [System]
      security: []
      summary: Check local API health
      responses:
        '200':
          description: API is healthy.
          content:
            application/json:
              schema:
                type: object
                required: [status, uptime, channel]
                properties:
                  status: { type: string, const: healthy }
                  uptime: { type: number }
                  channel: { type: string, enum: [stable, staging] }
  /api/v1/content/import/preview:
    post:
      tags: [Content]
      summary: Validate an import without writing it
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ImportRequest' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/content/import:
    post:
      tags: [Content]
      summary: Import or update local content
      description: Reusing a source identifier updates the matching item.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ImportRequest' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/first-imports:
    post:
      tags: [Workflows]
      summary: Register a metadata-only supported agent-history discovery
      description: Registers paths, file statistics, fingerprints, privacy posture, and exclusions. This endpoint never imports content.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FirstImportDiscovery' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
  /api/v1/first-imports/latest:
    get:
      tags: [Workflows]
      summary: Read the latest first-import session and reconciliation inventory
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/first-imports/{sessionId}:
    parameters:
      - { $ref: '#/components/parameters/FirstImportSessionId' }
    get:
      tags: [Workflows]
      summary: Read a first-import session and its source-backed item manifest
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/first-imports/{sessionId}/approve:
    parameters:
      - { $ref: '#/components/parameters/FirstImportSessionId' }
    post:
      tags: [Workflows]
      summary: Explicitly approve a subset of discovered history sources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [sourceIds]
              properties:
                sourceIds:
                  type: array
                  minItems: 1
                  uniqueItems: true
                  items: { $ref: '#/components/schemas/FirstImportSourceId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/first-imports/{sessionId}/start:
    parameters:
      - { $ref: '#/components/parameters/FirstImportSessionId' }
    post:
      tags: [Workflows]
      summary: Start an explicitly approved first import
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/first-imports/{sessionId}/events:
    parameters:
      - { $ref: '#/components/parameters/FirstImportSessionId' }
    post:
      tags: [Workflows]
      summary: Record a safe per-history import outcome
      description: Imported outcomes are accepted only when all referenced chat rows have non-empty summaries and a matching raw-archive manifest path.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FirstImportEvent' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/first-imports/{sessionId}/cancel:
    parameters:
      - { $ref: '#/components/parameters/FirstImportSessionId' }
    post:
      tags: [Workflows]
      summary: Request safe cancellation at the next resumable boundary
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/first-imports/{sessionId}/retry:
    parameters:
      - { $ref: '#/components/parameters/FirstImportSessionId' }
    post:
      tags: [Workflows]
      summary: Reset failed or interrupted selected items for retry
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/first-imports/{sessionId}/complete:
    parameters:
      - { $ref: '#/components/parameters/FirstImportSessionId' }
    post:
      tags: [Workflows]
      summary: Finalize only after every discovered item has an outcome
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/folder-sources:
    get:
      tags: [Workflows]
      summary: List explicitly selected local folder sources
      responses:
        '200': { $ref: '#/components/responses/Success' }
    post:
      tags: [Workflows]
      summary: Register a bounded local folder preview before full-file reads
      description: Never imports file content. Every path, exclusion, warning, limit, and fixed no-follow symlink policy is recorded for approval.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FolderSourceDiscovery' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
  /api/v1/folder-sources/latest:
    get:
      tags: [Workflows]
      summary: Read the latest selected folder and inventory run
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/folder-sources/{sourceId}:
    parameters:
      - { in: path, name: sourceId, required: true, schema: { type: string, format: uuid } }
    get:
      tags: [Workflows]
      summary: Inspect a folder source, all runs, and reconciled items
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/folder-sources/{sourceId}/refresh:
    parameters:
      - { in: path, name: sourceId, required: true, schema: { type: string, format: uuid } }
    post:
      tags: [Workflows]
      summary: Register an added/changed/unchanged/missing/excluded refresh preview
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FolderRefreshDiscovery' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/folder-sources/{sourceId}/remove:
    parameters:
      - { in: path, name: sourceId, required: true, schema: { type: string, format: uuid } }
    post:
      tags: [Workflows]
      summary: Prepare source removal with explicit keep or delete retention
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FolderRemoval' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/folder-sources/{sourceId}/remove/complete:
    parameters:
      - { in: path, name: sourceId, required: true, schema: { type: string, format: uuid } }
    post:
      tags: [Workflows]
      summary: Reconcile content/archive retention and complete audited removal
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FolderRemovalComplete' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/folder-sources/runs/{runId}/approve:
    parameters:
      - { in: path, name: runId, required: true, schema: { type: string, format: uuid } }
    post:
      tags: [Workflows]
      summary: Approve one exact folder inventory before any full file read
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/folder-sources/runs/{runId}/start:
    parameters:
      - { in: path, name: runId, required: true, schema: { type: string, format: uuid } }
    post:
      tags: [Workflows]
      summary: Start an approved folder run
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/folder-sources/runs/{runId}/events:
    parameters:
      - { in: path, name: runId, required: true, schema: { type: string, format: uuid } }
    post:
      tags: [Workflows]
      summary: Reconcile one preview row with integrity-checked lineage
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FolderIngestionEvent' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/folder-sources/runs/{runId}/cancel:
    parameters:
      - { in: path, name: runId, required: true, schema: { type: string, format: uuid } }
    post:
      tags: [Workflows]
      summary: Request cancellation at the next file boundary
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/folder-sources/runs/{runId}/retry:
    parameters:
      - { in: path, name: runId, required: true, schema: { type: string, format: uuid } }
    post:
      tags: [Workflows]
      summary: Reset failed or interrupted candidate rows
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/folder-sources/runs/{runId}/complete:
    parameters:
      - { in: path, name: runId, required: true, schema: { type: string, format: uuid } }
    post:
      tags: [Workflows]
      summary: Complete only after every preview row has an explained outcome
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/content:
    get:
      tags: [Content]
      summary: List, filter, sort, and paginate content
      description: Returns lightweight rows with source, status, and assigned tags. Stable cursors follow the selected sort field and direction.
      parameters:
        - { in: query, name: limit, schema: { type: integer, minimum: 1, maximum: 100, default: 25 } }
        - { in: query, name: cursor, schema: { type: string } }
        - { in: query, name: libraryId, schema: { type: string } }
        - { in: query, name: librarySlug, schema: { type: string } }
        - { in: query, name: search, schema: { type: string, maxLength: 500 } }
        - { in: query, name: contentType, schema: { $ref: '#/components/schemas/ContentType' } }
        - { in: query, name: contentTypes, description: Comma-separated content types., schema: { type: string } }
        - { in: query, name: source, schema: { type: string, maxLength: 120 } }
        - { in: query, name: sources, description: Comma-separated neutral source identifiers such as claude-code, codex, and cowork., schema: { type: string } }
        - { in: query, name: tag, schema: { type: string, maxLength: 120 } }
        - { in: query, name: tags, description: Comma-separated tag slugs., schema: { type: string } }
        - { in: query, name: status, schema: { enum: [active, archived] } }
        - { in: query, name: dateFrom, schema: { type: string, format: date-time } }
        - { in: query, name: dateTo, schema: { type: string, format: date-time } }
        - { in: query, name: sortBy, schema: { enum: [createdAt, title, contentType, source, status], default: createdAt } }
        - { in: query, name: sortDirection, schema: { enum: [asc, desc], default: desc } }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/content/raw-archive-references:
    get:
      tags: [Content]
      summary: List raw archive manifests still referenced by content
      description: Returns tenant-scoped manifest paths, including references held by soft-deleted content, so local retention can preserve recoverable sources.
      responses:
        '200':
          description: Referenced manifest paths.
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/SuccessEnvelope' }
                  - type: object
                    properties:
                      data: { $ref: '#/components/schemas/RawArchiveReferences' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/content/{id}:
    parameters:
      - { $ref: '#/components/parameters/ContentId' }
    get:
      tags: [Content]
      summary: Get a content item
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [Content]
      summary: Soft-delete a content item
      responses:
        '204': { description: Content deleted. }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/content/{id}/lineage:
    parameters:
      - { $ref: '#/components/parameters/ContentId' }
    get:
      tags: [Content]
      summary: Inspect source provenance and artifact history
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/agent/schema:
    get:
      tags: [Memory]
      summary: Discover available content and capabilities
      parameters:
        - { in: query, name: libraryId, schema: { type: string } }
        - { in: query, name: librarySlug, schema: { type: string } }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/agent/query:
    post:
      tags: [Memory]
      summary: Search local memory
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QueryRequest' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/agent/retrieve:
    post:
      tags: [Memory]
      summary: Retrieve known items or a conversation
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RetrieveRequest' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/agent/summarize:
    post:
      tags: [Memory]
      summary: Summarize local evidence
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SummarizeRequest' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/agent/ask:
    post:
      tags: [Memory]
      summary: Answer from local evidence with citations
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AskRequest' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/organization-plans:
    get:
      tags: [Organization]
      summary: List recent organization proposals
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Organization]
      summary: Create a non-mutating organization proposal
      description: Samples bounded titles, summaries, source metadata, and existing taxonomy. Full content and raw archives are never sent to the proposal model.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrganizationProposalRequest' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/organization-plans/{planId}:
    parameters:
      - { $ref: '#/components/parameters/PlanId' }
    get:
      tags: [Organization]
      summary: Inspect an organization proposal and its decisions
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/organization-plans/{planId}/apply:
    parameters:
      - { $ref: '#/components/parameters/PlanId' }
    post:
      tags: [Organization]
      summary: Apply individually reviewed organization suggestions
      description: Requires an accept or reject decision for every suggestion and refuses a stale source snapshot.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrganizationApplyRequest' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/organization-plans/{planId}/undo:
    parameters:
      - { $ref: '#/components/parameters/PlanId' }
    post:
      tags: [Organization]
      summary: Undo changes introduced by an applied organization plan
      description: Restores taxonomy and memberships without deleting imported content.
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/recall-tutorials/capabilities:
    get:
      tags: [Onboarding]
      summary: Preflight supported same-client and cross-client recall paths
      parameters:
        - in: query
          name: environment
          schema: { enum: [native, wsl], default: native }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/recall-tutorials:
    get:
      tags: [Onboarding]
      summary: List recent first-memory proof challenges
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Onboarding]
      summary: Create a harmless remember and fresh-chat recall challenge
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RecallTutorialCreateRequest' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/recall-tutorials/{tutorialId}:
    parameters:
      - { $ref: '#/components/parameters/TutorialId' }
    get:
      tags: [Onboarding]
      summary: Inspect tutorial progress and answer-free fresh-chat instructions
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/recall-tutorials/{tutorialId}/check:
    parameters:
      - { $ref: '#/components/parameters/TutorialId' }
    post:
      tags: [Onboarding]
      summary: Verify ordered remember, recall citation, and lineage tool evidence
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RecallTutorialCheckRequest' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/tags:
    get:
      tags: [Organization]
      summary: List active tags
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Organization]
      summary: Create a tag
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TagInput' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
  /api/v1/tags/{tagId}:
    parameters:
      - { $ref: '#/components/parameters/TagId' }
    patch:
      tags: [Organization]
      summary: Update a tag
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TagUpdate' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [Organization]
      summary: Archive a tag
      responses:
        '204': { description: Tag archived. }
  /api/v1/tags/{tagId}/content:
    parameters:
      - { $ref: '#/components/parameters/TagId' }
    post:
      tags: [Organization]
      summary: Assign a tag to content in bulk
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TagAssignment' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
    delete:
      tags: [Organization]
      summary: Remove a tag from content in bulk
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TagAssignment' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/libraries:
    get:
      tags: [Organization]
      summary: List libraries with effective member counts
      responses:
        '200': { $ref: '#/components/responses/Success' }
    post:
      tags: [Organization]
      summary: Create a saved content library
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LibraryInput' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
  /api/v1/libraries/{libraryId}:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
    get:
      tags: [Organization]
      summary: Get a library
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      tags: [Organization]
      summary: Update a user-defined library
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LibraryUpdate' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { description: A system-library invariant was violated. }
    delete:
      tags: [Organization]
      summary: Archive a user-defined library
      responses:
        '204': { description: Library archived. }
        '409': { description: The system library cannot be archived. }
  /api/v1/libraries/{libraryId}/members:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
    get:
      tags: [Organization]
      summary: Page through effective library membership
      description: Membership is `(saved filter OR manual include) AND NOT manual exclude`.
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/preview:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
    post:
      tags: [Organization]
      summary: Preview a strict saved filter without changing the library
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LibraryPreview' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
  /api/v1/libraries/{libraryId}/includes/{contentId}:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
      - { $ref: '#/components/parameters/MemberContentId' }
    put:
      tags: [Organization]
      summary: Add a manual library include
      responses:
        '200': { $ref: '#/components/responses/Success' }
    delete:
      tags: [Organization]
      summary: Remove a manual library include
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/excludes/{contentId}:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
      - { $ref: '#/components/parameters/MemberContentId' }
    put:
      tags: [Organization]
      summary: Add a manual library exclusion
      responses:
        '200': { $ref: '#/components/responses/Success' }
    delete:
      tags: [Organization]
      summary: Remove a manual library exclusion
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/recipes:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
    get:
      tags: [Workflows]
      summary: List library recipes
      responses:
        '200': { $ref: '#/components/responses/Success' }
    post:
      tags: [Workflows]
      summary: Create a versioned library recipe
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RecipeInput' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/recipes/{recipeId}:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
      - { $ref: '#/components/parameters/RecipeId' }
    patch:
      tags: [Workflows]
      summary: Save a new immutable recipe version
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RecipeUpdate' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
    delete:
      tags: [Workflows]
      summary: Deactivate a recipe
      responses:
        '204': { description: Recipe deactivated. }
  /api/v1/libraries/{libraryId}/recipes/{recipeId}/preview:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
      - { $ref: '#/components/parameters/RecipeId' }
    post:
      tags: [Workflows]
      summary: Preview recipe outputs over effective members
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RecipePreview' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/recipes/{recipeId}/runs:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
      - { $ref: '#/components/parameters/RecipeId' }
    get:
      tags: [Workflows]
      summary: List durable recipe runs
      responses:
        '200': { $ref: '#/components/responses/Success' }
    post:
      tags: [Workflows]
      summary: Queue a recipe run
      responses:
        '202': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/runs/{runId}:
    get:
      tags: [Workflows]
      summary: Get recipe-run progress and per-item results
      parameters:
        - { $ref: '#/components/parameters/LibraryId' }
        - { $ref: '#/components/parameters/RunId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/runs/{runId}/cancel:
    post:
      tags: [Workflows]
      summary: Safely cancel queued or running recipe work
      parameters:
        - { $ref: '#/components/parameters/LibraryId' }
        - { $ref: '#/components/parameters/RunId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/runs/{runId}/retry:
    post:
      tags: [Workflows]
      summary: Retry failed, partial, or canceled recipe work
      parameters:
        - { $ref: '#/components/parameters/LibraryId' }
        - { $ref: '#/components/parameters/RunId' }
      responses:
        '202': { $ref: '#/components/responses/Success' }
  /api/v1/content/{id}/artifacts:
    get:
      tags: [Workflows]
      summary: List artifact versions and lineage for content
      parameters:
        - { $ref: '#/components/parameters/ContentId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/artifacts/{artifactId}:
    get:
      tags: [Workflows]
      summary: Get an artifact version
      parameters:
        - { $ref: '#/components/parameters/ArtifactId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/reports:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
    get:
      tags: [Workflows]
      summary: List library report definitions
      responses:
        '200': { $ref: '#/components/responses/Success' }
    post:
      tags: [Workflows]
      summary: Create a library report definition
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReportInput' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/reports/{reportId}/generate:
    post:
      tags: [Workflows]
      summary: Queue a grounded report generation
      parameters:
        - { $ref: '#/components/parameters/LibraryId' }
        - { $ref: '#/components/parameters/ReportId' }
      responses:
        '202': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/reports/{reportId}:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
      - { $ref: '#/components/parameters/ReportId' }
    patch:
      tags: [Workflows]
      summary: Update a report definition
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReportUpdate' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
    delete:
      tags: [Workflows]
      summary: Delete a report definition and generated history
      responses:
        '204': { description: Report deleted. }
  /api/v1/libraries/{libraryId}/reports/{reportId}/generated:
    get:
      tags: [Workflows]
      summary: List generated report history
      parameters:
        - { $ref: '#/components/parameters/LibraryId' }
        - { $ref: '#/components/parameters/ReportId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/reports/{reportId}/generated/{generatedId}/cancel:
    post:
      tags: [Workflows]
      summary: Safely cancel queued or running report work
      parameters:
        - { $ref: '#/components/parameters/LibraryId' }
        - { $ref: '#/components/parameters/ReportId' }
        - { $ref: '#/components/parameters/GeneratedId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/reports/{reportId}/generated/{generatedId}/retry:
    post:
      tags: [Workflows]
      summary: Retry failed or canceled report work
      parameters:
        - { $ref: '#/components/parameters/LibraryId' }
        - { $ref: '#/components/parameters/ReportId' }
        - { $ref: '#/components/parameters/GeneratedId' }
      responses:
        '202': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/dashboards:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
    get:
      tags: [Workflows]
      summary: List library dashboards
      responses:
        '200': { $ref: '#/components/responses/Success' }
    post:
      tags: [Workflows]
      summary: Create a library dashboard
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DashboardInput' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
  /api/v1/libraries/{libraryId}/dashboards/{dashboardId}:
    parameters:
      - { $ref: '#/components/parameters/LibraryId' }
      - { $ref: '#/components/parameters/DashboardId' }
    patch:
      tags: [Workflows]
      summary: Update a library dashboard
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DashboardUpdate' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
    delete:
      tags: [Workflows]
      summary: Delete a library dashboard
      responses:
        '204': { description: Dashboard deleted. }
  /api/v1/batch-jobs:
    get:
      tags: [Operations]
      summary: List local batch jobs
      responses:
        '200': { $ref: '#/components/responses/Success' }
    post:
      tags: [Operations]
      summary: Queue a provider-neutral local batch job
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BatchJobInput' }
      responses:
        '202': { $ref: '#/components/responses/Success' }
  /api/v1/batch-jobs/{jobId}:
    get:
      tags: [Operations]
      summary: Get batch progress and per-item results
      parameters:
        - { $ref: '#/components/parameters/JobId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/batch-jobs/{jobId}/cancel:
    post:
      tags: [Operations]
      summary: Safely cancel queued or running batch work
      parameters:
        - { $ref: '#/components/parameters/JobId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/batch-jobs/{jobId}/retry:
    post:
      tags: [Operations]
      summary: Retry unfinished failed, partial, or canceled batch work
      description: Creates a new job that excludes records already completed successfully by the source job.
      parameters:
        - { $ref: '#/components/parameters/JobId' }
      responses:
        '202': { $ref: '#/components/responses/Success' }
  /api/v1/access-tokens:
    get:
      tags: [Operations]
      summary: List access-token metadata without secrets
      description: Marks the current and protected installer credentials so clients can omit unsafe mutation controls.
      responses:
        '200': { $ref: '#/components/responses/Success' }
    post:
      tags: [Operations]
      summary: Mint a tenant- or library-scoped access token
      description: The raw `ae_live_` token is returned only by this operation.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AccessTokenInput' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
  /api/v1/access-tokens/{tokenId}:
    patch:
      tags: [Operations]
      summary: Update access-token metadata or expiry
      description: The protected local installer credential and the credential authenticating the request cannot be changed.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AccessTokenUpdate' }
      parameters:
        - { $ref: '#/components/parameters/TokenId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
    delete:
      tags: [Operations]
      summary: Revoke an access token
      description: The protected local installer credential and the credential authenticating the request cannot be revoked.
      parameters:
        - { $ref: '#/components/parameters/TokenId' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/audit:
    get:
      tags: [Operations]
      summary: Page through local tenant or library audit history
      responses:
        '200': { $ref: '#/components/responses/Success' }
  /api/v1/settings:
    get:
      tags: [Operations]
      summary: Read safe local workspace preferences
      description: Returns only neutral UI preferences; installer-managed provider credentials are never exposed.
      responses:
        '200': { $ref: '#/components/responses/Success' }
    patch:
      tags: [Operations]
      summary: Update safe local workspace preferences
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LocalSettingsUpdate' }
      responses:
        '200': { $ref: '#/components/responses/Success' }
        '400': { $ref: '#/components/responses/ValidationError' }
  /api/v1/content/{id}/blobs:
    parameters:
      - { $ref: '#/components/parameters/ContentId' }
    get:
      tags: [Content]
      summary: List local blob metadata for content
      responses:
        '200': { $ref: '#/components/responses/Success' }
    post:
      tags: [Content]
      summary: Store a content blob beneath AE_HOME
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BlobUpload' }
      responses:
        '201': { $ref: '#/components/responses/Success' }
  /api/v1/blobs/{blobId}/download:
    get:
      tags: [Content]
      summary: Download a tenant-scoped local blob
      parameters:
        - { $ref: '#/components/parameters/BlobId' }
      responses:
        '200': { description: Blob bytes. }
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
    bearerKey:
      type: http
      scheme: bearer
  parameters:
    ContentId:
      in: path
      name: id
      required: true
      schema: { type: string, format: uuid }
    MemberContentId:
      in: path
      name: contentId
      required: true
      schema: { type: string, format: uuid }
    LibraryId:
      in: path
      name: libraryId
      required: true
      schema: { type: string, format: uuid }
    TagId:
      in: path
      name: tagId
      required: true
      schema: { type: string, format: uuid }
    RecipeId:
      in: path
      name: recipeId
      required: true
      schema: { type: string, format: uuid }
    RunId:
      in: path
      name: runId
      required: true
      schema: { type: string, format: uuid }
    ArtifactId:
      in: path
      name: artifactId
      required: true
      schema: { type: string, format: uuid }
    ReportId:
      in: path
      name: reportId
      required: true
      schema: { type: string, format: uuid }
    GeneratedId:
      in: path
      name: generatedId
      required: true
      schema: { type: string, format: uuid }
    DashboardId:
      in: path
      name: dashboardId
      required: true
      schema: { type: string, format: uuid }
    JobId:
      in: path
      name: jobId
      required: true
      schema: { type: string, format: uuid }
    TokenId:
      in: path
      name: tokenId
      required: true
      schema: { type: string, format: uuid }
    BlobId:
      in: path
      name: blobId
      required: true
      schema: { type: string, format: uuid }
    PlanId:
      in: path
      name: planId
      required: true
      schema: { type: string, format: uuid }
    TutorialId:
      in: path
      name: tutorialId
      required: true
      schema: { type: string, format: uuid }
    FirstImportSessionId:
      in: path
      name: sessionId
      required: true
      schema: { type: string, format: uuid }
  responses:
    Success:
      description: Request completed.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/SuccessEnvelope' }
    ValidationError:
      description: Input validation failed.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    Unauthorized:
      description: A valid local API key is required.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    NotFound:
      description: The requested content was not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
    Conflict:
      description: The requested mutation conflicts with protected or current resource state.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorEnvelope' }
  schemas:
    FirstImportSourceId:
      type: string
      enum: [claude-code, codex, cowork]
    FirstImportDiscovery:
      type: object
      additionalProperties: false
      required: [manifestPath, sources]
      properties:
        manifestPath: { type: string, minLength: 1 }
        sources:
          type: array
          minItems: 1
          maxItems: 3
          items:
            type: object
            additionalProperties: false
            required: [sourceId, label, paths, estimatedCount, estimatedBytes, privacyPosture, exclusions, availability, availabilityNote, items]
            properties:
              sourceId: { $ref: '#/components/schemas/FirstImportSourceId' }
              label: { type: string, minLength: 1 }
              paths: { type: array, items: { type: string, minLength: 1 } }
              estimatedCount: { type: integer, minimum: 0 }
              estimatedBytes: { type: integer, minimum: 0 }
              privacyPosture: { type: string, minLength: 1 }
              exclusions: { type: array, items: { type: string } }
              availability: { enum: [available, not_found, unsupported_platform, unavailable] }
              availabilityNote: { type: string, minLength: 1 }
              items:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required: [fingerprint, sourcePath, byteSize, modifiedAt]
                  properties:
                    fingerprint: { type: string, pattern: '^[a-f0-9]{64}$' }
                    sourcePath: { type: string, minLength: 1 }
                    byteSize: { type: integer, minimum: 0 }
                    modifiedAt: { type: string, format: date-time }
    FirstImportEvent:
      type: object
      additionalProperties: false
      required: [sourceId, fingerprint, outcome]
      properties:
        sourceId: { $ref: '#/components/schemas/FirstImportSourceId' }
        fingerprint: { type: string, pattern: '^[a-f0-9]{64}$' }
        outcome: { enum: [imported, duplicate, failed, skipped] }
        contentIds: { type: array, items: { type: string, format: uuid } }
        archiveManifestPath: { type: string, minLength: 1 }
        errorCode: { type: string, pattern: '^[A-Z0-9_]{2,80}$' }
        recoveryAction: { type: string, minLength: 1 }
    FolderInventoryItem:
      type: object
      additionalProperties: false
      required: [sourcePath, relativePath, byteSize, disposition, reason]
      properties:
        sourcePath: { type: string, minLength: 1 }
        relativePath: { type: string, minLength: 1 }
        fileType: { type: string }
        byteSize: { type: integer, minimum: 0 }
        modifiedAt: { type: string, format: date-time }
        disposition: { enum: [candidate, excluded, hidden, unsupported, binary, too_large, access_denied, symlink, aggregate_limit, missing] }
        reason: { type: string, minLength: 1 }
        metadataFingerprint: { type: string, pattern: '^[a-f0-9]{64}$' }
        change: { enum: [added, changed, unchanged, missing, excluded] }
    FolderSourceDiscovery:
      type: object
      additionalProperties: false
      required: [rootPath, includePatterns, excludePatterns, maxFileBytes, maxTotalBytes, symlinkPolicy, manifestPath, inventory]
      properties:
        rootPath: { type: string, minLength: 1 }
        libraryId: { type: string, format: uuid }
        includePatterns: { type: array, minItems: 1, items: { type: string, minLength: 1 } }
        excludePatterns: { type: array, items: { type: string, minLength: 1 } }
        maxFileBytes: { type: integer, minimum: 1 }
        maxTotalBytes: { type: integer, minimum: 1 }
        symlinkPolicy: { type: string, const: no_follow }
        manifestPath: { type: string, minLength: 1 }
        inventory: { type: array, items: { $ref: '#/components/schemas/FolderInventoryItem' } }
    FolderRefreshDiscovery:
      type: object
      additionalProperties: false
      required: [manifestPath, inventory]
      properties:
        manifestPath: { type: string, minLength: 1 }
        inventory: { type: array, items: { $ref: '#/components/schemas/FolderInventoryItem' } }
    FolderIngestionEvent:
      type: object
      additionalProperties: false
      required: [relativePath, outcome]
      properties:
        relativePath: { type: string, minLength: 1 }
        outcome: { enum: [imported, updated, duplicate, excluded, changed, failed, skipped, missing] }
        appliedSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
        contentId: { type: string, format: uuid }
        archiveManifestPath: { type: string, minLength: 1 }
        errorCode: { type: string, pattern: '^[A-Z0-9_]{2,80}$' }
        recoveryAction: { type: string, minLength: 1 }
    FolderRemoval:
      type: object
      additionalProperties: false
      required: [retention]
      properties:
        retention: { enum: [keep, delete] }
    FolderRemovalComplete:
      allOf:
        - { $ref: '#/components/schemas/FolderRemoval' }
        - type: object
          required: [deletedContentIds, archivesRemoved, failures]
          properties:
            deletedContentIds: { type: array, items: { type: string, format: uuid } }
            archivesRemoved: { type: integer, minimum: 0 }
            failures:
              type: array
              items:
                type: object
                required: [path, errorCode]
                properties:
                  path: { type: string }
                  errorCode: { type: string }
    SuccessEnvelope:
      type: object
      required: [success, data]
      properties:
        success: { type: boolean, const: true }
        data: {}
        meta: { type: object, additionalProperties: true }
    ErrorEnvelope:
      type: object
      required: [success, error]
      properties:
        success: { type: boolean, const: false }
        error:
          type: object
          required: [code, message]
          properties:
            code: { type: string }
            message: { type: string }
            details: {}
    RawArchiveReferences:
      type: object
      additionalProperties: false
      required: [manifestPaths]
      properties:
        manifestPaths:
          type: array
          items: { type: string }
          uniqueItems: true
    OrganizationProposalRequest:
      type: object
      additionalProperties: false
      properties:
        useModel: { type: boolean, default: false }
        limit: { type: integer, minimum: 1, maximum: 50, default: 50 }
    OrganizationDecision:
      type: object
      additionalProperties: false
      required: [suggestionId, decision]
      properties:
        suggestionId: { type: string, pattern: '^s-[a-f0-9]{16}$' }
        decision: { enum: [accept, reject] }
    OrganizationApplyRequest:
      type: object
      additionalProperties: false
      required: [decisions]
      properties:
        decisions:
          type: array
          maxItems: 30
          items: { $ref: '#/components/schemas/OrganizationDecision' }
    RecallTutorialCreateRequest:
      type: object
      additionalProperties: false
      required: [writeClient, recallClient]
      properties:
        writeClient: { $ref: '#/components/schemas/RecallTutorialClient' }
        recallClient: { $ref: '#/components/schemas/RecallTutorialClient' }
        environment: { enum: [native, wsl], default: native }
    RecallTutorialClient:
      enum: [codex, chatgpt-desktop, chatgpt-work, chatgpt-web, claude-code, claude-desktop, claude-cowork, cursor, cli]
    RecallTutorialCheckRequest:
      type: object
      additionalProperties: false
      properties:
        reportedFailure: { enum: [runtime, wiring, access, indexing, retrieval] }
    TagInput:
      type: object
      additionalProperties: false
      required: [slug, label]
      properties:
        slug: { type: string, pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$' }
        label: { type: string, minLength: 1, maxLength: 120 }
        description: { type: [string, 'null'], maxLength: 1000 }
        category: { type: [string, 'null'], maxLength: 120 }
        parentId: { type: [string, 'null'], format: uuid }
        color: { type: [string, 'null'], pattern: '^#[0-9A-Fa-f]{6}$' }
        metadata: { type: object, additionalProperties: true }
    TagUpdate:
      type: object
      additionalProperties: false
      properties:
        slug: { type: string, pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$' }
        label: { type: string, minLength: 1, maxLength: 120 }
        description: { type: [string, 'null'], maxLength: 1000 }
        category: { type: [string, 'null'], maxLength: 120 }
        parentId: { type: [string, 'null'], format: uuid }
        color: { type: [string, 'null'], pattern: '^#[0-9A-Fa-f]{6}$' }
        metadata: { type: object, additionalProperties: true }
    TagAssignment:
      type: object
      additionalProperties: false
      required: [contentIds]
      properties:
        contentIds:
          type: array
          minItems: 1
          maxItems: 500
          items: { type: string, format: uuid }
    LibraryFilter:
      type: object
      additionalProperties: false
      required: [conditions]
      properties:
        operator: { enum: [and, or], default: and }
        conditions:
          type: array
          minItems: 1
          maxItems: 25
          items:
            type: object
            additionalProperties: false
            required: [field, operator, value]
            properties:
              field:
                type: string
                description: content_type, source, created_at, tag, metadata.<key>, or analysis.<key>.
              operator: { enum: [eq, in, contains, gte, lte] }
              value:
                oneOf:
                  - { type: [string, number, boolean] }
                  - { type: array, minItems: 1, maxItems: 100, items: { type: [string, number, boolean] } }
    LibraryInput:
      type: object
      additionalProperties: false
      required: [name, slug]
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        slug: { type: string, pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$' }
        description: { type: [string, 'null'], maxLength: 2000 }
        filter:
          oneOf:
            - { $ref: '#/components/schemas/LibraryFilter' }
            - { type: 'null' }
        metadata: { type: object, additionalProperties: true }
    LibraryUpdate:
      type: object
      additionalProperties: false
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        slug: { type: string, pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$' }
        description: { type: [string, 'null'], maxLength: 2000 }
        filter:
          oneOf:
            - { $ref: '#/components/schemas/LibraryFilter' }
            - { type: 'null' }
        metadata: { type: object, additionalProperties: true }
    LibraryPreview:
      type: object
      additionalProperties: false
      properties:
        filter:
          oneOf:
            - { $ref: '#/components/schemas/LibraryFilter' }
            - { type: 'null' }
        limit: { type: integer, minimum: 1, maximum: 100, default: 25 }
    RecipeInput:
      type: object
      additionalProperties: false
      required: [name, contentTypes, systemPrompt, userPromptTemplate, outputType]
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        description: { type: [string, 'null'], maxLength: 2000 }
        contentTypes:
          type: array
          minItems: 1
          maxItems: 6
          items: { $ref: '#/components/schemas/ContentType' }
        systemPrompt: { type: string, minLength: 1, maxLength: 20000 }
        userPromptTemplate: { type: string, minLength: 1, maxLength: 20000 }
        outputType: { type: string, pattern: '^[a-z0-9]+(?:_[a-z0-9]+)*$' }
        outputSchema: { type: [object, 'null'], additionalProperties: true }
        modelId: { type: [string, 'null'], maxLength: 200 }
        maxTokens: { type: [integer, 'null'], minimum: 1, maximum: 32000 }
        isActive: { type: boolean, default: true }
    RecipeUpdate:
      type: object
      additionalProperties: false
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        description: { type: [string, 'null'], maxLength: 2000 }
        contentTypes:
          type: array
          minItems: 1
          maxItems: 6
          items: { $ref: '#/components/schemas/ContentType' }
        systemPrompt: { type: string, minLength: 1, maxLength: 20000 }
        userPromptTemplate: { type: string, minLength: 1, maxLength: 20000 }
        outputType: { type: string, pattern: '^[a-z0-9]+(?:_[a-z0-9]+)*$' }
        outputSchema: { type: [object, 'null'], additionalProperties: true }
        modelId: { type: [string, 'null'], maxLength: 200 }
        maxTokens: { type: [integer, 'null'], minimum: 1, maximum: 32000 }
        isActive: { type: boolean }
    RecipePreview:
      type: object
      additionalProperties: false
      properties:
        contentIds:
          type: array
          maxItems: 10
          items: { type: string, format: uuid }
        limit: { type: integer, minimum: 1, maximum: 10, default: 3 }
    ReportInput:
      type: object
      additionalProperties: false
      required: [title, slug, prompt]
      properties:
        title: { type: string, minLength: 1, maxLength: 300 }
        slug: { type: string, pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$' }
        description: { type: [string, 'null'], maxLength: 2000 }
        prompt: { type: string, minLength: 1, maxLength: 20000 }
        schedule: { type: [string, 'null'], maxLength: 200 }
        isActive: { type: boolean, default: true }
    ReportUpdate:
      type: object
      additionalProperties: false
      properties:
        title: { type: string, minLength: 1, maxLength: 300 }
        slug: { type: string, pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$' }
        description: { type: [string, 'null'], maxLength: 2000 }
        prompt: { type: string, minLength: 1, maxLength: 20000 }
        schedule: { type: [string, 'null'], maxLength: 200 }
        isActive: { type: boolean }
    DashboardInput:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        description: { type: [string, 'null'], maxLength: 2000 }
        layout: { type: array, maxItems: 100, items: { $ref: '#/components/schemas/DashboardLayout' }, default: [] }
        widgets: { type: array, maxItems: 100, items: { $ref: '#/components/schemas/DashboardWidget' }, default: [] }
    DashboardUpdate:
      type: object
      additionalProperties: false
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        description: { type: [string, 'null'], maxLength: 2000 }
        layout: { type: array, maxItems: 100, items: { $ref: '#/components/schemas/DashboardLayout' } }
        widgets: { type: array, maxItems: 100, items: { $ref: '#/components/schemas/DashboardWidget' } }
    DashboardLayout:
      type: object
      additionalProperties: false
      required: [widgetId, x, y, width, height]
      properties:
        widgetId: { type: string, format: uuid }
        x: { type: integer, minimum: 0, maximum: 11 }
        y: { type: integer, minimum: 0, maximum: 10000 }
        width: { type: integer, minimum: 1, maximum: 12 }
        height: { type: integer, minimum: 1, maximum: 100 }
    DashboardWidget:
      type: object
      additionalProperties: false
      required: [id, type, title, config]
      properties:
        id: { type: string, format: uuid }
        type: { enum: [metric, markdown, report, recent_content] }
        title: { type: string, minLength: 1, maxLength: 200 }
        config:
          type: object
          additionalProperties: false
          properties:
            value: { type: string, maxLength: 2000 }
            body: { type: string, maxLength: 50000 }
            reportId: { type: string, format: uuid }
            limit: { type: integer, minimum: 1, maximum: 100 }
    BatchJobInput:
      type: object
      additionalProperties: false
      required: [kind, name]
      properties:
        libraryId: { type: [string, 'null'], format: uuid }
        kind: { enum: [prompt, export, import] }
        name: { type: string, minLength: 1, maxLength: 200 }
        input: { type: object, additionalProperties: true, default: {} }
        contentIds:
          type: array
          maxItems: 10000
          items: { type: string, format: uuid }
    AccessTokenInput:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        description: { type: [string, 'null'], maxLength: 1000 }
        libraryId: { type: [string, 'null'], format: uuid }
        expiresAt: { type: [string, 'null'], format: date-time }
        capabilities:
          type: array
          description: Read authorizes retrieval endpoints; write authorizes mutations and does not implicitly grant read access.
          minItems: 1
          items: { enum: [read, write] }
          default: [read, write]
    AccessTokenUpdate:
      type: object
      additionalProperties: false
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        description: { type: [string, 'null'], maxLength: 1000 }
        expiresAt: { type: [string, 'null'], format: date-time }
    LocalSettingsUpdate:
      type: object
      additionalProperties: false
      properties:
        defaultPageSize: { type: integer, minimum: 10, maximum: 100 }
        defaultLibraryId: { type: [string, 'null'], format: uuid }
        density: { enum: [comfortable, compact] }
        defaultExportFormat: { enum: [json, csv, markdown] }
    BlobUpload:
      type: object
      additionalProperties: false
      required: [fileName, mediaType, dataBase64]
      properties:
        fileName: { type: string, minLength: 1, maxLength: 255 }
        mediaType: { type: string, minLength: 1, maxLength: 255 }
        dataBase64: { type: string, format: byte, minLength: 1, maxLength: 31457280 }
        sourceMetadata: { type: object, additionalProperties: true, default: {} }
    ImportRequest:
      type: object
      required: [items]
      properties:
        libraryId: { type: string }
        librarySlug: { type: string }
        items:
          type: array
          minItems: 1
          maxItems: 500
          items:
            type: object
            required: [title]
            properties:
              title: { type: string, maxLength: 500 }
              content: { type: string, maxLength: 5242880 }
              contentType: { $ref: '#/components/schemas/ContentType' }
              sourceIdentifier: { type: string, maxLength: 512 }
              source: { type: string, maxLength: 120 }
              sourceData: { type: object, additionalProperties: true }
              metadata: { type: object, additionalProperties: true }
              rawArchiveManifest: { type: object, additionalProperties: true }
              sourceAgentId: { type: string }
              conversationId: { type: string }
              turnIndex: { type: integer, minimum: 0 }
              turnRole:
                enum: [user, assistant, system, tool, developer, other]
              turnTimestamp: { type: string, format: date-time }
    QueryRequest:
      type: object
      required: [query]
      properties:
        query: { type: string, minLength: 1, maxLength: 2000 }
        searchType: { enum: [fulltext, semantic, hybrid], default: hybrid }
        libraryId: { type: string }
        librarySlug: { type: string }
        conversationId: { type: string }
        sourceAgentId: { type: string }
        include:
          type: array
          items: { enum: [summary, content, tags, metadata, artifacts, artifactBodies] }
        limit: { type: integer, minimum: 1, maximum: 50, default: 10 }
        filters:
          type: object
          properties:
            contentTypes:
              type: array
              items: { $ref: '#/components/schemas/ContentType' }
            tags: { type: array, items: { type: string } }
            dateFrom: { type: string, format: date-time }
            dateTo: { type: string, format: date-time }
            status: { enum: [active, archived] }
    RetrieveRequest:
      type: object
      description: Supply ids or conversationId.
      properties:
        ids:
          type: array
          minItems: 1
          maxItems: 50
          items: { type: string, format: uuid }
        conversationId: { type: string }
        sourceAgentId: { type: string }
        libraryId: { type: string }
        librarySlug: { type: string }
        include: { type: array, items: { type: string } }
    SummarizeRequest:
      type: object
      required: [prompt]
      properties:
        prompt: { type: string, minLength: 1, maxLength: 4000 }
        libraryId: { type: string }
        librarySlug: { type: string }
        limit: { type: integer, minimum: 1, maximum: 100, default: 20 }
    AskRequest:
      type: object
      required: [question]
      properties:
        question: { type: string, minLength: 3, maxLength: 4000 }
        contentIds:
          type: array
          maxItems: 50
          items: { type: string, format: uuid }
        libraryId: { type: string }
        librarySlug: { type: string }
        conversationId: { type: string }
        sourceAgentId: { type: string }
        retrievalMode: { enum: [fulltext, semantic, hybrid], default: hybrid }
        responseStyle: { enum: [cited, conversational], default: cited }
    ContentType:
      enum: [call, document, ticket, domain, chat, page]