FeatureBase
Powered by Redocly

FeatureBase Cloud REST API (2.0.0)

Download OpenAPI specification:Download

URL: https://www.featurebase.com Terms of Service

Introduction

FeatureBase Cloud allows you to launch FeatureBase clusters as a managed service in the cloud.

Version 2 Updates

  • Table creation or updates can be done through SQL.
  • Data Ingestion can also be done through SQL.

Please refer to SQL documentation https://docs.featurebase.com/docs/sql-guide/sql-guide-home/

Data Model

Customers can use REST APIs to perform CRUDL (Create/Read/Update/Delete/List) operations on their cloud resources. Every resource belongs to an organization. Each API resource type can be managed via a dedicated API endpoint. Resource types include:

  • Databases
  • Query
  • Invites
  • Users
  • Orgs
  • Service Properties
  • Roles

API Errors

All API errors include a JSON body with a human-readable message and a machine-readable error code designed for programmatic parsing. For example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 469
{
  "code": "InvalidParameter",
  "message": "The value for 'count' has to be greater than 0."
}

The following table describes the most common error types and their usage:

HTTP Response Status Code Error Code Example Message Client Retry Behavior
400 InvalidParameter Parameter ‘count’ cannot be empty No
400 MissingParameter Missing required parameter ‘count’ No
400 InvalidBody The request body is incorrectly formatted No
400 InvalidContentType The specified content-type is not supported. No
400 ResourceLimitExceeded The limit for number of databases has been exceeded. No
400 ResourceThroughputExceeded The provisioned resource capacity was exceeded. Retry with backoff
400 RelatedResourceNotFound Message should include which (non-URI) resources were not found. No
400 Bad Request Message includes the SQL3 error response. No
401 Unauthorized Authorization failed No
401 MissingAuthenticationToken Missing request authentication token No
404 ResourceNotFound Resource not found. No
408 RequestTimeout The client cancelled the request or failed to send a full request. Yes
409 ResourceAlreadyExists Requested resource already exists. No
409 IncorrectState The referenced resource is not ready to process requests. Retry with backoff
413 PayloadTooLarge The size of the request payload exceeds the maximum size permitted. No
422 QueryExecutionError There was an error executing query No
429 RequestLimitExceeded API rate limit exceeded. Retry with backoff
500 InternalServerError Unexpected error Retry with backoff

Database States

The following table describes each database state:

Database Status Definition Can query data
CREATING FeatureBase Cloud has received the signal to start provisioning a database. No
PROVISIONING A database is being created. No
RUNNING Database is running normally. Users may run queries. Yes
RESTORING Restoring data from a backup. No
BACKUP Creating a backup of the database. No
DELETING FeatureBase Cloud has received the signal to start deprovisioning a database. No
DEPROVISIONING Database is being deprovisioned (deleted). No
DELETED Deprovision completed successfully. No
FAILED Unrecoverable. Data is lost or Database failed to be provisioned. No
FROZEN There was a problem with backup and no new operations can be done on the database. No

Feedback

Were these docs helpful?




Databases

Databases embody FeatureBase clusters launched as a managed service in the FeatureBase Cloud. For table creation in a database please refer to https://docs.featurebase.com/docs/sql-guide/statements/statement-table-create-show/

Create database

Create a FeatureBase Cloud DataBase.

SecurityJWT
Request
Request Body schema: application/json
name
required
string

The user-friendly name for the database.

required
object

Options associated with this database.

Responses
201

Created

400

Bad Request

401

Unauthorized

post/databases
Request samples
application/json
{
  • "name": "example-database",
  • "database_options": {
    }
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "example-database",
  • "database_status": "RUNNING",
  • "database_options": {
    },
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "owned_by": "b54c13ac-3977-4e54-bbfa-b33713ac1540",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

List databases

Lists all the databases in the org.

SecurityJWT
Responses
200

Success

401

Unauthorized

get/databases
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/databases' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "next": "",
  • "resources": [
    ]
}

Get database

Return information about the specified database.

SecurityJWT
Request
path Parameters
database_id
required
string <uuid>

The id of the database to read.

Responses
200

Success

401

Unauthorized

404

Not Found

get/databases/{database_id}
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/databases/{database_id}' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "example-database",
  • "database_status": "RUNNING",
  • "database_options": {
    },
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "owned_by": "b54c13ac-3977-4e54-bbfa-b33713ac1540",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

