api reference

Cyxth REST API gives you endpoints to interact with your instance channels, users, messages and settings. you can also perform these tasks in the cyxth console if you prefer using the ui.

The api url is your app url in console /api i.e if your app url is r4.cyxth.com/app_id your api url is r4.cyxth.com/app_id/api. all requests to the api must use https or else they will fail.

Cyxth api uses JSON for all requests and responses where applicable.

# cyxth takes 'Content-Type' and 'Accept' json

curl -X POST https://beta.cyxth.com/app_id/users 
  -H 'Content-Type: application/json' 
  -H 'Accept: application/json'

Authentication

cyxth REST API uses api keys to authenticate requests. you can get your api keys from the cyxth console.

the api key is passed as an http bearer token in the header.

curl -X POST https://beta.cyxth.com/app_id/users 
  -H 'Authorization: Bearer {access-token}'

Errors

Cyxth uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided . Codes in the 5xx range indicate an error with cyxth's servers (these are rare).

errors

code	description
200 ok	everything worked as expected
400 bad request	the request was not expected
401 unauthorized	no api key was provided
403 forbidden	can't access resource with api key provided
404 not found	requested resource was not found
429 slow down	too many requests at the same time
5xx internal error	it's not you ,something is wrong with cyxth

error object

all errors returned have this form, some errors may contain a data field with more information

{
    "type": "string",
    "code": "string",
    "message":"string"
}

pagination

Fetching bulk data from cyxth supports pagination i.e getting all users, channels, mesages, etc, these take the following query parameters limit and starting_after.

limit - limit on number of objects returned
starting_after - the object id to start from

NOTE: all the resources are sorted by id

users

create users

post /users

create a user or users. send and array of Users returns the number of users created, will fail if any of the users supplied is already created

Body example

[
  {
    "id": "00uid0",
    "name": "john doe",
    "mode": 300,
    "metadata": {
      "avatar": "https://avtr.com/xyxerixcid"
    }
  },
  {
    "id": "00uid0",
    "name": "john doe",
    "mode": 300,
    "metadata": {
      "avatar": "https://avtr.com/xyxerixcid"
    }
  }
]

Responses

203

400

403

500

