Skip to main content
API docs by Redocly

Coordination API (1.0.0)

Download OpenAPI specification:Download

Seaplane IO, Inc.: support@seaplane.io License: Apache 2.0

Seaplane Global Coordination API

For information about authentication see authentication

config

Metadata key-value store API

Get contents of root directory

This query returns a single page of key-value pairs. If more keys exist, it also returns a value for the next_key. You can rerun the query with the from parameter set to next_key to get the next page of results. Some directories contain no keys, i.e., return an empty result while still returning a value for next_key. To get all your keys in your account, rerun the query until the value of next_key is null.

The CLI automatically reruns the query to return all key-value pairs in your account. This could take some time depending on the number of records in your account

Authorizations:
BasicAuth
query Parameters
from
string
Example: from=base64:dGhlIG5leHQga2V5

Values of the from parameter should be prefixed with the string "base64:"

Responses

Request samples 

seaplane metadata list --decode

Response samples

Content type
application/json
{
  • "next_key": "dGhlIG5leHQga2V5",
  • "kvs": [
    ]
}

Get the contents of a directory

This query returns a single page of key-value pairs. If more keys exist, it also returns a value for the next_key. You can rerun the query with the from parameter set to next_key to get the next page of results. To get all your keys in the specified directory, rerun the query until the value of next_key is null.

The CLI automatically reruns the query to return all key-value pairs in your account. This could take some time depending on the number of records in your account

Authorizations:
BasicAuth
path Parameters
key
required
string
Example: Zm9vL2Jhcgo

Key pointing to a directory, the key should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

query Parameters
from
string
Example: from=base64:dGhlIG5leHQga2V5

Values of the from parameter should be prefixed with the string "base64:"

Responses

Request samples 

seaplane metadata list <DIRECTORY> --decode

Response samples

Content type
application/json
{
  • "next_key": "dGhlIG5leHQga2V5",
  • "kvs": [
    ]
}

Get a key-value pair

Authorizations:
BasicAuth
path Parameters
key
required
string
Example: Zm9vL2Jhcgo

Key of the key-value pair, the key should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Responses

Request samples 

seaplane metadata get <KEY> --decode

Response samples

Content type
application/json
{
  • "key": "key_foo",
  • "value": "something"
}

Set a key-value pair

Authorizations:
BasicAuth
path Parameters
key
required
string
Example: Zm9vL2Jhcgo

Key of the key-value pair, the key should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Request Body schema: application/octet-stream

Base64-encoded value of the key-value pair

string

Responses

Request samples 

seaplane metadata set <KEY> <VALUE>

Response samples

Content type
application/json
"OK"

Delete a key-value pair

Authorizations:
BasicAuth
path Parameters
key
required
string
Example: Zm9vL2Jhcgo

Key of the key-value pair, the key should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Responses

Request samples 

seaplane metadata delete <KEY>

Response samples

Content type
application/json
"OK"

locks

Locks API

Get all locks in the root directory

This query returns a single page of locks. If more locks exist, it also returns a value for the next_lock. You can rerun the query with the from parameter set to next_lock to get the next page of results. Some directories contain no locks, i.e., return an empty result while still returning a value for next_key. To get all your keys in your account, rerun the query until the value of next_lock is null.

The CLI automatically reruns the query to return all key-value pairs in your account. This could take some time depending on the number of records in your account

Authorizations:
BasicAuth
query Parameters
from
string
Example: from=base64:bG9tb25k

Listing a directory of locks returns one page of results, if a GET / query returns a LockRange with a non-null next_lock you can repeat this query with the from parameter set to the next_lock value from the previous query to see the next page of results. Values of the from parameter should be prefixed with the string "base64:"

Responses

Request samples 

seaplane locks list --decode

Response samples

Content type
application/json
{
  • "next_lock": "bG9tb25k",
  • "locks": [
    ]
}

Get locks in a given directory

This query returns a single page of locks. If more locks exist, it also returns a value for the next_lock. You can rerun the query with the from parameter set to next_lock to get the next page of results. To get all your locks in the specified directory, rerun the query until the value of next_lock is null.

The CLI automatically reruns the query to return all key-value pairs in your account. This could take some time depending on the number of records in your account

Authorizations:
BasicAuth
path Parameters
dir
required
string (LockName)
Example: bG9tb25k

Name of a directory containing locks, the name should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

query Parameters
from
string
Example: from=base64:bG9tb25k

Listing a directory of locks returns one page of results, if a GET / query returns a LockRange with a non-null next_lock you can repeat this query with the from parameter set to the next_lock value from the previous query to see the next page of results. Values of the from parameter should be prefixed with the string "base64:"

Responses

Request samples 

seaplane locks list <DIRECTORY>/ --decode

Response samples

Content type
application/json
{
  • "next_lock": "bG9tb25k",
  • "locks": [
    ]
}

Get the information around a currently held lock

Authorizations:
BasicAuth
path Parameters
name
required
string (LockName)
Example: bG9tb25k

Name of the lock, the name should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Responses

Request samples 

seaplane locks list <LOCK-NAME> --decode

Response samples

Content type
application/json
{
  • "name": "bG9tb25k",
  • "id": "AOEHFRa4Ayg",
  • "info": {
    }
}

Attempt to acquire a lock

Authorizations:
BasicAuth
path Parameters
name
required
string (LockName)
Example: bG9tb25k

Name of the lock, the name should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

query Parameters
ttl
required
integer (TTL) [ 1 .. 4095 ]
Example: ttl=3600

The TTL set on the lock when it was last acquired/renewed in seconds

client-id
required
string (ClientID)
Example: client-id=worker-321

The Client ID of the current lock holder.

Responses

