ScreenApp API Documentation v2.0.0

ScreenApp's API enables you to automatically transcribe, summarize, and analyze video and audio content. Perfect for businesses looking to process customer calls, training videos, and meeting recordings at scale.

Key Use Cases

• Automatic Transcription & Summarization: Convert any video or audio into searchable text and concise summaries. Ideal for customer service teams, educational institutions, and content creators.
• Knowledge Management: Build a searchable repository of video content with automatic transcripts, summaries, and AI-powered insights. Perfect for training materials and company knowledge bases.
• Real-time Processing: Receive transcripts and summaries via webhooks as soon as recordings are processed. Great for integrating with CRM systems and customer service platforms.
• Embedded Recording: Add professional-grade recording capabilities to your application with our embeddable recorder that handles both screen and audio capture.

Plan Requirements & API Access

To use the ScreenApp API, you'll need:

1. An active Business plan subscription
2. API credentials from your ScreenApp dashboard

Getting Your API Credentials

1. Log into your ScreenApp account
2. Navigate to Settings → Integration
3. Here you'll find your:

• API Token
• Team ID

Keep these credentials secure and never share them publicly.

Quick Start

Want to get started right away? Follow these steps to integrate ScreenApp into your website:

1. Install the Plugin

Add this code to your website's HTML:

<script
  charset="UTF-8" 
  type="text/javascript"
  src="https://screenapp.io/app/plugin.js">
</script>

<script>
  function callback({ id, url }) {
    // When the recording ends, you'll get:
    // - id: unique identifier for the recording
    // - url: direct access URL for the recording
  }

  function loadScreenApp() {
    const screenApp = new window.ScreenApp('YOUR_PLUGIN_TOKEN', callback);
    screenApp.mount("#screenapp-plugin");
  }
</script>

<div id="screenapp-plugin"></div>

2. Add the Trigger Button

Add a button or trigger element to your page:

<button onclick="loadScreenApp()">Start Recording</button>

3. Configure the Callback

Customize the callback function to handle recording completion:

function callback({ id, url }) {
  // Example: Send to your backend
  fetch('/api/recordings', {
    method: 'POST',
    body: JSON.stringify({ recordingId: id, recordingUrl: url })
  });
  
  // Example: Update UI
  document.getElementById('status').innerHTML = 
    `Recording saved! View it at ${url}`;
}

Authentication

All API requests require authentication. ScreenApp uses token-based authentication along with team-specific identifiers.

Credentials You'll Need

• API Token: Your secret API key
• Team ID: Your unique team identifier

Authentication Example

curl -X POST "https://api.screenapp.io/v2/files/upload" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID"

Authentication Endpoints

Core Concepts

Before diving into specific endpoints, let's understand the key concepts in ScreenApp:

1. Recordings: Video and audio captures that can be uploaded and processed
2. Teams: Groups that can share and manage recordings
3. Webhooks: Real-time notifications for recording events and processing results
4. Tags: Metadata that can be attached to recordings, teams, or user profiles

API Reference

Team Management

{
  "key": "color",
  "value": "red"
}

{
  "key": "color"
}

Team Webhook Integration

{
  "url": "https://example.com/webhook",
  "name": "My Webhook"
}

User Integrations

{
  "url": "https://example.com/webhook",
  "name": "My Webhook"
}

Webhook Events

Your webhook endpoint will receive events in this format:

{
  "event": "recording.completed",
  "fileId": "file789",
  "teamId": "team123",
  "data": {
    "url": "https://screenapp.io/recording/file789",
    "duration": 300,
    "status": "processed"
  }
}

Common events include:

• recording.started
• recording.completed
• recording.processed
• recording.failed

File Management

{
  "key": "color",
  "value": "red"
}

{
  "key": "color"
}

{
  "promptText": "What are the key points discussed?",
  "mediaAnalysisOptions": {
    "transcript": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "video": {
      "segments": [
        {
          "start": 0,
          "end": 120
        }
      ]
    },
    "screenshots": {
      "timestamps": [
        30, 60, 90
      ]
    }
  }
}

File Upload

{
  "files": [
    {
      "contentType": "video/mp4",
      "name": "meeting-recording.mp4"
    }
  ]
}

{
  "file": {
    "fileId": "file123",
    "contentType": "video/mp4",
    "name": "Sales Call",
    "description": "Weekly sales call with customer",
    "recorderName": "John Doe",
    "recorderEmail": "john.doe@example.com"
  }
}

