API

The Hub's API provides a programmatic way to retrieve Generator Models in order to Generate Synthetic data via the Python client.

The API is JSON based, which means metadata responses are always returned as JSON data structures and all request parameters should be sent in JSON format.

Granting Access

In order to access Generator Models via the API, you need two things:

  1. Your API key.

    This is visible at the top of your Dashboard page. Click on your user icon at the top right of the page and select "Dashboard".

    By default the API key is hidden for security reasons. To view and hide it, click on the eye icon on the right.

  2. Team Membership.

    API access control is done via Teams. A high-level overview of this concept is:

    • Teams are given permissions to access some number of Generators
    • Access to a Generator is within a certain range of epsilon (privacy) values
    • To gain access to the Team's Generators, you must be a Member of the Team

Data Structure

In order to understand the API responses, you need to understand how Hazy structures its data in order to enable advanced workflows and exploration.

Each Generator has multiple "versions". A Version represents new set of Generator Models either based on the existing Synthesiser trained on an updated data set or an updated Synthesiser trained on the same data set, or both.

For every version Generator Models are grouped according to the Synthesiser that produced them. This allows multiple Synthesiser algorithms to co-exist, each being run against the same data set, either for comparison of different techniques or potentially tuned for different use cases.

For every version-synthesiser combination, there are multiple Generator Models, each trained with a varying level of differential privacy applied (represented by varying epsilon values -- higher epsilon, less privacy).

So in order to retrieve a Generator Model you need to specify:

  1. The Generator you're interested in
  2. The Version you require (defaulting to the most current)
  3. The Synthesiser used. In most cases a Generator Version will only have a single Synthesiser
  4. The privacy/epsilon value required (defaulting to the least private setting available to you based on your Team access)

Authentication

Authentication is done via the custom hazy-api-key HTTP header.

Example Session

Here's an example session showing the API being queried for a suitable Generator Model and the subsequent download of the Generator Model file.

In all the examples below, we will use an API key of RDLTtDe5RBDF9O1LCfhSJAHv13wxeuXi78kqxgA8z3Q=



# Get list of Generators

$ curl -H 'hazy-api-key: RDLTtDe5RBDF9O1LCfhSJAHv13wxeuXi78kqxgA8z3Q=' \
       -s https://hub.hazy.com/api/v2/generators

# [
#   {
#     "description": "",
#     "generator_id": "07f9da01-833a-4915-98c1-f9dba981caa2",
#     "name": "Customer Accounts",
#     "uri": "northwind-traders/customer-accounts"
#   }
# ]

## Search models with simple query

curl -s \
     -H 'hazy-api-key: RDLTtDe5RBDF9O1LCfhSJAHv13wxeuXi78kqxgA8z3Q=' \
     -H 'Content-type: application/json' \
     -d '{"epsilon":"0.1"}' \
     -X POST \
     https://hub.hazy.com/api/v2/generators/07f9da01-833a-4915-98c1-f9dba981caa2/model
    
# {
#   "algorithm": "northwind-traders/project-privb:20201015T160309",
#   "epsilon": "0.1",
#   "generator": "northwind-traders/customer-accounts:20201120T130600",
#   "generator_id": "07f9da01-833a-4915-98c1-f9dba981caa2",
#   "id": "01EQJZS8T3C39M0AS9S2X9WAK6",
#   "similarity": 83.0,
#   "uri": "northwind-traders/customer-accounts/northwind-traders/project-privb@0.1:20201120T130600",
#   "utility": 91.3
# }

## Return the "best" model (highest epsilon or not differentially private) at the latest version
## by not specifying any filters in the model query

curl -s \
     -H 'hazy-api-key: RDLTtDe5RBDF9O1LCfhSJAHv13wxeuXi78kqxgA8z3Q=' \
     -H 'Content-type: application/json' \
     -d '{}' \
     -X POST \
     https://hub.hazy.com/api/v2/generators/07f9da01-833a-4915-98c1-f9dba981caa2/model

