Note
If you feel something is missing from this API, please let us know. It may be easy to add, and helps make a better API. :)
Applications using this API
Libraries
API functions
Errors
Errors are signalled using standard HTTP status code in the response (eg 404 for "Not Found", 200 for "Success", etc).
When an error occurs, the response body will be a JSON object with an "error" field containing a text description of the problem as returned from DBHub.io. For example:
{
  "error": "The requested database wasn't found"
}
Branches
Query URL
Description
Returns the list of branches for a database
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
Return values (JSON)
The return value is a JSON object containing the default branch name, and a "branches" object with the details for each of the branches
Name
Type
Description
default_branch
string
The name of the default branch for the database. eg: "master"
branches
object
Contains details of all branches in the database, as an unordered set of "branch name": { branch details } pairs
branches → [branch name]
string
The name of a branch in the database. eg: "master"
branches → [branch object] → commit
string
The commit ID of the branch HEAD
branches → [branch object] → commit_count
number
The number of commits in the branch
branches → [branch object] → description
string
A free form text description for the branch
Example
To return the list of branches in dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" https://api.dbhub.io/v1/branches
Output:
{
  "branches": {
    "master": {
      "commit": "cb70855613d30019055a4d907b832c10014b0393556fc282e6b7d2803e2e9d59",
      "commit_count": 2,
      "description": "Our main development branch"
    }
  },
  "default_branch": "master"
}
Columns
Query URL
Description
Returns the details of all columns in a table or view, as per the SQLite "table_info" PRAGMA.
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
table
The name of the table or view to return column information for
Return values (JSON)
The return value is a JSON array, containing the details of each column in JSON objects.
Name
Type
Description
column_id
number
The numeric position of the column in the table or view, with the first column starting at 0
name
string
The name of the column
data_type
string
The data type of the column
not_null
boolean
Whether the column can be set to NULL
default_value
string
The default value for the column, if any
primary_key
number
This is set to zero for columns that are not part of the primary key, and is the index of the column in the primary key for columns that are part of the primary key
Example
To return the list of columns in the "table1" table of dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" -F table="table1" https://api.dbhub.io/v1/columns
Output:
[
  {
    "column_id": 0,
    "name": "id",
    "data_type": "INTEGER",
    "not_null": false,
    "default_value": "",
    "primary_key": 1,
    "autoinc": false,
    "collation_seq": ""
  },
  {
    "column_id": 1,
    "name": "Name",
    "data_type": "TEXT",
    "not_null": false,
    "default_value": "",
    "primary_key": 0,
    "autoinc": false,
    "collation_seq": ""
  }
]
Commits
Query URL
Description
Returns the details of all commits for a database
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
Return values (JSON)
The return value is a JSON object containing the details of all commits in the database
Name
Type
Description
[commit id]
string
The unique ID of the commit. This is a SHA256 of the contained values.
[commit id] → author_email
string
The email address of the person who added created this commit
[commit id] → author_name
string
The name of the person who added created this commit
[commit id] → committer_email
string
The email address of the person who added the commit to this database, if different from the author
[commit id] → committer_name
string
The name of the person who added the commit to this database, if different from the author
[commit id] → id
string
The unique ID of this commit
[commit id] → message
string
A free form text description for this commit
[commit id] → other_parents
array
A list of other parent commit IDs
[commit id] → parent
string
The ID of the parent commit
[commit id] → timestamp
string
When this commit was created
[commit id] → tree
object
Contains the information of the filesystem tree for this commit
[commit id] → tree → id
string
A unique id for this tree entry
[commit id] → tree → entries
Array
And array of tree entries, with one entry per filesystem object in the commit
[commit id] → tree → entries → entry_type
string
The type of entry. Only "db" so far.
[commit id] → tree → entries → last_modified
string
When this tree entry was created
[commit id] → tree → entries → licence
string
The sha256 (a unique identifier) of the licence for the database (up to this commit)
[commit id] → tree → entries → name
string
The name of the database file
[commit id] → tree → entries → sha256
string
The sha256 of the database file
[commit id] → tree → entries → size
number
The size of the database file in bytes
Example
To return the list of commits in dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" https://api.dbhub.io/v1/commits
Output:
{
  "cb70855613d30019055a4d907b832c10014b0393556fc282e6b7d2803e2e9d59": {
    "author_email": "justin@postgresql.org",
    "author_name": "Justin Clift",
    "committer_email": "",
    "committer_name": "",
    "id": "cb70855613d30019055a4d907b832c10014b0393556fc282e6b7d2803e2e9d59",
    "message": "",
    "other_parents": null,
    "parent": "ee752d746655cf141971a5db011aec2f395213cf76d8aa9c613a6c16902df521",
    "timestamp": "2020-07-30T12:22:46.714728207Z",
    "tree": {
      "id": "2a1969fe687ba6419ccea8c6ab104741fc5fa0195d32e8cf142e422dee2d41f1",
      "entries": [
        {
          "entry_type": "db",
          "last_modified": "2020-07-30T12:09:10Z",
          "licence": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499",
          "name": "Join Testing.sqlite",
          "sha256": "0ef691111cde5923085a2385a609c858555ec7101e3cda30dac94d1cf47429dc",
          "size": 12288
        }
      ]
    }
  },
  "ee752d746655cf141971a5db011aec2f395213cf76d8aa9c613a6c16902df521": {
    "author_email": "justin@postgresql.org",
    "author_name": "Justin Clift",
    "committer_email": "",
    "committer_name": "",
    "id": "ee752d746655cf141971a5db011aec2f395213cf76d8aa9c613a6c16902df521",
    "message": "Initial database upload, using licence CC0.",
    "other_parents": null,
    "parent": "",
    "timestamp": "2020-04-20T12:04:37.379693233Z",
    "tree": {
      "id": "51c87fe5a7b261e8f04d319ed50810198577b44a95701bc14917560d461948e0",
      "entries": [
        {
          "entry_type": "db",
          "last_modified": "2020-04-20T12:04:37.373275716Z",
          "licence": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499",
          "name": "Join Testing.sqlite",
          "sha256": "488f863d685125a82b1112304c936a8c8769d061a114ec466fd21bb882dc8d17",
          "size": 12288
        }
      ]
    }
  }
}
Databases
Query URL
Description
Returns the list of databases in the requesting users account
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
Return values (JSON)
The returned data is an array of JSON string values. Each string is the name of a database in your account.
Example
To return the list of databases in dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" https://api.dbhub.io/v1/databases
Output:
[
  "Join Testing.sqlite",
  "Assembly Election 2017.sqlite",
  "DB4S daily users by country.sqlite",
  "Marine Litter Survey (Keep Northern Ireland Beautiful).sqlite"
]
Diff
Query URL
Description
Generates a diff between two databases or two versions of a database
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner_a
The owner of the first database
dbname_a
The name of the first database
commit_a
The commit ID of the first database
dbowner_b
The owner of the second database
dbname_b
The name of the second database
commit_b
The commit ID of the second database
Return values (JSON)
TBD
TBD
Example
To return the list of diff in dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner_a="justinclift" -F dbname_a="Join Testing.sqlite" -F commit_a="cb70855613d30019055a4d907b832c10014b093556fc282e6b7d2803e2e9d59" \
    -F commit_b="218f28dcb54819e7e4b77e36012ff15d667ca55946c56ef6370b13bdc3ddf528" -F merge="preserve_pk" https://api.dbhub.io/v1/diff
