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.

bash$ 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.

bashcurl -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

json{
    "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 multiple users

Body example

json[
  {
    "id": "00uid0",
    "mode": 300,
    "data": "{}"
  }
]

Responses

2XX

default

json{
  "status": 4
}

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X POST /users
     -H Accept: application/json
     -H Content-Type: application/json
     -d '[{"id":"00uid0","mode":300,"data":"{}"}]'

list users

get /users

list application users, use `limit` and `starting_after` parameters for pagination

parameters

in	name	required	type
query	starting_after	false	string
query	limit	false	number

Responses

2XX

default

json[
  {
    "id": "00uid0",
    "mode": 300,
    "data": "{}"
  }
]

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X GET /users?starting_after={starting_after}&limit={limit}
     -H Accept: application/json

delete users

delete /users

delete multiple users by supplying their ids, all supplied users must be existing users, this operation is atomic and will fail if any of the supplied user ids does not exist

Body example

json[
  "id0",
  "id1",
  "..idn"
]

Responses

2XX

default

json{
  "status": 4
}

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X DELETE /users
     -H Accept: application/json
     -H Content-Type: application/json
     -d '["id0","id1","..idn"]'

moderate users

post /users/moderate

moderate multiple users by supplying their ids and the desired mode.

Body example

json{
  "ids": [
    "id0",
    "..idn"
  ],
  "mode": 300
}

Responses

2XX

default

json{
  "status": 4
}

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X POST /users/moderate
     -H Accept: application/json
     -H Content-Type: application/json
     -d '{"ids":["id0","..idn"],"mode":300}'

channels

create channels

post /channels

create multiple channels

Body example

json[
  {
    "id": "cn01",
    "data": "{}",
    "users": [
      {
        "id": "uid0",
        "data": "{}",
        "mode": 300
      }
    ]
  }
]

Responses

2XX

default

json{
  "status": 4
}

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X POST /channels
     -H Accept: application/json
     -H Content-Type: application/json
     -d '[{"id":"cn01","data":"{}","users":[{"id":"uid0","data":"{}","mode":300}]}]'

list channels

get /channels

list application's perment channels. these channels can be used for colab, chat and calls.

parameters

in	name	required	type
query	starting_after	false	string
query	limit	false	number

Responses

2XX

default

json[
  {
    "id": "cn01",
    "data": "{}",
    "users": [
      {
        "id": "uid0",
        "data": "{}",
        "mode": 300
      }
    ]
  }
]

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X GET /channels?starting_after={starting_after}&limit={limit}
     -H Accept: application/json

delete channels

delete /channels

delete multiple channels by supplying their ids, all supplied channels must be existing channels, this operation is atomic and will fail if any of the supplied channel ids does not exist

Body example

json[
  "id0",
  "id1",
  "..idn"
]

Responses

2XX

default

json{
  "status": 4
}

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X DELETE /channels
     -H Accept: application/json
     -H Content-Type: application/json
     -d '["id0","id1","..idn"]'

update channels

put /channels

update multiple channels, the id field is required and all fields provided will be updated

Body example

json{
  "id": "cn01",
  "data": "{"public": true}"
}

Responses

2XX

default

json{
  "status": 4
}

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X PUT /channels
     -H Accept: application/json
     -H Content-Type: application/json
     -d '{"id":"cn01","data":"{"public": true}"}'

add members

post /channels/{id}/members

add users to channel

parameters

in	name	required	type
path	id	true	string

Body example

json[
  {
    "id": "00uid0",
    "mode": 300,
    "data": "{}"
  }
]

Responses

2XX

default

json{
  "status": 4
}

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X POST /channels/{id}/members?
     -H Accept: application/json
     -H Content-Type: application/json
     -d '[{"id":"00uid0","mode":300,"data":"{}"}]'

list members

get /channels/{id}/members

list channel members

parameters

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

Responses

2XX

default

json[
  {
    "id": "00uid0",
    "mode": 300,
    "data": "{}"
  }
]

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X GET /channels/{id}/members?starting_after={starting_after}&limit={limit}
     -H Accept: application/json

remove members

delete /channels/{id}/members

remove users from channel by supplying their ids

parameters

in	name	required	type
path	id	true	string

Body example

json[
  "id0",
  "id1",
  "..idn"
]

Responses

2XX

default

json{
  "status": 4
}

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X DELETE /channels/{id}/members?
     -H Accept: application/json
     -H Content-Type: application/json
     -d '["id0","id1","..idn"]'

moderate members

post /channels/{id}/members/moderate

moderate channel members

parameters

in	name	required	type
path	id	true	string

Body example

json{
  "ids": [
    "id0",
    "..idn"
  ],
  "mode": 300
}

Responses

2XX

default

json{
  "status": 4
}

json{
  "message": "internal server error",
  "code": "E5601",
  "error": "InternalError"
}

Curl Command

bashcurl -X POST /channels/{id}/members/moderate?
     -H Accept: application/json
     -H Content-Type: application/json
     -d '{"ids":["id0","..idn"],"mode":300}'