# {
#   "algorithm": "northwind-traders/project-privb:20201015T160309",
#   "epsilon": null,
#   "generator": "northwind-traders/customer-accounts:20201120T130600",
#   "generator_id": "07f9da01-833a-4915-98c1-f9dba981caa2",
#   "id": "01F249Z1FPJNP9RSBX70ZB0P6B",
#   "similarity": 89.0,
#   "uri": "northwind-traders/customer-accounts/northwind-traders/project-privb@-:20201120T130600",
#   "utility": 95.3
# }

## List versions

curl -s \
     -H 'hazy-api-key: RDLTtDe5RBDF9O1LCfhSJAHv13wxeuXi78kqxgA8z3Q=' \
     https://hub.hazy.com/api/v2/generators/07f9da01-833a-4915-98c1-f9dba981caa2/versions

# [
#   {
#     "algorithms": {
#       "northwind-traders/project-privb": {
#         "algorithm": {
#           "description": null,
#           "differentially_private": true,
#           "name": "project-privb",
#           "uri": "northwind-traders/project-privb",
#           "version": {
#             "created_at": "2020-11-20T13:30:27.488491Z",
#             "version": "20201015T160309"
#           }
#         },
#         "models": [
#           {
#             "algorithm": "northwind-traders/project-privb:20201015T160309",
#             "epsilon": null,
#             "generator": "northwind-traders/customer-accounts:20201120T130600",
#             "generator_id": "07f9da01-833a-4915-98c1-f9dba981caa2",
#             "id": "01F249Z1FPJNP9RSBX70ZB0P6B",
#             "similarity": 89.0,
#             "uri": "northwind-traders/customer-accounts/northwind-traders/project-privb@-:20201120T130600",
#             "utility": 95.3
#           },
#           {
#             "algorithm": "northwind-traders/project-privb:20201015T160309",
#             "epsilon": "0.1",
#             "generator": "northwind-traders/customer-accounts:20201120T130600",
#             "generator_id": "07f9da01-833a-4915-98c1-f9dba981caa2",
#             "id": "01EQJZS8T3C39M0AS9S2X9WAK6",
#             "similarity": 83.0,
#             "uri": "northwind-traders/customer-accounts/northwind-traders/project-privb@0.1:20201120T130600",
#             "utility": 91.3
#           }
#         ]
#       }
#     },
#     "version": "20201120T130600"
#   }
# ]

Endpoints

GET /api/v2/generators

Retrieve a list of the generators you have access to.

Response format:

[ // list of Generators
  { // Generator instance
    "description": "Description of Generator", // Optional
    "name": "Generator Name",
    "generator_id": "07f9da01-833a-4915-98c1-f9dba981caa2",
    "uri": "/my-organisation/generator-name" // 
  },
  {
    "description": "",
    "name": "Another Generator Name",
    "generator_id": "4e5e8104-51aa-44c2-a3a9-8cb4f426cb7d",
    "uri": "/my-organisation/another-generator-name"
  },
  // etc...
]

Example request:

curl -H 'hazy-api-key: RDLTtDe5RBDF9O1LCfhSJAHv13wxeuXi78kqxgA8z3Q=' \
    https://hub.hazy.com/api/v2/generators

The generator_id is used in all further requests, when specifying a generator

GET /api/v2/generators/<generator_id>/versions

Retrieve a list of all available versions of the given Generator.

Response format:

