Back to Top

CloudState Core API

0.1.9

CloudState is a distributed state management system as a key-value store on HTTP.

This is the documentation for version 0.1.9 of the API. Last update on Jun 6, 2022.

Base URL 
https://c9db.io

Requests a verification token for an email.

POST /bucket_owner/verification_token_request

The verification token is sent to the e-mail address provided in the request.
The e-mail address is not verified at the time of the bucket creation. However, if you fail to verify the e-mail address within 14 days, the bucket data will be transitioned to archival state. To verify the e-mail address, please log in through usecloudstate.io, or use this API.

Body Required
Responses
  • • 204

    A verification token is sent to the specified e-mail address.

POST /bucket_owner/verification_token_request 
curl \
 -X POST https://c9db.io/bucket_owner/verification_token_request \
 -H "Content-Type: application/json" \
 -d '{"email":"string"}'
Request example 
{
  "email": "string"
}

Verify a verification token.

POST /bucket_owner/verification_token_verify

Using the token received, the e-mail address is verified.

Body Required
Responses
  • • 204 object

    The e-mail address is verified. The returned access_token is valid for 30 minutes.

POST /bucket_owner/verification_token_verify 
curl \
 -X POST https://c9db.io/bucket_owner/verification_token_verify \
 -H "Content-Type: application/json" \
 -d '{"email":"string","token":"string"}'
Request example 
{
  "email": "string",
  "token": "string"
}
Response example (204) 
{
  "access_token": "string"
}

List all buckets for an e-mail.

GET /bucket_owner/buckets

The list of buckets is returned.

Headers
  • Authorization Required / string

    The access token in the Bearer format. (e.g. Bearer access_token)

Responses
GET /bucket_owner/buckets 
curl \
 -X GET https://c9db.io/bucket_owner/buckets \
 -H "Authorization: string"
Response example (200) 
[
  {
    "bucket_id": "string",
    "read_key": "string",
    "write_key": "string",
    "admin_key": "string"
  }
]

Create a bucket.

POST /buckets

The e-mail address is not verified at the time of the bucket creation. However, if you fail to verify the e-mail address within 14 days, the bucket data will be transitioned to archival state. To verify the e-mail address, please log in through usecloudstate.io.

Body Required
Responses
POST /buckets 
curl \
 -X POST https://c9db.io/buckets \
 -H "Content-Type: application/json" \
 -d '{"email":"string"}'
Request example 
{
  "email": "string"
}
Response example (200) 
{
  "bucket_id": "string",
  "read_key": "string",
  "write_key": "string",
  "admin_key": "string"
}

Read a value from a bucket

GET /buckets/{bucket_id}/keys/{id}

The value is read from the bucket for the key. If the key does not exist, the call will return a 404.
The read_key is required to read a value from a bucket. If the read key is not provided, the call will be rejected.

Path parameters
  • bucket_id Required / string

    The bucket id.

  • id Required / string

    The key id.

Responses
  • • 200

    The value is returned by this call.

  • • 404

    The key does not exist in the bucket.

GET /buckets/{bucket_id}/keys/{id} 
curl \
 -X GET https://c9db.io/buckets/{bucket_id}/keys/{id}

Writes a value to a bucket

POST /buckets/{bucket_id}/keys/{id}

The value is stored in the bucket for the key. If the key already exists, the value is overwritten.
The write_key` is required to write a value to a bucket. If the write key is not provided, the call will be rejected.

Path parameters
  • bucket_id Required / string

    The bucket id.

  • id Required / string

    The key id.

Query parameters
  • consistency string

    The consistency level of the write. Evenutal writes complete the HTTP requests faster, but may not be consistent with other writes. Strong writes are slower, but are guaranteed to be consistent with other writes. Default is strong.

    Values are eventual or strong.

Responses
  • • 204

    No content is returned by this call

POST /buckets/{bucket_id}/keys/{id} 
curl \
 -X POST https://c9db.io/buckets/{bucket_id}/keys/{id} \
 -H "Content-Type: text/plain"