API

The Dataherald Engine exposes RESTful APIs that can be used to:

• 🔌 Connect to and manage connections to databases

• 🔑 Add context to the engine through scanning the databases, adding database level instructions, adding descriptions to tables and columns and adding golden records

• 🙋‍♀️ Ask natural language questions from the relational data

Our APIs have resource-oriented URL built around standard HTTP response codes and verbs. The core resources are described below.

Database Connections

The database-connections object allows you to define connections to your relational data stores.

Related endpoints are:

• Create database connection – POST api/v1/database-connections

• List database connections – GET api/v1/database-connections

• Update a database connection – PUT api/v1/database-connections/{db_connection_id}

Database connection resource example:

{
    "alias": "string",
    "use_ssh": false,
    "connection_uri": "string",
    "path_to_credentials_file": "string",
    "llm_api_key": "string",
    "ssh_settings": {
        "db_name": "string",
        "host": "string",
        "username": "string",
        "password": "string",
        "remote_host": "string",
        "remote_db_name": "string",
        "remote_db_password": "string",
        "private_key_password": "string",
        "db_driver": "string"
    }
}

Responses

The responses object is created from the answering natural language questions from the relational data.

The related endpoints are:

• add_question – POST api/v1/questions

• add_responses – POST api/v1/responses

• list_responses – GET api/v1/responses

• get_response – GET api/v1/responses/{response_id}

• get_response_file – GET api/v1/responses/{response_id}/file

Response resource example:

{
  "question_id": "string",
  "response": "string",
  "intermediate_steps": [
    "string"
  ],
  "sql_query": "string",
  "sql_query_result": {
    "columns": [
      "string"
    ],
    "rows": [
      {}
    ]
  },
  "sql_generation_status": "INVALID",
  "error_message": "string",
  "exec_time": 0,
  "total_tokens": 0,
  "total_cost": 0,
  "confidence_score": 0,
  "created_at": "2023-10-12T16:26:40.951158"
}

Table Descriptions

The table-descriptions object is used to add context about the tables and columns in the relational database. These are then used to help the LLM build valid SQL to answer natural language questions.

Related endpoints are:

• Scan table description – POST api/v1/table-descriptions/sync-schemas

• Update a table description – PATCH api/v1/table-descriptions/{table_description_id}

• List table description – GET api/v1/table-descriptions

• Get a description – GET api/v1/table-descriptions/{table_description_id}

Table description resource example:

{
    "columns": [{}],
    "db_connection_id": "string",
    "description": "string",
    "examples": [{}],
    "table_name": "string",
    "table_schema": "string"
}

Database Instructions

The database-instructions object is used to set constraints on the SQL that is generated by the LLM. These are then used to help the LLM build valid SQL to answer natural language questions based on your business rules.

Related endpoints are:

• Add database instructions – POST api/v1/{db_connection_id}/instructions

• List database instructions – GET api/v1/{db_connection_id}/instructions

• Update database instructions – PUT api/v1/{db_connection_id}/instructions/{instruction_id}

• Delete database instructions – DELETE api/v1/{db_connection_id}/instructions/{instruction_id}

Instruction resource example:

{
    "db_connection_id": "string",
    "instruction": "string",
}