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:

{
  "media_url": "https://example.com/audio-file.mp3",
  "media_type": "audio",  // "audio" or "video"
  "plan_tier": "freemium"  // "freemium" or "pro" (optional, defaults to "freemium")
}

Pro Plan Response (with speaker identification):

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

Freemium Plan Response (without speaker identification):

{
  "transcript": {
    "sentences": [
      {
        "sentence": "Hello and welcome to the meeting.",
        // No "speaker" field in freemium plan
        "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:

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

Freemium Plan Response:

{
  "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:

{
  "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:

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

Example Template:

{
  "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:

{
  "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:

{
  "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

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 (Pro plan with speaker identification)
transcribe_payload = {
    "media_url": "https://example.com/meeting-recording.mp3",
    "media_type": "audio",
    "plan_tier": "pro"  # Specify "pro" for speaker identification or "freemium" for no speakers
}

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

const axios = require('axios');

// API endpoint
const baseUrl = 'http://0.0.0.0:5056';

// 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',
    plan_tier: 'pro'  // Specify 'pro' for speaker identification or 'freemium' for no speakers
  };

  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();