Request samples 

seaplane locks acquire <LOCK-NAME> \
--client-id <CLIENT-ID> \
--ttl <TTL>

Response samples

Content type
application/json
{
  • "id": "AOEHFRa4Ayg",
  • "sequencer": 3
}

Release a currently held lock

Authorizations:
BasicAuth
path Parameters
name
required
string (LockName)
Example: bG9tb25k

Name of the lock, the name should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

query Parameters
id
required
string (LockID)
Example: id=AOEHFRa4Ayg

ID which allows for the renewal/release of a lock, represents "holding" the lock, this is usually only seen by the original acquirer of the lock but may be leaked by listing the locks. (NOTE: This allows you to alter lock semantics drastically so please ensure you understand the consequences before use)

Responses

Request samples 

seaplane locks release --lock-id <LOCK-ID> <LOCK-NAME>

Response samples

Content type
application/json
"OK"

Renew a held lock, with a given TTL

Authorizations:
BasicAuth
path Parameters
name
required
string (LockName)
Example: bG9tb25k

Name of the lock, the name should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

query Parameters
id
required
string (LockID)
Example: id=AOEHFRa4Ayg

ID which allows for the renewal/release of a lock, represents "holding" the lock, this is usually only seen by the original acquirer of the lock but may be leaked by listing the locks. (NOTE: This allows you to alter lock semantics drastically so please ensure you understand the consequences before use)

ttl
required
integer (TTL) [ 1 .. 4095 ]
Example: ttl=3600

The TTL set on the lock when it was last acquired/renewed in seconds

Responses

Request samples 

seaplane locks renew --lock-id <LOCK-ID> --ttl <TTL> <LOCK-NAME>

Response samples

Content type
application/json
"OK"

restrict

Provider and region restrictions API

For more information about restrictions see the restrictions background information documentation.

List information about all provider and region restrictions

This query returns a single page of restrictions. If more restrictions exist, it also returns a value for the next_key and next_api. You can rerun the query with the from parameter set to next_key and the from_api set to the next_api to get the next page of results. To get all restrictions in your account, rerun the query until the value of next_key and next_api is null.

The CLI automatically reruns the query to return all restrictions. This could take some time depending on the number of restrictions in your account.

Authorizations:
BasicAuth
query Parameters
from
string
Example: from=base64:dGhlIG5leHQga2V5

Values of the from parameter should be prefixed with the string "base64:"

from_api
string
Example: from_api=locks

Responses

Request samples 

seaplane restrict list --decode

Response samples

Content type
application/json
{
  • "next_api": "locks",
  • "next_key": "dGhlIG5leHQga2V5",
  • "restrictions": [
    ]
}

List information about the provider and region restrictions for an API

Authorizations:
BasicAuth
path Parameters
api
required
string (RestrictionApi)
Enum: "config" "locks"
Example: config

The name of a metadata API, for example "config" or "locks"

query Parameters
from
string
Example: from=base64:dGhlIG5leHQga2V5

Values of the from parameter should be prefixed with the string "base64:"

Responses

Request samples 

seaplane restrict list <API> --decode

Response samples

Content type
application/json
{
  • "next_key": "dGhlIG5leHQga2V5",
  • "restrictions": [
    ]
}

Replace all geographical or provider restrictions on a given directory with new restrictions

Authorizations:
BasicAuth
path Parameters
api
required
string (RestrictionApi)
Enum: "config" "locks"
Example: config

The name of a metadata API, for example "config" or "locks"

key
required
string
Example: Zm9vL2Jhcgo

Key pointing to a directory, the key should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Request Body schema: application/json

JSON object containing explicit allow or deny lists for geographies and cloud providers to be associated with a given directory

regions_allowed
Array of strings or null (Region)
Enum: "XA" "XC" "XE" "XF" "XN" "XO" "XQ" "XS" "XU"

A list of region codes

regions_denied
Array of strings or null (Region)
Enum: "XA" "XC" "XE" "XF" "XN" "XO" "XQ" "XS" "XU"

A list of region codes

providers_allowed
Array of strings or null (Provider)
Enum: "AWS" "Azure" "DigitalOcean" "Equinix" "GCP"

A list of provider names

providers_denied
Array of strings or null (Provider)
Enum: "AWS" "Azure" "DigitalOcean" "Equinix" "GCP"

A list of provider names

Responses

Request samples

Content type
application/json
{
  • "providers_allowed": [
    ],
  • "providers_denied": [
    ],
  • "regions_allowed": [
    ],
  • "regions_denied": [
    ]
}

Response samples

Content type
application/json
"OK"

Get information about the provider and region restrictions for a specific directory

Authorizations:
BasicAuth
path Parameters
api
required
string (RestrictionApi)
Enum: "config" "locks"
Example: config

The name of a metadata API, for example "config" or "locks"

key
required
string
Example: Zm9vL2Jhcgo

Key pointing to a directory, the key should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Responses

Request samples 

seaplane restrict get <API> <DIRECTORY> --decode

Response samples

Content type
application/json
{
  • "api": "config",
  • "directory": "Zm9vL2Jhcgo",
  • "details": {
    },
  • "state": "enforced"
}

Remove restrictions on a directory

Authorizations:
BasicAuth
path Parameters
api
required
string (RestrictionApi)
Enum: "config" "locks"
Example: config

The name of a metadata API, for example "config" or "locks"

key
required
string
Example: Zm9vL2Jhcgo

Key pointing to a directory, the key should be encoded using base64 encoding, unpadded, with URL and filename safe alphabet: RFC4648 section 5

Responses

Request samples 

seaplane restrict delete <API> <DIRECTORY>

Response samples

Content type
application/json
"OK"