{
  "status": 6
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X POST /users
     -H Accept: application/json
     -H Content-Type: application/json
     -d '[{"id":"00uid0","name":"john doe","mode":300,"metadata":{"avatar":"https://avtr.com/xyxerixcid"}},{"id":"00uid0","name":"john doe","mode":300,"metadata":{"avatar":"https://avtr.com/xyxerixcid"}}]'

get users

get /users

get all users. this supports pagination and returns the first 50 users by default

parameters

name	in	required	type
starting after	query	false	string
limit	query	false	number

Responses

200

400

403

500

[
  {
    "id": "oncyxth89",
    "name": "cyx9",
    "mode": 300,
    "metadata": {
      "avatar": "https://heloo.lq.com/avtr90"
    }
  }
]

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X GET /users?starting after={starting after}&limit={limit}
     -H Accept: application/json

delete users

delete /users

delete users by supplying user ids, returns the number of users deleted

Body example

[
  "idx98io090439d",
  "uisfjdfdjire0r",
  "wowcyxthiscool"
]

Responses

200

400

403

500

{
  "status": 6
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X DELETE /users
     -H Accept: application/json
     -H Content-Type: application/json
     -d '["idx98io090439d","uisfjdfdjire0r","wowcyxthiscool"]'

moderate users

post /users/moderate

moderate users, block users and give admin access

Body example

{
  "mode": 300,
  "ids": [
    "cyx8",
    "cyx7"
  ]
}

Responses

200

400

403

500

{
  "status": 6
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X POST /users/moderate
     -H Accept: application/json
     -H Content-Type: application/json
     -d '{"mode":300,"ids":["cyx8","cyx7"]}'

channels

create channels

post /channels

create a channel or channels, to add initial members add a members array to any Channel object with user ids, they will be added asynchronously and automaticaly subscribed to the new channel and can optionaly receive a notification. the maximum number of channels that can be created at a time is 1000 with a maximum initial members of your max channel user setting.this operation is atomic and will fail if any of the channels already exist

Body example

[
  {
    "id": "breakout",
    "name": "breakout",
    "logo": "https://logos.lq.com/rerju8u384bu4"
  },
  {
    "id": "maze0984",
    "name": "maze19"
  }
]

Responses

203

400

403

500

{
  "status": 6
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X POST /channels
     -H Accept: application/json
     -H Content-Type: application/json
     -d '[{"id":"breakout","name":"breakout","logo":"https://logos.lq.com/rerju8u384bu4"},{"id":"maze0984","name":"maze19"}]'

get channels

get /channels

get all channels, returns first 50 users by default if the pagination query is not supplied

parameters

name	in	required	type
starting after	query	false	string
limit	query	false	number

Responses

200

400

403

500

[
  {
    "id": "breakout",
    "name": "breakout",
    "logo": "https://logos.lq.com/rerju8u384bu4"
  },
  {
    "id": "maze0984",
    "name": "maze19"
  }
]

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X GET /channels?starting after={starting after}&limit={limit}
     -H Accept: application/json

delete channels

delete /channels

delete channels

Body example

[
  "idx98io090439d",
  "uisfjdfdjire0r",
  "wowcyxthiscool"
]

Responses

200

400

403

500

{
  "status": 6
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X DELETE /channels
     -H Accept: application/json
     -H Content-Type: application/json
     -d '["idx98io090439d","uisfjdfdjire0r","wowcyxthiscool"]'

channel

update channel

put /channels

update a channel, a channel id must be supplied, all the other fields supplied will be updated

Body example

{
  "id": "breakout",
  "name": "breakout",
  "logo": "https://logos.lq.com/rerju8u384bu4"
}

Responses

200

400

403

500

{
  "id": "breakout",
  "name": "breakout",
  "logo": "https://logos.lq.com/rerju8u384bu4"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X PUT /channels
     -H Accept: application/json
     -H Content-Type: application/json
     -d '{"id":"breakout","name":"breakout","logo":"https://logos.lq.com/rerju8u384bu4"}'

moderate channel

post /channels/{id}/moderate

moderate users in a channel

parameters

name	in	required	type
id	path	true	string

Body example

{
  "mode": 300,
  "ids": [
    "cyx8",
    "cyx7"
  ]
}

Responses

203

400

403

500

{
  "status": 6
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X POST /channels/{id}/moderate?
     -H Accept: application/json
     -H Content-Type: application/json
     -d '{"mode":300,"ids":["cyx8","cyx7"]}'

add members

post /channels/{id}/users

create a user or users in channel,

parameters

name	in	required	type
id	path	true	string

Body example

[
  "idx98io090439d",
  "uisfjdfdjire0r",
  "wowcyxthiscool"
]

Responses

200

401

403

500

{
  "status": 6
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X POST /channels/{id}/users?
     -H Accept: application/json
     -H Content-Type: application/json
     -d '["idx98io090439d","uisfjdfdjire0r","wowcyxthiscool"]'

get members

get /channels/{id}/users

get all users in channel

parameters

name	in	required	type
id	path	true	string
starting after	query	false	string
limit	query	false	number

Responses

200

401

403

500

[
  {
    "id": "oncyxth89",
    "name": "cyx9",
    "mode": 300,
    "metadata": {
      "avatar": "https://heloo.lq.com/avtr90"
    }
  }
]

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X GET /channels/{id}/users?starting after={starting after}&limit={limit}
     -H Accept: application/json

remove members

delete /channels/{id}/users

delete users in channel

parameters

name	in	required	type
id	path	true	string

Body example

[
  "idx98io090439d",
  "uisfjdfdjire0r",
  "wowcyxthiscool"
]

Responses

200

401

403

500

{
  "status": 6
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

{
  "message": "an error occured",
  "type": "error_type",
  "code": "ERR_CODE"
}

Curl Command

curl -X DELETE /channels/{id}/users?
     -H Accept: application/json
     -H Content-Type: application/json
     -d '["idx98io090439d","uisfjdfdjire0r","wowcyxthiscool"]'