L
LR

API Documentation

v2.1.0

Complete REST API reference with examples and SDK documentation. Integrate Lattice Engine into your applications.

Quick Start
curl -X POST http://localhost:8000/mutations/propose
  -H "Content-Type: application/json"
  -H "X-API-Key: your-api-key"
  -d '{"spec_id":"spec-123","operation_type":"update","changes":{"title":"Add hashing"},"reason":"Security","initiated_by":"user-42"}'

Start by proposing a mutation with your API key.

Authentication

Include your API key in the X-API-Key header for all requests. For WebSocket connections, include it as a query parameter: ?token=your-api-key

X-API-Key: your-api-key-here
SDKs
JavaScript SDKPython SDK
Rate Limits
Free Plan1,000 req/hr
Pro Plan10,000 req/hr
EnterpriseUnlimited

Overview

The Lattice Engine API provides programmatic access to all platform features. Use it to integrate Lattice into your applications, automate workflows, and build custom tools.

RESTful Design

Follows REST principles with predictable URLs and HTTP methods.

JSON Responses

All responses are in JSON format with consistent error handling.

Webhooks

Receive real-time notifications about mutations and deployments.

SDKs & Libraries

Python SDK
Direct FastAPI client for the Lattice Mutation Engine

Installation

pip install httpx pydantic

Example Usage

import httpx
from pydantic import BaseModel

class LatticeClient:
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url
        self.client = httpx.Client(
            base_url=base_url,
            headers={"X-API-Key": api_key}
        )

    async def propose_mutation(self, spec_id: str, operation_type: str,
                             changes: dict, reason: str, initiated_by: str):
        response = await self.client.post("/mutations/propose", json={
            "spec_id": spec_id,
            "operation_type": operation_type,
            "changes": changes,
            "reason": reason,
            "initiated_by": initiated_by
        })
        return response.json()

    async def get_specs(self, project_id: str):
        response = await self.client.get(f"/specs/{project_id}")
        return response.json()

# Usage
client = LatticeClient("http://localhost:8000", "your-api-key")
mutation = await client.propose_mutation(
    spec_id="spec-123",
    operation_type="update",
    changes={"title": "Add password hashing"},
    reason="Security enhancement",
    initiated_by="user-42"
)

Features

Async/await supportType hintsPydantic integrationDirect HTTP client

API Endpoints

Mutations

Propose and manage code mutations

POST/mutations/propose
Propose a mutation with multi-tenant context

Request Example

{
  "spec_id": "spec-123",
  "operation_type": "update",
  "changes": {
    "title": "Add password hashing",
    "files_modified": ["src/auth.ts"]
  },
  "reason": "Security enhancement to hash passwords",
  "initiated_by": "user-42",
  "priority": 5
}

Response

{
  "status": "proposed",
  "proposal": {
    "proposal_id": "prop-abc123",
    "spec_id": "spec-123",
    "operation_type": "update",
    "current_version": "1.0.0",
    "proposed_changes": {...},
    "reasoning": "Security enhancement identified",
    "confidence": 0.92,
    "impact_analysis": {
      "security_impact": "high",
      "complexity": "low"
    },
    "requires_approval": true,
    "affected_specs": ["spec-123", "auth-flow"]
  }
}

Approvals

Handle approval workflows and responses

POST/approvals/{request_id}/respond
Respond to an approval request

Request Example

{
  "request_id": "approval-req-123",
  "approved": true,
  "responded_by": "reviewer@example.com",
  "responded_via": "web",
  "comments": "Security enhancement approved"
}

Response

{
  "status": "processed",
  "result": {
    "request_id": "approval-req-123",
    "approved": true,
    "processed_at": "2024-01-15T11:00:00Z",
    "next_steps": ["mutation_execution"]
  }
}
GET/approvals/pending
Get pending approvals for a user

Request Example

GET /approvals/pending?user_id=user-42

Response

{
  "pending_approvals": [
    {
      "request_id": "approval-req-123",
      "proposal_id": "prop-abc123",
      "spec_id": "spec-123",
      "user_id": "user-42",
      "status": "pending",
      "created_at": "2024-01-15T10:30:00Z",
      "details": {...}
    }
  ]
}

