Skip to content

API Overview

Integrate MedTWIN into your workflow with our REST API.

Base URL

https://api.medtwin.ai/v1

All API requests must be made over HTTPS.

Authentication

MedTWIN uses API keys for authentication.

Get Your API Key

  1. Go to Settings → API Keys
  2. Click Generate New Key
  3. Copy and store securely (shown only once)

Using Your Key

Include in the Authorization header:

curl -X GET "https://api.medtwin.ai/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY"

Key Permissions

Scope Access
read View projects, analyses, papers
write Create/modify projects and analyses
admin Manage team, billing, API keys

Quick Examples

List Projects

curl -X GET "https://api.medtwin.ai/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "projects": [
    {
      "id": "proj_abc123",
      "name": "Diabetes Outcomes Study",
      "created_at": "2024-01-15T10:30:00Z",
      "status": "active"
    }
  ],
  "total": 1,
  "page": 1
}

Create Project

curl -X POST "https://api.medtwin.ai/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Study",
    "description": "Retrospective analysis of outcomes",
    "template": "retrospective_cohort"
  }'

Upload Data

curl -X POST "https://api.medtwin.ai/v1/projects/proj_abc123/data" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@data.xlsx"

Run Analysis

curl -X POST "https://api.medtwin.ai/v1/projects/proj_abc123/analysis/runs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cox_regression",
    "outcome": "mortality_30day",
    "time_variable": "followup_days",
    "predictors": ["age", "hba1c", "egfr"]
  }'

Core Endpoints

Projects

Method Endpoint Description
GET /projects List all projects
POST /projects Create a project
GET /projects/{id} Get project details
PUT /projects/{id} Update project
DELETE /projects/{id} Delete project

Data

Method Endpoint Description
POST /projects/{id}/data Upload data file
GET /projects/{id}/data List uploaded files
GET /projects/{id}/data/{file_id} Get file info
DELETE /projects/{id}/data/{file_id} Delete file

Mapping

Method Endpoint Description
GET /projects/{id}/mapping Get current mapping
PUT /projects/{id}/mapping Update mapping
POST /projects/{id}/mapping/commit Commit mapping
GET /projects/{id}/mapping/suggestions Get AI suggestions

Analysis

Method Endpoint Description
GET /projects/{id}/analysis/spec Get analysis config
PUT /projects/{id}/analysis/spec Update config
POST /projects/{id}/analysis/runs Start analysis run
GET /projects/{id}/analysis/runs List all runs
GET /projects/{id}/analysis/runs/{run_id} Get run results

Paper

Method Endpoint Description
GET /projects/{id}/paper Get paper content
PUT /projects/{id}/paper Update paper
POST /projects/{id}/paper/generate Generate section
POST /projects/{id}/paper/export Export paper

Literature

Method Endpoint Description
POST /literature/search Search PubMed/CrossRef
POST /projects/{id}/literature Add citation
GET /projects/{id}/literature List citations
DELETE /projects/{id}/literature/{cite_id} Remove citation

Request Format

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Request Body

JSON format for POST/PUT requests:

{
  "name": "Study Name",
  "settings": {
    "option1": "value1",
    "option2": true
  }
}

File Upload

Use multipart/form-data for file uploads:

curl -X POST "https://api.medtwin.ai/v1/projects/{id}/data" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@mydata.xlsx" \
  -F "description=Patient demographics"

Response Format

Success Response

{
  "data": {
    "id": "proj_abc123",
    "name": "My Project",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}

Error Response

{
  "error": {
    "code": "invalid_request",
    "message": "The 'name' field is required",
    "details": {
      "field": "name",
      "reason": "missing"
    }
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}

HTTP Status Codes

Code Meaning
200 Success
201 Created
400 Bad request
401 Unauthorized
403 Forbidden
404 Not found
429 Rate limited
500 Server error

Rate Limits

Plan Requests/min Requests/day
Free 10 100
Pro 60 10,000
Enterprise 300 Unlimited

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312200

Pagination

List endpoints support pagination:

GET /projects?page=2&per_page=20

Response includes pagination info:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "per_page": 20,
    "total": 47,
    "total_pages": 3
  }
}

Webhooks

Get notified when events occur.

Configure Webhooks

curl -X POST "https://api.medtwin.ai/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["analysis.completed", "paper.exported"]
  }'

Event Types

Event Description
analysis.started Analysis run started
analysis.completed Analysis run finished
analysis.failed Analysis run failed
paper.generated Paper section generated
paper.exported Paper exported
data.uploaded Data file uploaded
mapping.committed Mapping committed

Webhook Payload

{
  "event": "analysis.completed",
  "timestamp": "2024-01-15T14:30:22Z",
  "data": {
    "project_id": "proj_abc123",
    "run_id": "run_def456",
    "status": "success"
  }
}

SDKs

Python

pip install medtwin

from medtwin import MedTWIN

client = MedTWIN(api_key="YOUR_API_KEY")

# List projects
projects = client.projects.list()

# Upload data
client.projects.upload_data(
    project_id="proj_abc123",
    file_path="data.xlsx"
)

# Run analysis
run = client.analysis.run(
    project_id="proj_abc123",
    type="cox_regression",
    outcome="mortality_30day",
    predictors=["age", "hba1c"]
)

# Wait for completion
results = run.wait()
print(results.hazard_ratios)

JavaScript/Node.js

npm install @medtwin/sdk

import { MedTWIN } from '@medtwin/sdk';

const client = new MedTWIN({ apiKey: 'YOUR_API_KEY' });

// List projects
const projects = await client.projects.list();

// Upload data
await client.projects.uploadData('proj_abc123', {
  file: fs.createReadStream('data.xlsx')
});

// Run analysis
const run = await client.analysis.run('proj_abc123', {
  type: 'cox_regression',
  outcome: 'mortality_30day',
  predictors: ['age', 'hba1c']
});

Interactive Docs

Explore the API interactively:

Support