IoT Cloud Configuration v1.4.0

Specification of the API used to access and configure IoT Cloud services.

link https://api.iot.tcpisek.cz/v1

About

This documentation describes the configuration API of the IoT Platform.

Technical Contact:
support (at) hexio.io

© Copyright 2019 Hexio a.s. <www.hexio.io>

Changelog

v1.3.0 (2019-01-14)

  • POST /auth/login/credentials (implemented)
    The response code for invalid credentials was changed to 401.

  • PUT /auth/profile/password
    The response code for old password mismatch was added.

  • POST /auth/resetPassword
    The response code for invalid token was changed to 403.

  • GET /users/lookup
    The endpoint was deprecated.

  • POST /users/{userId}/resendWelcome renamed
    The endpoint POST /users/{userId}/resendWelcome was renamed to POST /users/{userId}/resendInvitation.

  • /mqtt-accounts
    Endpoints were marked as deprecated in favour of a new architecture.

  • Generic Collections
    Query parameters for filtering and sorting have changed. Query parameter isDeleted was removed.

  • Organization Entity New fields has been added and email field was marked as deprecated.
    Permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE were added.

  • Metrics Meta-data
    New endpoint for metrics meta-data was added: /orgs/{orgId}/projects/{projId}/metrics/{topic}/meta-data.
    Also new permission PROJECT_METRICS/UPDATE was added.

  • Permission endpoints
    Removed field availableRoles.

  • API credentials model
    Fields grafana and permissions marked as obsolete.

  • User entity
    Field phone is no longer required.

  • Project Channels
    Endpoints for project channels were added. New project permissions PROJECT_CHANNELS/* were added.

v1.4.0 (2019-08-01)

  • /orgs/{orgId}/projects/{projectId}/api
    Endpoints were marked as deprecated in favour of a new architecture.

  • Data Retention
    Added required property dataRetention for projects.

  • Project Stats
    Added datapoints enum as a option.

  • Project User Invitaion
    Endpoint for invite user to a project was added.

  • Organization User Invitaion
    Endpoint for invite user to a organization was added.

  • Device Management
    Basic CRUD endpoints for device management were added. Also new permissions PROJECT_DEVICE/* were added.

  • Device Manufacturers
    Basic CRUD endpoints for device manufacturers were added. Also new permissions DEVICE_MANUFACTURER/* were added.

  • Device Model
    Basic CRUD endpoints for device models were added. Also new permissions DEVICE_MODEL/* were added.

  • Meta-data
    Meta-data were moved from Metrics to Devices.

  • Server Status
    Endpoint for getting server status was added.

  • Move Project
    Project can be moved from one org to another now using /orgs/{orgId}/projects/{projectId}/move.

Editor Notes

Changes should be also mentioned in a description of individual components for at least one minor version if possible.

Resources

post /auth/login/credentials

Log in using credentials warning  

Logs a user in using a username and password.

Changes:
v1.3.0 - The response code for invalid credentials was changed to 401.

Breaking Change

Annotations chevron_right expand_more

  • Breaking Change

curl -X POST \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/auth/login/credentials

Request Body chevron_right expand_more

Credentials Request CredentialsRequest

application/json

Represents authentication request using username and password.

Inherits: object

ParameterTypeDescription
username*string

Username

password*string

Password

Request Body

Sample payload

Example username and password

{
  "username": "test",
  "password": "test123"
}

200 OK chevron_right expand_more

Login successfull

JWT Token JwtToken

application/json

Model containing a JWT authentication token.

Inherits: object

ParameterTypeDescription
token*string

A JWT token which must be passed as a Bearer Authorization header for future requests.

Response Body

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

401 Unauthorized chevron_right expand_more

Invalid credentials

404 Not Found chevron_right expand_more

Invalid credentials (deprecated)

post /auth/logout

Log out highlight_off  

Currently not working because there is no way how to revoke issued JWT token.

Not implemented

Annotations chevron_right expand_more

  • Not Implemented

curl -X POST \
  https://api.iot.tcpisek.cz/v1/auth/logout

204 No Content chevron_right expand_more

Logout successfull

post /auth/renewToken

Renew JWT token  lock

Renews the JWT token for future requests.

Request MUST be authorized with proper valid JWT token. New token can be issued only 10 minutes before expiration of the old one.

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

curl -X POST \
  https://api.iot.tcpisek.cz/v1/auth/renewToken

200 OK chevron_right expand_more

Token has been renewed.

JWT Token JwtToken

application/json

Model containing a JWT authentication token.

Inherits: object

ParameterTypeDescription
token*string

A JWT token which must be passed as a Bearer Authorization header for future requests.

Response Body

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

400 Bad Request chevron_right expand_more

Old token is not expiring yet.

API Error ApiError

application/json

Object representing an API error. Can contain additional properties related to specific errors.

Additional properties: Yes

Inherits: object

ParameterTypeDescription
timestamp*datetime

DateTime when error occured.

Format: rfc3339

status*integer

Status code.

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Invalid payload

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Invalid payload.",
  "message": "Property 'name' is required."
}

get /auth/profile

Get user profile  lock

Returns the current user profile.

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

curl -X GET \
  https://api.iot.tcpisek.cz/v1/auth/profile

200 OK chevron_right expand_more

The user profile.

User Entity UserProfile

application/json

User data model for full entity.

Inherits: UserProfileBase UserIdentifiers

ParameterTypeDescription
userId*integer

User ID

type*string

User account type

Enum:
  • regular
username*string

Username - must be unique.

Min. length: 4

Max. length: 255

firstName*string

First name

Max. length: 255

lastName*string

First name

Max. length: 255

email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

phone phonestring

Phone. No longer required since v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

lang*string

User UI language

Enum:
  • en
  • cs
hasProfilePicture*boolean

If the user has a profile picture uploaded.

permissions* permissionsarray

User permissions.

Inherits: array

permissions[]string

Permission name.

Enum:
  • ADMIN/READ
  • ADMIN_USER/READ
  • ADMIN_USER/CREATE
  • ADMIN_USER/UPDATE
  • ADMIN_USER/DELETE
  • ADMIN_USER/GRANT
  • ADMIN_ORGS/READ
  • ADMIN_NEW_CUSTOMER/CREATE
  • ORG/CREATE

Response Body

{
  "userId": 42,
  "type": "regular",
  "username": "john.doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.tld",
  "phone": "+420 123 456 789",
  "lang": "en",
  "hasProfilePicture": false,
  "permissions": [
    "ADMIN/READ",
    "ADMIN_ORGS/READ",
    "ADMIN_NEW_CUSTOMER/CREATE",
    "ORG/CREATE"
  ]
}

put /auth/profile

Update user profile  lock

Updates the current user profile.

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

curl -X PUT \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/auth/profile

Request Body chevron_right expand_more

User Profile Update Request UserUpdateProfileReq

application/json

Data model for the user profile update request.

Inherits: UserProfileBase

ParameterTypeDescription
firstName*string

First name

Max. length: 255

lastName*string

First name

Max. length: 255

email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

phone phonestring

Phone. No longer required since v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

lang*string

User UI language

Enum:
  • en
  • cs

Request Body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.tld",
  "phone": "+420 123 456 789",
  "lang": "en"
}

200 OK chevron_right expand_more

The user profile.

User Entity UserProfile

application/json

User data model for full entity.

Inherits: UserProfileBase UserIdentifiers

ParameterTypeDescription
userId*integer

User ID

type*string

User account type

Enum:
  • regular
username*string

Username - must be unique.

Min. length: 4

Max. length: 255

firstName*string

First name

Max. length: 255

lastName*string

First name

Max. length: 255

email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

phone phonestring

Phone. No longer required since v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

lang*string

User UI language

Enum:
  • en
  • cs
hasProfilePicture*boolean

If the user has a profile picture uploaded.

permissions* permissionsarray

User permissions.

Inherits: array

permissions[]string

Permission name.

Enum:
  • ADMIN/READ
  • ADMIN_USER/READ
  • ADMIN_USER/CREATE
  • ADMIN_USER/UPDATE
  • ADMIN_USER/DELETE
  • ADMIN_USER/GRANT
  • ADMIN_ORGS/READ
  • ADMIN_NEW_CUSTOMER/CREATE
  • ORG/CREATE

Response Body

{
  "userId": 42,
  "type": "regular",
  "username": "john.doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.tld",
  "phone": "+420 123 456 789",
  "lang": "en",
  "hasProfilePicture": false,
  "permissions": [
    "ADMIN/READ",
    "ADMIN_ORGS/READ",
    "ADMIN_NEW_CUSTOMER/CREATE",
    "ORG/CREATE"
  ]
}

400 Bad Request chevron_right expand_more

The payload is not valid.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

put /auth/profile/password

Change Password warning  lock

Changes the current user password.

Changes:
v1.3.0 - The response code for old password mismatch was added.

Breaking Change

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Breaking Change

curl -X PUT \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/auth/profile/password

Request Body chevron_right expand_more

Change Profile Password Request ChangeProfilePasswordReq

application/json

Data model describing request to change a user password.

Inherits: object

ParameterTypeDescription
oldPassword*string

Old password

newPassword* newPasswordstring

New password

Min. length: 6

Max. length: 1024

Inherits: string

Request Body

{
  "oldPassword": "password123",
  "newPassword": "password456"
}

204 No Content chevron_right expand_more

Password has been changed.

409 Conflict chevron_right expand_more

The old password does not match.

Password Match Error PasswordMatchError

application/json

Error object returned when a request to change a password failed because an old password does not match.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 409

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Password does not match

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 409,
  "error": "Password Match Error",
  "message": "The old password does not match."
}

post /auth/forgotPassword

Forgot Password  

Requests user account password reset.

The e-mail message with password reset details should be sent to the user.

curl -X POST \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/auth/forgotPassword

Request Body chevron_right expand_more

Forgot Password Request ForgotPasswordReq

application/json

Object describing request to reset password.

Inherits: object

ParameterTypeDescription
email* emailstring

E-mail address of an account the password should be reset for.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

Request Body

{
  "email": "john@doe.tld"
}

204 No Content chevron_right expand_more

Request fullfilled.

400 Bad Request chevron_right expand_more

The payload is not valid.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

404 Not Found chevron_right expand_more

User with given e-mail address was not found.

API Error ApiError

application/json

Object representing an API error. Can contain additional properties related to specific errors.

Additional properties: Yes

Inherits: object

ParameterTypeDescription
timestamp*datetime

DateTime when error occured.

Format: rfc3339

status*integer

Status code.

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Invalid payload

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Invalid payload.",
  "message": "Property 'name' is required."
}

post /auth/resetPassword

Reset Password warning  

Resets a user account password based on previous forgot password request.

Changes:
v1.3.0 - The response code for invalid token was changed to 403.

Breaking Change

Annotations chevron_right expand_more

  • Breaking Change

curl -X POST \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/auth/resetPassword

Request Body chevron_right expand_more

Reset Password Request ResetPasswordReq

application/json

Object describing request to change password via reset link.

Inherits: object

ParameterTypeDescription
token*string

The password reset token.

password* passwordstring

New password

Min. length: 6

Max. length: 1024

Inherits: string

Request Body

{
  "token": "xxxZHNqZiBsZml3aiBramRzZmlqaSBqZGZqIGl3ZWogaXdlaiBsa2Rqc2ZpaiBlaWZqIGtqZGZsa2pkc2xrZmogbGRqZmsgY3YsbWNudiwgamRzbGtmaiBsaWZ1ciBpdyBla2xqc2tkbCBmbW52LG0gY254dnNkZGZsd2VpZXcgcmlqIGZrbHNqZCBma2xtdm5jeCx2IGRzbGpmIGl3ag==",
  "password": "password789"
}

204 No Content chevron_right expand_more

Request fullfilled.

400 Bad Request chevron_right expand_more

The payload is not valid.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

403 Forbidden chevron_right expand_more

The provided token is not valid.

API Error ApiError

application/json

Object representing an API error. Can contain additional properties related to specific errors.

Additional properties: Yes

Inherits: object

ParameterTypeDescription
timestamp*datetime

DateTime when error occured.

Format: rfc3339

status*integer

Status code.

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Invalid payload

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Invalid payload.",
  "message": "Property 'name' is required."
}

404 Not Found chevron_right expand_more

Invalid token (deprecated)

get /orgs

Get organization list warning  lock

Returns a collection of organization records.

Changes:
v1.3.0 - Query parameters for filtering and sorting have changed. Query parameter isDeleted was removed.

Breaking Change

Parameters chevron_right expand_more

ParameterTypeDescription
Query
limitinteger

Maximum count of returned records.

Max. value: 1000

Default value: 100

offsetinteger

Record count offset.

withCountboolean

If total record count should be included in the response.

filterarray

Collection filters.

filter[] Organization Filter Paramobject

Filter settings.

Additional properties: Yes

Inherits: FilterParam

filter[].field*string

Field to filter on.

Enum:
  • name
  • companyId
  • vatId
  • active
  • fulltext
filter[].op*string

Filter operator. Size comparisions are allowed only on numerical fields.

Enum:
  • eq
  • contains
  • starts
  • ends
  • lt
  • lte
  • gt
  • gte
filter[].value*string

Filter value.

sortarray

Collection sorting.

sort[] Organization Sort Paramobject

Sort settings.

Additional properties: Yes

Inherits: SortParam

sort[].field*string

Field to sort by.

Enum:
  • name
sort[].order*string

Order type.

Enum:
  • asc
  • desc

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Breaking Change

curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs?limit=<value>&offset=<value>&withCount=<value>&filter[][field]=<value>&filter[][op]=<value>&filter[][value]=<value>&sort[][field]=<value>&sort[][order]=<value>

200 OK chevron_right expand_more

Collection items.

Organization Collection Response OrgCollectionRes

application/json

Response of the organization collection.

Inherits: CollectionRes

ParameterTypeDescription
items*array

Collection items.

items[] Organization Entityobject

Organization data model for full entity.

Inherits: EntityMetaDataDeletable OrgBase OrgIdentifiers

items[].orgId*integer

Organization ID.

items[].genId*string

Unique generated organization ID.

items[].name*string

Organization name.
Change of this field requires ORG/ADMIN_UPDATE permission since v1.3.0 (not implemented).

Min. length: 1

Max. length: 128

items[].descriptionstring

Description.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE since v1.3.0 (not implemented).

Max. length: 255

items[].companyIdstring

Legal company ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

items[].vatIdstring

VAT ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

items[].email emailstring

General contact email - DEPRECATED since v1.3.0. Use contactEmail instead.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

items[].contactEmail contactEmailstring

General contact email.
Added in v1.3.0.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

items[].contactPhone contactPhonestring

General contact phone.
Added in v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

items[].contactPersonstring

Name of a general contact person.
Added in v1.3.0.

Max. length: 128

items[].contactLangstring

General communication language.
Added in v1.3.0.

Max. length: 32

items[].notestring

Internal note.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

items[].logoUrlstring

URL to company logo.

Max. length: 1024

items[].externalUrlstring

Internal URL to optional external system such as CRM.
Not accessible by a regular user - requires special permission ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

Max. length: 1024

items[].projectsLimit*integer

Maximum number of projects in organization. -1 for unlimited.

items[].usersLimit*integer

Maximum number of users in organization. -1 for unlimited.

items[].devicesLimit*integer

Maximum number of devices in organization. -1 for unlimited.

items[].dashboardsLimit*integer

Maximum number of dashboards in organization. -1 for unlimited.

items[].amountOfDatapoints*integer

Number of datapoints for organization. -1 for unlimited.

items[].enabled*boolean

If the organization is enabled.
Disabled organization cannot be accessible without ORG/ADMIN_READ permission. Change of this field requires ORG/ADMIN_UPDATE permission.

items[].created*datetime

DateTime when the entity was created.

Format: rfc3339

items[].createdBy*string

Username of an account which has created the entity.

items[].modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

items[].modifiedBy*string

Username of an account which has modified the entity last.

items[].deleted*boolean

If the entity was deleted.

items[].permissions*array

Organization permissions.

Inherits: OrgPermissions

items[].permissions[]string

Permission name.

Permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE were added in v1.3.0 (not implemented).

Enum:
  • ORG/UPDATE
  • ORG/DELETE
  • ORG/GRANT
  • ORG/ADMIN_READ
  • ORG/ADMIN_UPDATE
  • PROJECT/CREATE
permissions*array

User permissions related to the collection.

permissions[]string

Permission name.

Enum:
  • ORG/CREATE
countinteger

Optional count of all collection items with respect to filters.

limit*integer

The limit value from the query parameter - helps a client to determine pagination.

offset*integer

The offset value from the query parameter - helps a client to determine pagination.

Response Body

{
  "items": [
    {
      "orgId": 42,
      "genId": "Da32pax0",
      "name": "Company ltd.",
      "description": "SmartCity projects.",
      "companyId": "12345678",
      "vatId": "CZ12345678",
      "contactEmail": "info@company.tld",
      "contactPhone": "+420 123 456 789",
      "contactPerson": "John Doe",
      "contactLang": "English",
      "note": "Jack Doe is responsible for this customer.",
      "logoUrl": "https://web.com/logo.png",
      "externalUrl": "https://web.com/",
      "projectsLimit": 5,
      "dashboardsLimit": 50,
      "usersLimit": 500,
      "devicesLimit": 5000,
      "amountOfDatapoints": 50000,
      "enabled": true,
      "permissions": [
        "ORG/UPDATE",
        "PROJECT/CREATE"
      ],
      "created": "2019-01-13T23:46:06.090Z",
      "createdBy": "john.doe",
      "modified": "2019-01-13T23:46:06.090Z",
      "modifiedBy": "john.doe",
      "deleted": false
    },
    {
      "orgId": 43,
      "genId": "Ur24ah8d",
      "name": "Company ltd.",
      "description": "SmartCity projects.",
      "companyId": "12345678",
      "vatId": "CZ12345678",
      "contactEmail": "info@company.tld",
      "contactPhone": "+420 123 456 789",
      "contactPerson": "John Doe",
      "contactLang": "English",
      "note": "Jack Doe is responsible for this customer.",
      "logoUrl": "https://web.com/logo.png",
      "externalUrl": "https://web.com/",
      "projectsLimit": 5,
      "usersLimit": 50,
      "dashboardsLimit": 500,
      "devicesLimit": 5000,
      "amountOfDatapoints": 50000,
      "enabled": true,
      "permissions": [
        "ORG/UPDATE",
        "PROJECT/CREATE"
      ],
      "created": "2019-01-13T23:46:06.090Z",
      "createdBy": "john.doe",
      "modified": "2019-01-13T23:46:06.090Z",
      "modifiedBy": "john.doe",
      "deleted": false
    },
    {
      "orgId": 44,
      "genId": "Pa24garI",
      "name": "Company ltd.",
      "description": "SmartCity projects.",
      "companyId": "12345678",
      "vatId": "CZ12345678",
      "contactEmail": "info@company.tld",
      "contactPhone": "+420 123 456 789",
      "contactPerson": "John Doe",
      "contactLang": "Czech",
      "note": "Jack Doe is responsible for this customer.",
      "logoUrl": "https://web.com/logo.png",
      "externalUrl": "https://web.com/",
      "projectsLimit": 5,
      "usersLimit": 500,
      "dashboardsLimit": 50,
      "devicesLimit": 5000,
      "amountOfDatapoints": 50000,
      "enabled": false,
      "permissions": [
        "ORG/UPDATE",
        "PROJECT/CREATE"
      ],
      "created": "2019-01-13T23:46:06.090Z",
      "createdBy": "john.doe",
      "modified": "2019-01-13T23:46:06.090Z",
      "modifiedBy": "john.doe",
      "deleted": false
    }
  ],
  "count": 3,
  "limit": 100,
  "offset": 0,
  "permissions": [
    "ORG/CREATE"
  ]
}

post /orgs

Create organization  lock vpn_key

Creates a new organization.

vpn_key Required permissions

ORG/CREATE

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/CREATE
curl -X POST \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs

Request Body chevron_right expand_more

Organization Create Request OrgCreateReq

application/json

Data model for the organization create request.

Inherits: OrgBase

ParameterTypeDescription
name*string

Organization name.
Change of this field requires ORG/ADMIN_UPDATE permission since v1.3.0 (not implemented).

Min. length: 1

Max. length: 128

descriptionstring

Description.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE since v1.3.0 (not implemented).

Max. length: 255

companyIdstring

Legal company ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

vatIdstring

VAT ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

email emailstring

General contact email - DEPRECATED since v1.3.0. Use contactEmail instead.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

contactEmail contactEmailstring

General contact email.
Added in v1.3.0.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

contactPhone contactPhonestring

General contact phone.
Added in v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

contactPersonstring

Name of a general contact person.
Added in v1.3.0.

Max. length: 128

contactLangstring

General communication language.
Added in v1.3.0.

Max. length: 32

notestring

Internal note.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

logoUrlstring

URL to company logo.

Max. length: 1024

externalUrlstring

Internal URL to optional external system such as CRM.
Not accessible by a regular user - requires special permission ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

Max. length: 1024

projectsLimit*integer

Maximum number of projects in organization. -1 for unlimited.

usersLimit*integer

Maximum number of users in organization. -1 for unlimited.

devicesLimit*integer

Maximum number of devices in organization. -1 for unlimited.

dashboardsLimit*integer

Maximum number of dashboards in organization. -1 for unlimited.

amountOfDatapoints*integer

Number of datapoints for organization. -1 for unlimited.

enabled*boolean

If the organization is enabled.
Disabled organization cannot be accessible without ORG/ADMIN_READ permission. Change of this field requires ORG/ADMIN_UPDATE permission.

Request Body

{
  "name": "Company ltd.",
  "description": "SmartCity projects.",
  "companyId": "12345678",
  "vatId": "CZ12345678",
  "contactEmail": "info@company.tld",
  "contactPhone": "+420 123 456 789",
  "contactPerson": "John Doe",
  "contactLang": "English",
  "note": "Jack Doe is responsible for this customer.",
  "logoUrl": "https://web.com/logo.png",
  "externalUrl": "https://web.com/",
  "projectsLimit": 5,
  "usersLimit": 500,
  "dashboardsLimit": 50,
  "devicesLimit": 5000,
  "amountOfDatapoints": 50000,
  "enabled": true
}

201 Created chevron_right expand_more

Organization has been created.

Organization Entity OrgEntity

application/json

Organization data model for full entity.

Inherits: EntityMetaDataDeletable OrgBase OrgIdentifiers

ParameterTypeDescription
orgId*integer

Organization ID.

genId*string

Unique generated organization ID.

name*string

Organization name.
Change of this field requires ORG/ADMIN_UPDATE permission since v1.3.0 (not implemented).

Min. length: 1

Max. length: 128

descriptionstring

Description.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE since v1.3.0 (not implemented).

Max. length: 255

companyIdstring

Legal company ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

vatIdstring

VAT ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

email emailstring

General contact email - DEPRECATED since v1.3.0. Use contactEmail instead.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

contactEmail contactEmailstring

General contact email.
Added in v1.3.0.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

contactPhone contactPhonestring

General contact phone.
Added in v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

contactPersonstring

Name of a general contact person.
Added in v1.3.0.

Max. length: 128

contactLangstring

General communication language.
Added in v1.3.0.

Max. length: 32

notestring

Internal note.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

logoUrlstring

URL to company logo.

Max. length: 1024

externalUrlstring

Internal URL to optional external system such as CRM.
Not accessible by a regular user - requires special permission ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

Max. length: 1024

projectsLimit*integer

Maximum number of projects in organization. -1 for unlimited.

usersLimit*integer

Maximum number of users in organization. -1 for unlimited.

devicesLimit*integer

Maximum number of devices in organization. -1 for unlimited.

dashboardsLimit*integer

Maximum number of dashboards in organization. -1 for unlimited.

amountOfDatapoints*integer

Number of datapoints for organization. -1 for unlimited.

enabled*boolean

If the organization is enabled.
Disabled organization cannot be accessible without ORG/ADMIN_READ permission. Change of this field requires ORG/ADMIN_UPDATE permission.

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

permissions*array

Organization permissions.

Inherits: OrgPermissions

permissions[]string

Permission name.

Permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE were added in v1.3.0 (not implemented).

Enum:
  • ORG/UPDATE
  • ORG/DELETE
  • ORG/GRANT
  • ORG/ADMIN_READ
  • ORG/ADMIN_UPDATE
  • PROJECT/CREATE

Response Body

{
  "orgId": 42,
  "genId": "Da32pax0",
  "name": "Company ltd.",
  "description": "SmartCity projects.",
  "companyId": "12345678",
  "vatId": "CZ12345678",
  "contactEmail": "info@company.tld",
  "contactPhone": "+420 123 456 789",
  "contactPerson": "John Doe",
  "contactLang": "English",
  "note": "Jack Doe is responsible for this customer.",
  "logoUrl": "https://web.com/logo.png",
  "externalUrl": "https://web.com/",
  "projectsLimit": 5,
  "usersLimit": 50,
  "dashboardsLimit": 500,
  "devicesLimit": 5000,
  "amountOfDatapoints": 50000,
  "enabled": true,
  "permissions": [
    "ORG/UPDATE",
    "PROJECT/CREATE"
  ],
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "john.doe",
  "deleted": false
}

400 Bad Request chevron_right expand_more

Invalid payload or constraint violated.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

get /orgs/{orgId}

Get organization  lock vpn_key

Returns an organization entity based on ID.

vpn_key Required permissions

ORG/READ

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/READ
curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}

200 OK chevron_right expand_more

The organization entity.

Organization Entity OrgEntity

application/json

Organization data model for full entity.

Inherits: EntityMetaDataDeletable OrgBase OrgIdentifiers

ParameterTypeDescription
orgId*integer

Organization ID.

genId*string

Unique generated organization ID.

name*string

Organization name.
Change of this field requires ORG/ADMIN_UPDATE permission since v1.3.0 (not implemented).

Min. length: 1

Max. length: 128

descriptionstring

Description.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE since v1.3.0 (not implemented).

Max. length: 255

companyIdstring

Legal company ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

vatIdstring

VAT ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

email emailstring

General contact email - DEPRECATED since v1.3.0. Use contactEmail instead.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

contactEmail contactEmailstring

General contact email.
Added in v1.3.0.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

contactPhone contactPhonestring

General contact phone.
Added in v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

contactPersonstring

Name of a general contact person.
Added in v1.3.0.

Max. length: 128

contactLangstring

General communication language.
Added in v1.3.0.

Max. length: 32

notestring

Internal note.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

logoUrlstring

URL to company logo.

Max. length: 1024

externalUrlstring

Internal URL to optional external system such as CRM.
Not accessible by a regular user - requires special permission ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

Max. length: 1024

projectsLimit*integer

Maximum number of projects in organization. -1 for unlimited.

usersLimit*integer

Maximum number of users in organization. -1 for unlimited.

devicesLimit*integer

Maximum number of devices in organization. -1 for unlimited.

dashboardsLimit*integer

Maximum number of dashboards in organization. -1 for unlimited.

amountOfDatapoints*integer

Number of datapoints for organization. -1 for unlimited.

enabled*boolean

If the organization is enabled.
Disabled organization cannot be accessible without ORG/ADMIN_READ permission. Change of this field requires ORG/ADMIN_UPDATE permission.

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

permissions*array

Organization permissions.

Inherits: OrgPermissions

permissions[]string

Permission name.

Permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE were added in v1.3.0 (not implemented).

Enum:
  • ORG/UPDATE
  • ORG/DELETE
  • ORG/GRANT
  • ORG/ADMIN_READ
  • ORG/ADMIN_UPDATE
  • PROJECT/CREATE

Response Body

{
  "orgId": 42,
  "genId": "Da32pax0",
  "name": "Company ltd.",
  "description": "SmartCity projects.",
  "companyId": "12345678",
  "vatId": "CZ12345678",
  "contactEmail": "info@company.tld",
  "contactPhone": "+420 123 456 789",
  "contactPerson": "John Doe",
  "contactLang": "English",
  "note": "Jack Doe is responsible for this customer.",
  "logoUrl": "https://web.com/logo.png",
  "externalUrl": "https://web.com/",
  "projectsLimit": 5,
  "usersLimit": 50,
  "dashboardsLimit": 500,
  "devicesLimit": 5000,
  "amountOfDatapoints": 50000,
  "enabled": true,
  "permissions": [
    "ORG/UPDATE",
    "PROJECT/CREATE"
  ],
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "john.doe",
  "deleted": false
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

put /orgs/{orgId}

Update organization  lock vpn_key

Updates the organization entity.

vpn_key Required permissions

ORG/UPDATE

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/UPDATE
curl -X PUT \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}

Request Body chevron_right expand_more

Organization Update Request OrgUpdateReq

application/json

Data model for the organization update request.

Inherits: OrgBase

ParameterTypeDescription
name*string

Organization name.
Change of this field requires ORG/ADMIN_UPDATE permission since v1.3.0 (not implemented).

Min. length: 1

Max. length: 128

descriptionstring

Description.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE since v1.3.0 (not implemented).

Max. length: 255

companyIdstring

Legal company ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

vatIdstring

VAT ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

email emailstring

General contact email - DEPRECATED since v1.3.0. Use contactEmail instead.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

contactEmail contactEmailstring

General contact email.
Added in v1.3.0.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

contactPhone contactPhonestring

General contact phone.
Added in v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

contactPersonstring

Name of a general contact person.
Added in v1.3.0.

Max. length: 128

contactLangstring

General communication language.
Added in v1.3.0.

Max. length: 32

notestring

Internal note.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

logoUrlstring

URL to company logo.

Max. length: 1024

externalUrlstring

Internal URL to optional external system such as CRM.
Not accessible by a regular user - requires special permission ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

Max. length: 1024

projectsLimit*integer

Maximum number of projects in organization. -1 for unlimited.

usersLimit*integer

Maximum number of users in organization. -1 for unlimited.

devicesLimit*integer

Maximum number of devices in organization. -1 for unlimited.

dashboardsLimit*integer

Maximum number of dashboards in organization. -1 for unlimited.

amountOfDatapoints*integer

Number of datapoints for organization. -1 for unlimited.

enabled*boolean

If the organization is enabled.
Disabled organization cannot be accessible without ORG/ADMIN_READ permission. Change of this field requires ORG/ADMIN_UPDATE permission.

Request Body

{
  "name": "Company ltd.",
  "description": "SmartCity projects.",
  "companyId": "12345678",
  "vatId": "CZ12345678",
  "contactEmail": "info@company.tld",
  "contactPhone": "+420 123 456 789",
  "contactPerson": "John Doe",
  "contactLang": "English",
  "note": "Jack Doe is responsible for this customer.",
  "logoUrl": "https://web.com/logo.png",
  "externalUrl": "https://web.com/",
  "projectsLimit": 5,
  "usersLimit": 500,
  "dashboardsLimit": 50,
  "devicesLimit": 5000,
  "amountOfDatapoints": 50000,
  "enabled": true
}

200 OK chevron_right expand_more

Organization has been updated.

Organization Entity OrgEntity

application/json

Organization data model for full entity.

Inherits: EntityMetaDataDeletable OrgBase OrgIdentifiers

ParameterTypeDescription
orgId*integer

Organization ID.

genId*string

Unique generated organization ID.

name*string

Organization name.
Change of this field requires ORG/ADMIN_UPDATE permission since v1.3.0 (not implemented).

Min. length: 1

Max. length: 128

descriptionstring

Description.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE since v1.3.0 (not implemented).

Max. length: 255

companyIdstring

Legal company ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

vatIdstring

VAT ID.
Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0.

Max. length: 32

email emailstring

General contact email - DEPRECATED since v1.3.0. Use contactEmail instead.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

contactEmail contactEmailstring

General contact email.
Added in v1.3.0.

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

contactPhone contactPhonestring

General contact phone.
Added in v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

contactPersonstring

Name of a general contact person.
Added in v1.3.0.

Max. length: 128

contactLangstring

General communication language.
Added in v1.3.0.

Max. length: 32

notestring

Internal note.
Not accessible by a regular user - requires special permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

logoUrlstring

URL to company logo.

Max. length: 1024

externalUrlstring

Internal URL to optional external system such as CRM.
Not accessible by a regular user - requires special permission ORG/ADMIN_READ and ORG/ADMIN_UPDATE.
Added in v1.3.0.

Max. length: 1024

projectsLimit*integer

Maximum number of projects in organization. -1 for unlimited.

usersLimit*integer

Maximum number of users in organization. -1 for unlimited.

devicesLimit*integer

Maximum number of devices in organization. -1 for unlimited.

dashboardsLimit*integer

Maximum number of dashboards in organization. -1 for unlimited.

amountOfDatapoints*integer

Number of datapoints for organization. -1 for unlimited.

enabled*boolean

If the organization is enabled.
Disabled organization cannot be accessible without ORG/ADMIN_READ permission. Change of this field requires ORG/ADMIN_UPDATE permission.

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

permissions*array

Organization permissions.

Inherits: OrgPermissions

permissions[]string

Permission name.

Permissions ORG/ADMIN_READ and ORG/ADMIN_UPDATE were added in v1.3.0 (not implemented).

Enum:
  • ORG/UPDATE
  • ORG/DELETE
  • ORG/GRANT
  • ORG/ADMIN_READ
  • ORG/ADMIN_UPDATE
  • PROJECT/CREATE

Response Body

{
  "orgId": 42,
  "genId": "Da32pax0",
  "name": "Company ltd.",
  "description": "SmartCity projects.",
  "companyId": "12345678",
  "vatId": "CZ12345678",
  "contactEmail": "info@company.tld",
  "contactPhone": "+420 123 456 789",
  "contactPerson": "John Doe",
  "contactLang": "English",
  "note": "Jack Doe is responsible for this customer.",
  "logoUrl": "https://web.com/logo.png",
  "externalUrl": "https://web.com/",
  "projectsLimit": 5,
  "usersLimit": 50,
  "dashboardsLimit": 500,
  "devicesLimit": 5000,
  "amountOfDatapoints": 50000,
  "enabled": true,
  "permissions": [
    "ORG/UPDATE",
    "PROJECT/CREATE"
  ],
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "john.doe",
  "deleted": false
}

400 Bad Request chevron_right expand_more

Invalid payload or constraint violated.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

delete /orgs/{orgId}

Delete organization  lock vpn_key

Deletes the organization entity.

Constraints:
Organization cannot be deleted if contains any sub resources.

vpn_key Required permissions

ORG/DELETE

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/DELETE
curl -X DELETE \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}

204 No Content chevron_right expand_more

Organization was deleted.

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

get /orgs/{orgId}/permissions

Get permissions  lock vpn_key

Returns permissions assigned to the organization.

Resource type: is always ORG.

Changes:
v1.3.0 - Parameter withRoles and a availableRoles response property were removed.

vpn_key Required permissions

ORG/GRANT

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

Query
withUsersboolean

If to return related user snippets.

withOrgsboolean

If to return related organization snippets.

withProjectsboolean

If to return related project snippets.

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/GRANT
curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/permissions?withUsers=<value>&withOrgs=<value>&withProjects=<value>

200 OK chevron_right expand_more

Assigned permissions.

Permissions Response PermissionsRes

application/json

Model describing permissions assigned to the resource or a user and related entities snippets.

Changes:
v1.3.0 - Removed field availableRoles.

Inherits: object

ParameterTypeDescription
assignedRoles*array

List of assigned roles

assignedRoles[] Role Assignmentobject

Model describing a role assigned to a user and a resource.

Inherits: Roles

assignedRoles[].roles*array

List of assigned roles

assignedRoles[].roles[]integer

Role ID

assignedRoles[].resourceType*string

Resource type

Enum:
  • ORG
  • PROJECT
  • ADMIN
  • ADMIN_USER
  • ADMIN_ORGS
  • ADMIN_ROLES
  • ADMIN_NEW_CUSTOMER
  • ADMIN_MQTT_ACC
  • ADMIN_MQTT_ACC_AUTH
assignedRoles[].resourceIdinteger

Resource ID

Can be null if a role is assigned globally to all resources of a given type.

assignedRoles[].userId*integer

User ID

usersarray

List of user snippets of users which are present in an assignedRoles array. Returned only if withUsers query parameter is true.

users[] User Snippetobject

User entity snippet data model.

Inherits: UserSnippet

users[].userId*integer

User ID

users[].username*string

Username

users[].firstName*string

First name

users[].lastName*string

First name

users[].email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

users[].hasProfilePicture*boolean

If the user has a profile picture uploaded.

users[].enabled*boolean

If the user is enabled

orgsarray

List of organization snippets of organizations which are present in an assignedRoles array. Returned only if withOrgs query parameter is true.

orgs[] Organization Snippetobject

Organization entity snippet model.

Changes: v1.3.0 - Field `active was added.

Inherits: OrgSnippet

orgs[].orgId*integer

Organization ID.

orgs[].name*string

Organization name.
Change of this field requires ORG/ADMIN_UPDATE permission since v1.3.0 (not implemented).

Min. length: 1

Max. length: 128

orgs[].enabled*boolean

If the organization is enabled.
Disabled organization cannot be accessible without ORG/ADMIN_READ permission. Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0, not implemented.

projectsarray

List of project snippets of projects which are present in an assignedRoles array. Returned only if withProjects query parameter is true.

projects[] Project Snippetobject

Project entity snippet model.

Changes: v1.3.0 - Field description was added.

Inherits: ProjectSnippet

projects[].projectId*integer

Project ID.

projects[].orgId*integer

Organization ID.

projects[].name*string

Project name

Min. length: 1

Max. length: 128

projects[].descriptionstring

Description

Max. length: 255

Response Body

Permissions related to an organization

{
  "assignedRoles": [
    {
      "userId": 12,
      "resourceType": "ORG",
      "resourceId": 42,
      "roles": [
        3,
        5
      ]
    },
    {
      "userId": 13,
      "resourceType": "ORG",
      "resourceId": 42,
      "roles": [
        4,
        5
      ]
    }
  ],
  "users": [
    {
      "userId": 12,
      "username": "john.doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@doe.tld",
      "hasProfilePicture": true,
      "enabled": true
    },
    {
      "userId": 13,
      "username": "jack.doe",
      "firstName": "Jack",
      "lastName": "Doe",
      "email": "jack@doe.tld",
      "hasProfilePicture": true,
      "enabled": true
    }
  ],
  "orgs": [
    {
      "orgId": 42,
      "name": "Company ltd.",
      "enabled": true
    }
  ],
  "projects": []
}

Permissions related to a user

{
  "assignedRoles": [
    {
      "userId": 12,
      "resourceType": "ORG",
      "resourceId": 11,
      "roles": [
        1
      ]
    },
    {
      "userId": 12,
      "resourceType": "PROJECT",
      "resourceId": 22,
      "roles": [
        2
      ]
    }
  ],
  "users": [
    {
      "userId": 12,
      "username": "john.doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@doe.tld",
      "hasProfilePicture": true,
      "enabled": true
    }
  ],
  "orgs": [
    {
      "orgId": 11,
      "name": "Company ltd.",
      "enabled": true
    }
  ],
  "projects": [
    {
      "projectId": 22,
      "orgId": 11,
      "name": "My Project",
      "description": "Project for smart parking."
    }
  ]
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

put /orgs/{orgId}/permissions

Update permissions  lock vpn_key

Updates permissions assigned to the organization.

Resource type: is always ORG.

When the payload is an empty array nothing is changed.

When the roles property in a payload item is empty then access for a given combination of a user and resource is removed.

vpn_key Required permissions

ORG/GRANT

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/GRANT
curl -X PUT \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/permissions

Request Body chevron_right expand_more

Permissions Request PermissionsReq

application/json

Model describing a request to update permissions assigned to a resource or a user.

Inherits: array

ParameterTypeDescription
[] Role Assignmentobject

Model describing a role assigned to a user and a resource.

Inherits: Roles

[].roles*array

List of assigned roles

[].roles[]integer

Role ID

[].resourceType*string

Resource type

Enum:
  • ORG
  • PROJECT
  • ADMIN
  • ADMIN_USER
  • ADMIN_ORGS
  • ADMIN_ROLES
  • ADMIN_NEW_CUSTOMER
  • ADMIN_MQTT_ACC
  • ADMIN_MQTT_ACC_AUTH
[].resourceIdinteger

Resource ID

Can be null if a role is assigned globally to all resources of a given type.

[].userId*integer

User ID

Request Body

[
  {
    "userId": 12,
    "resourceType": "ORG",
    "resourceId": 42,
    "roles": [
      3,
      5
    ]
  },
  {
    "userId": 13,
    "resourceType": "ORG",
    "resourceId": 42,
    "roles": [
      4,
      5
    ]
  }
]

204 No Content chevron_right expand_more

Permissions were updated.

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

post /orgs/{orgId}/invite

Invite user highlight_off  lock vpn_key

Invite user to the organization.

Not implemented

vpn_key Required permissions

ORG/ADMIN

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Not Implemented

  • Permissions:

    • ORG/ADMIN
curl -X POST \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/invite

Request Body chevron_right expand_more

User Invitation UserCreateWithPermsReq

application/json

User data model for full entity.

Inherits: UserCreateReq Roles

ParameterTypeDescription
roles*array

List of assigned roles

roles[]integer

Role ID

firstName*string

First name

Max. length: 255

lastName*string

First name

Max. length: 255

email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

phone phonestring

Phone. No longer required since v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

lang*string

User UI language

Enum:
  • en
  • cs
enabled*boolean

If the user is enabled

username*string

Username - must be unique.

Min. length: 4

Max. length: 255

password* passwordstring

Password in plaintext.

Min. length: 6

Max. length: 1024

Inherits: string

Request Body

{
  "username": "john.doe",
  "password": "john123doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.tld",
  "phone": "+420 123 456 789",
  "lang": "en",
  "enabled": true,
  "roles": [
    3
  ]
}

200 OK chevron_right expand_more

User has been invited.

User Entity UserEntity

application/json

User data model for full entity.

Inherits: EntityMetaDataDeletable UserBase UserIdentifiers

ParameterTypeDescription
userId*integer

User ID

type*string

User account type

Enum:
  • regular
username*string

Username - must be unique.

Min. length: 4

Max. length: 255

firstName*string

First name

Max. length: 255

lastName*string

First name

Max. length: 255

email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

phone phonestring

Phone. No longer required since v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

lang*string

User UI language

Enum:
  • en
  • cs
enabled*boolean

If the user is enabled

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

lastLoginIp* lastLoginIpstring

IP address a user logged from last time

Pattern: ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$

Inherits: string

lastLogin*datetime

DateTime of last login.

Format: rfc3339

hasProfilePicture*boolean

If the user has a profile picture uploaded.

Response Body

{
  "userId": 42,
  "type": "regular",
  "username": "john.doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.tld",
  "phone": "+420 123 456 789",
  "lang": "en",
  "enabled": true,
  "hasProfilePicture": false,
  "lastLogin": "2019-01-13T23:46:06.090Z",
  "lastLoginIp": "1.2.3.4",
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "admin",
  "deleted": false
}

201 Created chevron_right expand_more

User has been created and invited.

User Entity UserEntity

application/json

User data model for full entity.

Inherits: EntityMetaDataDeletable UserBase UserIdentifiers

ParameterTypeDescription
userId*integer

User ID

type*string

User account type

Enum:
  • regular
username*string

Username - must be unique.

Min. length: 4

Max. length: 255

firstName*string

First name

Max. length: 255

lastName*string

First name

Max. length: 255

email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

phone phonestring

Phone. No longer required since v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

lang*string

User UI language

Enum:
  • en
  • cs
enabled*boolean

If the user is enabled

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

lastLoginIp* lastLoginIpstring

IP address a user logged from last time

Pattern: ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$

Inherits: string

lastLogin*datetime

DateTime of last login.

Format: rfc3339

hasProfilePicture*boolean

If the user has a profile picture uploaded.

Response Body

{
  "userId": 42,
  "type": "regular",
  "username": "john.doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.tld",
  "phone": "+420 123 456 789",
  "lang": "en",
  "enabled": true,
  "hasProfilePicture": false,
  "lastLogin": "2019-01-13T23:46:06.090Z",
  "lastLoginIp": "1.2.3.4",
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "admin",
  "deleted": false
}

400 Bad Request chevron_right expand_more

Invalid payload or constraint violated.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

403 Forbidden chevron_right expand_more

Exceeded number of users in organization.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

get /orgs/{orgId}/stats

Get organization statistics highlight_off  lock vpn_key

Returns an organization stats entity based on ID.

Not implemented

vpn_key Required permissions

ORG/READ

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

Query
stats* Organization Stats Paramarray

Specifies which stats series should be returned.

stats[] Project Stats Paramstring

Name of project stats series.

Enum:
  • msgIn
  • msgOut
  • datapoints
  • metricsCount
  • metricsErrorCount
  • metricsStorage
  • mqttConn
  • mqttSub
  • httpSub
  • projects
  • channels
  • devices
  • users
  • dashboards

Inherits: string

timeWindow* TimeWindowParamstring

Time window parameter.

Pattern: ^[0-9]+[u|ms|s|m|h|d|w]$

Inherits: string

timeCount* TimeCountParaminteger

Count of time windows. Must be >=0, if 0 then one last window must be return without gruping.

Eg. if timeWindow is 10s and timeCount is zero, then window is retrived as aggregated values from last 10 seconds.

Inherits: integer

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Not Implemented

  • Permissions:

    • ORG/READ
curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/stats?stats[]=<value>&TimeWindowParam=<value>&TimeCountParam=<value>

200 OK chevron_right expand_more

The organization stats entity.

Organization Stats Response OrgStatsRes

application/json

Organization statistics response model.

Inherits: object

ParameterTypeDescription
msgInarray

Incoming messages

msgIn[] StatsDataPointobject

Stats Data Point

Inherits: object

msgIn[].t*datetime

DateTime.

Format: rfc3339

msgIn[].v*number

Value

msgIn[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

msgIn[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

msgOutarray

Outgoing messages

msgOut[] StatsDataPointobject

Stats Data Point

Inherits: object

msgOut[].t*datetime

DateTime.

Format: rfc3339

msgOut[].v*number

Value

msgOut[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

msgOut[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

datapointsarray

Consumed datapoints

datapoints[] StatsDataPointobject

Stats Data Point

Inherits: object

datapoints[].t*datetime

DateTime.

Format: rfc3339

datapoints[].v*number

Value

datapoints[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

datapoints[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsCountarray

Count of stored metrics

metricsCount[] StatsDataPointobject

Stats Data Point

Inherits: object

metricsCount[].t*datetime

DateTime.

Format: rfc3339

metricsCount[].v*number

Value

metricsCount[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsCount[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsErrorCountarray

Count of metrics reported with errors

metricsErrorCount[] StatsDataPointobject

Stats Data Point

Inherits: object

metricsErrorCount[].t*datetime

DateTime.

Format: rfc3339

metricsErrorCount[].v*number

Value

metricsErrorCount[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsErrorCount[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsStoragearray

Metrics storage usage

metricsStorage[] StatsDataPointobject

Stats Data Point

Inherits: object

metricsStorage[].t*datetime

DateTime.

Format: rfc3339

metricsStorage[].v*number

Value

metricsStorage[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsStorage[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

mqttConnarray

Number of active MQTT connections

mqttConn[] StatsDataPointobject

Stats Data Point

Inherits: object

mqttConn[].t*datetime

DateTime.

Format: rfc3339

mqttConn[].v*number

Value

mqttConn[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

mqttConn[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

mqttSubarray

Number of active MQTT subscriptions

mqttSub[] StatsDataPointobject

Stats Data Point

Inherits: object

mqttSub[].t*datetime

DateTime.

Format: rfc3339

mqttSub[].v*number

Value

mqttSub[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

mqttSub[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

httpSubarray

Number of active HTTP subscriptions

httpSub[] StatsDataPointobject

Stats Data Point

Inherits: object

httpSub[].t*datetime

DateTime.

Format: rfc3339

httpSub[].v*number

Value

httpSub[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

httpSub[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

channelsarray

Number of channels in all organization

channels[] StatsDataPointobject

Stats Data Point

Inherits: object

channels[].t*datetime

DateTime.

Format: rfc3339

channels[].v*number

Value

channels[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

channels[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

devicesarray

Number of devices in all organization

devices[] StatsDataPointobject

Stats Data Point

Inherits: object

devices[].t*datetime

DateTime.

Format: rfc3339

devices[].v*number

Value

devices[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

devices[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

usersarray

Number of users in all organization

users[] StatsDataPointobject

Stats Data Point

Inherits: object

users[].t*datetime

DateTime.

Format: rfc3339

users[].v*number

Value

users[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

users[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

projectsarray

Number of projects in all organization

projects[] StatsDataPointobject

Stats Data Point

Inherits: object

projects[].t*datetime

DateTime.

Format: rfc3339

projects[].v*number

Value

projects[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

projects[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

dashboardsarray

Number of dashboards in all organization

dashboards[] StatsDataPointobject

Stats Data Point

Inherits: object

dashboards[].t*datetime

DateTime.

Format: rfc3339

dashboards[].v*number

Value

dashboards[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

dashboards[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

Response Body

{
  "msgIn": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 39,
      "st": 1.549910488216,
      "et": 1.5499104987
    }
  ],
  "msgOut": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 5.4,
      "st": 1.549910488216,
      "et": 1.5499104987
    }
  ],
  "metricsCount": [
    {
      "t": "2019-02-11T18:41:30Z",
      "v": 438
    }
  ],
  "metricsErrorCount": [
    {
      "t": "2019-02-11T18:41:30Z",
      "v": 3
    }
  ],
  "metricsStorage": [
    {
      "t": "2019-02-11T18:41:30Z",
      "v": 3141592650000000
    }
  ],
  "mqttConn": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 12
    }
  ],
  "mqttSub": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 24
    }
  ],
  "httpSub": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 2
    }
  ],
  "projects": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 3
    }
  ],
  "channels": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 6
    }
  ],
  "devices": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 40
    }
  ],
  "users": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 9
    }
  ],
  "dashboards": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 2
    }
  ]
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

get /orgs/{orgId}/projects

Get project list warning  lock vpn_key

Returns a collection of project records.

Changes:
v1.3.0 - Query parameters for filtering and sorting have changed. Query parameter isDeleted was removed.

Breaking Change

vpn_key Required permissions

ORG/READ

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

Query
limitinteger

Maximum count of returned records.

Max. value: 1000

Default value: 100

offsetinteger

Record count offset.

withCountboolean

If total record count should be included in the response.

filterarray

Collection filters.

filter[] Project Filter Paramobject

Filter settings.

Additional properties: Yes

Inherits: FilterParam

filter[].field*string

Field to filter on.

Enum:
  • name
  • description
  • fulltext
filter[].op*string

Filter operator. Size comparisions are allowed only on numerical fields.

Enum:
  • eq
  • contains
  • starts
  • ends
  • lt
  • lte
  • gt
  • gte
filter[].value*string

Filter value.

sortarray

Collection sorting.

sort[] Project Sort Paramobject

Sort settings.

Additional properties: Yes

Inherits: SortParam

sort[].field*string

Field to sort by.

Enum:
  • name
sort[].order*string

Order type.

Enum:
  • asc
  • desc

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Breaking Change

  • Permissions:

    • ORG/READ
curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects?limit=<value>&offset=<value>&withCount=<value>&filter[][field]=<value>&filter[][op]=<value>&filter[][value]=<value>&sort[][field]=<value>&sort[][order]=<value>

200 OK chevron_right expand_more

Collection items.

Project Collection Response ProjectCollectionRes

application/json

Response of the project collection.

Inherits: CollectionRes

ParameterTypeDescription
items*array

Collection items.

items[] Project Entityobject

Project data model for full entity.

Inherits: EntityMetaDataDeletable ProjectBase ProjectIdentifiers

items[].orgId*integer

Organization ID.

items[].projectId*integer

Project ID.

items[].genId*string

Unique generated organization ID.

items[].name*string

Project name.

Min. length: 1

Max. length: 128

items[].descriptionstring

Project description.

Max. length: 255

items[].rateLimit*number

Global project message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

items[].dataRetention*string

Project data retention. Available postfixes are h, d, M, y. Examples 12h, 7d, 1M, 2y. Not implemented yet

Max. length: 8

items[].logoUrlstring

URL to project logo. Not implemented yet

Max. length: 1024

items[].usersLimit*integer

Maximum number of users in the project. -1 for unlimited.

items[].devicesLimit*integer

Maximum number of devices in the project. -1 for unlimited.

items[].dashboardsLimit*integer

Maximum number of dashboards in the project. -1 for unlimited.

items[].amountOfDatapoints*integer

Number of datapoints for the project. -1 for unlimited.

items[].created*datetime

DateTime when the entity was created.

Format: rfc3339

items[].createdBy*string

Username of an account which has created the entity.

items[].modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

items[].modifiedBy*string

Username of an account which has modified the entity last.

items[].deleted*boolean

If the entity was deleted.

items[].permissions*array

Project permissions.

Inherits: ProjectPermissions

items[].permissions[]string

Permission name.

Enum:
  • PROJECT/UPDATE
  • PROJECT/DELETE
  • PROJECT/GRANT
  • PROJECT_DEVICES/READ
  • PROJECT_CHANNELS/READ
  • PROJECT_CHANNELS/CREATE
  • PROJECT_CHANNELS/UPDATE
  • PROJECT_CHANNELS/DELETE
  • PROJECT_METRICS/READ
  • PROJECT_METRICS/UPDATE
  • PROJECT_METRICS/DELETE
  • PROJECT_VISUALIZATION/READ
  • PROJECT_INTEGRATION/READ
  • PROJECT_API_CREDS/UPDATE
permissions*array

User permissions related to the collection.

permissions[]string

Permission name.

Enum:
  • PROJECT/CREATE
countinteger

Optional count of all collection items with respect to filters.

limit*integer

The limit value from the query parameter - helps a client to determine pagination.

offset*integer

The offset value from the query parameter - helps a client to determine pagination.

Response Body

{
  "items": [
    {
      "orgId": 1,
      "projectId": 2,
      "genId": "rx248adp",
      "name": "Parking Project",
      "description": "Project for smart parking.",
      "rateLimit": 1000,
      "dataRetention": "2y",
      "logoUrl": "project.com/logo.png",
      "usersLimit": 1,
      "devicesLimit": 10,
      "dashboardsLimit": 100,
      "amountOfDatapoints": 1000,
      "permissions": [
        "PROJECT/UPDATE",
        "PROJECT_DEVICES/READ",
        "PROJECT_METRICS/READ",
        "PROJECT_VISUALIZATION/READ",
        "PROJECT_INTEGRATION/READ"
      ],
      "created": "2019-01-13T23:46:06.090Z",
      "createdBy": "john.doe",
      "modified": "2019-01-13T23:46:06.090Z",
      "modifiedBy": "john.doe",
      "deleted": false
    },
    {
      "orgId": 1,
      "projectId": 3,
      "genId": "w24uhar2",
      "name": "Enviro Project",
      "description": "Project for environmental mesaurements.",
      "rateLimit": 100,
      "dataRetention": "7d",
      "logoUrl": "project.com/logo.png",
      "usersLimit": 1,
      "devicesLimit": 10,
      "dashboardsLimit": 100,
      "amountOfDatapoints": 1000,
      "permissions": [
        "PROJECT/UPDATE",
        "PROJECT_DEVICES/READ",
        "PROJECT_METRICS/READ",
        "PROJECT_VISUALIZATION/READ",
        "PROJECT_INTEGRATION/READ"
      ],
      "created": "2019-01-13T23:46:06.090Z",
      "createdBy": "john.doe",
      "modified": "2019-01-13T23:46:06.090Z",
      "modifiedBy": "john.doe",
      "deleted": false
    }
  ],
  "count": 2,
  "limit": 100,
  "offset": 0,
  "permissions": [
    "PROJECT/CREATE"
  ]
}

post /orgs/{orgId}/projects

Create project  lock vpn_key

Creates a new project.

vpn_key Required permissions

ORG/READ PROJECT/CREATE

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/READ
    • PROJECT/CREATE
curl -X POST \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects

Request Body chevron_right expand_more

Project Create Request ProjectCreateReq

application/json

Data model for the project create request.

Inherits: ProjectBase

ParameterTypeDescription
name*string

Project name.

Min. length: 1

Max. length: 128

descriptionstring

Project description.

Max. length: 255

rateLimit*number

Global project message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

dataRetention*string

Project data retention. Available postfixes are h, d, M, y. Examples 12h, 7d, 1M, 2y. Not implemented yet

Max. length: 8

logoUrlstring

URL to project logo. Not implemented yet

Max. length: 1024

usersLimit*integer

Maximum number of users in the project. -1 for unlimited.

devicesLimit*integer

Maximum number of devices in the project. -1 for unlimited.

dashboardsLimit*integer

Maximum number of dashboards in the project. -1 for unlimited.

amountOfDatapoints*integer

Number of datapoints for the project. -1 for unlimited.

Request Body

{
  "name": "My Project",
  "description": "Project for smart parking.",
  "rateLimit": 1000,
  "dataRetention": "2y",
  "logoUrl": "project.com/logo.png",
  "usersLimit": 1,
  "devicesLimit": 10,
  "dashboardsLimit": 100,
  "amountOfDatapoints": 1000
}

201 Created chevron_right expand_more

Project has been created.

Project Entity ProjectEntity

application/json

Project data model for full entity.

Inherits: EntityMetaDataDeletable ProjectBase ProjectIdentifiers

ParameterTypeDescription
orgId*integer

Organization ID.

projectId*integer

Project ID.

genId*string

Unique generated organization ID.

name*string

Project name.

Min. length: 1

Max. length: 128

descriptionstring

Project description.

Max. length: 255

rateLimit*number

Global project message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

dataRetention*string

Project data retention. Available postfixes are h, d, M, y. Examples 12h, 7d, 1M, 2y. Not implemented yet

Max. length: 8

logoUrlstring

URL to project logo. Not implemented yet

Max. length: 1024

usersLimit*integer

Maximum number of users in the project. -1 for unlimited.

devicesLimit*integer

Maximum number of devices in the project. -1 for unlimited.

dashboardsLimit*integer

Maximum number of dashboards in the project. -1 for unlimited.

amountOfDatapoints*integer

Number of datapoints for the project. -1 for unlimited.

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

permissions*array

Project permissions.

Inherits: ProjectPermissions

permissions[]string

Permission name.

Enum:
  • PROJECT/UPDATE
  • PROJECT/DELETE
  • PROJECT/GRANT
  • PROJECT_DEVICES/READ
  • PROJECT_CHANNELS/READ
  • PROJECT_CHANNELS/CREATE
  • PROJECT_CHANNELS/UPDATE
  • PROJECT_CHANNELS/DELETE
  • PROJECT_METRICS/READ
  • PROJECT_METRICS/UPDATE
  • PROJECT_METRICS/DELETE
  • PROJECT_VISUALIZATION/READ
  • PROJECT_INTEGRATION/READ
  • PROJECT_API_CREDS/UPDATE

Response Body

{
  "orgId": 1,
  "projectId": 2,
  "genId": "abc123",
  "name": "My Project",
  "description": "Project for smart parking.",
  "rateLimit": 1000,
  "dataRetention": "2y",
  "logoUrl": "project.com/logo.png",
  "usersLimit": 1,
  "devicesLimit": 10,
  "dashboardsLimit": 100,
  "amountOfDatapoints": 1000,
  "permissions": [
    "PROJECT/UPDATE",
    "PROJECT_DEVICES/READ",
    "PROJECT_METRICS/READ",
    "PROJECT_VISUALIZATION/READ",
    "PROJECT_INTEGRATION/READ"
  ],
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "john.doe",
  "deleted": false
}

400 Bad Request chevron_right expand_more

Invalid payload or constraint violated.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

403 Forbidden chevron_right expand_more

Exceeded number of projects in organization.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Organization not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

get /orgs/{orgId}/projects/{projectId}

Get project  lock vpn_key

Returns a project entity based on ID.

vpn_key Required permissions

ORG/READ PROJECT/READ

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/READ
    • PROJECT/READ
curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}

200 OK chevron_right expand_more

The project entity.

Project Entity ProjectEntity

application/json

Project data model for full entity.

Inherits: EntityMetaDataDeletable ProjectBase ProjectIdentifiers

ParameterTypeDescription
orgId*integer

Organization ID.

projectId*integer

Project ID.

genId*string

Unique generated organization ID.

name*string

Project name.

Min. length: 1

Max. length: 128

descriptionstring

Project description.

Max. length: 255

rateLimit*number

Global project message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

dataRetention*string

Project data retention. Available postfixes are h, d, M, y. Examples 12h, 7d, 1M, 2y. Not implemented yet

Max. length: 8

logoUrlstring

URL to project logo. Not implemented yet

Max. length: 1024

usersLimit*integer

Maximum number of users in the project. -1 for unlimited.

devicesLimit*integer

Maximum number of devices in the project. -1 for unlimited.

dashboardsLimit*integer

Maximum number of dashboards in the project. -1 for unlimited.

amountOfDatapoints*integer

Number of datapoints for the project. -1 for unlimited.

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

permissions*array

Project permissions.

Inherits: ProjectPermissions

permissions[]string

Permission name.

Enum:
  • PROJECT/UPDATE
  • PROJECT/DELETE
  • PROJECT/GRANT
  • PROJECT_DEVICES/READ
  • PROJECT_CHANNELS/READ
  • PROJECT_CHANNELS/CREATE
  • PROJECT_CHANNELS/UPDATE
  • PROJECT_CHANNELS/DELETE
  • PROJECT_METRICS/READ
  • PROJECT_METRICS/UPDATE
  • PROJECT_METRICS/DELETE
  • PROJECT_VISUALIZATION/READ
  • PROJECT_INTEGRATION/READ
  • PROJECT_API_CREDS/UPDATE

Response Body

{
  "orgId": 1,
  "projectId": 2,
  "genId": "abc123",
  "name": "My Project",
  "description": "Project for smart parking.",
  "rateLimit": 1000,
  "dataRetention": "2y",
  "logoUrl": "project.com/logo.png",
  "usersLimit": 1,
  "devicesLimit": 10,
  "dashboardsLimit": 100,
  "amountOfDatapoints": 1000,
  "permissions": [
    "PROJECT/UPDATE",
    "PROJECT_DEVICES/READ",
    "PROJECT_METRICS/READ",
    "PROJECT_VISUALIZATION/READ",
    "PROJECT_INTEGRATION/READ"
  ],
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "john.doe",
  "deleted": false
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

put /orgs/{orgId}/projects/{projectId}

Update project  lock vpn_key

Updates the project entity.

vpn_key Required permissions

ORG/READ PROJECT/UPDATE

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/READ
    • PROJECT/UPDATE
curl -X PUT \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}

Request Body chevron_right expand_more

Project Update Request ProjectUpdateReq

application/json

Data model for the project update request.

Inherits: ProjectBase

ParameterTypeDescription
name*string

Project name.

Min. length: 1

Max. length: 128

descriptionstring

Project description.

Max. length: 255

rateLimit*number

Global project message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

dataRetention*string

Project data retention. Available postfixes are h, d, M, y. Examples 12h, 7d, 1M, 2y. Not implemented yet

Max. length: 8

logoUrlstring

URL to project logo. Not implemented yet

Max. length: 1024

usersLimit*integer

Maximum number of users in the project. -1 for unlimited.

devicesLimit*integer

Maximum number of devices in the project. -1 for unlimited.

dashboardsLimit*integer

Maximum number of dashboards in the project. -1 for unlimited.

amountOfDatapoints*integer

Number of datapoints for the project. -1 for unlimited.

Request Body

{
  "name": "My Project",
  "description": "Project for smart parking.",
  "rateLimit": 1000,
  "dataRetention": "2y",
  "logoUrl": "project.com/logo.png",
  "usersLimit": 1,
  "devicesLimit": 10,
  "dashboardsLimit": 100,
  "amountOfDatapoints": 1000
}

200 OK chevron_right expand_more

Project has been updated.

Project Entity ProjectEntity

application/json

Project data model for full entity.

Inherits: EntityMetaDataDeletable ProjectBase ProjectIdentifiers

ParameterTypeDescription
orgId*integer

Organization ID.

projectId*integer

Project ID.

genId*string

Unique generated organization ID.

name*string

Project name.

Min. length: 1

Max. length: 128

descriptionstring

Project description.

Max. length: 255

rateLimit*number

Global project message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

dataRetention*string

Project data retention. Available postfixes are h, d, M, y. Examples 12h, 7d, 1M, 2y. Not implemented yet

Max. length: 8

logoUrlstring

URL to project logo. Not implemented yet

Max. length: 1024

usersLimit*integer

Maximum number of users in the project. -1 for unlimited.

devicesLimit*integer

Maximum number of devices in the project. -1 for unlimited.

dashboardsLimit*integer

Maximum number of dashboards in the project. -1 for unlimited.

amountOfDatapoints*integer

Number of datapoints for the project. -1 for unlimited.

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

permissions*array

Project permissions.

Inherits: ProjectPermissions

permissions[]string

Permission name.

Enum:
  • PROJECT/UPDATE
  • PROJECT/DELETE
  • PROJECT/GRANT
  • PROJECT_DEVICES/READ
  • PROJECT_CHANNELS/READ
  • PROJECT_CHANNELS/CREATE
  • PROJECT_CHANNELS/UPDATE
  • PROJECT_CHANNELS/DELETE
  • PROJECT_METRICS/READ
  • PROJECT_METRICS/UPDATE
  • PROJECT_METRICS/DELETE
  • PROJECT_VISUALIZATION/READ
  • PROJECT_INTEGRATION/READ
  • PROJECT_API_CREDS/UPDATE

Response Body

{
  "orgId": 1,
  "projectId": 2,
  "genId": "abc123",
  "name": "My Project",
  "description": "Project for smart parking.",
  "rateLimit": 1000,
  "dataRetention": "2y",
  "logoUrl": "project.com/logo.png",
  "usersLimit": 1,
  "devicesLimit": 10,
  "dashboardsLimit": 100,
  "amountOfDatapoints": 1000,
  "permissions": [
    "PROJECT/UPDATE",
    "PROJECT_DEVICES/READ",
    "PROJECT_METRICS/READ",
    "PROJECT_VISUALIZATION/READ",
    "PROJECT_INTEGRATION/READ"
  ],
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "john.doe",
  "deleted": false
}

400 Bad Request chevron_right expand_more

Invalid payload or constraint violated.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

delete /orgs/{orgId}/projects/{projectId}

Delete project  lock vpn_key

Deletes the project entity.

vpn_key Required permissions

ORG/READ PROJECT/DELETE

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/READ
    • PROJECT/DELETE
curl -X DELETE \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}

204 No Content chevron_right expand_more

Project was deleted.

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

put /orgs/{orgId}/projects/{projectId}/move

Move Projecft highlight_off stars  lock vpn_key

Move project from one organization to another.

Not implemented Proposal

vpn_key Required permissions

ORG/ADMIN PROJECT/ADMIN

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Not Implemented

  • Proposal

  • Permissions:

    • ORG/ADMIN
    • PROJECT/ADMIN
curl -X PUT \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/move

Request Body chevron_right expand_more

Project Move Req ProjectMoveReq

application/json

Move project from one organization to another.

Inherits: object

ParameterTypeDescription
orgId*integer

ID of target organization.

inviteUsers*boolean

Invite project users to the target organization.

Request Body

{
  "orgId": 123,
  "inviteUsers": true
}

204 No Content chevron_right expand_more

Project has been moved.

400 Bad Request chevron_right expand_more

Invalid payload or constraint violated.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

403 Forbidden chevron_right expand_more

You have not permissions.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

get /orgs/{orgId}/projects/{projectId}/permissions

Get permissions  lock vpn_key

Returns permissions assigned to the project.

Resource type: is always PROJECT.

Changes:
v1.3.0 - Parameter withRoles and a availableRoles response property were removed.

vpn_key Required permissions

ORG/READ PROJECT/GRANT

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Query
withUsersboolean

If to return related user snippets.

withOrgsboolean

If to return related organization snippets.

withProjectsboolean

If to return related project snippets.

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/READ
    • PROJECT/GRANT
curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/permissions?withUsers=<value>&withOrgs=<value>&withProjects=<value>

200 OK chevron_right expand_more

Assigned permissions.

Permissions Response PermissionsRes

application/json

Model describing permissions assigned to the resource or a user and related entities snippets.

Changes:
v1.3.0 - Removed field availableRoles.

Inherits: object

ParameterTypeDescription
assignedRoles*array

List of assigned roles

assignedRoles[] Role Assignmentobject

Model describing a role assigned to a user and a resource.

Inherits: Roles

assignedRoles[].roles*array

List of assigned roles

assignedRoles[].roles[]integer

Role ID

assignedRoles[].resourceType*string

Resource type

Enum:
  • ORG
  • PROJECT
  • ADMIN
  • ADMIN_USER
  • ADMIN_ORGS
  • ADMIN_ROLES
  • ADMIN_NEW_CUSTOMER
  • ADMIN_MQTT_ACC
  • ADMIN_MQTT_ACC_AUTH
assignedRoles[].resourceIdinteger

Resource ID

Can be null if a role is assigned globally to all resources of a given type.

assignedRoles[].userId*integer

User ID

usersarray

List of user snippets of users which are present in an assignedRoles array. Returned only if withUsers query parameter is true.

users[] User Snippetobject

User entity snippet data model.

Inherits: UserSnippet

users[].userId*integer

User ID

users[].username*string

Username

users[].firstName*string

First name

users[].lastName*string

First name

users[].email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

users[].hasProfilePicture*boolean

If the user has a profile picture uploaded.

users[].enabled*boolean

If the user is enabled

orgsarray

List of organization snippets of organizations which are present in an assignedRoles array. Returned only if withOrgs query parameter is true.

orgs[] Organization Snippetobject

Organization entity snippet model.

Changes: v1.3.0 - Field `active was added.

Inherits: OrgSnippet

orgs[].orgId*integer

Organization ID.

orgs[].name*string

Organization name.
Change of this field requires ORG/ADMIN_UPDATE permission since v1.3.0 (not implemented).

Min. length: 1

Max. length: 128

orgs[].enabled*boolean

If the organization is enabled.
Disabled organization cannot be accessible without ORG/ADMIN_READ permission. Change of this field requires ORG/ADMIN_UPDATE permission.
Added in v1.3.0, not implemented.

projectsarray

List of project snippets of projects which are present in an assignedRoles array. Returned only if withProjects query parameter is true.

projects[] Project Snippetobject

Project entity snippet model.

Changes: v1.3.0 - Field description was added.

Inherits: ProjectSnippet

projects[].projectId*integer

Project ID.

projects[].orgId*integer

Organization ID.

projects[].name*string

Project name

Min. length: 1

Max. length: 128

projects[].descriptionstring

Description

Max. length: 255

Response Body

Permissions related to an organization

{
  "assignedRoles": [
    {
      "userId": 12,
      "resourceType": "ORG",
      "resourceId": 42,
      "roles": [
        3,
        5
      ]
    },
    {
      "userId": 13,
      "resourceType": "ORG",
      "resourceId": 42,
      "roles": [
        4,
        5
      ]
    }
  ],
  "users": [
    {
      "userId": 12,
      "username": "john.doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@doe.tld",
      "hasProfilePicture": true,
      "enabled": true
    },
    {
      "userId": 13,
      "username": "jack.doe",
      "firstName": "Jack",
      "lastName": "Doe",
      "email": "jack@doe.tld",
      "hasProfilePicture": true,
      "enabled": true
    }
  ],
  "orgs": [
    {
      "orgId": 42,
      "name": "Company ltd.",
      "enabled": true
    }
  ],
  "projects": []
}

Permissions related to a user

{
  "assignedRoles": [
    {
      "userId": 12,
      "resourceType": "ORG",
      "resourceId": 11,
      "roles": [
        1
      ]
    },
    {
      "userId": 12,
      "resourceType": "PROJECT",
      "resourceId": 22,
      "roles": [
        2
      ]
    }
  ],
  "users": [
    {
      "userId": 12,
      "username": "john.doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@doe.tld",
      "hasProfilePicture": true,
      "enabled": true
    }
  ],
  "orgs": [
    {
      "orgId": 11,
      "name": "Company ltd.",
      "enabled": true
    }
  ],
  "projects": [
    {
      "projectId": 22,
      "orgId": 11,
      "name": "My Project",
      "description": "Project for smart parking."
    }
  ]
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

put /orgs/{orgId}/projects/{projectId}/permissions

Update permissions  lock vpn_key

Updates permissions assigned to the project.

Resource type: is always PROJECT.

When the payload is an empty array nothing is changed.

When the roles property in a payload item is empty then access for a given combination of a user and resource is removed.

vpn_key Required permissions

ORG/READ PROJECT/GRANT

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/READ
    • PROJECT/GRANT
curl -X PUT \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/permissions

Request Body chevron_right expand_more

Permissions Request PermissionsReq

application/json

Model describing a request to update permissions assigned to a resource or a user.

Inherits: array

ParameterTypeDescription
[] Role Assignmentobject

Model describing a role assigned to a user and a resource.

Inherits: Roles

[].roles*array

List of assigned roles

[].roles[]integer

Role ID

[].resourceType*string

Resource type

Enum:
  • ORG
  • PROJECT
  • ADMIN
  • ADMIN_USER
  • ADMIN_ORGS
  • ADMIN_ROLES
  • ADMIN_NEW_CUSTOMER
  • ADMIN_MQTT_ACC
  • ADMIN_MQTT_ACC_AUTH
[].resourceIdinteger

Resource ID

Can be null if a role is assigned globally to all resources of a given type.

[].userId*integer

User ID

Request Body

[
  {
    "userId": 12,
    "resourceType": "ORG",
    "resourceId": 42,
    "roles": [
      3,
      5
    ]
  },
  {
    "userId": 13,
    "resourceType": "ORG",
    "resourceId": 42,
    "roles": [
      4,
      5
    ]
  }
]

204 No Content chevron_right expand_more

Permissions were updated.

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

post /orgs/{orgId}/projects/{projectId}/invite

Invite user highlight_off  lock vpn_key

Invite user to the project.

Not implemented

vpn_key Required permissions

ORG/ADMIN PROJECT/ADMIN

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Not Implemented

  • Permissions:

    • ORG/ADMIN
    • PROJECT/ADMIN
curl -X POST \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/invite

Request Body chevron_right expand_more

User Invitation UserCreateWithPermsReq

application/json

User data model for full entity.

Inherits: UserCreateReq Roles

ParameterTypeDescription
roles*array

List of assigned roles

roles[]integer

Role ID

firstName*string

First name

Max. length: 255

lastName*string

First name

Max. length: 255

email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

phone phonestring

Phone. No longer required since v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

lang*string

User UI language

Enum:
  • en
  • cs
enabled*boolean

If the user is enabled

username*string

Username - must be unique.

Min. length: 4

Max. length: 255

password* passwordstring

Password in plaintext.

Min. length: 6

Max. length: 1024

Inherits: string

Request Body

{
  "username": "john.doe",
  "password": "john123doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.tld",
  "phone": "+420 123 456 789",
  "lang": "en",
  "enabled": true,
  "roles": [
    3
  ]
}

200 OK chevron_right expand_more

User has been invited.

User Entity UserEntity

application/json

User data model for full entity.

Inherits: EntityMetaDataDeletable UserBase UserIdentifiers

ParameterTypeDescription
userId*integer

User ID

type*string

User account type

Enum:
  • regular
username*string

Username - must be unique.

Min. length: 4

Max. length: 255

firstName*string

First name

Max. length: 255

lastName*string

First name

Max. length: 255

email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

phone phonestring

Phone. No longer required since v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

lang*string

User UI language

Enum:
  • en
  • cs
enabled*boolean

If the user is enabled

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

lastLoginIp* lastLoginIpstring

IP address a user logged from last time

Pattern: ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$

Inherits: string

lastLogin*datetime

DateTime of last login.

Format: rfc3339

hasProfilePicture*boolean

If the user has a profile picture uploaded.

Response Body

{
  "userId": 42,
  "type": "regular",
  "username": "john.doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.tld",
  "phone": "+420 123 456 789",
  "lang": "en",
  "enabled": true,
  "hasProfilePicture": false,
  "lastLogin": "2019-01-13T23:46:06.090Z",
  "lastLoginIp": "1.2.3.4",
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "admin",
  "deleted": false
}

201 Created chevron_right expand_more

User has been created and invited.

User Entity UserEntity

application/json

User data model for full entity.

Inherits: EntityMetaDataDeletable UserBase UserIdentifiers

ParameterTypeDescription
userId*integer

User ID

type*string

User account type

Enum:
  • regular
username*string

Username - must be unique.

Min. length: 4

Max. length: 255

firstName*string

First name

Max. length: 255

lastName*string

First name

Max. length: 255

email* emailstring

E-mail

Pattern: ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$

Max. length: 200

Inherits: string

phone phonestring

Phone. No longer required since v1.3.0.

Pattern: ^\+?[0-9 ]+$

Max. length: 32

Inherits: string

lang*string

User UI language

Enum:
  • en
  • cs
enabled*boolean

If the user is enabled

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

lastLoginIp* lastLoginIpstring

IP address a user logged from last time

Pattern: ^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$

Inherits: string

lastLogin*datetime

DateTime of last login.

Format: rfc3339

hasProfilePicture*boolean

If the user has a profile picture uploaded.

Response Body

{
  "userId": 42,
  "type": "regular",
  "username": "john.doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@doe.tld",
  "phone": "+420 123 456 789",
  "lang": "en",
  "enabled": true,
  "hasProfilePicture": false,
  "lastLogin": "2019-01-13T23:46:06.090Z",
  "lastLoginIp": "1.2.3.4",
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "admin",
  "deleted": false
}

400 Bad Request chevron_right expand_more

Invalid payload or constraint violated.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

403 Forbidden chevron_right expand_more

Exceeded number of users in organization.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

get /orgs/{orgId}/projects/{projectId}/api

Get API credentials delete_forever  lock vpn_key

Returns available project API credentials based on allowed permissions.

Deprecated

vpn_key Required permissions

ORG/READ PROJECT/READ PROJECT_DEVICES/READ? PROJECT_VISUALIZATION/READ? PROJECT_INTEGRATION/READ?

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Deprecated

  • Permissions:

    • ORG/READ
    • PROJECT/READ
    • PROJECT_DEVICES/READ?
    • PROJECT_VISUALIZATION/READ?
    • PROJECT_INTEGRATION/READ?
curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/api

200 OK chevron_right expand_more

Project API Credentials ProjectApiCredentials

application/json

Project API credentials model.

Individual service credentials are returned based on allowed permissions.

Changes: v1.3.0 - Fields grafana and permissions marked as obsolete.

Inherits: object

ParameterTypeDescription
mqttobject

MQTT credentials

Additional properties: Yes

mqtt.server*string

MQTT hostname

Max. length: 1024

mqtt.username*string

MQTT account username

Max. length: 64

mqtt.password*string

MQTT account password

Max. length: 1024

mqtt.rateLimit*number

MQTT message rate limit as messages per second. Value of -1 means no limit.

Min. value: -1

mqtt.maxConnections*number

Maximum count of active MQTT connections using this account. Value of -1 means no limit.

Min. value: -1

grafanaobject

Grafana credentials. Obsolete.

Additional properties: Yes

grafana.server*string

Grafana hostname

Max. length: 1024

grafana.username*string

Grafana account username. Not provided anymore.

grafana.password*string

Grafana account password. Not provided anymore.

influxdbobject

InfluxDB credentials

Additional properties: Yes

influxdb.server*string

InfluxDB hostname

Max. length: 1024

influxdb.username*string

InfluxDB account username

Max. length: 64

influxdb.password*string

InfluxDB account password

Max. length: 1024

permissionsstring

Permission list. Obsolete.

Enum:
  • regenerate

Response Body

{
  "mqtt": {
    "server": "iot.tcpisek.cz:1883",
    "username": "test123",
    "password": "dGVzdDEyMw==",
    "rateLimit": 256,
    "maxConnections": 16
  },
  "grafana": {
    "server": "https://iot.tcpisek.cz/",
    "username": "",
    "password": ""
  },
  "influxdb": {
    "server": "https://iot.tcpisek.cz:8086",
    "username": "test123",
    "password": "dGVzdDEyMw=="
  }
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

post /orgs/{orgId}/projects/{projectId}/api

Regenerate API credentials delete_forever highlight_off  lock vpn_key

Generates new project API credentials.

Deprecated Not implemented

vpn_key Required permissions

ORG/READ PROJECT/READ PROJECT_API_CREDS/UPDATE

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Deprecated

  • Not Implemented

  • Permissions:

    • ORG/READ
    • PROJECT/READ
    • PROJECT_API_CREDS/UPDATE
curl -X POST \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/api

204 No Content chevron_right expand_more

Credentials have been regenerated.

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

get /orgs/{orgId}/projects/{projectId}/stats

Get Project Stats  lock vpn_key

Returns project statistics.

Changes:
v1.4.0 - datapoints option was added for return consumed data points.

vpn_key Required permissions

ORG/READ PROJECT/READ

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Query
stats* Project Stats Paramarray

Specifies which stats series should be returned.

stats[] Project Stats Paramstring

Name of project stats series.

Enum:
  • msgIn
  • msgOut
  • datapoints
  • metricsCount
  • metricsErrorCount
  • metricsStorage
  • mqttConn
  • mqttSub
  • httpSub
  • channels
  • devices
  • users
  • dashboards

Inherits: string

timeWindow* TimeWindowParamstring

Time window parameter.

Pattern: ^[0-9]+[u|ms|s|m|h|d|w]$

Inherits: string

timeCount* TimeCountParaminteger

Count of time windows. Must be >=0, if 0 then one last window must be return without gruping.

Eg. if timeWindow is 10s and timeCount is zero, then window is retrived as aggregated values from last 10 seconds.

Inherits: integer

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Permissions:

    • ORG/READ
    • PROJECT/READ
curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/stats?stats[]=<value>&TimeWindowParam=<value>&TimeCountParam=<value>

200 OK chevron_right expand_more

Project Stats Response ProjectStatsRes

application/json

Project statistics response model.

Inherits: object

ParameterTypeDescription
msgInarray

Incoming messages

msgIn[] StatsDataPointobject

Stats Data Point

Inherits: object

msgIn[].t*datetime

DateTime.

Format: rfc3339

msgIn[].v*number

Value

msgIn[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

msgIn[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

msgOutarray

Outgoing messages

msgOut[] StatsDataPointobject

Stats Data Point

Inherits: object

msgOut[].t*datetime

DateTime.

Format: rfc3339

msgOut[].v*number

Value

msgOut[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

msgOut[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

datapointsarray

Consumed datapoints

datapoints[] StatsDataPointobject

Stats Data Point

Inherits: object

datapoints[].t*datetime

DateTime.

Format: rfc3339

datapoints[].v*number

Value

datapoints[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

datapoints[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsCountarray

Count of stored metrics

metricsCount[] StatsDataPointobject

Stats Data Point

Inherits: object

metricsCount[].t*datetime

DateTime.

Format: rfc3339

metricsCount[].v*number

Value

metricsCount[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsCount[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsErrorCountarray

Count of metrics reported with errors

metricsErrorCount[] StatsDataPointobject

Stats Data Point

Inherits: object

metricsErrorCount[].t*datetime

DateTime.

Format: rfc3339

metricsErrorCount[].v*number

Value

metricsErrorCount[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsErrorCount[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsStoragearray

Metrics storage usage

metricsStorage[] StatsDataPointobject

Stats Data Point

Inherits: object

metricsStorage[].t*datetime

DateTime.

Format: rfc3339

metricsStorage[].v*number

Value

metricsStorage[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

metricsStorage[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

mqttConnarray

Number of active MQTT connections

mqttConn[] StatsDataPointobject

Stats Data Point

Inherits: object

mqttConn[].t*datetime

DateTime.

Format: rfc3339

mqttConn[].v*number

Value

mqttConn[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

mqttConn[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

mqttSubarray

Number of active MQTT subscriptions

mqttSub[] StatsDataPointobject

Stats Data Point

Inherits: object

mqttSub[].t*datetime

DateTime.

Format: rfc3339

mqttSub[].v*number

Value

mqttSub[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

mqttSub[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

httpSubarray

Number of active HTTP subscriptions

httpSub[] StatsDataPointobject

Stats Data Point

Inherits: object

httpSub[].t*datetime

DateTime.

Format: rfc3339

httpSub[].v*number

Value

httpSub[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

httpSub[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

channelsarray

Number of channels in project

channels[] StatsDataPointobject

Stats Data Point

Inherits: object

channels[].t*datetime

DateTime.

Format: rfc3339

channels[].v*number

Value

channels[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

channels[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

devicesarray

Number of devices in project

devices[] StatsDataPointobject

Stats Data Point

Inherits: object

devices[].t*datetime

DateTime.

Format: rfc3339

devices[].v*number

Value

devices[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

devices[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

usersarray

Number of users in project

users[] StatsDataPointobject

Stats Data Point

Inherits: object

users[].t*datetime

DateTime.

Format: rfc3339

users[].v*number

Value

users[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

users[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

dashboardsarray

Number of dashboards in project

dashboards[] StatsDataPointobject

Stats Data Point

Inherits: object

dashboards[].t*datetime

DateTime.

Format: rfc3339

dashboards[].v*number

Value

dashboards[].stnumber

Measurement start time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

dashboards[].etnumber

Measurement end time as unix timestamp. Used only for rated current stats, eg. timeCount = 0.

Response Body

{
  "msgIn": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 39,
      "st": 1.549910488216,
      "et": 1.5499104987
    }
  ],
  "msgOut": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 5.4,
      "st": 1.549910488216,
      "et": 1.5499104987
    }
  ],
  "metricsCount": [
    {
      "t": "2019-02-11T18:41:30Z",
      "v": 438
    }
  ],
  "metricsErrorCount": [
    {
      "t": "2019-02-11T18:41:30Z",
      "v": 3
    }
  ],
  "metricsStorage": [
    {
      "t": "2019-02-11T18:41:30Z",
      "v": 3141592650000000
    }
  ],
  "mqttConn": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 12
    }
  ],
  "mqttSub": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 24
    }
  ],
  "httpSub": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 12
    }
  ],
  "channels": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 3
    }
  ],
  "devices": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 20
    }
  ],
  "users": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 4
    }
  ],
  "dashboards": [
    {
      "t": "2019-02-11T18:41:28.936356082Z",
      "v": 0
    }
  ]
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

get /orgs/{orgId}/projects/{projectId}/channels

Get Channel List highlight_off warning  lock vpn_key

Returns a collection of channel records.

Changes:
v1.3.0 - Query parameters for filtering and sorting have changed. Query parameter isDeleted was removed.

Not implemented Breaking Change

vpn_key Required permissions

ORG/READ PROJECT/READ PROJECT_CHANNELS/READ

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Query
limitinteger

Maximum count of returned records.

Max. value: 1000

Default value: 100

offsetinteger

Record count offset.

withCountboolean

If total record count should be included in the response.

filterarray

Collection filters.

filter[] Channel Filter Paramobject

Filter settings.

Additional properties: Yes

Inherits: FilterParam

filter[].field*string

Field to filter on.

Enum:
  • name
  • type
  • enabled
filter[].op*string

Filter operator. Size comparisions are allowed only on numerical fields.

Enum:
  • eq
  • contains
  • starts
  • ends
  • lt
  • lte
  • gt
  • gte
filter[].value*string

Filter value.

sortarray

Collection sorting.

sort[] Channel Sort Paramobject

Sort settings.

Additional properties: Yes

Inherits: SortParam

sort[].field*string

Field to sort by.

Enum:
  • name
  • type
  • enabled
sort[].order*string

Order type.

Enum:
  • asc
  • desc

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Not Implemented

  • Permissions:

    • ORG/READ
    • PROJECT/READ
    • PROJECT_CHANNELS/READ
  • Breaking Change

curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/channels?limit=<value>&offset=<value>&withCount=<value>&filter[][field]=<value>&filter[][op]=<value>&filter[][value]=<value>&sort[][field]=<value>&sort[][order]=<value>

200 OK chevron_right expand_more

Collection items.

Channel Collection Response ChannelCollectionRes

application/json

Response of the channel collection.

Inherits: CollectionRes

ParameterTypeDescription
items*array

Collection items.

items[] Channel Entityobject

Channel data model for full entity.

Inherits: EntityMetaDataDeletable ChannelBase ChannelIdentifiers

items[].channelId*integer

Channel ID

items[].projectId*integer

Project ID

items[].type*string

Channel type. Supported channels may vary.

Enum:
  • mqtt
  • http
items[].name*string

Label

Min. length: 1

Max. length: 255

items[].config*object

Channel configuration - depends on a channel type.

items[].enabled*boolean

If a channel is enabled

items[].created*datetime

DateTime when the entity was created.

Format: rfc3339

items[].createdBy*string

Username of an account which has created the entity.

items[].modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

items[].modifiedBy*string

Username of an account which has modified the entity last.

items[].deleted*boolean

If the entity was deleted.

permissions* permissionsarray

List of channel collection permissions.

Inherits: array

permissions[]string

Permission name.

Enum:
  • PROJECT_CHANNEL/CREATE
countinteger

Optional count of all collection items with respect to filters.

limit*integer

The limit value from the query parameter - helps a client to determine pagination.

offset*integer

The offset value from the query parameter - helps a client to determine pagination.

Response Body

{
  "items": [
    {
      "channelId": 123,
      "projectId": 2,
      "type": "mqtt",
      "name": "Primary MQTT",
      "config": {
        "username": "ad24HuRI2",
        "password": "mqttSecret123",
        "rateLimit": 100,
        "maxConnections": 4
      },
      "enabled": true,
      "created": "2019-01-13T23:46:06.090Z",
      "createdBy": "john.doe",
      "modified": "2019-01-13T23:46:06.090Z",
      "modifiedBy": "john.doe",
      "deleted": false
    },
    {
      "channelId": 342,
      "projectId": 2,
      "type": "http",
      "name": "Primary HTTP",
      "config": {
        "username": "dr248ahC2",
        "password": "httpSecret123",
        "rateLimit": 100,
        "maxConnections": 4
      },
      "enabled": true,
      "created": "2019-01-13T23:46:06.090Z",
      "createdBy": "john.doe",
      "modified": "2019-01-13T23:46:06.090Z",
      "modifiedBy": "john.doe",
      "deleted": false
    }
  ],
  "count": 2,
  "limit": 100,
  "offset": 0,
  "permissions": [
    "PROJECT_CHANNEL/CREATE"
  ]
}

get /orgs/{orgId}/projects/{projectId}/channels/mqtt

Get MQTT channel list warning highlight_off  lock vpn_key

Returns a collection of MQTT channel records.

Changes:
v1.3.0 - Query parameters for filtering and sorting have changed. Query parameter isDeleted was removed.
v1.3.0 - Project channels were added.

Breaking Change Not implemented

vpn_key Required permissions

ORG/READ PROJECT/READ PROJECT_CHANNELS/READ

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Query
limitinteger

Maximum count of returned records.

Max. value: 1000

Default value: 100

offsetinteger

Record count offset.

withCountboolean

If total record count should be included in the response.

filterarray

Collection filters.

filter[] Channel Filter Paramobject

Filter settings.

Additional properties: Yes

Inherits: FilterParam

filter[].field*string

Field to filter on.

Enum:
  • name
  • type
  • enabled
filter[].op*string

Filter operator. Size comparisions are allowed only on numerical fields.

Enum:
  • eq
  • contains
  • starts
  • ends
  • lt
  • lte
  • gt
  • gte
filter[].value*string

Filter value.

sortarray

Collection sorting.

sort[] Channel Sort Paramobject

Sort settings.

Additional properties: Yes

Inherits: SortParam

sort[].field*string

Field to sort by.

Enum:
  • name
  • type
  • enabled
sort[].order*string

Order type.

Enum:
  • asc
  • desc

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Breaking Change

  • Not Implemented

  • Permissions:

    • ORG/READ
    • PROJECT/READ
    • PROJECT_CHANNELS/READ
curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/channels/mqtt?limit=<value>&offset=<value>&withCount=<value>&filter[][field]=<value>&filter[][op]=<value>&filter[][value]=<value>&sort[][field]=<value>&sort[][order]=<value>

200 OK chevron_right expand_more

Collection items.

MQTT Channel Collection Response ChannelMqttCollectionRes

application/json

Response of the MQTT channel collection.

Inherits: CollectionRes

ParameterTypeDescription
items*array

Collection items.

items[] MQTT Channel Entityobject

MQTT Channel full entity model.

Inherits: ChannelEntity

items[].type*string

Channel type.

Enum:
  • mqtt
items[].config*object

Channel configuration

items[].config.username*string

MQTT account username

items[].config.password* passwordstring

MQTT account password

Min. length: 6

Max. length: 1024

Inherits: string

items[].config.rateLimit*number

Message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

items[].config.maxConnections*number

Maximum number of active connections. For no limit use value of -1.

Min. value: -1

items[].config.accessList accessListobject

Channel access list

Inherits: object

items[].config.accessList.publisharray

Publish operation rules

items[].config.accessList.publish[] Channel ACL Ruleobject

Channel access list rule object.

Inherits: object

items[].config.accessList.publish[].topic*string

Topic the rule applies to.

The following wildcards are allowed: # - anything, + anything in current level.

items[].config.accessList.publish[].allow*boolean

If an operation on a topic specified by the rule is allowed or denied.

items[].config.accessList.subscribearray

Subscribe operation rules

items[].config.accessList.subscribe[] Channel ACL Ruleobject

Channel access list rule object.

Inherits: object

items[].config.accessList.subscribe[].topic*string

Topic the rule applies to.

The following wildcards are allowed: # - anything, + anything in current level.

items[].config.accessList.subscribe[].allow*boolean

If an operation on a topic specified by the rule is allowed or denied.

items[].channelId*integer

Channel ID

items[].projectId*integer

Project ID

items[].name*string

Label

Min. length: 1

Max. length: 255

items[].enabled*boolean

If a channel is enabled

items[].created*datetime

DateTime when the entity was created.

Format: rfc3339

items[].createdBy*string

Username of an account which has created the entity.

items[].modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

items[].modifiedBy*string

Username of an account which has modified the entity last.

items[].deleted*boolean

If the entity was deleted.

permissions* permissionsarray

List of channel collection permissions.

Inherits: array

permissions[]string

Permission name.

Enum:
  • PROJECT_CHANNEL/CREATE
countinteger

Optional count of all collection items with respect to filters.

limit*integer

The limit value from the query parameter - helps a client to determine pagination.

offset*integer

The offset value from the query parameter - helps a client to determine pagination.

Response Body

{
  "items": [
    {
      "channelId": 123,
      "projectId": 2,
      "type": "mqtt",
      "name": "Primary MQTT",
      "config": {
        "username": "ad24HuRI2",
        "password": "mqttSecret123",
        "rateLimit": 100,
        "maxConnections": 4,
        "accessList": {
          "publish": [
            {
              "topic": "my-device/_internal/#",
              "allow": false
            },
            {
              "topic": "my-device/#",
              "allow": true
            }
          ],
          "subscribe": [
            {
              "topic": "top/+/secret",
              "allow": false
            },
            {
              "topic": "#",
              "allow": true
            }
          ]
        }
      },
      "enabled": true,
      "created": "2019-01-13T23:46:06.090Z",
      "createdBy": "john.doe",
      "modified": "2019-01-13T23:46:06.090Z",
      "modifiedBy": "john.doe",
      "deleted": false
    },
    {
      "channelId": 342,
      "projectId": 2,
      "type": "mqtt",
      "name": "Secondary MQTT",
      "config": {
        "username": "urd23AHPeX",
        "password": "mqttSecret456",
        "rateLimit": 50,
        "maxConnections": 1
      },
      "enabled": true,
      "created": "2019-01-13T23:46:06.090Z",
      "createdBy": "john.doe",
      "modified": "2019-01-13T23:46:06.090Z",
      "modifiedBy": "john.doe",
      "deleted": false
    }
  ],
  "count": 2,
  "limit": 100,
  "offset": 0,
  "permissions": [
    "PROJECT_CHANNEL/CREATE"
  ]
}

post /orgs/{orgId}/projects/{projectId}/channels/mqtt

Create MQTT Channel highlight_off  lock vpn_key

Creates a new MQTT channel.

Changes:
v1.3.0 - Project channels were added.

Not implemented

vpn_key Required permissions

ORG/READ PROJECT/READ PROJECT_CHANNELS/CREATE

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Not Implemented

  • Permissions:

    • ORG/READ
    • PROJECT/READ
    • PROJECT_CHANNELS/CREATE
curl -X POST \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/channels/mqtt

Request Body chevron_right expand_more

MQTT Channel Base ChannelMqttBase

application/json

MQTT Channel entity base model.

Inherits: ChannelBase

ParameterTypeDescription
config*object

Channel configuration

config.password* passwordstring

MQTT account password

Min. length: 6

Max. length: 1024

Inherits: string

config.rateLimit*number

Message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

config.maxConnections*number

Maximum number of active connections. For no limit use value of -1.

Min. value: -1

config.accessList accessListobject

Channel access list

Inherits: object

config.accessList.publisharray

Publish operation rules

config.accessList.publish[] Channel ACL Ruleobject

Channel access list rule object.

Inherits: object

config.accessList.publish[].topic*string

Topic the rule applies to.

The following wildcards are allowed: # - anything, + anything in current level.

config.accessList.publish[].allow*boolean

If an operation on a topic specified by the rule is allowed or denied.

config.accessList.subscribearray

Subscribe operation rules

config.accessList.subscribe[] Channel ACL Ruleobject

Channel access list rule object.

Inherits: object

config.accessList.subscribe[].topic*string

Topic the rule applies to.

The following wildcards are allowed: # - anything, + anything in current level.

config.accessList.subscribe[].allow*boolean

If an operation on a topic specified by the rule is allowed or denied.

name*string

Label

Min. length: 1

Max. length: 255

enabled*boolean

If a channel is enabled

Request Body

{
  "name": "Primary MQTT",
  "config": {
    "password": "mqttSecret123",
    "rateLimit": 100,
    "maxConnections": 4,
    "accessList": {
      "publish": [
        {
          "topic": "my-device/_internal/#",
          "allow": false
        },
        {
          "topic": "my-device/#",
          "allow": true
        }
      ],
      "subscribe": [
        {
          "topic": "top/+/secret",
          "allow": false
        },
        {
          "topic": "#",
          "allow": true
        }
      ]
    }
  },
  "enabled": true
}

201 Created chevron_right expand_more

Channel has been created.

MQTT Channel Entity ChannelMqttEntity

application/json

MQTT Channel full entity model.

Inherits: ChannelEntity

ParameterTypeDescription
type*string

Channel type.

Enum:
  • mqtt
config*object

Channel configuration

config.username*string

MQTT account username

config.password* passwordstring

MQTT account password

Min. length: 6

Max. length: 1024

Inherits: string

config.rateLimit*number

Message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

config.maxConnections*number

Maximum number of active connections. For no limit use value of -1.

Min. value: -1

config.accessList accessListobject

Channel access list

Inherits: object

config.accessList.publisharray

Publish operation rules

config.accessList.publish[] Channel ACL Ruleobject

Channel access list rule object.

Inherits: object

config.accessList.publish[].topic*string

Topic the rule applies to.

The following wildcards are allowed: # - anything, + anything in current level.

config.accessList.publish[].allow*boolean

If an operation on a topic specified by the rule is allowed or denied.

config.accessList.subscribearray

Subscribe operation rules

config.accessList.subscribe[] Channel ACL Ruleobject

Channel access list rule object.

Inherits: object

config.accessList.subscribe[].topic*string

Topic the rule applies to.

The following wildcards are allowed: # - anything, + anything in current level.

config.accessList.subscribe[].allow*boolean

If an operation on a topic specified by the rule is allowed or denied.

channelId*integer

Channel ID

projectId*integer

Project ID

name*string

Label

Min. length: 1

Max. length: 255

enabled*boolean

If a channel is enabled

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

Response Body

{
  "channelId": 123,
  "projectId": 2,
  "type": "mqtt",
  "name": "Primary MQTT",
  "config": {
    "username": "ad24HuRI2",
    "password": "mqttSecret123",
    "rateLimit": 100,
    "maxConnections": 4,
    "accessList": {
      "publish": [
        {
          "topic": "my-device/_internal/#",
          "allow": false
        },
        {
          "topic": "my-device/#",
          "allow": true
        }
      ],
      "subscribe": [
        {
          "topic": "top/+/secret",
          "allow": false
        },
        {
          "topic": "#",
          "allow": true
        }
      ]
    }
  },
  "enabled": true,
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "john.doe",
  "deleted": false
}

400 Bad Request chevron_right expand_more

Invalid payload or constraint violated.

Validation Error ValidationError

application/json

Error object returned when a request payload is not valid or some constraint was violated.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 400

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Missing property

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Validation error",
  "message": "Property 'name' is required."
}

Violated constraint

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 400,
  "error": "Constraint violation error",
  "message": "Property `email` must be unique."
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

get /orgs/{orgId}/projects/{projectId}/channels/mqtt/{channId}

Get Channel highlight_off  lock vpn_key

Returns a MQTT channel entity based on ID.

Changes:
v1.3.0 - Project channels were added.

Not implemented

vpn_key Required permissions

ORG/READ PROJECT/READ PROJECT_CHANNELS/READ

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

channId*integer

Channel ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Not Implemented

  • Permissions:

    • ORG/READ
    • PROJECT/READ
    • PROJECT_CHANNELS/READ
curl -X GET \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/channels/mqtt/{channId}

200 OK chevron_right expand_more

The MQTT channel entity.

MQTT Channel Entity ChannelMqttEntity

application/json

MQTT Channel full entity model.

Inherits: ChannelEntity

ParameterTypeDescription
type*string

Channel type.

Enum:
  • mqtt
config*object

Channel configuration

config.username*string

MQTT account username

config.password* passwordstring

MQTT account password

Min. length: 6

Max. length: 1024

Inherits: string

config.rateLimit*number

Message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

config.maxConnections*number

Maximum number of active connections. For no limit use value of -1.

Min. value: -1

config.accessList accessListobject

Channel access list

Inherits: object

config.accessList.publisharray

Publish operation rules

config.accessList.publish[] Channel ACL Ruleobject

Channel access list rule object.

Inherits: object

config.accessList.publish[].topic*string

Topic the rule applies to.

The following wildcards are allowed: # - anything, + anything in current level.

config.accessList.publish[].allow*boolean

If an operation on a topic specified by the rule is allowed or denied.

config.accessList.subscribearray

Subscribe operation rules

config.accessList.subscribe[] Channel ACL Ruleobject

Channel access list rule object.

Inherits: object

config.accessList.subscribe[].topic*string

Topic the rule applies to.

The following wildcards are allowed: # - anything, + anything in current level.

config.accessList.subscribe[].allow*boolean

If an operation on a topic specified by the rule is allowed or denied.

channelId*integer

Channel ID

projectId*integer

Project ID

name*string

Label

Min. length: 1

Max. length: 255

enabled*boolean

If a channel is enabled

created*datetime

DateTime when the entity was created.

Format: rfc3339

createdBy*string

Username of an account which has created the entity.

modified*datetime

DateTime when the entity was last modified.

Format: rfc3339

modifiedBy*string

Username of an account which has modified the entity last.

deleted*boolean

If the entity was deleted.

Response Body

{
  "channelId": 123,
  "projectId": 2,
  "type": "mqtt",
  "name": "Primary MQTT",
  "config": {
    "username": "ad24HuRI2",
    "password": "mqttSecret123",
    "rateLimit": 100,
    "maxConnections": 4,
    "accessList": {
      "publish": [
        {
          "topic": "my-device/_internal/#",
          "allow": false
        },
        {
          "topic": "my-device/#",
          "allow": true
        }
      ],
      "subscribe": [
        {
          "topic": "top/+/secret",
          "allow": false
        },
        {
          "topic": "#",
          "allow": true
        }
      ]
    }
  },
  "enabled": true,
  "created": "2019-01-13T23:46:06.090Z",
  "createdBy": "john.doe",
  "modified": "2019-01-13T23:46:06.090Z",
  "modifiedBy": "john.doe",
  "deleted": false
}

403 Forbidden chevron_right expand_more

Access denied.

Access Denied Error AccessDeniedError

application/json

Error object returned when a user has insufficient permissions.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 403

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Access denied

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Access denied.",
  "message": "You have insufficient permissions to access this endpoint."
}

Limit exceeded

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 403,
  "error": "Limit exceeded.",
  "message": "You have exceeded resources limitation."
}

404 Not Found chevron_right expand_more

Resource was not found.

Not Found Error NotFoundError

application/json

Error object returned when a requested resources was not found.

Additional properties: Yes

Inherits: ApiError

ParameterTypeDescription
status*integer

Status code or name.

Default value: 404

timestamp*datetime

DateTime when error occured.

Format: rfc3339

error*string

Error name.

messagestring

Optional error message containing more details.

Response Body

Not found

{
  "timestamp": "2019-01-13T23:46:06.090Z",
  "status": 404,
  "error": "Not found",
  "message": "Resource was not found."
}

put /orgs/{orgId}/projects/{projectId}/channels/mqtt/{channId}

Update Channel highlight_off  lock vpn_key

Updates the MQTT channel entity.

Changes:
v1.3.0 - Project channels were added.

Not implemented

vpn_key Required permissions

ORG/READ PROJECT/READ PROJECT_CHANNELS/UPDATE

Parameters chevron_right expand_more

ParameterTypeDescription
Path
orgId*integer

Organization ID

projectId*integer

Project ID

channId*integer

Channel ID

Secured By chevron_right expand_more

JSON Web Token jwt

The API is using JWT (JSON Web Token) authorization method.

Service Account serviceAccount

The API is using service account authorization method.

Annotations chevron_right expand_more

  • Not Implemented

  • Permissions:

    • ORG/READ
    • PROJECT/READ
    • PROJECT_CHANNELS/UPDATE
curl -X PUT \
  -H "Content-type: application/json"
  -d @body.json \
  https://api.iot.tcpisek.cz/v1/orgs/{orgId}/projects/{projectId}/channels/mqtt/{channId}

Request Body chevron_right expand_more

MQTT Channel Base ChannelMqttBase

application/json

MQTT Channel entity base model.

Inherits: ChannelBase

ParameterTypeDescription
config*object

Channel configuration

config.password* passwordstring

MQTT account password

Min. length: 6

Max. length: 1024

Inherits: string

config.rateLimit*number

Message rate limit as messages per second. For no limit use value of -1.

Min. value: -1

config.maxConnections*number

Maximum number of active connections. For no limit use value of -1.

Min. value: -1

config.accessList accessListobject

Channel access list

Inherits: object

config.accessList.publisharray

Publish operation rules

config.accessList.publish[] Channel ACL Ruleobject

Channel access list rule object.

Inherits: object

config.accessList.publish[].topic*string

Topic the rule applies to.

The following wildcards are allowed: # - anything, + anything in current level.

config.accessList.publish[].allow*boolean

If an operation on a topic specified by the rule is allowed or denied.

config.accessList.subscribearray

Subscribe operation rules

config.accessList.subscribe[] Channel ACL Ruleobject

Channel access list rule object.

Inherits: object

config.accessList.subscribe[].topic*string

Topic the rule applies to.

The following wildcards are allowed: # - anything, + anything in current level.

config.accessList.subscribe[].allow*boolean

If an operation on a topic specified by the rule is allowed or denied.

name*string

Label

Min. length: 1

Max. length: 255

enabled*boolean

If a channel is enabled

Request Body

{
  "name": "Primary MQTT",
  "config": {
    "password": "mqttSecret123",
    "rateLimit": 100,
    "maxConnections": 4,
    "accessList": {
      "publish": [
        {
          "topic": "my-device/_internal/#",
          "allow": false
        },
        {
          "topic": "my-device/#",
          "allow": true
        }
      ],
      "subscribe": [
        {
          "topic": "top/+/secret",
          "allow": false
        },
        {
          "topic": "#",
          "allow": true
        }
      ]
    }
  },
  "enabled": true
}

200 OK chevron_right expand_more

MQTT channel has been updated.

MQTT Channel Entity ChannelMqttEntity

application/json

MQTT Channel full entity model.

Inherits: ChannelEntity

ParameterTypeDescription
type*string

Channel type.

Enum:
  • mqtt
config*object

Channel configuration

config.username*string

MQTT account username

config.password* passwordstring

MQTT account password

Min. length: 6

Max. length: 1024

Inherits: string

config.rateLimit*num