Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
552 lines (462 loc) · 9.94 KB

API_DOCUMENTATION.md

File metadata and controls

552 lines (462 loc) · 9.94 KB

Agent Shadow API Documentation

Base URL

https://YOUR_PROJECT.supabase.co/functions/v1

Authentication

All authenticated endpoints require:

Authorization: Bearer YOUR_SUPABASE_JWT_TOKEN

Webhook endpoint accepts user_id in query params or body.

Endpoints

1. Sync Google Calendar

Endpoint: POST /sync-calendar

Authentication: Required

Request Body:

{
  "user_id": "uuid"
}

Response:

{
  "success": true,
  "synced": 15,
  "new_meetings": 3
}

Description: Fetches events from user's Google Calendar and syncs to Agent Shadow database.

Rate Limit: 1 request per minute

2. Sync Gmail

Endpoint: POST /sync-emails

Authentication: Required

Request Body:

{
  "user_id": "uuid"
}

Response:

{
  "success": true,
  "synced": 25,
  "total_threads": 25
}

Description: Fetches recent emails, groups by thread, performs AI analysis, and stores in database.

Rate Limit: 1 request per 5 minutes

3. Make.com Webhook

Endpoint: POST /make-webhook?user_id=YOUR_USER_ID

Authentication: Not required (uses service role internally)

Event Types:

Meeting Recorded

{
  "event_type": "meeting_recorded",
  "user_id": "uuid",
  "data": {
    "meeting_id": "uuid",
    "recording_url": "https://...",
    "transcript": {
      "text": "Full transcript...",
      "segments": [
        {
          "speaker": "Speaker 1",
          "text": "Hello everyone...",
          "timestamp": "00:00:15"
        }
      ],
      "summary": "Meeting discussed...",
      "key_points": ["Point 1", "Point 2"],
      "action_items": [
        {
          "task": "Complete design mockups",
          "assignee": "John",
          "priority": 1,
          "deadline": "2024-01-15",
          "estimated_time": "2 hours"
        }
      ]
    }
  }
}

Response:

{
  "success": true,
  "webhook_id": "uuid",
  "processing_result": {
    "meeting_updated": true,
    "transcript_created": true
  }
}

Transcription Complete

{
  "event_type": "transcription_complete",
  "user_id": "uuid",
  "data": {
    "meeting_id": "uuid",
    "transcript": "Full transcript text...",
    "summary": "Brief meeting summary...",
    "key_points": ["Point 1", "Point 2", "Point 3"],
    "action_items": [
      {
        "task": "Review proposal",
        "assignee": "freelancer",
        "priority": 1,
        "deadline": "2024-01-20"
      }
    ]
  }
}

Response:

{
  "success": true,
  "webhook_id": "uuid",
  "processing_result": {
    "transcription_saved": true,
    "document_created": true
  }
}

Task Created

{
  "event_type": "task_created",
  "user_id": "uuid",
  "data": {
    "title": "Design homepage mockup",
    "description": "Create responsive mockup for new homepage",
    "deadline": "2024-01-25",
    "project_id": "uuid",  // optional
    "priority": 1,  // 1-3
    "estimated_time": "4 hours"  // optional
  }
}

Response:

{
  "success": true,
  "webhook_id": "uuid",
  "processing_result": {
    "task_created": true,
    "task_id": "uuid"
  }
}

Email Received

{
  "event_type": "email_received",
  "user_id": "uuid",
  "data": {
    "subject": "Project update request",
    "from": "client@example.com",
    "body": "Email body content...",
    "contains_deadline": true,
    "extracted_deadlines": [
      {
        "description": "Submit final report",
        "date": "2024-01-30"
      }
    ],
    "importance_score": 85
  }
}

Response:

{
  "success": true,
  "webhook_id": "uuid",
  "processing_result": {
    "email_logged": true
  }
}

Database Tables Reference

Integrations

{
  id: uuid
  user_id: uuid
  service_type: 'gmail' | 'google_calendar' | 'make_webhook' | 'zoom' | 'meet'
  credentials: {
    access_token: string
    refresh_token: string
    expires_at: timestamp
  }
  settings: object
  is_active: boolean
  last_synced_at: timestamp
  created_at: timestamp
  updated_at: timestamp
}

Meetings

{
  id: uuid
  user_id: uuid
  client_id: uuid | null
  project_id: uuid | null
  title: string
  description: string | null
  meeting_url: string | null
  calendar_event_id: string | null
  scheduled_start: timestamp
  scheduled_end: timestamp | null
  actual_start: timestamp | null
  actual_end: timestamp | null
  status: 'scheduled' | 'in_progress' | 'completed' | 'cancelled'
  attendees: object | null
  recording_url: string | null
  created_at: timestamp
  updated_at: timestamp
}

Meeting Transcripts