Update database

Update information about the specified database.

SecurityJWT
Request
path Parameters
database_id
required
string <uuid>

The id of the database to update.

Request Body schema: application/json
name
string

The new name for the database.

owned_by
string <uuid>

The new owner for the database.

Responses
202

Success

401

Unauthorized

404

Not Found

put/databases/{database_id}
Request samples
application/json
{
  • "name": "example-database",
  • "owned_by": "b54c13ac-3977-4e54-bbfa-b33713ac1540"
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "example-database",
  • "database_status": "RUNNING",
  • "database_options": {
    },
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "owned_by": "b54c13ac-3977-4e54-bbfa-b33713ac1540",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

Delete database

Deletes the specified database.

SecurityJWT
Request
path Parameters
database_id
required
string <uuid>

The id of the database to delete.

Responses
202

Accepted

401

Unauthorized

404

Not Found

delete/databases/{database_id}
Request samples 
curl --location --request DELETE 'https://api.featurebase.com/v2/databases/{database_id}' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "code": "Unauthorized",
  • "message": "User is not authorized to perform this operation."
}

Query

Execute SQL query

Execute a query against an existing database. Note that you must use the server https://query.featurebase.com/v2 for all query requests.

SecurityJWT
Request
path Parameters
database_id
required
string

The id of the database where the query should be executed.

Request Body schema: text/plain
text
required
string

The sql query text.

Responses
200

Success

400

Bad Request

401

Unauthorized

404

Not Found

500

Internal Server Error

post/databases/{database_id}/query/sql
Request samples
text/plain
select count(*) from test-table
Response samples
application/json
{
  • "schema": {
    }
}

Execute PQL query

Execute a query against an existing database. Note that you must use the server https://query.featurebase.com/v2 for all query requests.

SecurityJWT
Request
path Parameters
database_id
required
string

The id of the database where the query should be executed.

Request Body schema: application/json
statement
required
string

The pql query text.

table
required
string

The table to select from

Responses
200

Success

400

Bad Request

401

Unauthorized

404

Not Found

post/databases/{database_id}/query/pql
Request samples
application/json
{
  • "statement": "Count(Intersect(Row(hobbies=\"Teaching\"),Distinct(Row(bools='available_for_hire'), field= id, index=skills)))",
  • "table": "cseg"
}
Response samples
application/json
{
  • "results": [
    ]
}

Invites

Invite user

Invite an user to the organization. Only Org Owner can use this API.

SecurityJWT
Request
Request Body schema: application/json
email
required
string

email of the user.

Responses
201

Created

400

Bad Request

401

Unauthorized

post/invites
Request samples
application/json
{
  • "email": "example-email@abc.com"
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "Organization for example-org@abc.com",
  • "email": "example-email@abc.com",
  • "accepted": false,
  • "move_org": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "date_expiry": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

List invites

Lists all invites in the org. Only Org Owner can use this API.

SecurityJWT
Responses
200

Success

401

Unauthorized

get/invites
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/invites' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "next": "",
  • "resources": [
    ]
}

Get invite

Return information about the specified invite. Only Org Owner can use this API.

SecurityJWT
Request
path Parameters
inviteId
required
string <uuid>

The id of the invite to read.

Responses
200

Success

401

Unauthorized

404

Not Found

get/invites/{inviteId}
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/invites/{inviteId}' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "Organization for example-org@abc.com",
  • "email": "example-email@abc.com",
  • "accepted": false,
  • "move_org": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "date_expiry": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

Update invite

Update information about the specified invite. Only Org Owner can use this API.

SecurityJWT
Request
path Parameters
inviteId
required
string <uuid>

The id of the invite to update.

Request Body schema: application/json
accepted
boolean

Update user invite acceptance status.

Responses
202

Success

400

Bad Request

401

Unauthorized

404

Not Found

