MyoSapiens

API Reference

Complete REST API documentation for MyoSapiens.

The MyoSapiens REST API provides programmatic access to all platform features. While we recommend using the Python SDK for most use cases, the REST API is available for direct integration.

Base URL

Production: https://api.myolab.ai

Authentication

All API requests require authentication using an API key. Include your API key in one of two ways:

Header Authentication

X-Api-Key: your_api_key_here

or

Authorization: Bearer your_api_key_here

Getting an API Key

  1. Sign up at dev.myolab.ai
  2. Create a tenant (workspace)
  3. Generate an API key in your tenant settings
Security: Never commit API keys to version control. Store them securely using environment variables or a secrets management system.

Rate Limits

API requests are subject to rate limiting based on your plan. When rate limits are exceeded, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Error Handling

The API uses standard HTTP status codes:

  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 204 No Content - Request succeeded, no content to return
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Authentication failed
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource conflict (e.g., asset has active references)
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

Error responses include a JSON body with a detail field:

{
  "detail": "Error message describing what went wrong"
}

Endpoints

Assets

Manage file uploads and downloads.

Using the SDK: For most use cases, we recommend using the Python SDK which provides a simple upload_file() method. The SDK handles all upload complexity automatically.

List Assets

GET /v1/assets?purpose=retarget&limit=50&offset=0

List assets with optional filtering.

Query Parameters:

  • purpose (optional) - Filter by purpose: retarget
  • reference_count (optional) - Filter by reference count
  • limit (default: 50) - Items per page (1-100)
  • offset (default: 0) - Items to skip

Response:

{
  "assets": [
    {
      "asset_id": "uuid",
      "purpose": "retarget",
      "filename": "motion.c3d",
      "size_bytes": 1024000,
      "status": "completed",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}

Get Asset Details

GET /v1/assets/{asset_id}

Get detailed information about an asset, including download URL.

Response:

{
  "asset_id": "uuid",
  "purpose": "retarget",
  "filename": "motion.c3d",
  "size_bytes": 1024000,
  "status": "completed",
  "download_url": "https://...",
  "created_at": "2024-01-01T00:00:00Z"
}

Delete Asset

DELETE /v1/assets/{asset_id}

Delete an asset. Only succeeds if the asset has no active references.

Response: 204 No Content

Characters

Browse available characters for retargeting.

List Characters

GET /v1/characters?name_contains=human&has_ready_versions=true&limit=50&offset=0

List available characters.

Query Parameters:

  • name_contains (optional) - Filter by name substring
  • has_ready_versions (optional) - Only include characters with READY versions
  • limit (default: 50) - Items per page (1-100)
  • offset (default: 0) - Items to skip

Response:

{
  "characters": [
    {
      "character_id": "uuid",
      "name": "Human Character",
      "description": "...",
      "version_count": 2,
      "latest_version": "v1.0.0"
    }
  ],
  "total": 10,
  "limit": 50,
  "offset": 0
}

Get Character Details

GET /v1/characters/{character_id}

Get detailed information about a character, including all versions.

Response:

{
  "character_id": "uuid",
  "name": "Human Character",
  "description": "...",
  "created_at": "2024-01-01T00:00:00Z",
  "versions": [
    {
      "version": "v1.0.0",
      "status": "READY",
      "created_at": "2024-01-01T00:00:00Z",
      "manifest_s3": "s3://..."
    }
  ],
  "latest_version": {
    "version": "v1.0.0",
    "status": "READY",
    "created_at": "2024-01-01T00:00:00Z",
    "manifest_s3": "s3://..."
  },
  "ready_versions": [...],
  "total_versions": 2,
  "ready_version_count": 1
}

Validate Character Manifest

POST /v1/characters/{character_id}/validate-manifest?version=v1.0.0

Validate that a character manifest exists in storage.

Query Parameters:

  • version (required) - Character version to validate

Response:

{
  "version_id": "uuid",
  "character_id": "uuid",
  "version": "v1.0.0",
  "status": "READY",
  "created_at": "2024-01-01T00:00:00Z",
  "manifest_s3_key": "s3://...",
  "updated_at": "2024-01-01T00:00:00Z"
}

Jobs

Manage retargeting jobs.

Start Retarget Job

POST /v1/runs/retarget

Start a character retargeting job.

Request Body:

{
  "c3d_asset_id": "uuid",
  "markerset_asset_id": "uuid",
  "character_id": "uuid",
  "character_version": "v1.0.0",
  "enable_scaling": true,
  "subject_gender": "male",
  "subject_height": 1.75,
  "subject_weight": 70.0,
  "metadata": {}
}

Note: You can use either c3d_asset_id/markerset_asset_id or c3d_s3/markerset_s3 to reference files.

Response:

{
  "job_id": "uuid",
  "type": "retarget",
  "status": "QUEUED",
  "message": "Retarget job created successfully",
  "estimated_wait_time_seconds": 10
}

Get Job Status

GET /v1/jobs/{job_id}

Get the current status of a job.

Response:

{
  "job_id": "uuid",
  "type": "retarget",
  "status": "SUCCEEDED",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "started_at": "2024-01-01T00:01:00Z",
  "completed_at": "2024-01-01T00:05:00Z",
  "message": "Job completed successfully",
  "output": {
    "retarget_output_asset_id": "uuid"
  },
  "download_urls": {
    "retarget_output": "https://..."
  }
}

Job Statuses:

  • QUEUED - Job is waiting to be processed
  • RUNNING - Job is currently being processed
  • SUCCEEDED - Job completed successfully
  • FAILED - Job failed with an error
  • CANCELED - Job was canceled

List Jobs

GET /v1/jobs?status=SUCCEEDED&type=retarget&limit=50&offset=0

List jobs with optional filtering.

Query Parameters:

  • status (optional, repeatable) - Filter by status: QUEUED, RUNNING, SUCCEEDED, FAILED, CANCELED
  • type (optional, repeatable) - Filter by type: retarget
  • created_after (optional) - ISO 8601 timestamp for lower bound
  • created_before (optional) - ISO 8601 timestamp for upper bound
  • run_id (optional) - Filter by run identifier
  • has_output (optional) - Filter jobs that have (or do not have) output assets
  • input_asset_id (optional) - Filter jobs that used a given input asset
  • limit (default: 50) - Items per page (1-100)
  • offset (default: 0) - Items to skip

Response:

{
  "jobs": [
    {
      "job_id": "uuid",
      "type": "retarget",
      "status": "SUCCEEDED",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:05:00Z"
    }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}

Cancel Job

DELETE /v1/jobs/{job_id}

Cancel a queued or running job.

Response:

{
  "job_id": "uuid",
  "status": "CANCELED",
  "message": "Job canceled successfully"
}

Using the SDK

The Python SDK (myosdk) wraps the REST API and handles:

  • Authentication - Automatically includes your API key in requests
  • File uploads - Manages presigned URLs and upload process
  • Job polling - Convenient wait() method for async operations
  • Error handling - Typed exceptions for different error scenarios
  • Retry logic - Automatic retries for transient failures

For most use cases, we recommend using the SDK. See the SDK Reference for complete documentation.

Resources

Tutorial

Complete walkthrough of motion retargeting from C3D data to joint angles.