Specifications

Manage project specifications and documents

GET/specs/{project_id}
List all specifications for a project

Request Example

GET /specs/proj-123

Response

{
  "project_id": "proj-123",
  "specs": [
    {
      "id": "spec-123",
      "name": "User Authentication",
      "type": "SPEC",
      "description": "Authentication flow specifications",
      "content": "Detailed auth requirements...",
      "status": "ACTIVE",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}
POST/specs/create
Create a new specification

Request Example

{
  "name": "Payment Processing",
  "description": "Payment gateway integration specs",
  "content": "Payment processing requirements...",
  "spec_source": "payment-team",
  "metadata": {
    "priority": "high",
    "team": "backend"
  }
}

Response

{
  "created": {
    "id": "spec-456",
    "name": "Payment Processing",
    "type": "SPEC",
    "description": "Payment gateway integration specs",
    "content": "Payment processing requirements...",
    "status": "DRAFT",
    "created_at": "2024-01-15T11:00:00Z"
  }
}
PATCH/specs/update
Update an existing specification

Request Example

{
  "spec_id": "spec-123",
  "file_path": "docs/auth.md",
  "diff_summary": "Added MFA requirements",
  "user_context": {
    "updated_by": "security-team"
  }
}

Response

{
  "graph_snapshot": {
    "nodes_updated": ["spec-123"],
    "edges_updated": [],
    "timestamp": "2024-01-15T11:00:00Z"
  }
}
POST/specs/approve
Approve a specification

Request Example

{
  "spec_id": "spec-123"
}

Response

{
  "status": "approved",
  "spec_id": "spec-123",
  "approved_at": "2024-01-15T11:00:00Z"
}
DELETE/specs/{spec_id}
Delete a specification

Request Example

DELETE /specs/spec-123

Response

{
  "deleted": "spec-123",
  "deleted_at": "2024-01-15T11:00:00Z"
}

Graph Query

Query and search the specification graph

POST/graph/query
Query the graph with filters

Request Example

{
  "node_type": "SPEC",
  "filters": {
    "status": "ACTIVE",
    "team": "backend"
  }
}

Response

{
  "nodes": [
    {
      "id": "spec-123",
      "name": "User Authentication",
      "type": "SPEC",
      "status": "ACTIVE",
      "metadata": {...}
    }
  ]
}
POST/graph/semantic-search
Perform semantic search on specifications

Request Example

{
  "query": "password authentication security",
  "top_k": 5,
  "filters": {
    "status": "ACTIVE"
  }
}

Response

{
  "results": [
    {
      "id": "spec-123",
      "name": "User Authentication",
      "content": "Authentication and password requirements...",
      "similarity_score": 0.95
    }
  ]
}
GET/graph/semantic-search/stats
Get semantic search statistics

Request Example

GET /graph/semantic-search/stats

Response

{
  "available": true,
  "backend": "qdrant",
  "total_documents": 150,
  "embedding_model": "all-MiniLM-L6-v2",
  "index_size": "2.3MB"
}

Tasks

Manage background tasks and operations

POST/tasks/request
Request a background task

Request Example

{
  "requester_id": "user-42",
  "operation": "validate_spec",
  "input_data": {
    "spec_id": "spec-123",
    "validation_rules": ["security", "performance"]
  },
  "target_agent_type": "validator",
  "priority": 7
}

Response

{
  "status": "requested",
  "task": {
    "task_id": "task-789",
    "requester_id": "user-42",
    "operation": "validate_spec",
    "status": "pending",
    "created_at": "2024-01-15T11:00:00Z",
    "target_agent_type": "validator"
  }
}
POST/tasks/clarify
Request clarification for a task

Request Example

{
  "task_id": "task-789",
  "note": "Please specify which security validation rules to apply",
  "from_user_id": "user-42"
}

Response

{
  "status": "clarification_requested",
  "task": {
    "task_id": "task-789",
    "status": "clarification_requested",
    "clarification_notes": [
      {
        "note": "Please specify which security validation rules to apply",
        "from_user_id": "user-42",
        "timestamp": "2024-01-15T11:05:00Z"
      }
    ]
  }
}
POST/tasks/complete
Mark a task as completed

Request Example

{
  "task_id": "task-789",
  "success": true,
  "result": {
    "validation_passed": true,
    "issues_found": 0
  },
  "notes": "Spec validation completed successfully"
}

Response

{
  "status": "completed",
  "task": {
    "task_id": "task-789",
    "status": "completed",
    "result": {
      "validation_passed": true,
      "issues_found": 0
    },
    "completed_at": "2024-01-15T11:10:00Z"
  }
}
GET/tasks/status/{task_id}
Get task status

Request Example

GET /tasks/status/task-789

Response

{
  "task": {
    "task_id": "task-789",
    "requester_id": "user-42",
    "operation": "validate_spec",
    "status": "completed",
    "result": {
      "validation_passed": true,
      "issues_found": 0
    },
    "created_at": "2024-01-15T11:00:00Z",
    "updated_at": "2024-01-15T11:10:00Z"
  }
}

Spec Sync

Manage specification synchronization

GET/spec-sync/status
Get spec sync daemon status

Request Example

GET /spec-sync/status

Response

{
  "enabled": true,
  "running": true,
  "dir": "specs"
}
POST/spec-sync/start
Start the spec sync daemon

Request Example

POST /spec-sync/start

Response

{
  "status": "started",
  "dir": "specs"
}
POST/spec-sync/stop
Stop the spec sync daemon

Request Example

POST /spec-sync/stop

Response

{
  "status": "stopped"
}

System

System health and monitoring endpoints

GET/health
Check API health status

Request Example

GET /health

Response

{
  "status": "healthy",
  "engine_initialized": true,
  "timestamp": "2024-01-15T11:00:00Z"
}
GET/metrics
Get Prometheus metrics

Request Example

GET /metrics

Response

# HELP lattice_mutations_proposed_total Total number of mutations proposed
# TYPE lattice_mutations_proposed_total counter
lattice_mutations_proposed_total 42

# HELP lattice_websocket_connections Current WebSocket connections
# TYPE lattice_websocket_connections gauge
lattice_websocket_connections 5

Error Handling

Standard Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "spec_id",
      "issue": "Required field is missing"
    },
    "request_id": "req_abc123"
  }
}

