Skip to main content

​
Overview

The Repurchase Engine API provides programmatic access to all simulation, scenario management, and data retrieval capabilities.
Base URL: https://api.villagelabs.com/v1All API requests require authentication via API key.

​
Authentication

Include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Get Your API Key

Contact [email protected] to receive your API credentials.

​
Quick Start

1

Install SDK

pip install villagelabs-repurchase
2

Initialize Client

from villagelabs import RepurchaseEngine

engine = RepurchaseEngine(api_key="your_api_key")
3

Run Simulation

results = engine.simulate(
    plan_rules=plan_rules,
    operating_assumptions=operating_assumptions,
    initial_state=initial_state
)

​
Core Endpoints

POST /simulate

Run a new simulation

GET /scenarios

List all scenarios

POST /scenarios

Create a new scenario

GET /runs/{id}

Get simulation run details

​
Request Format

All requests use JSON: 
{
  "planRules": {
    "plan_name": "Acme Corp ESOP",
    "vesting_schedule": {...}
  },
  "operatingAssumptions": {
    "contribution_policy": {...}
  },
  "initialState": {
    "participants": [...]
  }
}

​
Response Format

Standard API response structure: 
{
  "success": true,
  "data": {
    "simulation_id": "sim_2024_001",
    "status": "completed",
    "results": {...}
  },
  "meta": {
    "execution_time_ms": 1842,
    "api_version": "1.0"
  }
}

​
Error Handling

Errors return standard HTTP status codes with detailed messages: 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid vesting schedule",
    "details": {
      "field": "vesting_schedule.years",
      "issue": "Must be between 2 and 7"
    }
  }
}

​
Rate Limits

Standard Tier

100 requests/hour10 simulations/hour

Enterprise Tier

Unlimited requestsDedicated infrastructure

​
SDKs & Libraries

pip install villagelabs-repurchase
GitHub Repository

​
Data Schemas

PlanRules

Legal framework schema

OperatingAssumptions

Strategy configuration schema

Response Formats

Output data structures

​
Webhooks

Subscribe to simulation events: 
{
  "event": "simulation.completed",
  "simulation_id": "sim_2024_001",
  "status": "completed",
  "webhook_url": "https://your-app.com/webhooks/simulations"
}

​
Best Practices

Use SDK validation methods before making API calls to catch errors early
Store simulation results locally; re-run only when inputs change
For long-running simulations, use webhooks instead of polling
Implement retry logic with exponential backoff for transient errors

​
Next Steps

Run Simulation

Execute your first API simulation

Manage Scenarios

Create and organize scenarios

View Schemas

Complete schema reference

Examples

See full code examples

​
Support

Need Help?

Email: [email protected]Documentation: You’re reading it!GitHub Issues: Report bugs and request features