schemes:
  - http
  - https
swagger: '2.0'
info:
  description: >-
    REST API gateway for MatsuDB services providing document intelligence with
    vector search
  title: MatsuDB REST API
  contact: {}
basePath: /
paths:
  /v1/corpus:
    get:
      security:
        - BearerAuth: []
      description: Get a list of all corpus documents in the namespace
      produces:
        - application/json
      tags:
        - Corpus
      summary: List all corpus documents
      parameters:
        - type: integer
          default: 20
          description: Page size
          name: page_size
          in: query
        - type: string
          description: Page token for pagination
          name: page_token
          in: query
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.ListCorporaResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
    post:
      security:
        - BearerAuth: []
      description: >-
        Upload a document to create a new corpus. Optimized for large file
        streaming.
      consumes:
        - multipart/form-data
      produces:
        - application/json
      tags:
        - Corpus
      summary: Upload a new corpus document
      parameters:
        - type: file
          description: Document file to upload
          name: file
          in: formData
          required: true
        - type: string
          description: Original filename (optional, inferred from file if not provided)
          name: original_name
          in: formData
        - type: string
          description: Custom storage key (optional, auto-generated if not provided)
          name: key
          in: formData
        - type: string
          description: MIME type (optional, inferred if not provided)
          name: mime_type
          in: formData
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/responses.CreateCorpusResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '413':
          description: Request Entity Too Large
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '422':
          description: Unprocessable Entity
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/corpus/{corpus_id}:
    get:
      security:
        - BearerAuth: []
      description: Get details of a specific corpus document by its ID
      produces:
        - application/json
      tags:
        - Corpus
      summary: Get corpus document by ID
      parameters:
        - type: string
          description: Corpus ID
          name: corpus_id
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.GetCorpusResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/corpus/{corpus_id}/reindex:
    post:
      security:
        - BearerAuth: []
      description: Triggers a forced reindexation of the specified corpus document
      produces:
        - application/json
      tags:
        - Corpus
      summary: Force reindexation of a corpus
      parameters:
        - type: string
          description: Corpus ID
          name: corpus_id
          in: path
          required: true
      responses:
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/responses.ForceReindexResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/nodes:
    get:
      security:
        - BearerAuth: []
      description: Get a list of child nodes for a given root node (e.g. a corpus)
      produces:
        - application/json
      tags:
        - Nodes
      summary: List child nodes
      parameters:
        - type: string
          description: Root Node ID (e.g. a corpus id)
          name: root_node_id
          in: query
          required: true
        - type: integer
          default: 20
          description: Page size
          name: page_size
          in: query
        - type: string
          description: Page token for pagination
          name: page_token
          in: query
        - type: string
          description: Comma-separated list of node types to filter
          name: node_types
          in: query
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.ListNodesResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/nodes/{node_id}:
    get:
      security:
        - BearerAuth: []
      description: Get details of a specific node by its ID
      produces:
        - application/json
      tags:
        - Nodes
      summary: Get a node by ID
      parameters:
        - type: string
          description: Node ID
          name: node_id
          in: path
          required: true
        - type: string
          description: Root Node ID (e.g. a corpus id)
          name: root_node_id
          in: query
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.GetNodeResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/rules:
    get:
      security:
        - BearerAuth: []
      description: List all rules for the current namespace
      produces:
        - application/json
      tags:
        - Rules
      summary: List rules
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.ListRulesResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
    put:
      security:
        - BearerAuth: []
      description: Create or update a rule for a specific trigger
      consumes:
        - application/json
      produces:
        - application/json
      tags:
        - Rules
      summary: Create or update a rule
      parameters:
        - description: Rule upsert request
          name: request
          in: body
          required: true
          schema:
            $ref: '#/definitions/requests.UpsertRuleRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.UpsertRuleResponse'
        '201':
          description: Created
          schema:
            $ref: '#/definitions/responses.UpsertRuleResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/rules/{trigger_id}:
    get:
      security:
        - BearerAuth: []
      description: Get a specific rule by trigger ID
      produces:
        - application/json
      tags:
        - Rules
      summary: Get a rule
      parameters:
        - type: string
          description: Trigger ID
          name: trigger_id
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.GetRuleResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
    delete:
      security:
        - BearerAuth: []
      description: Delete a rule by trigger ID
      produces:
        - application/json
      tags:
        - Rules
      summary: Delete a rule
      parameters:
        - type: string
          description: Trigger ID
          name: trigger_id
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.DeleteRuleResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/search/dense:
    post:
      security:
        - BearerAuth: []
      description: >-
        Search nodes using semantic text search (auto-generates dense
        embeddings)
      consumes:
        - application/json
      produces:
        - application/json
      tags:
        - Search
      summary: Perform dense vector search from text
      parameters:
        - description: Dense search request
          name: request
          in: body
          required: true
          schema:
            $ref: '#/definitions/requests.DenseSearchRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.SearchResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/search/exact:
    post:
      security:
        - BearerAuth: []
      description: Search nodes using exact text matching (ILIKE)
      consumes:
        - application/json
      produces:
        - application/json
      tags:
        - Search
      summary: Perform exact text search
      parameters:
        - description: Exact search request
          name: request
          in: body
          required: true
          schema:
            $ref: '#/definitions/requests.ExactSearchRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.SearchResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/search/sparse:
    post:
      security:
        - BearerAuth: []
      description: >-
        Search nodes using text search with sparse embeddings (auto-generates
        sparse vectors)
      consumes:
        - application/json
      produces:
        - application/json
      tags:
        - Search
      summary: Perform sparse vector search from text
      parameters:
        - description: Sparse search request
          name: request
          in: body
          required: true
          schema:
            $ref: '#/definitions/requests.SparseSearchRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.SearchResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/triggers:
    get:
      security:
        - BearerAuth: []
      description: List all available triggers that can be configured
      produces:
        - application/json
      tags:
        - Rules
      summary: List available triggers
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.ListTriggersResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
  /v1/triggers/{trigger_id}/schema:
    get:
      security:
        - BearerAuth: []
      description: Get detailed schema information for a specific trigger
      produces:
        - application/json
      tags:
        - Rules
      summary: Get trigger schema
      parameters:
        - type: string
          description: Trigger ID
          name: trigger_id
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/responses.GetTriggerSchemaResponse'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/matsuerrors.HTTPResponse'
definitions:
  requests.DenseSearchRequest:
    description: Request to perform semantic text search (auto-generates dense embeddings).
    type: object
    required:
      - query_text
    properties:
      min_similarity:
        description: Minimum similarity threshold (0.0 to 1.0)
        type: number
        maximum: 1
        minimum: 0
        example: 0.7
      node_types:
        description: Node types to filter by
        type: array
        items:
          type: string
      query_text:
        description: Text query to convert to dense embeddings
        type: string
        example: What is machine learning?
      root_node_ids:
        description: Root node IDs to search within (as strings)
        type: array
        items:
          type: string
      similarity_metric:
        description: >-
          Similarity metric to use (cosine, inner_product, l2). Defaults to
          inner_product
        type: string
        enum:
          - cosine
          - inner_product
          - l2
        example: inner_product
      top_k:
        description: Maximum number of results to return
        type: integer
        minimum: 1
        example: 10
  requests.ExactSearchRequest:
    description: Request to perform exact text matching (ILIKE).
    type: object
    required:
      - query
    properties:
      node_types:
        description: Node types to filter by
        type: array
        items:
          type: string
      query:
        description: Text query for exact matching
        type: string
        example: search term
      root_node_ids:
        description: Root node IDs to search within (as strings)
        type: array
        items:
          type: string
  requests.SparseSearchRequest:
    description: >-
      Request to perform text search with sparse embeddings (auto-generates
      sparse vectors).
    type: object
    required:
      - query_text
    properties:
      min_similarity:
        description: Minimum similarity threshold (0.0 to 1.0)
        type: number
        maximum: 1
        minimum: 0
        example: 0.5
      node_types:
        description: Node types to filter by
        type: array
        items:
          type: string
      query_text:
        description: Text query to convert to sparse embeddings
        type: string
        example: machine learning algorithms
      root_node_ids:
        description: Root node IDs to search within (as strings)
        type: array
        items:
          type: string
      similarity_metric:
        description: >-
          Similarity metric to use (cosine, inner_product, l2). Defaults to
          inner_product
        type: string
        enum:
          - cosine
          - inner_product
          - l2
        example: inner_product
      top_k:
        description: Maximum number of results to return
        type: integer
        minimum: 1
        example: 10
  requests.UpsertRuleRequest:
    description: Request to create or update a rule for a specific trigger.
    type: object
    required:
      - filters
      - trigger_id
    properties:
      filters:
        description: Filter configuration as JSON object
        type: array
        items:
          type: integer
      trigger_id:
        description: Trigger ID to configure
        type: string
        example: corpus_parsing
  responses.Corpus:
    description: Corpus document information.
    type: object
    properties:
      blob_uri:
        description: URI to the blob storage location
        type: string
        example: s3://bucket/key
      corpus_checksum:
        description: Checksum of the corpus blob
        type: string
        example: 7cc1b5cf8a72caa6fc7f6f8aa984f4f834b4b1dc6db2d13ba6be4ad837398a62
      corpus_id:
        description: Corpus ID (same as node_id) as string
        type: string
        example: '12345'
      created_at:
        description: Creation timestamp (ISO 8601 format)
        type: string
        example: '2025-01-01T12:00:00Z'
      indexation_status:
        description: 'Indexation status: pending, processing, completed, failed'
        type: string
        example: completed
      mime_type:
        description: MIME type of the document (extracted from classifications)
        type: string
        example: application/pdf
      original_name:
        description: Original filename of the uploaded document
        type: string
        example: document.pdf
  responses.CreateCorpusResponse:
    description: Response after successfully creating a corpus.
    type: object
    properties:
      corpus:
        description: The corpus data
        allOf:
          - $ref: '#/definitions/responses.Corpus'
      ok:
        description: Indicates if the corpus was created successfully
        type: boolean
        example: true
  responses.DeleteRuleResponse:
    description: Response after successfully deleting a rule.
    type: object
    properties:
      success:
        description: Indicates if the deletion was successful
        type: boolean
        example: true
  responses.ForceReindexResponse:
    description: Response after triggering a force reindexation.
    type: object
    properties:
      corpus_id:
        description: The corpus ID being reindexed
        type: string
        example: '12345'
      message:
        description: Human-readable message
        type: string
        example: Reindexation triggered successfully
      status:
        description: Current status of the reindexation
        type: string
        example: pending
      success:
        description: Indicates if the reindexation was triggered successfully
        type: boolean
        example: true
  responses.GetCorpusResponse:
    description: Response containing a single corpus node.
    type: object
    properties:
      corpus:
        description: The corpus data
        allOf:
          - $ref: '#/definitions/responses.Corpus'
  responses.GetNodeResponse:
    description: Response containing a single node.
    type: object
    properties:
      node:
        description: The node data
        allOf:
          - $ref: '#/definitions/responses.Node'
  responses.GetRuleResponse:
    description: Response containing a single rule.
    type: object
    properties:
      rule:
        description: The rule data
        allOf:
          - $ref: '#/definitions/responses.Rule'
  responses.GetTriggerSchemaResponse:
    description: Response containing schema information for a trigger.
    type: object
    properties:
      schema:
        description: The trigger schema
        allOf:
          - $ref: '#/definitions/responses.TriggerInfo'
  responses.ListCorporaResponse:
    description: Response containing a list of corpus nodes with pagination.
    type: object
    properties:
      corpora:
        description: List of corpus documents
        type: array
        items:
          $ref: '#/definitions/responses.Corpus'
      next_page_token:
        description: Token for pagination to get the next page
        type: string
        example: eyJwYWdlIjoxfQ==
      total_count:
        description: Total count of corpora matching the filter
        type: integer
        example: 42
  responses.ListNodesResponse:
    description: Response containing a list of nodes with pagination.
    type: object
    properties:
      next_page_token:
        description: Token for pagination to get the next page
        type: string
        example: eyJwYWdlIjoxfQ==
      nodes:
        description: List of nodes
        type: array
        items:
          $ref: '#/definitions/responses.Node'
      total_count:
        description: Total count of nodes matching the filter
        type: integer
        example: 42
  responses.ListRulesResponse:
    description: Response containing a list of rules.
    type: object
    properties:
      rules:
        description: List of rules
        type: array
        items:
          $ref: '#/definitions/responses.Rule'
  responses.ListTriggersResponse:
    description: Response containing a list of available triggers.
    type: object
    properties:
      triggers:
        description: List of available triggers
        type: array
        items:
          $ref: '#/definitions/responses.TriggerInfo'
  responses.MatsuPosition:
    type: object
    properties:
      path:
        description: Position path as string (converted from []int32, e.g., "1,2,3")
        type: string
        example: 1,2,3
      payload:
        description: Position geometry payload (WKT or original format)
        type: string
        example: (x0,y0,x1,y1)
      position_type:
        description: Position type name
        type: string
        example: bbox
  responses.Node:
    description: Node information with string IDs.
    type: object
    properties:
      blob_checksum:
        description: Blob checksum
        type: string
        example: 7cc1b5cf8a72caa6fc7f6f8aa984f4f834b4b1dc6db2d13ba6be4ad837398a62
      blob_uri:
        description: Blob URI
        type: string
        example: s3://bucket/key
      classifications:
        description: Array of classification strings
        type: array
        items:
          type: string
        example:
          - '[application/pdf]'
      created_at:
        description: Creation timestamp (ISO 8601 format)
        type: string
        example: '2025-01-01T12:00:00Z'
      hierarchical_path:
        description: Hierarchical path (ltree)
        type: string
        example: 1.2.3
      metadata:
        description: Metadata
        type: object
        additionalProperties: true
      namespace_id:
        description: Namespace ID
        type: string
        example: namespace-123
      next_node_id:
        description: Next node ID as string
        type: string
        example: '12346'
      node_id:
        description: Node ID as string
        type: string
        example: '12345'
      node_type:
        description: Node type (e.g., 'CORPUS', 'ARTIFACT', 'TEXT', 'IMAGE')
        type: string
        example: TEXT
      parent_node_id:
        description: Parent node ID as string
        type: string
        example: '12344'
      positions:
        description: Positions
        type: array
        items:
          $ref: '#/definitions/responses.MatsuPosition'
      root_node_id:
        description: Root node ID as string
        type: string
        example: '12345'
      sparse_vec:
        description: Sparse vector embedding as string
        type: string
        example: '{0:0.5,1:0.3}/250002'
      tags:
        description: Tags (e.g., ["important", "document"])
        type: array
        items:
          type: string
      text_content:
        description: Text content
        type: string
        example: Document content
      text_hash:
        description: Text hash
        type: string
        example: abc123
      token_count:
        description: Token count
        type: integer
        example: 1000
      vec:
        description: Dense vector embedding (array of float32, e.g., [0.1, 0.2, 0.3])
        type: array
        items:
          type: number
  responses.Rule:
    description: Rule information.
    type: object
    properties:
      filters:
        description: Filter configuration specific to the trigger (FilterConfig)
        type: array
        items:
          type: integer
      namespace_id:
        description: Namespace to which this rule applies
        type: string
        example: my-namespace
      trigger_id:
        description: ID of the trigger that will execute this rule
        type: string
        example: corpus_parsing
      updated_at:
        description: Timestamp of last update (ISO 8601 format)
        type: string
        example: '2025-01-01T12:00:00Z'
  responses.SearchResponse:
    description: Response containing search results with scored nodes.
    type: object
    properties:
      results:
        description: List of search results with scores
        type: array
        items:
          $ref: '#/definitions/responses.SearchResult'
      total_count:
        description: Total number of results found
        type: integer
        example: 42
  responses.SearchResult:
    type: object
    properties:
      node:
        description: The matched node
        allOf:
          - $ref: '#/definitions/responses.Node'
      score:
        description: Similarity score for this result
        type: number
        example: 0.95
  responses.TriggerInfo:
    description: Trigger information.
    type: object
    properties:
      filter_config_type:
        description: |-
          Full name of the FilterConfig protobuf message type
          Example: "matsu.rules.v1.CorpusParsingFilterConfig"
        type: string
        example: matsu.rules.v1.CorpusParsingFilterConfig
      trigger_id:
        description: Unique identifier of the trigger
        type: string
        example: corpus_parsing
  responses.UpsertRuleResponse:
    description: Response after successfully creating or updating a rule.
    type: object
    properties:
      created:
        description: Indicates if the rule was created (true) or updated (false)
        type: boolean
        example: true
      updated:
        description: Indicates if the rule was updated (true) or created (false)
        type: boolean
        example: false
  matsuerrors.HTTPResponse:
    type: object
    properties:
      detail:
        type: string
      errors:
        type: array
        items:
          $ref: '#/definitions/matsuerrors.ValidationErrorJSON'
      extensions:
        type: object
        additionalProperties: true
      instance:
        type: string
      retryInfo:
        $ref: '#/definitions/matsuerrors.RetryInfoJSON'
      status:
        type: integer
      timestamp:
        type: string
      title:
        type: string
      traceId:
        type: string
      type:
        type: string
  matsuerrors.RetryInfoJSON:
    type: object
    properties:
      backoffMs:
        type: integer
      backoffType:
        type: string
      maxRetries:
        type: integer
      retryAfterMs:
        type: integer
      retryable:
        type: boolean
  matsuerrors.ValidationErrorJSON:
    type: object
    properties:
      code:
        type: string
      constraint:
        type: string
      field:
        type: string
      message:
        type: string
securityDefinitions:
  BearerAuth:
    type: apiKey
    name: Authorization
    in: header
    description: >-
      Bearer token authentication. The namespace context is encapsulated within
      the security token.
