Typesense Search API — Operations

naftiko: 1.0.0-alpha2
info:
  label: Typesense Search API — Operations
  description: 'Typesense Search API — Operations. 5 operations. Lead operation: Clear The LRU Cache. Self-contained Naftiko
    capability covering one Typesense business surface.'
  tags:
  - Typesense
  - Operations
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    TYPESENSE_API_KEY: TYPESENSE_API_KEY
capability:
  consumes:
  - type: http
    namespace: search-operations
    baseUri: ''
    description: Typesense Search API — Operations business capability. Self-contained, no shared references.
    resources:
    - name: operations-cache-clear
      path: /operations/cache/clear
      operations:
      - name: clearcache
        method: POST
        description: Clear The LRU Cache
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: operations-db-compact
      path: /operations/db/compact
      operations:
      - name: compactdatabase
        method: POST
        description: Compact The On-disk Database
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: operations-schema_changes
      path: /operations/schema_changes
      operations:
      - name: getschemachanges
        method: GET
        description: Get Schema Change Status
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: operations-snapshot
      path: /operations/snapshot
      operations:
      - name: takesnapshot
        method: POST
        description: Create A Point-in-time Snapshot
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: snapshot_path
          in: query
          type: string
          description: Absolute filesystem path where the snapshot will be stored.
          required: true
    - name: operations-vote
      path: /operations/vote
      operations:
      - name: vote
        method: POST
        description: Trigger Raft Voting
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    authentication:
      type: apikey
      key: X-TYPESENSE-API-KEY
      value: '{{env.TYPESENSE_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: search-operations-rest
    port: 8080
    description: REST adapter for Typesense Search API — Operations. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/operations/cache/clear
      name: operations-cache-clear
      description: REST surface for operations-cache-clear.
      operations:
      - method: POST
        name: clearcache
        description: Clear The LRU Cache
        call: search-operations.clearcache
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/operations/db/compact
      name: operations-db-compact
      description: REST surface for operations-db-compact.
      operations:
      - method: POST
        name: compactdatabase
        description: Compact The On-disk Database
        call: search-operations.compactdatabase
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/operations/schema-changes
      name: operations-schema-changes
      description: REST surface for operations-schema_changes.
      operations:
      - method: GET
        name: getschemachanges
        description: Get Schema Change Status
        call: search-operations.getschemachanges
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/operations/snapshot
      name: operations-snapshot
      description: REST surface for operations-snapshot.
      operations:
      - method: POST
        name: takesnapshot
        description: Create A Point-in-time Snapshot
        call: search-operations.takesnapshot
        with:
          snapshot_path: rest.snapshot_path
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/operations/vote
      name: operations-vote
      description: REST surface for operations-vote.
      operations:
      - method: POST
        name: vote
        description: Trigger Raft Voting
        call: search-operations.vote
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: search-operations-mcp
    port: 9090
    transport: http
    description: MCP adapter for Typesense Search API — Operations. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: clear-lru-cache
      description: Clear The LRU Cache
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: search-operations.clearcache
      outputParameters:
      - type: object
        mapping: $.
    - name: compact-disk-database
      description: Compact The On-disk Database
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: search-operations.compactdatabase
      outputParameters:
      - type: object
        mapping: $.
    - name: get-schema-change-status
      description: Get Schema Change Status
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: search-operations.getschemachanges
      outputParameters:
      - type: object
        mapping: $.
    - name: create-point-time-snapshot
      description: Create A Point-in-time Snapshot
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: search-operations.takesnapshot
      with:
        snapshot_path: tools.snapshot_path
      outputParameters:
      - type: object
        mapping: $.
    - name: trigger-raft-voting
      description: Trigger Raft Voting
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: search-operations.vote
      outputParameters:
      - type: object
        mapping: $.