API Reference

REST API endpoints for programmatic access to Teidelum.

Overview

Teidelum exposes a REST API at /api/v1/ when started with the --port flag. All requests and responses use JSON.

./teidelum --port 8080

The base URL for all endpoints is http://localhost:8080/api/v1/. All request bodies must be sent as Content-Type: application/json.

Authentication

Authentication is optional. To enable it, set the TEIDELUM_API_KEY environment variable before starting the server:

TEIDELUM_API_KEY=your-secret-key ./teidelum --port 8080

When set, all requests must include a Bearer token in the Authorization header:

Authorization: Bearer your-secret-key

If the API key is not set, all requests are accepted without authentication.

Tables

Create Table

POST /api/v1/tables

Create a new table with a defined schema.

Request body:

{
  "name": "employees",
  "columns": [
    { "name": "id", "type": "integer" },
    { "name": "name", "type": "string" },
    { "name": "department", "type": "string" },
    { "name": "start_date", "type": "string" }
  ]
}

Response: 201 Created

{
  "status": "ok",
  "table": "employees"
}

Insert Rows

POST /api/v1/tables/:name/rows

Insert one or more rows into an existing table.

Request body:

{
  "rows": [
    { "id": 1, "name": "Alice Chen", "department": "Engineering", "start_date": "2023-01-15" },
    { "id": 2, "name": "Bob Smith", "department": "Product", "start_date": "2023-03-01" }
  ]
}

Response: 200 OK

{
  "status": "ok",
  "inserted": 2
}

Delete Table

DELETE /api/v1/tables/:name

Delete a table and all its data.

Response: 200 OK

{
  "status": "ok",
  "table": "employees"
}

Documents

Add Document

POST /api/v1/documents

Add a document to the full-text search index.

Request body:

{
  "id": "doc-001",
  "title": "Deployment Runbook",
  "body": "Step 1: Pull latest from main. Step 2: Run migrations...",
  "source": "wiki",
  "url": "https://wiki.example.com/deploy"
}

Response: 201 Created

{
  "status": "ok",
  "id": "doc-001"
}

Delete Document

DELETE /api/v1/documents/:id

Remove a document from the search index.

Response: 200 OK

{
  "status": "ok",
  "id": "doc-001"
}

Search

POST /api/v1/search

Full-text search across all indexed documents.

Request body:

{
  "query": "JWT token rotation",
  "sources": ["notion"],
  "limit": 5
}

Response: 200 OK

{
  "results": [
    {
      "id": "page-auth-v2",
      "title": "Auth Service v2 — Token Rotation",
      "snippet": "...implements automatic JWT token rotation with a 15-minute refresh window...",
      "source": "notion",
      "score": 8.42,
      "url": "https://notion.so/page-auth-v2"
    }
  ],
  "total": 1
}

SQL

POST /api/v1/sql

Run analytical SQL queries over structured data from all sources.

Request body:

{
  "query": "SELECT assignee, COUNT(*) as task_count FROM project_tasks WHERE status = 'in_progress' GROUP BY assignee ORDER BY task_count DESC"
}

Response: 200 OK

{
  "columns": ["assignee", "task_count"],
  "rows": [
    ["Alice Chen", 5],
    ["Bob Smith", 3],
    ["Carol Davis", 2]
  ],
  "row_count": 3
}

Graph

Neighbors

POST /api/v1/graph/neighbors

Discover entities connected to a starting node via foreign-key relationships.

Request body:

{
  "table": "team_members",
  "key": "Alice Chen",
  "key_col": "name",
  "depth": 2,
  "direction": "both"
}

Response: 200 OK

{
  "origin": { "table": "team_members", "key": "Alice Chen" },
  "neighbors": [
    {
      "table": "project_tasks",
      "key": "Implement JWT rotation",
      "depth": 1,
      "relationship": "assigned_to"
    },
    {
      "table": "incidents",
      "key": "API Gateway Timeout",
      "depth": 2,
      "relationship": "reported_by"
    }
  ],
  "total": 2
}

Path

POST /api/v1/graph/path

Find the shortest path between two entities through foreign-key relationships.

Request body:

{
  "table": "team_members",
  "key": "Alice Chen",
  "to_table": "incidents",
  "to_key": "API Gateway Timeout",
  "depth": 4
}

Response: 200 OK

{
  "path": [
    { "table": "team_members", "key": "Alice Chen" },
    { "table": "project_tasks", "key": "Implement JWT rotation", "relationship": "assigned_to" },
    { "table": "incidents", "key": "API Gateway Timeout", "relationship": "related_task" }
  ],
  "length": 2
}

Relationships

POST /api/v1/relationships

Request body:

{
  "from_table": "project_tasks",
  "from_column": "assignee",
  "to_table": "team_members",
  "to_column": "name",
  "rel_type": "assigned_to"
}

Response: 201 Created

{
  "status": "ok",
  "relationship": {
    "from": "project_tasks.assignee",
    "to": "team_members.name",
    "type": "assigned_to"
  }
}

Describe

List All Sources

GET /api/v1/describe

Returns the complete catalog: all tables, their columns and types, and all registered foreign-key relationships.

Response: 200 OK

{
  "tables": [
    {
      "name": "team_members",
      "source": "local",
      "columns": [
        { "name": "name", "type": "string" },
        { "name": "role", "type": "string" },
        { "name": "team", "type": "string" }
      ]
    },
    {
      "name": "project_tasks",
      "source": "local",
      "columns": [
        { "name": "name", "type": "string" },
        { "name": "status", "type": "string" },
        { "name": "assignee", "type": "string" }
      ]
    }
  ],
  "relationships": [
    {
      "from": "project_tasks.assignee",
      "to": "team_members.name",
      "type": "assigned_to"
    }
  ]
}

Describe Single Source

GET /api/v1/describe/:source

Returns catalog information filtered to a specific source.

Response: 200 OK

{
  "tables": [
    {
      "name": "team_members",
      "source": "local",
      "columns": [
        { "name": "name", "type": "string" },
        { "name": "role", "type": "string" },
        { "name": "team", "type": "string" }
      ]
    }
  ],
  "relationships": []
}

Error Responses

All errors return a JSON object with an error field and an appropriate HTTP status code.

400 Bad Request

Returned when the request body is malformed or a required parameter is missing.

{
  "error": "missing required field: query"
}

401 Unauthorized

Returned when TEIDELUM_API_KEY is set but the request has a missing or invalid Bearer token.

{
  "error": "unauthorized: invalid or missing API key"
}

500 Internal Server Error

Returned when an unexpected error occurs during processing.

{
  "error": "internal error: failed to execute query"
}