{
  id: uuid
  meeting_id: uuid
  user_id: uuid
  full_transcript: string
  speakers: object | null
  transcript_segments: object | null
  ai_summary: string | null
  key_points: array | null
  action_items: array | null
  mentioned_deadlines: array | null
  sentiment_analysis: object | null
  created_at: timestamp
}

Meeting Documents

{
  id: uuid
  meeting_id: uuid
  user_id: uuid
  document_type: 'summary' | 'notes' | 'action_items' | 'follow_up'
  title: string
  content: string
  metadata: object | null
  created_at: timestamp
  updated_at: timestamp
}

Email Threads

{
  id: uuid
  user_id: uuid
  client_id: uuid | null
  project_id: uuid | null
  thread_id: string
  subject: string
  participants: object
  last_message_date: timestamp
  message_count: number
  labels: array | null
  ai_summary: string | null
  contains_deadline: boolean
  extracted_deadlines: array | null
  importance_score: number (0-100)
  created_at: timestamp
  updated_at: timestamp
}

Webhook Events

{
  id: uuid
  user_id: uuid
  event_type: string
  source: string
  payload: object
  processed: boolean
  processed_at: timestamp | null
  error_message: string | null
  created_at: timestamp
}

Error Codes

Code Description
400 Bad Request - Invalid payload or missing required fields
401 Unauthorized - Invalid or missing authentication
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Something went wrong

Error Response Format

{
  "error": "Detailed error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "specific field that caused error"
  }
}

Rate Limits

Endpoint Limit Window
/sync-calendar 1 request 1 minute
/sync-emails 1 request 5 minutes
/make-webhook 100 requests 1 minute

Rate limit headers included in response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Webhook Testing

Using cURL

curl -X POST \
  'https://YOUR_PROJECT.supabase.co/functions/v1/make-webhook?user_id=YOUR_USER_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_type": "task_created",
    "user_id": "YOUR_USER_ID",
    "data": {
      "title": "Test task",
      "priority": 1
    }
  }'

Using Postman

  1. Create new POST request
  2. URL: https://YOUR_PROJECT.supabase.co/functions/v1/make-webhook?user_id=YOUR_USER_ID
  3. Headers: Content-Type: application/json
  4. Body: Select "raw" and "JSON"
  5. Paste webhook payload
  6. Send

Using Make.com

  1. Create HTTP module
  2. Method: POST
  3. URL: Webhook endpoint
  4. Body type: Raw
  5. Content type: JSON
  6. Body: Your webhook payload
  7. Run once to test

Best Practices

1. Idempotency

Include a unique idempotency_key in your webhook payload to prevent duplicate processing:

{
  "event_type": "task_created",
  "idempotency_key": "unique-id-12345",
  "user_id": "uuid",
  "data": {...}
}

2. Retry Logic

Implement exponential backoff for failed requests:

  • 1st retry: Wait 1 second
  • 2nd retry: Wait 2 seconds
  • 3rd retry: Wait 4 seconds
  • Max retries: 5

3. Payload Validation

Always validate webhook payloads before sending:

const validatePayload = (payload) => {
  if (!payload.event_type) throw new Error('event_type required')
  if (!payload.user_id) throw new Error('user_id required')
  if (!payload.data) throw new Error('data required')
  return true
}

4. Logging

Log all webhook calls for debugging:

console.log('Webhook sent:', {
  timestamp: new Date(),
  event_type: payload.event_type,
  status: response.status
})

5. Security

  • Never expose your webhook URL publicly
  • Validate the source of webhook calls
  • Use HTTPS only
  • Rotate user_id values if compromised

SDK Examples

JavaScript/TypeScript

const sendWebhook = async (eventType: string, data: any) => {
  const response = await fetch(
    `https://YOUR_PROJECT.supabase.co/functions/v1/make-webhook?user_id=YOUR_USER_ID`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        event_type: eventType,
        user_id: 'YOUR_USER_ID',
        data,
      }),
    }
  )
  
  if (!response.ok) {
    throw new Error(`Webhook failed: ${response.statusText}`)
  }
  
  return await response.json()
}

// Usage
await sendWebhook('task_created', {
  title: 'New task',
  priority: 1
})

Python

import requests

def send_webhook(event_type, data):
    url = f"https://YOUR_PROJECT.supabase.co/functions/v1/make-webhook"
    params = {"user_id": "YOUR_USER_ID"}
    
    payload = {
        "event_type": event_type,
        "user_id": "YOUR_USER_ID",
        "data": data
    }
    
    response = requests.post(url, params=params, json=payload)
    response.raise_for_status()
    return response.json()

# Usage
send_webhook("task_created", {
    "title": "New task",
    "priority": 1
})

Changelog

v1.0.0 (2024-01-13)

  • Initial API release
  • Calendar sync endpoint
  • Email sync endpoint
  • Make.com webhook endpoint
  • Support for 4 event types

For support, please refer to the main documentation or open an issue on GitHub.