Skip to main content
API docs by Redocly

MatsuDB REST API

Download OpenAPI specification:Download

REST API gateway for MatsuDB services providing document intelligence with vector search

Corpus

List all corpus documents

Get a list of all corpus documents in the namespace

Authorizations:
BearerAuth
query Parameters
page_size
integer
Default: 20

Page size

page_token
string

Page token for pagination

Responses

Response samples

Content type
application/json
{
  • "corpora": [
    ],
  • "next_page_token": "eyJwYWdlIjoxfQ==",
  • "total_count": 42
}

Upload a new corpus document

Upload a document to create a new corpus. Optimized for large file streaming.

Authorizations:
BearerAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

Document file to upload

original_name
string

Original filename (optional, inferred from file if not provided)

key
string

Custom storage key (optional, auto-generated if not provided)

mime_type
string

MIME type (optional, inferred if not provided)

Responses

Response samples

Content type
application/json
{
  • "corpus": {
    },
  • "ok": true
}

Get corpus document by ID

Get details of a specific corpus document by its ID

Authorizations:
BearerAuth
path Parameters
corpus_id
required
string

Corpus ID

Responses

Response samples

Content type
application/json
{
  • "corpus": {
    }
}

Force reindexation of a corpus

Triggers a forced reindexation of the specified corpus document

Authorizations:
BearerAuth
path Parameters
corpus_id
required
string

Corpus ID

Responses

Response samples

Content type
application/json
{
  • "corpus_id": "12345",
  • "message": "Reindexation triggered successfully",
  • "status": "pending",
  • "success": true
}

Nodes

List child nodes

Get a list of child nodes for a given root node (e.g. a corpus)

Authorizations:
BearerAuth
query Parameters
root_node_id
required
string

Root Node ID (e.g. a corpus id)

page_size
integer
Default: 20

Page size

page_token
string

Page token for pagination

node_types
string

Comma-separated list of node types to filter

Responses

Response samples

Content type
application/json
{
  • "next_page_token": "eyJwYWdlIjoxfQ==",
  • "nodes": [
    ],
  • "total_count": 42
}

Get a node by ID

Get details of a specific node by its ID

Authorizations:
BearerAuth
path Parameters
node_id
required
string

Node ID

query Parameters
root_node_id
required
string

Root Node ID (e.g. a corpus id)

Responses

Response samples

Content type
application/json
{
  • "node": {
    }
}

Rules

List rules

List all rules for the current namespace

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ]
}

Create or update a rule

Create or update a rule for a specific trigger

Authorizations:
BearerAuth
Request Body schema: application/json
required

Rule upsert request

filters
required
Array of integers

Filter configuration as JSON object

trigger_id
required
string

Trigger ID to configure

Responses

Request samples

Content type
application/json
{
  • "filters": [
    ],
  • "trigger_id": "corpus_parsing"
}

Response samples

Content type
application/json
{
  • "created": true,
  • "updated": false
}

Get a rule

Get a specific rule by trigger ID

Authorizations:
BearerAuth
path Parameters
trigger_id
required
string

Trigger ID

Responses

Response samples

Content type
application/json
{
  • "rule": {
    }
}

Delete a rule

Delete a rule by trigger ID

Authorizations:
BearerAuth
path Parameters
trigger_id
required
string

Trigger ID

Responses

Response samples

Content type
application/json
{
  • "success": true
}

List available triggers

List all available triggers that can be configured

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "triggers": [
    ]
}

Get trigger schema

Get detailed schema information for a specific trigger

Authorizations:
BearerAuth
path Parameters
trigger_id
required
string

Trigger ID

Responses

Response samples

Content type
application/json
{
  • "schema": {
    }
}

Search

Perform dense vector search from text

Search nodes using semantic text search (auto-generates dense embeddings)

Authorizations:
BearerAuth
Request Body schema: application/json
required

Dense search request

min_similarity
number [ 0 .. 1 ]

Minimum similarity threshold (0.0 to 1.0)

node_types
Array of strings

Node types to filter by

query_text
required
string

Text query to convert to dense embeddings

root_node_ids
Array of strings

Root node IDs to search within (as strings)

similarity_metric
string
Enum: "cosine" "inner_product" "l2"

Similarity metric to use (cosine, inner_product, l2). Defaults to inner_product

top_k
integer >= 1

Maximum number of results to return

Responses

Request samples

Content type
application/json
{
  • "min_similarity": 0.7,
  • "node_types": [
    ],
  • "query_text": "What is machine learning?",
  • "root_node_ids": [
    ],
  • "similarity_metric": "inner_product",
  • "top_k": 10
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total_count": 42
}

Perform exact text search

Search nodes using exact text matching (ILIKE)

Authorizations:
BearerAuth
Request Body schema: application/json
required

Exact search request

node_types
Array of strings

Node types to filter by

query
required
string

Text query for exact matching

root_node_ids
Array of strings

Root node IDs to search within (as strings)

Responses

Request samples

Content type
application/json
{
  • "node_types": [
    ],
  • "query": "search term",
  • "root_node_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total_count": 42
}

Perform sparse vector search from text

Search nodes using text search with sparse embeddings (auto-generates sparse vectors)

Authorizations:
BearerAuth
Request Body schema: application/json
required

Sparse search request

min_similarity
number [ 0 .. 1 ]

Minimum similarity threshold (0.0 to 1.0)

node_types
Array of strings

Node types to filter by

query_text
required
string

Text query to convert to sparse embeddings

root_node_ids
Array of strings

Root node IDs to search within (as strings)

similarity_metric
string
Enum: "cosine" "inner_product" "l2"

Similarity metric to use (cosine, inner_product, l2). Defaults to inner_product

top_k
integer >= 1

Maximum number of results to return

Responses

Request samples

Content type
application/json
{
  • "min_similarity": 0.5,
  • "node_types": [
    ],
  • "query_text": "machine learning algorithms",
  • "root_node_ids": [
    ],
  • "similarity_metric": "inner_product",
  • "top_k": 10
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total_count": 42
}