API Documentation

Learn how to integrate surgical video analysis into your applications.

Getting Started

The Surgical Video Labeler API allows you to analyze surgical videos using AI to identify phases, instruments, and key events. All API requests require authentication via an API key.

Get API KeyBase URL: https://api.opensurgery.ai

Authentication

Include your API key in the X-API-Key header with every request:

curl -H "X-API-Key: YOUR_API_KEY" https://api.opensurgery.ai/api/v1/health

Endpoints

POST/api/v1/analyze

Upload and analyze a surgical video. Returns a job ID for tracking progress.

Parameters

Name	Type	Description
video	file	Video file (MP4, MOV, AVI)
surgery_type	string	cholecystectomy, appendectomy, colectomy

curl -X POST "https://api.opensurgery.ai/api/v1/analyze" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "video=@surgery_video.mp4" \
  -F "surgery_type=cholecystectomy"

GET/api/v1/jobs/{job_id}

Check the status and progress of an analysis job.

curl -X GET "https://api.opensurgery.ai/api/v1/jobs/JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

GET/api/v1/jobs/{job_id}/results

Retrieve the analysis results including identified phases, instruments, and timestamps.

curl -X GET "https://api.opensurgery.ai/api/v1/jobs/JOB_ID/results" \
  -H "X-API-Key: YOUR_API_KEY"

POST/api/v1/jobs/{job_id}/query

Ask a natural language question about the analyzed video.

curl -X POST "https://api.opensurgery.ai/api/v1/jobs/JOB_ID/query" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What surgical instruments were used?"}'

Response Codes

Code	Description
200	Success
400	Bad request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not found - Job ID doesn't exist
429	Too many requests - Rate limit exceeded
500	Server error

Supported Surgery Types

🔬

Cholecystectomy

Gallbladder removal

cholecystectomy

🏥

Appendectomy

Appendix removal

appendectomy

⚕️

Colectomy

Colon removal

colectomy

MCP Server

Use surgical video analysis directly in Claude Desktop

Setup for Claude Desktop

The MCP (Model Context Protocol) server allows you to use surgical video analysis tools directly within Claude Desktop. Claude can analyze videos, check job status, and answer questions about surgical procedures.

1. Clone the repository

git clone https://github.com/dptru10/cholecystectomy-video-labeler-api.git
cd cholecystectomy-video-labeler-api
pip install -r requirements.txt

2. Configure Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "surgical-video-labeler": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/path/to/cholecystectomy-video-labeler-api",
      "env": {
        "API_BASE_URL": "https://api.opensurgery.ai"
      }
    }
  }
}

3. Restart Claude Desktop

After saving the config, restart Claude Desktop. You'll see the surgical video labeler tools available in Claude's tool menu.

Available Tools

The MCP server exposes these tools to Claude:

analyze_videoMain

Start analysis of a surgical video from a URL. Returns a job_id for tracking progress.

get_job_status

Check the current status and progress of an analysis job.

get_job_results

Get detected surgical phases with timestamps and summary.

query_video

Ask natural language questions about an analyzed video (e.g., "How long did the dissection phase take?").

generate_post_op_note

Generate a formatted post-operative note from analysis results.

list_surgery_types

Get available surgery types (cholecystectomy, appendectomy, colectomy).

get_config / update_config

View or modify analysis settings (model, clip length, FPS).

list_jobs / delete_job

Manage analysis jobs - list all jobs or delete specific ones.

Example Usage

Once configured, you can ask Claude things like:

"Analyze this cholecystectomy video: https://example.com/surgery.mp4"
"What's the status of job abc123?"
"How long did the gallbladder dissection take in the last analysis?"
"Generate a post-op note for patient John Smith from job abc123"

Need Help?

Have questions or need assistance? Our team is here to help you get started.

Contact Support →