put/invites/{inviteId}
Request samples
application/json
{
  • "accepted": true
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "Organization for example-org@abc.com",
  • "email": "example-email@abc.com",
  • "accepted": false,
  • "move_org": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "date_expiry": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

Users

Create user

Create an user in the organization.

SecurityJWT
Request
Request Body schema: application/json
firstname
required
string

Firstname of the user.

lastname
required
string

Lastname of the user.

Responses
201

Created

400

Bad Request

401

Unauthorized

post/users
Request samples
application/json
{
  • "firstname": "example-firstname",
  • "lastname": "example-lastname"
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "Organization for example-org@abc.com",
  • "idp_id": "03d5d6f7-e2a3-4a79-8306-b71262b7b42e",
  • "username": "example-email@abc.com",
  • "firstname": "example-firstname",
  • "lastname": "example-lastname",
  • "status": "Active",
  • "acl": [
    ],
  • "roles": [
    ],
  • "primary_email": "example-email@abc.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

List users

Lists all users in the org.

SecurityJWT
Responses
200

Success

401

Unauthorized

get/users
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/users' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "next": "",
  • "resources": [
    ]
}

Get current user

Get information about current user in the org.

SecurityJWT
Responses
200

Success

401

Unauthorized

get/users/current
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/users/current' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "Organization for example-org@abc.com",
  • "idp_id": "03d5d6f7-e2a3-4a79-8306-b71262b7b42e",
  • "username": "example-email@abc.com",
  • "firstname": "example-firstname",
  • "lastname": "example-lastname",
  • "status": "Active",
  • "acl": [
    ],
  • "roles": [
    ],
  • "primary_email": "example-email@abc.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

Update user

Update an user in the organization.

SecurityJWT
Request
path Parameters
id
required
string <uuid>

The unique id of the user.

Request Body schema: application/json
firstname
string

Firstname of the user.

lastname
string

Lastname of the user.

acl
Array of strings

List of permissions user has. Users can not update their own permissions. Only Org_Owner can update permissions of other users in the org.

status
string

The status of the user. Users can not update their own status. Only Org_Owner can update the status of other users in the org.

Enum: "Active" "Deactivated"
Responses
202

Accepted

401

Unauthorized

404

Not Found

put/users/{id}
Request samples
application/json
{
  • "firstname": "example-firstname",
  • "lastname": "example-lastname",
  • "acl": [
    ],
  • "status": "Active"
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "Organization for example-org@abc.com",
  • "idp_id": "03d5d6f7-e2a3-4a79-8306-b71262b7b42e",
  • "username": "example-email@abc.com",
  • "firstname": "example-firstname",
  • "lastname": "example-lastname",
  • "status": "Active",
  • "acl": [
    ],
  • "roles": [
    ],
  • "primary_email": "example-email@abc.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

Get user

Get the information about user with id.

SecurityJWT
Request
path Parameters
id
required
string <uuid>

The unique id of the user.

Responses
200

Success

401

Unauthorized

404

Not Found

get/users/{id}
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/users/{id}' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "Organization for example-org@abc.com",
  • "idp_id": "03d5d6f7-e2a3-4a79-8306-b71262b7b42e",
  • "username": "example-email@abc.com",
  • "firstname": "example-firstname",
  • "lastname": "example-lastname",
  • "status": "Active",
  • "acl": [
    ],
  • "roles": [
    ],
  • "primary_email": "example-email@abc.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

Create user roles

Add roles to the user with id. Only user with Org_Owner role can update other users roles in the org.

SecurityJWT
Request
path Parameters
id
required
string <uuid>

The unique id of the user.

Request Body schema: application/json
rolenames
Array of strings

List of roles associated with user.

Responses
201

Created

401

Unauthorized

404

Not Found

post/users/{id}/roles
Request samples
application/json
{
  • "rolenames": [
    ]
}
Response samples
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "rolenames": [
    ]
}

Move user org

This endpoint is used to move user from one org to the other.

SecurityJWT
Request
path Parameters
id
required
string <uuid>

The unique id of the user.

Request Body schema: application/json
invite_id
required
string

Invite id from the org into which the user is moving.

Responses
202

Accepted

400

Bad Request

401

Unauthorized

409

Conflict

post/users/{id}/action/invite
Request samples
application/json
{
  • "invite_id": "2818c738-8b76-408a-9294-ea9d0ab5d105"
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "org_name": "Organization for example-org@abc.com",
  • "idp_id": "03d5d6f7-e2a3-4a79-8306-b71262b7b42e",
  • "username": "example-email@abc.com",
  • "firstname": "example-firstname",
  • "lastname": "example-lastname",
  • "status": "Active",
  • "acl": [
    ],
  • "roles": [
    ],
  • "primary_email": "example-email@abc.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

Orgs

Get org

Return information about the specified org. Users can only check information about the org to which they belong.

SecurityJWT
Request
path Parameters
id
required
string <uuid>

The id of the org to read.

Responses
200

Success

401

Unauthorized

get/orgs/{id}
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/orgs/{id}' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Organization for example-user@abc.com",
  • "company_name": "FeatureBase",
  • "address": "test-address",
  • "tech_contact_emali": "example-user@abc.com",
  • "billing_contact_emali": "example-user@abc.com",
  • "org_type": "trial",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

Update org

Update information about the specified org.

SecurityJWT
Request
path Parameters
id
required
string <uuid>

The id of the org to update.

Request Body schema: application/json
name
string

The name of the org.

company_name
string

The name of the comapny.

address
string

The address of the user who creates the org.

tech_contact_emali
string

Email of the user creating the org.

billing_contact_emali
string

Email of the user for billing related to org resources.

Responses
202

Success

401

Unauthorized

put/orgs/{id}
Request samples
application/json
{
  • "name": "Organization for example-user@abc.com",
  • "company_name": "FeatureBase",
  • "address": "test-address",
  • "tech_contact_emali": "example-user@abc.com",
  • "billing_contact_emali": "example-user@abc.com"
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Organization for example-user@abc.com",
  • "company_name": "FeatureBase",
  • "address": "test-address",
  • "tech_contact_emali": "example-user@abc.com",
  • "billing_contact_emali": "example-user@abc.com",
  • "org_type": "trial",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "deea00dc-b6b6-4412-a483-26ac61e1f6fe"
}

Service Properties

Get service properties

Get information about service properties of the org.

SecurityJWT
Request
path Parameters
property
required
string

The name of service property. There are 3 service properties about which we can get information. They are "database:shapes", "database:limits", "source:limits".

Responses
200

Success

401

Unauthorized

404

Not Found

get/service-properties/{property}
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/service-properties/{property}' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "property": "database:shapes",
  • "value": [
    ]
}

Roles

Create role

Create a role in the org. Only user with ORG OWNER permission can use this endpoint.

SecurityJWT
Request
Request Body schema: application/json
rolename
required
string

The name of the role that need to added to the org.

acl
Array of strings

List of permissions user has.

Responses
201

Created

400

Bad Request

401

Unauthorized

409

Conflict

post/roles
Request samples
application/json
{
  • "rolename": "example-rolename",
  • "acl": [
    ]
}
Response samples
application/json
{
  • "rolename": "example-rolename",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "acl": [
    ]
}

List roles

Lists all roles in the org. Only user with ORG OWNER permission can use this endpoint.

SecurityJWT
Responses
200

Success

401

Unauthorized

get/roles
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/roles' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "next": "",
  • "resources": [
    ]
}