Output:
{
  "diff": [
    {
      "object_name": "indexId",
      "object_type": "index",
      "schema": {
        "action_type": "add",
        "sql": "CREATE INDEX \"indexId\" ON \"table1\" (\n\t\"id\"\n);"
      },
      "data": null
    },
    {
      "object_name": "indexName",
      "object_type": "index",
      "schema": {
        "action_type": "add",
        "sql": "CREATE INDEX \"indexName\" ON \"table1\" (\n\t\"Name\"\tASC\n);"
      },
      "data": null
    }
  ]
}
Download
Query URL
Description
Returns the requested SQLite database file as a stream of bytes
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
Return values (JSON)
The database file is returned as a stream of bytes in the request body
Example
To download dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" https://api.dbhub.io/v1/download
Indexes
Query URL
Description
Returns the details of all indexes in a SQLite database
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
Return values (JSON)
The return value is a JSON array, containing the details of each index in JSON objects
Name
Type
Description
name
string
The name of the index
table
string
The name of the table the index belongs to
columns
array
An array of objects listing the columns in the index
columns → id
number
The numeric position of the column in the index, with the first column starting at 0
columns → name
string
The name of the column in the table
Example
To return the list of indexes in dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" https://api.dbhub.io/v1/indexes
Output:
[
  {
    "name": "indexId",
    "table": "table1",
    "columns": [
      {
        "id": 0,
        "name": "id"
      }
    ]
  },
  {
    "name": "indexName",
    "table": "table1",
    "columns": [
      {
        "id": 1,
        "name": "Name"
      }
    ]
  }
]
Metadata
Query URL
Description
Returns the commit, branch, release, tag and web page information for a database
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
Return values (JSON)
The return value is a JSON object, containing the details of all branches, commits, releases, tags, the default branch, and the web page of the commit.
Refer to the return value information for each of the functions for details:
Example
To return the list of metadata in dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" https://api.dbhub.io/v1/metadata
Output:
{
  "branches": {
    "master": {
      "commit": "cb70855613d30019055a4d907b832c10014b0393556fc282e6b7d2803e2e9d59",
      "commit_count": 2,
      "description": ""
    }
  },
  "commits": {
    "cb70855613d30019055a4d907b832c10014b0393556fc282e6b7d2803e2e9d59": {
      "author_email": "justin@postgresql.org",
      "author_name": "Justin Clift",
      "committer_email": "",
      "committer_name": "",
      "id": "cb70855613d30019055a4d907b832c10014b0393556fc282e6b7d2803e2e9d59",
      "message": "",
      "other_parents": null,
      "parent": "ee752d746655cf141971a5db011aec2f395213cf76d8aa9c613a6c16902df521",
      "timestamp": "2020-07-30T12:22:46.714728207Z",
      "tree": {
        "id": "2a1969fe687ba6419ccea8c6ab104741fc5fa0195d32e8cf142e422dee2d41f1",
        "entries": [
          {
            "entry_type": "db",
            "last_modified": "2020-07-30T12:09:10Z",
            "licence": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499",
            "name": "Join Testing.sqlite",
            "sha256": "0ef691111cde5923085a2385a609c858555ec7101e3cda30dac94d1cf47429dc",
            "size": 12288
          }
        ]
      }
    },
    "ee752d746655cf141971a5db011aec2f395213cf76d8aa9c613a6c16902df521": {
      "author_email": "justin@postgresql.org",
      "author_name": "Justin Clift",
      "committer_email": "",
      "committer_name": "",
      "id": "ee752d746655cf141971a5db011aec2f395213cf76d8aa9c613a6c16902df521",
      "message": "Initial database upload, using licence CC0.",
      "other_parents": null,
      "parent": "",
      "timestamp": "2020-04-20T12:04:37.379693233Z",
      "tree": {
        "id": "51c87fe5a7b261e8f04d319ed50810198577b44a95701bc14917560d461948e0",
        "entries": [
          {
            "entry_type": "db",
            "last_modified": "2020-04-20T12:04:37.373275716Z",
            "licence": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499",
            "name": "Join Testing.sqlite",
            "sha256": "488f863d685125a82b1112304c936a8c8769d061a114ec466fd21bb882dc8d17",
            "size": 12288
          }
        ]
      }
    }
  },
  "default_branch": "master",
  "releases": {
    "v0.0.1": {
      "commit": "ee752d746655cf141971a5db011aec2f395213cf76d8aa9c613a6c16902df521",
      "date": "2020-08-05T21:24:03.661192606+10:00",
      "description": "Initial release! :)",
      "email": "justin@postgresql.org",
      "name": "Justin Clift",
      "size": 12288
    },
    "v0.0.2": {
      "commit": "cb70855613d30019055a4d907b832c10014b0393556fc282e6b7d2803e2e9d59",
      "date": "2020-08-05T21:25:14.160011088+10:00",
      "description": "Another release",
      "email": "justin@postgresql.org",
      "name": "Justin Clift",
      "size": 12288
    }
  },
  "tags": {
    "first": {
      "commit": "ee752d746655cf141971a5db011aec2f395213cf76d8aa9c613a6c16902df521",
      "date": "2020-08-05T21:27:36.493329953+10:00",
      "description": "First tag",
      "email": "justin@postgresql.org",
      "name": "Justin Clift"
    },
    "second": {
      "commit": "cb70855613d30019055a4d907b832c10014b0393556fc282e6b7d2803e2e9d59",
      "date": "2020-08-05T21:27:50.253727352+10:00",
      "description": "Second tag",
      "email": "justin@postgresql.org",
      "name": "Justin Clift"
    }
  },
  "web_page": "https://dbhub.io/justinclift/Join Testing.sqlite"
}
Query
Query URL
Description
Run a SQLite query on a database
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
sql
The SQL query, Base64 encoded
Return values (JSON)
The returned data (JSON) is in a fairly verbose format, with each field returned from the SQL query having three components:
  • The name of the return field
  • The type of data in the field (numeric)
  • The value of the field
