How-to Guide

ScreenApp API and SDK Documentation

ScreenApps API enables you to automatically transcribe, summarize, and analyze video and audio content

By ScreenApp Team

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

✨ Popular Use Case: Customer service teams use our API to automatically transcribe support calls and generate summaries, which are then synced to their CRM through webhooks.

Get API Credentials in Dashboard →

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>
  // Plugin installation code here
</script>

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

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

GET /auth/google

Redirect to Google for authentication

Query Parameters:

GET /auth/facebook

Redirect to Facebook for authentication

Query Parameters:

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

POST /team/{teamId}/tag

Add tag to team

Path Parameters:

Request Body:

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

DELETE /team/{teamId}/tag

Remove tag from team

Path Parameters:

Request Body:

{
  "key": "color"
}

Team Webhook Integration

POST /team/{teamId}/integrations/webhook

Register a new webhook URL for the team

Path Parameters:

Request Body:

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

Responses:

DELETE /team/{teamId}/integrations/webhook

Unregister a webhook URL for the team

Path Parameters:

Query Parameters:

Responses:

GET /team/{teamId}/integrations/zapier/sample/list

Get sample data for Zapier as an array

Path Parameters:

Responses:

User Integrations

POST /integrations/webhook

Register a new webhook for the user

Request Body:

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

Responses:

DELETE /integrations/webhook

Unregister a webhook for the user

Query Parameters:

Responses:

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:

File Management

POST /files/{fileId}/tag

Add tag to file

Path Parameters:

Request Body:

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

DELETE /files/{fileId}/tag

Remove tag from file

Path Parameters:

Request Body:

{
  "key": "color"
}

POST /files/{fileId}/ask/multimodal

Ask a question about a file using multiple AI models

Path Parameters:

Request Body:

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

Responses:

File Upload

POST /files/upload/{teamId}/{folderId}/url

Generate pre-signed URLs for file uploads

Path Parameters:

Request Body:

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

Responses:

POST /files/upload/{teamId}/{folderId}/finalize

Finalize uploaded files

Path Parameters:

Request Body:

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

Responses:

Multipart Upload (for large files)

PUT /files/upload/multipart/init/{teamId}/{folderId}

Initialize a multipart upload for a large file

Path Parameters:

Request Body:

{
  "contentType": "video/mp4"
}

Responses:

Response Example:

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

PUT /files/upload/multipart/url/{teamId}/{folderId}/{fileId}/{uploadId}/{partNumber}

Get upload URL for a specific part

Path Parameters:

Request Body:

{
  "contentType": "video/mp4"
}

Responses:

Response Example:

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

PUT /files/upload/multipart/finalize/{teamId}/{folderId}/{fileId}/{uploadId}

Finalize a multipart upload

Path Parameters:

Request Body:

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

Responses:

PUT /files/upload/multipart/fallback/{teamId}/{folderId}/{fileId}/{partNumber}

Upload file part via backend (fallback)

Path Parameters:

Form Data:

Responses:

Account Management

POST /v2/account/tag

Add a tag to the authenticated user

Request Body:

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

Responses:

PUT /account/profile

Update the authenticated user’s profile

Request Body:

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

Responses:

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

Error Response Format

Error responses typically follow this format:

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

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'
      }
    })
  }
);

Get API Credentials in Dashboard →