Skip to content

REST API Reference

Jump to bottom
Eric Fitzgerald edited this page Nov 21, 2025 · 2 revisions

REST API Reference

This page provides a comprehensive reference to TMI's REST API endpoints organized by resource category.

API Specifications

OpenAPI Documentation

The complete API specification is available in OpenAPI 3.0.3 format:

Source Specification:

Processed Specifications (all references resolved):

Interactive Documentation:

Base URL

Development: http://localhost:8080

Production: https://api.tmi.dev

API Prefix: /api/v1 (coming soon, currently endpoints at root)

Rate Limiting

All API endpoints are subject to rate limiting to ensure fair usage and system stability. TMI implements a four-tier rate limiting strategy:

  • Public Discovery: 10 requests/minute (IP-based)
  • Auth Flows: Multi-scope limits (session, IP, user identifier)
  • Resource Operations: 100 requests/minute per user (configurable)
  • Webhooks: Multiple limits including subscriptions and events (configurable)

When rate limited, the API returns 429 Too Many Requests with X-RateLimit-* and Retry-After headers.

See: API-Rate-Limiting for complete rate limiting documentation including client integration examples.

Endpoint Categories

Core Resources

  1. Threat Models - Threat modeling workspaces
  2. Diagrams - Data flow diagrams
  3. Threats - Security threats
  4. Assets - System assets
  5. Documents - Reference documents
  6. Notes - Markdown notes
  7. Repositories - Source code repositories
  8. Metadata - Custom metadata

Integration Resources

  1. Webhooks - Webhook subscriptions and deliveries
  2. Addons - Addon registrations and invocations
  3. Authorization - Access control

System Resources

  1. Users - User management
  2. Health - System health and readiness
  3. Authentication - OAuth endpoints

Threat Models

Threat models are the primary workspace for security analysis.

List Threat Models

GET /threat_models
Authorization: Bearer {token}

Query Parameters:

  • limit (integer): Number of results (default: 50, max: 500)
  • offset (integer): Pagination offset (default: 0)
  • owner (string): Filter by owner email
  • created_after (RFC3339): Filter by creation date
  • sort (string): Sort field (e.g., -created_at)

Response (200 OK):

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production API Security",
      "description": "Threat model for production API",
      "owner": "[email protected]",
      "created_at": "2025-01-15T10:00:00Z",
      "modified_at": "2025-01-15T15:30:00Z",
      "diagram_count": 3,
      "threat_count": 12,
      "document_count": 2
    }
  ],
  "total": 25,
  "limit": 50,
  "offset": 0
}

Get Threat Model

GET /threat_models/{id}
Authorization: Bearer {token}

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production API Security",
  "description": "Comprehensive threat model for production API services",
  "owner": "[email protected]",
  "created_by": "[email protected]",
  "created_at": "2025-01-15T10:00:00Z",
  "modified_at": "2025-01-15T15:30:00Z",
  "authorization": [
    {
      "subject": "security-team",
      "subject_type": "group",
      "role": "writer"
    }
  ],
  "metadata": {
    "project": "API-Gateway",
    "compliance": "GDPR"
  }
}

Create Threat Model

POST /threat_models
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "My Threat Model",
  "description": "Security analysis for new feature",
  "authorization": [
    {
      "subject": "security-team",
      "subject_type": "group",
      "role": "writer"
    }
  ],
  "metadata": {
    "project": "MyProject"
  }
}

Response (201 Created):

{
  "id": "7d8f6e5c-4b3a-2190-8765-fedcba987654",
  "name": "My Threat Model",
  "owner": "[email protected]",
  "created_at": "2025-01-15T16:00:00Z"
}

Important: Do NOT include server-generated fields:

  • id - Server generates UUID
  • owner - Extracted from JWT token
  • created_at, modified_at - Set by server
  • Calculated counts (diagram_count, etc.)

Update Threat Model

Full Update (PUT):

PUT /threat_models/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Updated Name",
  "description": "Updated description",
  "authorization": [...]
}

Partial Update (PATCH):

PATCH /threat_models/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "New Name Only"
}

Response (200 OK): Returns updated resource

Delete Threat Model

DELETE /threat_models/{id}
Authorization: Bearer {token}

Response (204 No Content)

Note: Requires owner role. Cascades to all related resources.

Diagrams

Data flow diagrams visualize system architecture.

List Diagrams

GET /threat_models/{threat_model_id}/diagrams
Authorization: Bearer {token}

Query Parameters: Same as threat models (limit, offset, sort)

Response (200 OK):

{
  "items": [
    {
      "id": "diagram-uuid",
      "threat_model_id": "tm-uuid",
      "title": "System Architecture",
      "diagram_type": "data_flow",
      "version": 3,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Get Diagram

GET /diagrams/{id}
Authorization: Bearer {token}

Response (200 OK):

{
  "id": "diagram-uuid",
  "threat_model_id": "tm-uuid",
  "title": "System Architecture",
  "diagram_type": "data_flow",
  "diagram_json": {
    "cells": [...],
    "assets": [...]
  },
  "version": 3,
  "created_at": "2025-01-15T10:00:00Z",
  "modified_at": "2025-01-15T14:30:00Z"
}

Create Diagram

POST /threat_models/{threat_model_id}/diagrams
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "System Architecture",
  "diagram_type": "data_flow",
  "diagram_json": {
    "cells": [],
    "assets": []
  }
}

Update/Delete Diagram

Similar patterns to threat models.

Real-time editing: Use WebSocket API for collaborative diagram editing (see WebSocket-API-Reference).

Threats

Security threats identified in threat models.

List Threats

GET /threats
Authorization: Bearer {token}

Query Parameters:

  • threat_model_id (UUID): Filter by threat model
  • severity (string): Filter by severity (critical, high, medium, low)
  • status (string): Filter by status
  • category (string): Filter by category

Response (200 OK):

{
  "items": [
    {
      "id": "threat-uuid",
      "threat_model_id": "tm-uuid",
      "title": "SQL Injection Vulnerability",
      "description": "User input not sanitized",
      "category": "injection",
      "severity": "high",
      "likelihood": "medium",
      "status": "open",
      "mitigation": "Use parameterized queries",
      "created_at": "2025-01-15T11:00:00Z"
    }
  ]
}

Create Threat

POST /threats
Authorization: Bearer {token}
Content-Type: application/json

{
  "threat_model_id": "tm-uuid",
  "title": "SQL Injection Vulnerability",
  "description": "Detailed description",
  "category": "injection",
  "severity": "high",
  "likelihood": "medium",
  "mitigation": "Use parameterized queries"
}

Webhooks

Webhook subscriptions for real-time event notifications.

Create Webhook Subscription

POST /webhook/subscriptions
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "My Integration",
  "url": "https://your-domain.com/webhooks/tmi",
  "events": ["threat_model.created", "threat_model.updated"],
  "secret": "your-hmac-secret",
  "threat_model_id": "tm-uuid"
}

Response (201 Created):

{
  "id": "webhook-uuid",
  "status": "pending_verification",
  "name": "My Integration",
  "url": "https://your-domain.com/webhooks/tmi",
  "events": ["threat_model.created", "threat_model.updated"],
  "created_at": "2025-01-15T10:00:00Z"
}

Challenge-Response: TMI sends challenge to verify endpoint before activating subscription.

List Webhook Subscriptions

GET /webhook/subscriptions
Authorization: Bearer {token}

Get Webhook Subscription

GET /webhook/subscriptions/{id}
Authorization: Bearer {token}

Delete Webhook Subscription

DELETE /webhook/subscriptions/{id}
Authorization: Bearer {token}

List Webhook Deliveries

GET /webhook/deliveries
Authorization: Bearer {token}

Query Parameters:

  • subscription_id (UUID): Filter by subscription
  • status (string): Filter by status (pending, delivered, failed)

Response (200 OK):

{
  "items": [
    {
      "id": "delivery-uuid",
      "subscription_id": "webhook-uuid",
      "event_type": "threat_model.created",
      "status": "delivered",
      "attempts": 1,
      "created_at": "2025-01-15T12:00:00Z",
      "delivered_at": "2025-01-15T12:00:01Z"
    }
  ]
}

See Webhook-Integration for complete webhook documentation.

Addons

Addon registrations and invocations.

List Addons

GET /addons
Authorization: Bearer {token}

Query Parameters:

  • threat_model_id (UUID): Filter by threat model

Response (200 OK):

{
  "addons": [
    {
      "id": "addon-uuid",
      "name": "STRIDE Analysis",
      "description": "Automated STRIDE analysis",
      "icon": "material-symbols:security",
      "objects": ["threat_model", "asset"],
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Create Addon (Admin Only)

POST /addons
Authorization: Bearer {admin-token}
Content-Type: application/json

{
  "name": "STRIDE Analysis",
  "webhook_id": "webhook-uuid",
  "description": "Automated STRIDE analysis",
  "icon": "material-symbols:security",
  "objects": ["threat_model", "asset"]
}

Invoke Addon

POST /addons/{addon_id}/invoke
Authorization: Bearer {token}
Content-Type: application/json

{
  "threat_model_id": "tm-uuid",
  "object_type": "asset",
  "object_id": "asset-uuid",
  "payload": {
    "analysis_type": "full"
  }
}

Response (202 Accepted):

{
  "invocation_id": "invocation-uuid",
  "status": "pending",
  "created_at": "2025-01-15T12:00:00Z"
}

Get Invocation Status

GET /invocations/{invocation_id}
Authorization: Bearer {token}

Response (200 OK):

{
  "id": "invocation-uuid",
  "addon_id": "addon-uuid",
  "status": "in_progress",
  "status_percent": 75,
  "status_message": "Analyzing assets...",
  "created_at": "2025-01-15T12:00:00Z",
  "status_updated_at": "2025-01-15T12:02:30Z"
}

See Addon-System for complete addon documentation.

Authorization

Manage access control for resources.

Get Authorization

GET /threat_models/{id}/authorization
Authorization: Bearer {token}

Response (200 OK):

{
  "owner": "[email protected]",
  "authorization": [
    {
      "subject": "security-team",
      "subject_type": "group",
      "role": "writer"
    },
    {
      "subject": "[email protected]",
      "subject_type": "user",
      "role": "reader"
    }
  ]
}

Update Authorization (Owner Only)

PUT /threat_models/{id}/authorization
Authorization: Bearer {token}
Content-Type: application/json

{
  "authorization": [
    {
      "subject": "security-team",
      "subject_type": "group",
      "role": "writer"
    }
  ]
}

Roles:

  • owner - Full permissions (set via owner field, not authorization array)
  • writer - Read and write, cannot delete or change permissions
  • reader - Read-only access

Subject Types:

  • user - Individual user (by email)
  • group - Group of users

Special Groups:

  • everyone - All authenticated users

Users

User management and profile information.

Get Current User

GET /users/me
Authorization: Bearer {token}

Response (200 OK):

{
  "id": "user-uuid",
  "email": "[email protected]",
  "name": "Alice Smith",
  "created_at": "2025-01-01T00:00:00Z"
}

List Users (Admin Only)

GET /users
Authorization: Bearer {admin-token}

Health

System health and readiness endpoints.

Health Check

GET /health

Response (200 OK):

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2025-01-15T12:00:00Z"
}

Readiness Check

GET /ready

Response:

  • 200 OK: System ready (database and Redis connected)
  • 503 Service Unavailable: System not ready

Authentication

OAuth authentication endpoints.

Initiate OAuth Login

GET /auth/{provider}/login

Providers: github, google, microsoft, saml

Response: Redirects to OAuth provider

OAuth Callback

GET /auth/{provider}/callback?code={code}

Response: Returns JWT token or redirects to application

Common Patterns

Error Handling

All errors follow standard format:

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    "field": "Additional context"
  }
}

Example Usage:

try {
  const response = await fetch('/api/v1/threat-models', {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error: ${error.message}`);
    // Handle specific error codes
    if (error.error === 'unauthorized') {
      // Re-authenticate
    }
  }

  const data = await response.json();
  // Process data
} catch (e) {
  console.error('Network error:', e);
}

Pagination

async function fetchAllThreatModels() {
  const allModels = [];
  let offset = 0;
  const limit = 50;

  while (true) {
    const response = await fetch(
      `/api/v1/threat-models?limit=${limit}&offset=${offset}`,
      { headers: { 'Authorization': `Bearer ${token}` }}
    );

    const data = await response.json();
    allModels.push(...data.items);

    if (allModels.length >= data.total) {
      break;
    }

    offset += limit;
  }

  return allModels;
}

Filtering and Sorting

# Combine filters and sorting
GET /api/v1/threat-models?[email protected]&created_after=2025-01-01&sort=-created_at&limit=20

SDK Examples

Python

from tmi_client import TMIClient

client = TMIClient(
    base_url='https://api.tmi.dev',
    token='your-jwt-token'
)

# List threat models
threat_models = client.threat_models.list(
    owner='[email protected]',
    limit=10
)

# Create threat model
new_tm = client.threat_models.create({
    'name': 'My Threat Model',
    'description': 'Security analysis'
})

# Get threat model
tm = client.threat_models.get(new_tm['id'])

# Update threat model
client.threat_models.update(tm['id'], {
    'description': 'Updated description'
})

JavaScript

import { TMIClient } from '@tmi/client';

const client = new TMIClient({
  baseUrl: 'https://api.tmi.dev',
  token: 'your-jwt-token'
});

// List threat models
const threatModels = await client.threatModels.list({
  owner: '[email protected]',
  limit: 10
});

// Create threat model
const newTm = await client.threatModels.create({
  name: 'My Threat Model',
  description: 'Security analysis'
});

Related Documentation

Home

Getting Started

Deployment

Operation

Troubleshooting

Development

Integrations

Tools

API Reference

Reference

Clone this wiki locally