Common Error Codes

400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Conflict
422Validation Error
429Rate Limit Exceeded
500Server Error

WebSocket API

Connection Endpoint

ws://localhost:8000/ws/{user_id}/{client_type}

Real-time WebSocket connection for approval requests and notifications

WebSocket Events

Event: approval:response

Handle approval responses via WebSocket

{
  "event": "approval:response",
  "data": {
    "request_id": "approval-req-123",
    "approved": true,
    "responded_by": "reviewer@example.com",
    "comments": "Approved via WebSocket"
  }
}

JavaScript WebSocket Example

const ws = new WebSocket('ws://localhost:8000/ws/user-42/web?token=your-api-key');

ws.onopen = () => {
  console.log('Connected to Lattice WebSocket');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);

  if (message.event === 'approval:response') {
    // Handle approval response
    handleApprovalResponse(message.data);
  }
};

function sendApprovalResponse(approvalRequest, approved, comments) {
  ws.send(JSON.stringify({
    event: 'approval:response',
    data: {
      request_id: approvalRequest.request_id,
      approved: approved,
      responded_by: 'user-42',
      responded_via: 'web',
      comments: comments
    }
  }));
}

Webhooks

Webhook Payload

When events trigger your webhook, you'll receive a JSON payload:

{
  "event": "mutation.approved",
  "data": {
    "mutation": {
      "id": "mut_abc123",
      "title": "Add password hashing",
      "status": "approved"
    },
    "project": {
      "id": "proj_456",
      "name": "My Project"
    },
    "reviewer": "security-team",
    "timestamp": "2024-01-15T11:00:00Z"
  }
}

Signature Verification

Verify webhook signatures using HMAC-SHA256:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}