Example
To run this query on dbhub.io/justinclift/Join Testing.sqlite:
SELECT table1.Name, table2.value
FROM table1 JOIN table2
USING (id)
ORDER BY table1.id;
Using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" \
    -F sql="U0VMRUNUIHRhYmxlMS5OYW1lLCB0YWJsZTIudmFsdWUKRlJPTSB0YWJsZTEgSk9JTiB0YWJsZTIKVVNJTkcgKGlkKQpPUkRFUiBCWSB0YWJsZTEuaWQ7" \
    https://api.dbhub.io/v1/query
Output:
[[{"Name":"Name","Type":3,"Value":"Foo"} ... (shortened for clarity)
Note - If you'd like the data to be returned in a different format, please let us know. It's easy for us to add new output formats, and helps make a better API. :)
Releases
Query URL
Description
Returns the details of all releases for a database
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
Return values (JSON)
The return value is a JSON object containing the details of all the releases of the database
Name
Type
Description
[release name]
string
The name of the release. eg: "v0.0.1"
[release name] → commit
string
The commit ID the release corresponds to
[release name] → date
string
When the release was created
[release name] → description
string
A free form text description of the release
[release name] → email
string
The email address of the person who created the release
[release name] → name
string
The name of the person who created the release
[release name] → size
number
The file size of the release database, in bytes
Example
To return the list of releases in dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" https://api.dbhub.io/v1/releases
Output:
{
  "v0.0.1": {
    "commit": "ee752d746655cf141971a5db011aec2f395213cf76d8aa9c613a6c16902df521",
    "date": "2020-08-05T21:24:03.661192606+10:00",
    "description": "Initial release! :)",
    "email": "justin@postgresql.org",
    "name": "Justin Clift",
    "size": 12288
  },
  "v0.0.2": {
    "commit": "cb70855613d30019055a4d907b832c10014b0393556fc282e6b7d2803e2e9d59",
    "date": "2020-08-05T21:25:14.160011088+10:00",
    "description": "Another release",
    "email": "justin@postgresql.org",
    "name": "Justin Clift",
    "size": 12288
  }
}
Tables
Query URL
Description
Returns the list of tables in a SQLite database
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
Return values (JSON)
The returned data is an array of JSON string values. Each string is the name of a table in the database.
Example
To return the list of tables in dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" https://api.dbhub.io/v1/tables
Output:
[
  "table1",
  "table2",
  "table3"
]
Tags
Query URL
Description
Returns the details of all tags for a database
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
Return values (JSON)
The return value is a JSON object containing the details of all the tags in the database
Name
Type
Description
[tag name]
string
The name of the tag. eg: "my first tag"
[tag name] → commit
string
The commit ID the tag corresponds to
[tag name] → date
string
When the tag was created
[tag name] → description
string
A free form text description of the tag
[tag name] → email
string
The email address of the person who created the tag
[tag name] → name
string
The name of the person who created the tag
[tag name] → size
number
The file size of the tagged database, in bytes
Example
To return the list of tags in dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" https://api.dbhub.io/v1/tags
Output:
{
  "first": {
    "commit": "ee752d746655cf141971a5db011aec2f395213cf76d8aa9c613a6c16902df521",
    "date": "2020-08-05T21:27:36.493329953+10:00",
    "description": "First tag",
    "email": "justin@postgresql.org",
    "name": "Justin Clift"
  },
  "second": {
    "commit": "cb70855613d30019055a4d907b832c10014b0393556fc282e6b7d2803e2e9d59",
    "date": "2020-08-05T21:27:50.253727352+10:00",
    "description": "Second tag",
    "email": "justin@postgresql.org",
    "name": "Justin Clift"
  }
}
Views
Query URL
Description
Returns the list of views in a SQLite database
Parameters (POST)
apikey
Your API key. These can be generated in your Settings page, when logged in.
dbowner
The owner of the database to query
dbname
The name of the database
Return values (JSON)
The returned data is an array of JSON string values. Each string is the name of a view in the database.
Example
To return the list of views in dbhub.io/justinclift/Join Testing.sqlite using curl, it would be:
$ curl -F apikey="YOUR_API_KEY_HERE" -F dbowner="justinclift" -F dbname="Join Testing.sqlite" https://api.dbhub.io/v1/views
Output:
[
  "joinedView",
  "view1",
  "view2"
]