REST API

Complete REST API reference for Conjure server integration.

Overview

The Conjure REST API provides programmatic access to CAD operations, user management, and premium features. All endpoints require authentication via API key unless otherwise noted.

Base URL: https://conjure.lautrek.com/api/v1

Authentication

All authenticated endpoints require an API key in the X-API-Key header: 

curl -H "X-API-Key: your_api_key_here" \
  https://conjure.lautrek.com/api/v1/auth/user

See the Authentication guide for details.

Core Endpoints

GET /health

Health check endpoint (no authentication required).

Example Response 
{
  "status": "healthy"
}
GET /api/v1/info

Get server information and available features.

Example Response 
{
  "name": "FreeCAD MCP Hosted Server",
  "version": "0.1.0",
  "features": [
    "Authentication via API key",
    "Cloud libraries (fasteners, bearings)",
    "Design templates",
    "Design validation"
  ]
}

User Management

POST /api/v1/auth/register

Register a new user account.

Request Body

{
  "email": "[email protected]",
  "tier": "pro"  // "free", "maker", "pro", "team", or "enterprise"
}
Example Response 
{
  "user_id": "usr_abc123",
  "email": "[email protected]",
  "api_key": "conjure_live_xyz789...",
  "tier": "pro",
  "subscription_status": "active",
  "message": "Save your API key! It will not be shown again."
}
Important: The API key is only shown once. Store it securely!
GET /api/v1/auth/user Auth Required

Get current authenticated user information and usage stats.

Example Response 
{
  "user_id": "usr_abc123",
  "email": "[email protected]",
  "tier": "pro",
  "rate_limit": {
    "operations_used": 45,
    "operations_limit": 20000,
    "reset_at": "2025-01-01T00:00:00"
  }
}
GET /api/v1/usage Auth Required

Get detailed usage information for your account.

Command Execution

POST /api/v1/execute Auth Required

Execute a CAD command with descriptive names.

Request Body

{
  "command": "create_box",
  "parameters": {
    "length": 50.0,
    "width": 30.0,
    "height": 20.0
  }
}
Example Response 
{
  "success": true,
  "result": {
    "object_id": "Box001",
    "type": "Part::Box"
  },
  "rate_limit_info": {
    "operations_used": 46,
    "operations_limit": 20000,
    "reset_at": "2025-01-01T00:00:00"
  }
}
POST /api/v1/op Auth Required Recommended

Execute operations using obfuscated operation IDs. Preferred for production clients to prevent API structure leakage.

Request Body

{
  "op": "a3f2b1c4",  // Opaque operation ID
  "p": {             // Parameters
    "length": 50.0,
    "width": 30.0,
    "height": 20.0
  }
}
Example Response 
{
  "s": true,         // Success
  "r": {             // Result
    "object_id": "Box001"
  },
  "rl": {            // Rate limit
    "u": 46,         // Used
    "l": 20000       // Limit
  }
}
GET /api/v1/ops Auth Required

List available operation IDs for your subscription tier. Use these IDs with the /api/v1/op endpoint.

Example Response 
{
  "operations": [
    {
      "id": "a3f2b1c4",
      "premium": false,
      "available": true
    },
    {
      "id": "b7e4d9a2",
      "premium": true,
      "available": false
    }
  ],
  "total": 25,
  "tier": "pro"
}

MCP Tool Execution

POST /api/v1/mcp/execute Auth Required

Execute an MCP tool. This is the primary endpoint for AI assistant integration.

Request Body

{
  "tool_name": "create_box",
  "parameters": {
    "length": 50.0,
    "width": 30.0,
    "height": 20.0
  },
  "adapter_id": "adapter_xyz789"  // Optional - auto-selected if omitted
}
Example Response 
{
  "success": true,
  "result": {
    "object_id": "Box001",
    "bounding_box": {
      "min": [0, 0, 0],
      "max": [50, 30, 20]
    }
  },
  "execution_time_ms": 45.2,
  "commands_executed": 1
}
GET /api/v1/mcp/tools Auth Required

List available MCP tools for your subscription tier.

Example Response 
{
  "tier": "pro",
  "tools": [
    {
      "name": "create_box",
      "description": "Create a rectangular box primitive",
      "category": "primitives",
      "operation_cost": 1,
      "requires_adapter": true
    }
  ],
  "total_count": 25
}
GET /api/v1/adapter/status Auth Required

Get status of connected CAD adapters for your account.

Example Response 
{
  "adapters": [
    {
      "adapter_id": "adapter_xyz789",
      "adapter_type": "freecad",
      "status": "active",
      "connected_at": "2025-01-15T10:30:00",
      "last_heartbeat": "2025-01-15T10:35:00",
      "healthy": true,
      "capabilities": ["primitives", "booleans", "transforms"]
    }
  ],
  "total_connected": 1
}

Premium Features

Premium endpoints require a Pro, Team, or Enterprise subscription.

Cloud Libraries

GET /api/v1/premium/libraries Premium

List available cloud libraries (fasteners, bearings, etc).

GET /api/v1/premium/library/{library}/{part_id} Premium

Get a specific part from a cloud library.

POST /api/v1/premium/library/search Premium

Search cloud libraries by query.

Design Templates

GET /api/v1/premium/templates Premium

List available design templates.

GET /api/v1/premium/template/{template_id} Premium

Get a specific design template.

Engineering Standards

GET /api/v1/premium/standards Premium

Browse engineering standards library (sockets, fasteners, materials, threads).

GET /api/v1/premium/standards/{category}/{spec_id} Premium

Get detailed specifications for a standard.

POST /api/v1/premium/validate Premium

Validate a CAD design for manufacturing feasibility.

Error Handling

The API uses standard HTTP status codes and returns errors in JSON format:

200 OK

Request succeeded

400 Bad Request

Invalid request parameters

401 Unauthorized

Missing or invalid API key

403 Forbidden

Premium feature requires upgrade

500 Server Error

Internal server error

Example Error Response

{
  "error": "Invalid parameter: length must be positive",
  "status_code": 400
}

Next Steps

Authentication API key management WebSocket Protocol Real-time adapter bridge MCP Integration AI assistant setup