variable

variable API

One Pager Swagger UI ReDoc

Welcome to the Variable API! This API allows you to programmatically run pricing simulations, interactively build demand profiles, and perform powerful Exploratory Data Analysis (EDA) on the resulting scenario datasets.

1. Authentication

All endpoints in the Variable API (under the /v1/ prefix) are secured and require tenant-isolated authentication.

You must pass your JSON Web Token (JWT) in the Authorization header of every request:

Authorization: Bearer <your_access_token>

2. Core Concepts

  • Seed: A foundational Parquet dataset containing survey responses and demographic data.
  • Scenario: A generated dataset resulting from a simulation. It builds upon a seed by appending metrics like willingness_to_pay.
  • Parquet: The highly efficient columnar storage format used for all datasets. Our API extracts human-readable labels from Parquet metadata automatically.

3. Demand Builder API

The Demand Builder allows you to run an active learning loop to iteratively determine the willingness-to-pay for various customer profiles.

GET /v1/demand-builder/seeds

Retrieves the list of foundational .parquet files available for simulations.

  • Response: {"files": ["seed_1.parquet", "seed_2.parquet"]}
POST /v1/demand-builder/init

Begins a new simulation by passing an Ideal Customer Profile (ICP) and the initial Willingness to Pay (WTP).

  • Payload: DemandBuilderInitRequest
{
  "offer": "Premium Subscription",
  "price_point": 49.99,
  "icp_attributes": {"IS_REGION": "1.0"},
  "icp_wtp": 60.0,
  "prioritized_questions": ["IS_REGION", "IS_AGE"],
  "origin_parquet_file": "seed_1.parquet"
}
POST /v1/demand-builder/{scenario_id}/next

Submits the user's evaluation of the previous profiles and returns the next batch of profiles to be evaluated by the active learning engine.

  • Payload: DemandBuilderNextRequest

4. Scenario Retrieval API

Once a scenario is generated, you can query its structure and raw records.

GET /v1/scenarios/

Returns all scenario files available in your workspace.

GET /v1/scenarios/{scenario_id}/schema

Returns the data types for all columns.

GET /v1/scenarios/{scenario_id}/questions

Extracts the human-readable question text and categorical options from the Parquet metadata.

  • Response Format:
{
  "questions": [
    {
      "column": "IS_REGION",
      "text": "What region are you currently in?",
      "options": {"1.0": "North", "2.0": "South"}
    }
  ]
}
GET /v1/scenarios/{scenario_id}/records?limit=50&cursor=0&sort=-willingness_to_pay

Retrieves paginated, filtered raw data rows from the scenario.

5. Exploratory Data Analysis (EDA)

The EDA engine uses Pandas on the backend to perform lightning-fast aggregations on your scenario datasets. Responses are formatted perfectly for charting libraries (like Chart.js).

POST /v1/scenarios/{scenario_id}/functions/eda
  • Payload: EdaQueryRequest
{
  "x_axis": "IS_REGION",
  "y_axis": "IS_GENDER",
  "z_axis": "willingness_to_pay",
  "method": "mean"
}

Supported methods: mean, median, sum, count, min, max.

  • Response: EdaQueryResponse

The response automatically maps numerical categories back to their human-readable strings based on the Parquet metadata.

{
  "labels": ["North", "South", "East", "West"],
  "datasets": [
    {
      "label": "Male",
      "data": [45.5, 50.0, null, 42.1]
    },
    {
      "label": "Female",
      "data": [48.0, 52.5, 41.0, 44.0]
    }
  ]
}

6. Playgrounds

If you prefer to interact with the API via a user interface, we provide two HTML playgrounds:

  1. Demand Builder Playground: http://api.tryvariable.com/api/playground/
    Used for running simulations and evaluating profiles.
  2. EDA Dashboard: http://api.tryvariable.com/api/playground/eda/
    Used for visually charting and grouping scenario data.

Error Handling

The API adheres to the RFC 9457 standard for Problem Details. If a request fails, you will receive a structured JSON response:

{
  "type": "https://api.variable.sh/errors/invalid-method",
  "title": "Invalid Aggregation Method",
  "status": 400,
  "detail": "Method 'variance' is not supported.",
  "instance": "/v1/scenarios/123/functions/eda"
}