API

Overview

This documentation outlines instructions on the usage of the Fairly Platform API.

Authentication

Each endpoint requires an Access Token in the API request header in the form of a bearer token. To get this token:

1. Log in to the Fairly Platform
2. At the main dashboard, click on your user name button
3. Select Settings
4. Select the Personal Access Token tab
5. Click on New Token button
6. Enter a description and click Generate
7. Copy the generated token and keep it safe. This token will not be displayed again.
8. Use this token to access the APIs.

Getting Project Information

endpoint: GET /service-api/v1/project-info/:projectId

header: Authorization: Bearer your-personal-access-token

response:

Code: 200

Description: Request Success. Returns the test requirements for the project given the project id

{
    "projectId": "project_id",
    "context": [
        {
            "autoGenerate": true,
            "protectedClasses": [
                ...
            ]
        }
    ],
    "assessments": [
        {
            "assessmentId": "assessment_id",
            "policyId": "policy_id",
            "policyName": "Policy_Name",
            "controlBundles": [
                {
                    "controlBundleId": "control_bundle_id",
                    "controlBundleName": "control_bundle_name",
                    "algorithmId": "algorighm_id",
                    "controls": [
                        {
                            "controlIdentifier": "accuracy_score"
                        },
                        {
                            "controlIdentifier": "demographic_parity"
                        },

Code: 401

Description: User is not authorized.

Uploading Test Results

endpoint: POST /service-api/v1/test-results/:projectId

header:

Authorization: Bearer your-personal-access-token Content-Type: application/json

payload:

{
    "projectId": "project_id",
    "assessments": [
        {
            "datasets": [
                {
                    "name": "data_set_name",
                    "uri": "file://data_set_location",
                    "sensitive_features": [
                        "race"
                    ]
                }
            ],
            "model": {
                "modelName": "model_name",
                "modelConfig": {
                    "model_type": "model_type",
                    "model_params": {}
                }
            },
            "assessmentId": "assessment_id",
            "policyId": "policy_id",
            "policyName": "policy_name",
            "executionDate": execution_date_as_integer,
            "controlBundles": [
                {
                    "controlBundleId": "control_bundle_id",
                    "controlBundleName": "control_bundle_name",
                    "controls": [
                        {
                            "controlIdentifier": "control_identifier_1",
                            "testValue": {
                                "value": value_as_number,
                                "valueType": "NUMBER"
                            },
                            "labels": [
                                "label1",
                                "label2"
                            ]
                        },
                        {
                            "controlIdentifier": "control_identifier_2",
                            "testValue": {
                                "value": value_as_number,
                                "valueType": "NUMBER"
                            },
                            "labels": [
                                "label1",
                                "label2"
                            ]
                        },

response:

Code: 200

Description: Request Success. Results added to the project.

Code: 400

Description: Project ID does not match

Code: 401

Description: User is not authorized