Introduction🔗
Documentation for CloudKarafka API.
This API is used for creating instances and are available to the customer that have signed up via https://www.cloudkarafka.com.
We have another API, which is per instance, to manage alarms, integrations and more, which all customers have access to.
That documentation for the Instance API can be found here: Instance API Documentation
You can get the API key for the other API from Get instance endpoint.
Authentication🔗
Authentication is done by sending your API key in the password field in Basic Auth, the username should be kept empty.
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx \
https://customer.cloudkarafka.com/api/instances
You can find, or create, your API keys at https://customer.cloudkarafka.com/apikeys
Instances🔗
List instances🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/instances
The above command returns JSON structured like this:
[
{
"id": 1234,
"plan": "ducky",
"region": "amazon-web-services::eu-west-1",
"name": "My test",
"tags": ["test-instance"],
"providerid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
]
This endpoint retrieves all instances.
HTTP Request🔗
GET https://customer.cloudkarafka.com/api/instances
Get instance info🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/instances/1234
The above command returns JSON structured like this:
{
"id": 2898,
"name": "sample cluster",
"plan": "mouse-3",
"region": "amazon-web-services::us-east-1",
"providerid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tags": ["test-instance"],
"ca": "-----BEGIN XXXX CERTIFICATE-----\n",
"apikey": "XXX-XXX-XXX-XXX",
"brokers": "test-fastcar-01.srvs.cloudkafka.com:9094",
"password": "MFOmvlRPyFKR8asdasdasdasasdas6K",
"username": "aiqasdasda",
"topic_prefix": "aiqasdasda-",
"ready": true
}
This endpoint retrieves a specific instance.
The API key returned in this response is the key that you will use for the Instance API that we have. That API is per instance and there you can configure alarms, log and metric integrations and more.
That documentation for the Instance API can be found here: Instance API Documentation
HTTP Request🔗
GET https://customer.cloudkarafka.com/api/instances/<ID>
URL Parameters🔗
| Parameter | Description |
|---|---|
| ID | The ID of the instance to retrieve |
Create an Instance🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
-d "name=test&plan=tiger®ion=amazon-web-services::us-east-1" \
https://customer.cloudkarafka.com/api/instances
The above command returns JSON structured like this:
{
"id": 2234,
"url": "amqp://user:password@lemur.cloudkarafka.com/vhost",
"apikey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx"
}
HTTP Request🔗
POST https://customer.cloudkarafka.com/api/instances
Request Parameters🔗
| Parameter | Description |
|---|---|
| name | The name of the instance |
| plan | Which subscription plan to use |
| region | Name of the region you want to create your instance in |
| vpc_subnet | Dedicated VPC subnet, shouldn't overlap with your current VPC's subnet. |
| nodes | Number of nodes in cluster (plan must support it) |
| kafka_version | Desired kafka version (optional) |
Change an Instance🔗
curl -XPUT -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
-d"name=test2&plan=lemur" \
https://customer.cloudkarafka.com/api/instances/1234
This endpoint changes an instance
HTTP Request🔗
PUT https://customer.cloudkarafka.com/api/instances/<ID>
URL Parameters🔗
| Parameter | Description |
|---|---|
| ID | The ID of the instance to delete |
Request Parameters🔗
| Parameter | Description |
|---|---|
| name | The name of the instance |
| plan | Which subscription plan to use |
| nodes | Number of nodes in cluster (plan must support it) |
Delete an Instance🔗
curl -XDELETE -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/instances/1234
This endpoint deletes an instance
HTTP Request🔗
DELETE https://customer.cloudkarafka.com/api/instances/<ID>
URL Parameters🔗
| Parameter | Description |
|---|---|
| ID | The ID of the instance to delete |
Invoices🔗
List invoices🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/invoices
The above command returns JSON structured like this:
[
{
"id": 1234,
"period": "2022/5",
"number": 2345,
"paid": false,
"total": 929,
"currency": "USD",
"account_name": "84codes AB"
},
{
"id": 6789,
"period": "2022/6",
"number": 7890,
"paid": true,
"total": 99,
"currency": "USD",
"account_name": "84codes AB"
},
...
]
HTTP Request🔗
GET https://customer.cloudkarafka.com/api/invoices
URL Parameters🔗
| Parameter | Description |
|---|---|
| from | Year-month start, e.g. 2022-05 |
| to | Year-month end, e.g. 2022-06 |
Get invoice for a specific period🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/invoices/period
The above command returns JSON structured like this:
{
"period": "2022/6",
"total": 16.1,
"currency": "USD",
"lines": [
{
"subscription_id": 187,
"amount": 16.1,
"from": "2022-06-01T00:00:00+00:00",
"to": "2022-06-10T15:51:29+00:00",
"name": "Test server",
"plan": "squirrel-1",
"tags": []
}
],
"customer": {
"company": "Cool company",
"address": "The park",
"country": "Sweden",
"account_name": "Cool company"
},
"seller": {
"company": "84codes AB",
"address": "C/O United Spaces Torsgatan 26",
"zipcode": "113 21 Stockholm",
"country": "Sweden",
"vatid": "SE556898078201"
}
}
HTTP Request🔗
GET https://customer.cloudkarafka.com/api/invoices/period
URL Parameters🔗
| Parameter | Description |
|---|---|
| year | Year to calculate for |
| month | Year-month end, e.g. 2022-06 |
Get invoice by id🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/invoices/<id>
The above command returns JSON structured like this:
{
"period": "2022/6",
"total": 16.1,
"currency": "USD",
"lines": [
{
"subscription_id": 187,
"amount": 16.1,
"from": "2022-06-01T00:00:00+00:00",
"to": "2022-06-10T15:51:29+00:00",
"name": "Test server",
"plan": "squirrel-1",
"tags": []
}
],
"customer": {
"company": "Cool company",
"address": "The park",
"country": "Sweden",
"account_name": "Cool company"
},
"seller": {
"company": "84codes AB",
"address": "C/O United Spaces Torsgatan 26",
"zipcode": "113 21 Stockholm",
"country": "Sweden",
"vatid": "SE556898078201"
}
}
HTTP Request🔗
GET https://customer.cloudkarafka.com/api/invoices/<id>
URL Parameters🔗
| Parameter | Description |
|---|---|
| id | The invoice id |
Auditlog🔗
Get auditlog in CSV format🔗
Returns auditlog in CSV format for latest month, or for month specified in params.
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/auditlog/csv
The above command text formatted in a CSV on following format:
Timestamp,Event,Source,User,Extras
2022-12-12 11:05:17 UTC,login,web,john@company.com,type = pwd
2022-12-12 09:52:16 UTC,login,web,jane@company.com,type = pwd
HTTP Request🔗
GET https://customer.cloudkarafka.com/api/auditlog/csv
URL Parameters🔗
| Parameter | Description |
|---|---|
| timestamp | YYYY-MM , e.g. 2022-12 |
Regions🔗
List available regions🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/regions
The above command returns JSON structured like this:
[
{
"provider": "amazon-web-services",
"region": "us-east-1",
"name": "Amazon Web Services - US-East-1 (Northern Virginia)",
"has_shared_plans": true
},
{
"provider": "google-compute-engine",
"region": "us-central1",
"name": "Google Compute Engine - us-central1 (Iowa)",
"has_shared_plans": true
},
...
]
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/regions?provider=amazon-web-services
The above command returns JSON structured like this:
[
{
"provider": "amazon-web-services",
"region": "us-east-1",
"name": "Amazon Web Services - US-East-1 (Northern Virginia)",
"has_shared_plans": true
},
...
]
HTTP Request🔗
GET https://customer.cloudkarafka.com/api/regions
Query Parameters🔗
| Parameter | Description |
|---|---|
| provider | Filter result with a specific provider, e.g. amazon-web-services. |
Team🔗
List team members🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/team
The above command returns JSON structured like this:
[
{
"id": "f49afe6f-7b96-496e-8966-72daddfb897b",
"email": "john@company.com",
"tfa_auth_enabled": false,
"roles": [
"member"
]
},
{
"id": "823e6c7d-2a94-4cc7-9615-4d699ebea95c",
"email": "jane@company.com",
"tfa_auth_enabled": true,
"roles": [
"admin"
]
}
]
HTTP Request🔗
GET https://customer.cloudkarafka.com/api/team
Invite a new user to the team🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx -d \
"email=john@company.com" https://customer.cloudkarafka.com/api/team/invite
The command below is for a user with specific role
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx -d \
"email=jane@company.com&role=member&tags=tag1,tag2" https://customer.cloudkarafka.com/api/team/invite
All the above commands returns JSON structured like this:
{"message":"Email invitation sent"}
This endpoint invites a user to team
POST https://customer.cloudkarafka.com/api/team/invite
The user will get the role member by default if no role is specified.
| Parameter | Description |
|---|---|
| The user's email | |
| role | User's role in the team |
| tags | Tag roles for member and monitor users |
| Roles | Permissions |
|---|---|
admin |
Full access to team and instances |
devops |
Full access to instances (including create/delete) |
member |
Manage Instances (access control panel) |
monitor |
View Instances (restricted access control panel) Not allowed to reconfigure, restart, reboot etc. |
billing manager |
Full Billing access |
Remove a user from the team🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
-d "email=jane@company.com" https://customer.cloudkarafka.com/api/team/remove
The above command returns JSON structured like this:
{"message":"The user has been deleted from team"}
This endpoint removes a user from team
POST https://customer.cloudkarafka.com/api/team/remove
| Parameter | Description |
|---|---|
| The user's email |
Update user role and tags🔗
curl -X PUT -u xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx: \
-d "tags=tag1,tag2,tag3&role=member" https://customer.cloudkarafka.com/api/team/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
The above command returns JSON structured like this:
{"message":"Role and tags updated for user."}
This endpoint updates role and tags for a user in a team
PUT https://customer.cloudkarafka.com/api/team/{user-id}
This endpoint requires at least one of the following optional parameters to be provided:
| Parameter | Required | Type | Description |
|---|---|---|---|
| role | false | string | User's role in the team |
| tags | false | string | List of user's tags in the team (separated by comma; "tag1,tag2,tag3") |
| Roles | Permissions |
|---|---|
admin |
Full access to team and instances |
billing manager |
Full Billing access |
devops |
Full access to instances (including create/delete) |
member |
Manage Instances (access control panel) |
monitor |
View Instances (restricted access control panel) Not allowed to reconfigure, restart, reboot etc. |
API keys🔗
Rotate API key🔗
The API key used in the request will be removed. A new API key with matching permissions will be created and returned in the response. The comment of the old key will be carried over to the new key.
curl -XPOST -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/apikeys/rotate-apikey
The above command returns JSON structured like this:
{
"apikey": "..."
}
HTTP Request🔗
POST https://customer.cloudkarafka.com/api/apikeys/rotate-apikey
Plans🔗
All prices are in USD and per month. Read more on which plans are available at https://www.cloudkarafka.com/plans.html
List available plans🔗
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/plans
The above command returns JSON structured like this:
[
{
"name": "plan-a",
"price": 0,
"backend": "some-service",
"shared": true
},
{
"name": "plan-b",
"price": 99,
"backend": "another-service",
"shared": false
}
...
]
curl -u :xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx \
https://customer.cloudkarafka.com/api/plans?backend=some-service
The above command returns JSON structured like this:
[
{
"name": "plan-a",
"price": 0,
"backend": "some-service",
"shared": true
},
...
]
HTTP Request🔗
GET https://customer.cloudkarafka.com/api/plans
Query Parameters🔗
| Parameter | Description |
|---|---|
| backend | Filter result with a specific backend software, e.g. some-service. |
Formats🔗
All API end points support form FormData and JSON in the request.
You need to format the request accordingly and if you send the request as JSON
be sure to add the content type header content-type: application/json otherwise the server won't be able to parse your request.
Status Codes🔗
| Status Code | Meaning |
|---|---|
| 200 | The request completed successfully. |
| 204 | The request completed successfully. |
| 400 | Bad Request -- Your request might be invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The kitten requested is hidden for administrators only. |
| 404 | Not Found -- The specified kitten could not be found. |
| 405 | Method Not Allowed -- You tried to access a kitten with an invalid method. |
| 429 | Too Many Requests -- Rate limiting, you have requested too many kittens in a given amount of time. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |