ds_microdot/API_DOCUMENTATION.md

# Microdot AI API Documentation

## Overview

Microdot AI provides a powerful API for transcribing audio/video content and generating AI-powered summaries. The API supports different pricing tiers with varying features and capabilities.

## Base URL

```
http://0.0.0.0:5056
```

## Authentication

All API requests require authentication using a Bearer token.

```
Authorization: Bearer YOUR_API_KEY
```

## Endpoints

### 1. Transcribe Media

Transcribes audio or video content from a URL.

**Endpoint:** `/microdot-ai/transcribe`

**Method:** POST

**Request Body:**

```json
{
  "media_url": "https://example.com/audio-file.mp3",
  "media_type": "audio"  // "audio" or "video"
}
```

**Response:**

```json
{
  "transcript": {
    "sentences": [
      {
        "sentence": "Hello and welcome to the meeting.",
        "speaker": "speaker_0",
        "start": 0.0,
        "end": 2.5,
        "words": [
          {
            "word": "Hello",
            "start": 0.0,
            "end": 0.4
          },
          // Additional words...
        ]
      },
      // Additional sentences...
    ]
  }
}
```

### 2. Generate General Summary

Generates a summary of a transcript based on the user's plan tier.

**Endpoint:** `/microdot-ai/general-summary`

**Method:** POST

**Request Body:**

```json
{
  "transcript": "JSON_STRING_OF_TRANSCRIPT",
  "plan_tier": "pro"  // "freemium" or "pro"
}
```

#### Freemium Plan Response:

```json
{
  "transcript": {
    "Key_Points": [
      {
        "text": "Team discussed Q3 marketing strategy.",
        "timestamp": 120.5
      },
      {
        "text": "Budget approval needed by Friday.",
        "timestamp": 360.2
      },
      {
        "text": "New product launch delayed until September.",
        "timestamp": 480.7
      }
    ],
    "Summary": {
      "text": "Marketing team meeting to review Q3 plans and budget requirements. Team agreed on strategy but product launch delayed.",
      "duration_minutes": 15.5
    }
  }
}
```

#### Pro Plan Response:

```json
{
  "transcript": {
    "Purpose": {
      "text": "Discuss project progress and define upcoming milestones."
    },
    "Chapters": {
      "minutes_total": 3,
      "content": [
        {
          "chapter": "Project Overview",
          "time_stamp": {"start": 5.12, "end": 5.68},
          "content": [
            {"text": "- overview of the project's objectives.", "original_transcript_start": 3.4, "original_transcript_end": 5.7},
            // Additional content...
          ],
          "words_time_stamp": [
            {"word": "Project", "timestamp": 5.12},
            {"word": "Overview", "timestamp": 5.12}
          ]
        },
        // Additional chapters...
      ]
    },
    "Outcomes": {
      "minutes_total": 3,
      "content": [
        // Outcome content...
      ]
    },
    "Action_Items_Per_User": [
      {
        "speaker": "Speaker_A",
        "minutes_total": 3,
        "action_items": [
          // Action items...
        ]
      }
    ]
  }
}
```

### 3. Generate Template Summary

Generates a custom summary based on a user-defined template.

**Endpoint:** `/microdot-ai/template-summary`

**Method:** POST

**Request Body:**

```json
{
  "transcript": "JSON_STRING_OF_TRANSCRIPT",
  "template": "JSON_STRING_OF_TEMPLATE"
}
```

**Example Template:**

```json
{
  "Key_Points": "Summarize the most critical discussion points from the meeting.",
  "Summary": "Provide a brief overall summary of what was discussed.",
  "Next_Steps": "List the next steps decided during the meeting, including any action items."
}
```

**Response:**

```json
{
  "transcript": {
    "Key_Points": {
      "minutes_total": 3.5,
      "content": [
        {
          "text": "Introductions between Diane Taylor and Cody Smith.",
          "time_stamp": {"start": 5.12, "end": 5.68},
          "words_time_stamp": [
            {"word": "Introductions", "timestamp": 5.12},
            // Additional words...
          ]
        }
      ]
    },
    "Summary": {
      // Summary content...
    },
    "Next_Steps": {
      // Next steps content...
    }
  }
}
```

## Plan Features

### Freemium Plan

- 200 minutes of transcription per month
- Basic AI summarization (short bullet points)
- 7-day transcript history
- Limited integrations (Google Meet & Zoom only)

### Pro Plan

- 600 minutes of transcription per month
- Advanced AI summarization with action items
- Speaker identification
- 30-day transcript history
- Multi-platform integrations (Slack, Notion, Asana, Microsoft Teams)

## Error Responses

All endpoints return standard HTTP status codes:

- `200 OK`: Request successful
- `400 Bad Request`: Invalid request parameters
- `401 Unauthorized`: Invalid or missing API key
- `500 Internal Server Error`: Server-side error

Error response format:

```json
{
  "detail": {
    "error": "Error type",
    "message": "Detailed error message"
  }
}
```

## Rate Limits

- Freemium Plan: 100 requests per day
- Pro Plan: 1000 requests per day

Exceeding your plan's transcription minutes will result in a `402 Payment Required` response until the next billing cycle.

## Code Examples

### Python

```python
import requests
import json

# API endpoint
base_url = "https://api.microdot.ai"

# Your API key
api_key = "your_api_key_here"

# Headers
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

# 1. Transcribe an audio file
transcribe_payload = {
    "media_url": "https://example.com/meeting-recording.mp3",
    "media_type": "audio"
}

transcribe_response = requests.post(
    f"{base_url}/microdot-ai/transcribe", 
    headers=headers,
    json=transcribe_payload
)

# Check if transcription was successful
if transcribe_response.status_code == 200:
    transcript_data = transcribe_response.json()
    transcript_json = json.dumps(transcript_data["transcript"])
    
    # 2. Generate a summary (Pro plan)
    summary_payload = {
        "transcript": transcript_json,
        "plan_tier": "pro"
    }
    
    summary_response = requests.post(
        f"{base_url}/microdot-ai/general-summary", 
        headers=headers,
        json=summary_payload
    )
    
    if summary_response.status_code == 200:
        summary_data = summary_response.json()
        print("Summary generated successfully!")
        print(json.dumps(summary_data["transcript"], indent=2))
    else:
        print(f"Summary generation failed: {summary_response.text}")
else:
    print(f"Transcription failed: {transcribe_response.text}")
```

### JavaScript

```javascript
const axios = require('axios');

// API endpoint
const baseUrl = 'https://api.microdot.ai';

// Your API key
const apiKey = 'your_api_key_here';

// Headers
const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

// 1. Transcribe an audio file
const transcribeAudio = async () => {
  const transcribePayload = {
    media_url: 'https://example.com/meeting-recording.mp3',
    media_type: 'audio'
  };
  
  try {
    const transcribeResponse = await axios.post(
      `${baseUrl}/microdot-ai/transcribe`,
      transcribePayload,
      { headers }
    );
    
    const transcriptData = transcribeResponse.data;
    const transcriptJson = JSON.stringify(transcriptData.transcript);
    
    // 2. Generate a summary (Pro plan)
    const summaryPayload = {
      transcript: transcriptJson,
      plan_tier: 'pro'
    };
    
    const summaryResponse = await axios.post(
      `${baseUrl}/microdot-ai/general-summary`,
      summaryPayload,
      { headers }
    );
    
    console.log('Summary generated successfully!');
    console.log(JSON.stringify(summaryResponse.data.transcript, null, 2));
    
  } catch (error) {
    console.error('Error:', error.response ? error.response.data : error.message);
  }
};

transcribeAudio();
```