Get role

Return information about the specified role. Only user with ORG OWNER permission can use this endpoint.

SecurityJWT
Request
path Parameters
roleName
required
string

The name of the role.

Responses
200

Success

401

Unauthorized

404

Not Found

get/roles/{roleName}
Request samples 
curl --location --request GET 'https://api.featurebase.com/v2/roles/{roleName}' \
--header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "rolename": "example-rolename",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "acl": [
    ]
}

Update role

Update information about the specified role. Only user with ORG OWNER permission can use this endpoint.

SecurityJWT
Request
path Parameters
roleName
required
string

The name of the role.

Request Body schema: application/json
acl
Array of strings

List of permissions user has.

Responses
202

Accepted

401

Unauthorized

404

Not Found

put/roles/{roleName}
Request samples
application/json
{
  • "acl": [
    ]
}
Response samples
application/json
{
  • "rolename": "example-rolename",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "acl": [
    ]
}

Delete role

Deletes the specified role. Only user with ORG OWNER permission can use this endpoint.

SecurityJWT
Request
path Parameters
roleName
required
string

The name of the role.

Responses
202

Accepted

401

Unauthorized

delete/roles/{roleName}
Request samples 
curl --location --request DELETE 'https://api.featurebase.com/v2/roles/{roleName}' \
     --header 'Authorization: Bearer <token>'
Response samples
application/json
{
  • "code": "InvalidParameter",
  • "message": "Incorrect parameter value."
}