ASTROLABE

API Reference

REST API endpoints for the Astrolabe backend server.

Astrolabe's Python backend exposes a FastAPI server with REST endpoints for project management, graph analysis, and real-time updates.

Base URL

http://localhost:8765/api

Health & Initialization

Health Check

GET /api/health

Returns server status.

Load Project

POST /api/project/load

Load a Lean 4 project from a directory path.

Body:

{
  "path": "/path/to/lean/project"
}

Initialize Project

POST /api/project/init

Initialize a new project configuration.

Project Data

Get Project

GET /api/project

Returns the full project graph with nodes and edges.

Refresh Project

POST /api/project/refresh

Re-parse project files and rebuild the graph.

Project Statistics

GET /api/project/stats

Returns node/edge counts, type distributions, and graph metrics.

Project Status

GET /api/project/status

Check if a project is loaded and its current state.

Node Operations

Get Node

GET /api/project/node/{node_id}

Returns details for a specific node including metadata.

Get Node Dependencies

GET /api/project/node/{node_id}/deps

Returns all nodes this node depends on.

Update Node Metadata

PATCH /api/project/node/{node_id}/meta

Body:

{
  "key": "value"
}

Delete Node Metadata

DELETE /api/project/node/{node_id}/meta

Custom User Nodes

POST /api/project/user-node     # Create
GET /api/project/user-nodes     # List all
PATCH /api/project/user-node/{node_id}  # Update
DELETE /api/project/user-node/{node_id}  # Delete

Edge Operations

Update Edge Metadata

PATCH /api/project/edge/{edge_id}/meta

Delete Edge Metadata

DELETE /api/project/edge/{edge_id}/meta

Custom User Edges

POST /api/project/user-edge     # Create
GET /api/project/user-edges     # List all
DELETE /api/project/user-edge/{edge_id}  # Delete

Search & Navigation

Search Nodes

GET /api/project/search?q={query}

Fuzzy search by node name.

List Namespaces

GET /api/project/namespaces

Returns all namespaces in the project.

Namespace Declaration

GET /api/project/namespace-declaration?ns={namespace}

Get the declaration for a specific namespace.

Namespace Index

GET /api/project/namespace-index
POST /api/project/namespace-index/build

Get or rebuild the namespace index.

Canvas Operations

Get Canvas

GET /api/canvas

Returns current canvas state (visible nodes, positions).

Save Canvas

POST /api/canvas

Save the current canvas configuration.

Canvas Modifications

POST /api/canvas/add          # Add single node
POST /api/canvas/add-batch    # Add multiple nodes
POST /api/canvas/remove       # Remove node
POST /api/canvas/positions    # Update positions
POST /api/canvas/clear        # Clear all

Viewport

GET /api/canvas/viewport      # Get camera state
PATCH /api/canvas/viewport    # Update camera

File Operations

Read File

GET /api/file?path={filepath}

Read source file contents.

Position Persistence

Save Positions

POST /api/project/positions

Body:

{
  "positions": {
    "node_id": { "x": 0, "y": 0, "z": 0 }
  }
}

Analysis Endpoints

All analysis endpoints return computed metrics for the loaded project.

Basic Statistics

GET /api/project/analysis/degree         # Degree distribution
GET /api/project/analysis/statistics     # Overall stats
GET /api/project/analysis/dag            # DAG properties

Centrality Measures

GET /api/project/analysis/pagerank       # PageRank scores
GET /api/project/analysis/betweenness    # Betweenness centrality
GET /api/project/analysis/katz           # Katz centrality

Clustering & Communities

GET /api/project/analysis/communities    # Louvain community detection
GET /api/project/analysis/clustering     # Clustering coefficients
GET /api/project/analysis/spectral?n_clusters=5     # Spectral clustering
GET /api/project/analysis/hierarchical?n_clusters=5  # Hierarchical clustering

Structural Analysis

GET /api/project/analysis/structural           # Overall structure
GET /api/project/analysis/critical-path        # Critical path
GET /api/project/analysis/transitive-reduction # Transitive reduction

Advanced Metrics

GET /api/project/analysis/entropy        # Graph entropy
GET /api/project/analysis/curvature      # Ricci curvature
GET /api/project/analysis/geometry       # Geometric properties
GET /api/project/analysis/topology       # Topological features

Machine Learning

GET /api/project/analysis/embedding           # Node embeddings
GET /api/project/analysis/embedding-clusters  # Embedding-based clusters
GET /api/project/analysis/link-prediction     # Link prediction
GET /api/project/analysis/patterns            # Graph patterns
GET /api/project/analysis/motif-participation # Motif analysis
GET /api/project/analysis/mapper              # Mapper algorithm
GET /api/project/analysis/correlations        # Metric correlations

Lean-Specific

GET /api/project/analysis/lean/types          # Type distribution
GET /api/project/analysis/lean/namespaces     # Namespace analysis
GET /api/project/analysis/lean/quality        # Code quality metrics
GET /api/project/analysis/lean/breaking-change # Breaking change detection

All Metrics

GET /api/project/analysis/metrics/all

Returns all computed metrics in a single response.

Metadata & Reset

Clear Metadata

POST /api/meta/clear

Clear all custom metadata.

Reset Project

POST /api/reset

Fully reset the project state.

WebSocket

Watch Project

WebSocket /api/project/watch

Real-time notifications when .ilean or meta.json files change.

Events:

{
  "type": "file_changed",
  "path": "/path/to/file.ilean"
}