Multipart Upload (for large files)

{
  "contentType": "video/mp4"
}

{
  "success": true,
  "data": {
    "fileId": "file789",
    "uploadId": "upload123"
  }
}

{
  "contentType": "video/mp4"
}

{
  "success": true,
  "data": {
    "uploadUrl": "https://presigned-s3-url.com/part1"
  }
}

{
  "file": {
    "contentType": "video/mp4",
    "recorderName": "John Doe",
    "recorderEmail": "john@example.com",
    "name": "My Recording",
    "description": "A recorded video session",
    "notes": [
      {
        "text": "Important point discussed",
        "timestamp": 1234567890
      }
    ]
  }
}

Account Management

{
  "key": "color",
  "value": "red"
}

{
  "firstName": "John",
  "lastName": "Doe",
  "name": "John Doe",
  "gender": "male",
  "userType": "user",
  "company": "Acme Inc",
  "role": "Developer",
  "goals": "Learn new technologies",
  "phoneNumber": "+1234567890",
  "location": "San Francisco, CA",
  "website": "https://example.com",
  "picture": "https://example.com/avatar.jpg",
  "provider": "local",
  "providerId": "12345",
  "primaryField": "development"
}

Advanced Features

AI Analysis

Use AI to analyze your recordings for insights:

// Request AI analysis of a recording
const analysis = await fetch(`/v2/files/${fileId}/ask/multimodal`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    promptText: "What are the key discussion points?",
    mediaAnalysisOptions: {
      transcript: {
        segments: [{ start: 0, end: 300 }]
      },
      video: {
        segments: [{ start: 0, end: 300 }]
      }
    }
  })
});

Batch Operations

Efficiently manage multiple recordings:

// Tag multiple recordings
async function batchTag(fileIds, tag) {
  const promises = fileIds.map(fileId => 
    fetch(`/v2/files/${fileId}/tag`, {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(tag)
    })
  );
  
  await Promise.all(promises);
}

Error Handling

Common Error Codes

• 400: Invalid request parameters
• 403: AI usage limit exceeded or unauthorized access
• 404: Resource not found
• 500: Server error

Error Response Format

Error responses typically follow this format:

{
  "success": false,
  "message": "Detailed error message"
}

Implementation Examples

Setting Up Team Webhooks

Webhooks allow you to receive real-time updates when recordings are processed:

// Register a new webhook for your team
async function registerTeamWebhook(teamId, webhookUrl, webhookName) {
  const response = await fetch(`/v2/team/${teamId}/integrations/webhook`, {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: webhookUrl,
      name: webhookName
    })
  });
  
  return await response.json();
}

// Example usage
const result = await registerTeamWebhook(
  'team123',
  'https://your-domain.com/webhooks/screenapp',
  'Recording Updates'
);

Uploading and Processing a Large File

For files larger than 100MB, use the multipart upload flow:

// 1. Initialize upload
const initResponse = await fetch(`/v2/files/upload/multipart/init/${teamId}/${folderId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    contentType: 'video/mp4'
  })
});

const { data: { fileId, uploadId } } = await initResponse.json();

// 2. Split file into chunks and upload each part
const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB chunks
const totalParts = Math.ceil(file.size / CHUNK_SIZE);

for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
  // Get upload URL for this part
  const urlResponse = await fetch(
    `/v2/files/upload/multipart/url/${teamId}/${folderId}/${fileId}/${uploadId}/${partNumber}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        contentType: 'video/mp4'
      })
    }
  );
  
  const { data: { uploadUrl } } = await urlResponse.json();
  
  // Create the chunk from the file
  const start = (partNumber - 1) * CHUNK_SIZE;
  const end = Math.min(start + CHUNK_SIZE, file.size);
  const chunk = file.slice(start, end);
  
  // Upload the chunk directly to S3
  await fetch(uploadUrl, {
    method: 'PUT',
    body: chunk,
    headers: {
      'Content-Type': 'video/mp4'
    }
  });
}

// 3. Finalize the upload
const finalizeResponse = await fetch(
  `/v2/files/upload/multipart/finalize/${teamId}/${folderId}/${fileId}/${uploadId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      file: {
        contentType: 'video/mp4',
        name: 'Customer Meeting Recording',
        description: 'Quarterly review with client',
        recorderName: 'Jane Smith',
        recorderEmail: 'jane@example.com'
      }
    })
  }
);