[ // list of Versions, most recent first
  { // Version instance
    "algorithms": { // List of synthesisers
      "northwind-traders/project-privb": { // Synthesiser instance
        "algorithm": { // Synthesiser details
          "description": null,
          "differentially_private": true,
          "name": "project-privb",
          "uri": "northwind-traders/project-privb",
          "version": {
            "created_at": "2020-11-20T13:30:27.488491Z",
            "version": "20201015T160309"
          }
        },
        "models": [ // list of models available for this Version
          { // Model instance with epsilon 0.1
            "algorithm": "northwind-traders/project-privb:20201015T160309",
            "epsilon": "0.1",
            "generator": "northwind-traders/customer-accounts:20201120T130600",
            "generator_id": "4e5e8104-51aa-44c2-a3a9-8cb4f426cb7d",
            "id": "01EQJZS8T3C39M0AS9S2X9WAK6", // Model ID
            "similarity": 88.0,
            "uri": "northwind-traders/customer-accounts/northwind-traders/project-privb@0.1:20201120T130600",
            "utility": 98.3
          },
          { // Model instance with epsilon 0.01
            "algorithm": "northwind-traders/project-privb:20201015T160309",
            "epsilon": "0.01",
            "generator": "northwind-traders/customer-accounts:20201120T130600",
            "generator_id": "4e5e8104-51aa-44c2-a3a9-8cb4f426cb7d",
            "id": "01EQJZS8T9QF1200CHATP3SQPW",
            "similarity": 85.0,
            "uri": "northwind-traders/customer-accounts/northwind-traders/project-privb@0.01:20201120T130600",
            "utility": 92.1
          }
        ]
      }
    },
    "version": "20201120T130600" // the Version number
  },
  // Other versions available
  {
    "algorithms": {
        // ...
    },
    "version": "20201020T130512" // the Version number
  }
]


Example request:

curl -H 'hazy-api-key: RDLTtDe5RBDF9O1LCfhSJAHv13wxeuXi78kqxgA8z3Q=' \
    https://hub.hazy.com/api/v2/generators/4e5e8104-51aa-44c2-a3a9-8cb4f426cb7d/versions

GET /api/v2/models/<model_id>

Download a Generator Model file.

<model_id> is the ID of a Generator Model as returned from the list Versions endpoint, e.g. from above 01EQJZS8T9QF1200CHATP3SQPW

Response format:

The response is the binary Generator Model file.

Example request:

curl -H 'hazy-api-key: RDLTtDe5RBDF9O1LCfhSJAHv13wxeuXi78kqxgA8z3Q=' \
    https://hub.hazy.com/api/v2/models/01EQJZS8T9QF1200CHATP3SQPW > model-01EQJZS8T9QF1200CHATP3SQPW.hazymodel

POST /api/v2/generators/<generator_id>/models

Search the available models based on the query parameters and return the best matching model. "Best" means the model with the highest epsilon (lowest privacy) available.

Parameters

The body should be a JSON formatted set of filters to apply to the models for the given Generator.

  • epsilon: Specify the privacy value of the returned model, should be:

    • a floating point number formatted as a string, e.g. "0.1", "1.0" in order to specify a model with a specific epsilon value,
    • false to specify a model with differential privacy disabled, or
    • null to indicate that the epsilon value is unimportant
  • version: Specify the Version to return, e.g. "20201020T130512" or null to use the most recent version

  • algorithm: Specify the Synthesiser to return, e.g. "northwind-traders/project-privb" or null to not specify the Synthesiser

Example query:

// return the best model from version "20201020T130512" with no differential privacy
{
  "epsilon": false,
  "version": "20201020T130512",
  "algorithm": null
}

// return the best model (from any synthesiser) from the most recent version with an epsilon of 0.1
{
  "epsilon": "0.1",
  "version": null,
  "algorithm": null
}

// return the best model (from any synthesiser) from the most recent version, equivalent to `{}` or no parameters at all
{
  "epsilon": null,
  "version": null,
  "algorithm": null
}

Response format:

{
  "algorithm": "northwind-traders/project-privb:20201015T160309",
  "epsilon": "0.1",
  "generator": "northwind-traders/customer-accounts:20201120T130600",
  "generator_id": "07f9da01-833a-4915-98c1-f9dba981caa2",
  "id": "01EQJZS8T3C39M0AS9S2X9WAK6",
  "similarity": 83.0,
  "uri": "northwind-traders/customer-accounts/northwind-traders/project-privb@0.1:20201120T130600",
  "utility": 91.3
}

Example request:

curl -H 'hazy-api-key: RDLTtDe5RBDF9O1LCfhSJAHv13wxeuXi78kqxgA8z3Q=' \
    -H 'Content-type: application/json' \
    -X POST \
    -d '{"epsilon":"0.1"}' \
    https://hub.hazy.com/api/v2/generators/07f9da01-833a-4915-98c1-f9dba981caa2/models