> ## Documentation Index
> Fetch the complete documentation index at: https://village-docs.villagelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Getting started with the Repurchase Engine API

## Overview

The Repurchase Engine API provides programmatic access to all simulation, scenario management, and data retrieval capabilities.

<Info>
  **Base URL:** `https://api.villagelabs.com/v1`

  All API requests require authentication via API key.
</Info>

## Authentication

Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Get Your API Key

Contact [support@villagelabs.com](mailto:support@villagelabs.com) to receive your API credentials.

## Quick Start

<Steps>
  <Step title="Install SDK">
    <CodeGroup>
      ```bash Python theme={null}
      pip install villagelabs-repurchase
      ```

      ```bash JavaScript theme={null}
      npm install @villagelabs/repurchase-engine
      ```
    </CodeGroup>
  </Step>

  <Step title="Initialize Client">
    <CodeGroup>
      ```python Python theme={null}
      from villagelabs import RepurchaseEngine

      engine = RepurchaseEngine(api_key="your_api_key")
      ```

      ```javascript JavaScript theme={null}
      import { RepurchaseEngine } from '@villagelabs/repurchase-engine';

      const engine = new RepurchaseEngine({ apiKey: 'your_api_key' });
      ```
    </CodeGroup>
  </Step>

  <Step title="Run Simulation">
    <CodeGroup>
      ```python Python theme={null}
      results = engine.simulate(
          plan_rules=plan_rules,
          operating_assumptions=operating_assumptions,
          initial_state=initial_state
      )
      ```

      ```javascript JavaScript theme={null}
      const results = await engine.simulate({
        planRules,
        operatingAssumptions,
        initialState
      });
      ```
    </CodeGroup>
  </Step>
</Steps>

## Core Endpoints

<CardGroup cols={2}>
  <Card title="POST /simulate" icon="play" href="/api-reference/simulate">
    Run a new simulation
  </Card>

  <Card title="GET /scenarios" icon="list" href="/api-reference/scenarios">
    List all scenarios
  </Card>

  <Card title="POST /scenarios" icon="plus" href="/api-reference/scenarios">
    Create a new scenario
  </Card>

  <Card title="GET /runs/{id}" icon="magnifying-glass" href="/api-reference/runs">
    Get simulation run details
  </Card>
</CardGroup>

## Request Format

All requests use JSON:

```json theme={null}
{
  "planRules": {
    "plan_name": "Acme Corp ESOP",
    "vesting_schedule": {...}
  },
  "operatingAssumptions": {
    "contribution_policy": {...}
  },
  "initialState": {
    "participants": [...]
  }
}
```

## Response Format

Standard API response structure:

```json theme={null}
{
  "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:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid vesting schedule",
    "details": {
      "field": "vesting_schedule.years",
      "issue": "Must be between 2 and 7"
    }
  }
}
```

## Rate Limits

<CardGroup cols={2}>
  <Card title="Standard Tier" icon="gauge">
    100 requests/hour

    10 simulations/hour
  </Card>

  <Card title="Enterprise Tier" icon="rocket">
    Unlimited requests

    Dedicated infrastructure
  </Card>
</CardGroup>

## SDKs & Libraries

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install villagelabs-repurchase
    ```

    [GitHub Repository](https://github.com/villagelabsdotapp/repurchase-python)
  </Tab>

  <Tab title="JavaScript/TypeScript">
    ```bash theme={null}
    npm install @villagelabs/repurchase-engine
    ```

    [GitHub Repository](https://github.com/villagelabsdotapp/repurchase-js)
  </Tab>

  <Tab title="REST API">
    Direct HTTP calls to `api.villagelabs.com/v1`

    Works with any language/tool
  </Tab>
</Tabs>

## Data Schemas

<CardGroup cols={3}>
  <Card title="PlanRules" icon="scale-balanced" href="/api-reference/schemas/plan-rules">
    Legal framework schema
  </Card>

  <Card title="OperatingAssumptions" icon="chart-mixed" href="/api-reference/schemas/operating-assumptions">
    Strategy configuration schema
  </Card>

  <Card title="Response Formats" icon="file-code" href="/api-reference/schemas/responses">
    Output data structures
  </Card>
</CardGroup>

## Webhooks

Subscribe to simulation events:

```json theme={null}
{
  "event": "simulation.completed",
  "simulation_id": "sim_2024_001",
  "status": "completed",
  "webhook_url": "https://your-app.com/webhooks/simulations"
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Validate Inputs Locally" icon="clipboard-check">
    Use SDK validation methods before making API calls to catch errors early
  </Accordion>

  <Accordion title="Cache Results" icon="database">
    Store simulation results locally; re-run only when inputs change
  </Accordion>

  <Accordion title="Use Async Processing" icon="clock">
    For long-running simulations, use webhooks instead of polling
  </Accordion>

  <Accordion title="Handle Errors Gracefully" icon="shield">
    Implement retry logic with exponential backoff for transient errors
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Run Simulation" icon="play" href="/api-reference/simulate">
    Execute your first API simulation
  </Card>

  <Card title="Manage Scenarios" icon="folder" href="/api-reference/scenarios">
    Create and organize scenarios
  </Card>

  <Card title="View Schemas" icon="file-code" href="/api-reference/schemas/plan-rules">
    Complete schema reference
  </Card>

  <Card title="Examples" icon="code" href="/examples/basic-simulation">
    See full code examples
  </Card>
</CardGroup>

## Support

<Card title="Need Help?" icon="headset">
  **Email:** [support@villagelabs.com](mailto:support@villagelabs.com)

  **Documentation:** You're reading it!

  **GitHub Issues:** Report bugs and request features
</Card>