API Reference

Authentication

All API requests require authentication using a Bearer token or API key. Include your token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Alternatively, use an API key via the X-API-Key header:

X-API-Key: YOUR_API_KEY

MCP Server Integration

Praetor provides a Model Context Protocol (MCP) server that integrates seamlessly with Claude Code. The MCP server exposes 60+ tools for code analysis, specification management, and brownfield convergence.

Available Tool Categories

• audit.* - Code quality auditing and convergence analysis
• code.* - Code scanning (files, symbols, dependencies)
• findings.* - Security and quality findings management
• convergence.* - Spec-to-code convergence tracking
• obligations.* - Implementation obligation tracking
• standards.* - Coding standards validation
• playbook.* - Test automation and quality playbooks
• test.* - E2E test execution and validation

Installation & Setup

1. Generate an API key in your Developer Settings
2. Install the MCP package: npm install -g @strata19/mcp
3. Create a .praetor/config.yaml file with your API key
4. Register with Claude Code: claude mcp add praetor-audit --command "praetor-mcp"
5. Verify: claude mcp list

For step-by-step instructions with pre-filled API key, visit your Developer Settings.

Base URL

All API endpoints are relative to the base URL:

https://your-instance.praetor.app/api

Main Resources

Projects

Manage specification projects.

• GET /projects - List all projects
• POST /projects - Create a new project
• GET /projects/:id - Get project details
• PATCH /projects/:id - Update a project
• DELETE /projects/:id - Delete a project

User Stories

Access generated user stories and specifications.

• GET /userstories - List user stories
• POST /userstories - Create a user story
• GET /userstories/:id - Get story details
• PATCH /userstories/:id - Update a story

Kits

Manage code generation kits.

• GET /kits - List available kits
• POST /kits - Create a new kit
• GET /kits/:id - Get kit details
• PATCH /kits/:id - Update a kit

Workflows

Orchestrate multi-agent workflows.

• GET /workflows - List workflows
• POST /workflows - Start a workflow
• GET /workflows/:id - Get workflow status
• POST /workflows/:id/cancel - Cancel a workflow

Response Format

All API responses follow a consistent JSON structure:

{
  "data": { /* resource data */ },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-02-24T00:00:00Z"
  }
}

Error Handling

Errors return appropriate HTTP status codes with details:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": { /* additional context */ }
  }
}

Rate Limiting

API requests are rate limited to 1000 requests per hour per user. Rate limit information is included in response headers:

• X-RateLimit-Limit - Total requests allowed
• X-RateLimit-Remaining - Requests remaining
• X-RateLimit-Reset - Unix timestamp when limit resets

Interactive Documentation

For an interactive API explorer with request/response examples, try the OpenAPI specification with your preferred API client (Postman, Insomnia, etc.).