Introduction

Overview of the FalkorDB Cloud API

The FalkorDB Cloud API lets you provision and manage FalkorDB instances across service tiers and deployment models.

Base URL

https://api.omnistrate.cloud

Every resource path is prefixed with /2022-09-01-00/resource-instance/sp-JvkxkPhinN/falkordb/v1/prod/, followed by the service tier, the deployment model, and the component.

Authentication

All endpoints except sign-in are authenticated with a session cookie.

Cookie: omnistrate_token=<jwt>

Sign in with HTTP Basic authentication using your FalkorDB Cloud credentials. The response sets two HttpOnly cookies scoped to .falkordb.cloud:

Cookie	Lifetime	Purpose
omnistrate_token	1 hour	Authorizes API requests.
omnistrate_refresh_token	24 hours	Obtains a new session token.

Browsers send the cookies automatically when requests include credentials. Server-side and CLI clients must store the Set-Cookie values and replay them on every request.

Account management

Before you can create a deployment instance you need a subscription to a service plan. The account management endpoints let you:

• Discover the available plans with List service plans.
• Subscribe to a plan with Create subscription.
• Share a subscription with teammates using Invite user and Revoke user role.

Every deployment instance belongs to a subscription. Pass the subscription ID as the subscriptionId query parameter on instance requests.

Service tiers

The API is organized by service tier and hosting model:

Tier	Tenancy	Components
Enterprise BYOA	Dedicated	Standalone, Single-Zone, Multi-Zone, Cluster (Single-Zone), Cluster (Multi-Zone)
Enterprise	Dedicated	Standalone, Single-Zone, Multi-Zone, Cluster (Single-Zone), Cluster (Multi-Zone)
Pro	Dedicated	Standalone, Single-Zone, Multi-Zone, Cluster (Multi-Zone)
Startup	Multi-tenant	Standalone
Free	Multi-tenant	Free

Enterprise BYOA deploys into your own cloud account, so create requests take a cloud_provider_account_config_id. Enterprise deploys into a custom network you provide with custom_network_id.

Infrastructure

Area	Description
Cloud accounts	Register and bootstrap your own AWS, GCP, Azure, or OCI account for Enterprise BYOA. Produces the cloud_provider_account_config_id used at instance creation.
Custom networks	Reserve CIDR blocks per cloud provider region. Produces the custom_network_id used at instance creation and on snapshot restore.
Snapshots	Take, copy, and restore point-in-time snapshots of a deployment instance.

Database users

Database users are the credentials your application uses to connect to an instance. They are managed through a separate FalkorDB API host at https://api.falkordb.cloud/v1/customer-ldap using bearer token authentication rather than the session cookie.

Operations

Every component supports the same set of operations.

Operation	Method	Path
List	GET	/{component}
Create	POST	/{component}
Describe	GET	/{component}/{id}
Update	PUT	/{component}/{id}
Delete	DELETE	/{component}/{id}
Backup	POST	/{component}/{id}/backup
Copy snapshot	POST	/{component}/{id}/copy-snapshot
Failover	POST	/{component}/{id}/failover
Start	POST	/{component}/{id}/start
Stop	POST	/{component}/{id}/stop
Restart	POST	/{component}/{id}/restart

Asynchronous behavior

Create and lifecycle operations return 202 Accepted and complete in the background. Poll the Describe endpoint until status reflects the state you expect.

Errors

All endpoints return errors with the application/vnd.goa.error content type. See Error for the shape.