Usergrid API Reference

Generated from Swagger.

Methods

API methods are organized by the tags.

Following the methods is a listing of all Default Entity Models.

Access-Tokens

POST /management/token

Login with Admin-User or Organization credentials.

Parameters

  • login-credentials (LoginCredentials)
    Login credentials either username/password or id/secret. (Specified in body).

Responses

  • 200
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{appId}/token

Login with App-User or Application credentials.

Parameters

  • login-credentials (LoginCredentials)
    Login credentials either username/password or id/secret. (Specified in body).

Responses

  • 200
  • default
    • Description: Unexpected error.
    • Schema: [Error]

Activities

GET /{orgId}/{appId}/groups/{groupId}/feed

Get a group's feed through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • groupId (string)
    One of the group's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of group's activity.
    • Schema: [ActivityFeed]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{appId}/users/{userId}/activities

Create an activity in the activities collection.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • userId-3 (string)
    One of the user's identification which includes username or UUID. (Specified in path).
  • CreateActivity (CreateActivity)
    One or more sets of activity properties. (Specified in body).

Responses

  • 200
    • Description: An array of user's activity.
    • Schema: [ActivityFeed]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{appId}/users/{userId}/feed

Retrieve a user's feed through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • userId-3 (string)
    One of the user's identification which includes username or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of user's activity feed.
    • Schema: [ActivityFeed]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

Admin-Users

GET /management/orgs/{orgId}/users

Retrieve details about the admin users in an organization.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved Admin user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

DELETE /management/orgs/{orgId}/users/{userId}

Remove an admin user from an organization through providing both Id of application and organization.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • userId-2 (string)
    One of the user's identification which includes username, email address or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of deleted Admin user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /management/users

Create a whole new admin user.

Parameters

  • CreateAdminUser (CreateAdminUser)
    User entity with fields required for User creation. (Specified in body).

Responses

  • 200
    • Description: An API Response with a entities array containing the newly created Admin User.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/users/resetpw

Initiate the reset of an admin user's password.

Parameters

Responses

  • 200
    • Description: An array of complete messages.
    • Schema: [Action]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /management/users/resetpw

Complete the password reset through getting the newpassword and the old one for identification.

Parameters

  • ResetPWMsg (ResetPWMsg)
    Parameters and value for the Captcha challenge, the admin user's response to the Captcha challenge, and the admin user's email address. (Specified in body).

Responses

  • 200
    • Description: An array of complete messages.
    • Schema: []
  • default
    • Description:
    • Schema: [Error]

GET /management/users/{userId}

Retrieve details about an admin user.

Parameters

  • userId (string)
    One of the user's identification which includes username, real name, email address or UUID. (Specified in path).

Responses

  • 200
    • Description: An API Response with a entities array containing the Admin User.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

PUT /management/users/{userId}

Update the info of an admin user.

Parameters

  • userId (string)
    One of the user's identification which includes username, real name, email address or UUID. (Specified in path).

Responses

  • 200
    • Description: An API Response with a entities array containing the updated Admin User
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/users/{userId}/activate

Activate an admin user from a link provIded in an email notification.

Parameters

  • userId (string)
    One of the user's identification which includes username, real name, email address or UUID. (Specified in path).
  • token (string)
    Activation token's query statement. (Specified in query).
  • confirm_email (boolean)
    Query statement of whether send confimation email or not. (Specified in query).

Responses

  • 200
    • Description: An array of complete messages.
    • Schema: [Action]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

PUT /management/users/{userId}/password

Update an admin user's password through getting the newpassword and the old one for identification.

Parameters

  • userId (string)
    One of the user's identification which includes username, real name, email address or UUID. (Specified in path).
  • ResetPW (ResetPW)
    The user's old and new password. (Specified in body).

Responses

  • 200
    • Description: An array of complete messages.
    • Schema: [Action]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/users/{userId}/reactivate

Reactivate an expired admin user.

Parameters

  • userId (string)
    One of the user's identification which includes username, real name, email address or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of complete messages.
    • Schema: [Action]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

App-Users

GET /{orgId}/{appId}/users

Retrieve users though query statement.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • queryStatement (string)
    The query statement of the User. (Specified in query).

Responses

  • 200
    • Description: An array of retrieved user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{appId}/users

Create a user in the users collection through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • CreateUser (CreateUser)
    The properties of the user. (Specified in body).

Responses

  • 200
    • Description: An array of created user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{appId}/users/{userId}

Retrieve a user through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • userId-2 (string)
    One of the user's identification which includes username, email address or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

PUT /{orgId}/{appId}/users/{userId}

Update a user through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • userId-3 (string)
    One of the user's identification which includes username or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of updated user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

DELETE /{orgId}/{appId}/users/{userId}

Remove a user through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • userId-3 (string)
    One of the user's identification which includes username or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of deleted user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{appId}/users/{user}/password

Set a user's password or reset the user's existing password.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • username (string)
    The username of the user. (Specified in path).
  • ResetPW (ResetPW)
    The user's old and new password. (Specified in body).

Responses

  • 200
    • Description: An array of complete messages.
    • Schema: [Action]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

Entities-Collections

GET /{orgId}/{appId}/users/{userId}/{relation}

Retrieve a user's collections or connections through query statement.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • userId-3 (string)
    One of the user's identification which includes username or UUID. (Specified in path).
  • relation (string)
    The relation between user and collections. (Specified in path).
  • queryStatement (string)
    The query statement of the user. (Specified in query).

Responses

  • 200
    • Description: An array of user's collections info.
    • Schema: [Entity]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{appId}/{collectionId}

Retrieve collection through query statement.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • collectionId (string)
    One of the collection's identification which includes name or uuid. (Specified in path).
  • queryStatement (string)
    Any values specified in the query statement should be enclosed in single-quotes. (Specified in query).

Responses

  • 200
    • Description: An array of retrieved collection's info.
    • Schema: [Entity]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

PUT /{orgId}/{appId}/{collectionId}

Update collection through query statement.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • collectionId (string)
    One of the collection's identification which includes name or uuid. (Specified in path).
  • queryStatement (string)
    Any values specified in the query statement should be enclosed in single-quotes. (Specified in query).

Responses

  • 200
    • Description: An array of updated collection's info.
    • Schema: [Entity]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{appId}/{collectionId}/{entityId1}/{relation}/{entityId2}

Add an entity to a collection through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • collectionId (string)
    One of the collection's identification which includes name or uuid. (Specified in path).
  • entityId1 (string)
    The Id of the 1st entity. (Specified in path).
  • relation (string)
    The relation between 1st entity and 2nd entity. (Specified in path).
  • entityId2 (string)
    The Id of the 2nd entity. (Specified in path).

Responses

  • 200
    • Description: An array of added entity's info.
    • Schema: [Entity]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

DELETE /{orgId}/{appId}/{collectionId}/{entityId1}/{relation}/{entityId2}

Remove an entity from a collection through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • collectionId (string)
    One of the collection's identification which includes name or uuid. (Specified in path).
  • entityId1 (string)
    The Id of the 1st entity. (Specified in path).
  • relation (string)
    The relation between 1st entity and 2nd entity. (Specified in path).
  • entityId2 (string)
    The Id of the 2nd entity. (Specified in path).

Responses

  • 200
    • Description: An array of deleted entity's info.
    • Schema: [Entity]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{appId}/{collectionId}/{entityId}

Retrieve an entity through providing Id of application, organization, collection and entity.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • collectionId (string)
    One of the collection's identification which includes name or uuid. (Specified in path).
  • entityId (string)
    One of the entity's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved entity's info.
    • Schema: [Entity]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

PUT /{orgId}/{appId}/{collectionId}/{entityId}

One or more properties can be updated with a single request.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • collectionId (string)
    One of the collection's identification which includes name or uuid. (Specified in path).
  • entityId (string)
    One of the entity's identification which includes name or uuid. (Specified in path).
  • entityproperty (CreateEntities)
    The properties of the entity. (Specified in body).

Responses

  • 200
    • Description: An array of updated entity's info.
    • Schema: [Entity]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

DELETE /{orgId}/{appId}/{collectionId}/{entityId}

Delete an entity from the collection.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • collectionId (string)
    One of the collection's identification which includes name or uuid. (Specified in path).
  • entityId (string)
    One of the entity's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of deleted entity's info.
    • Schema: [Entity]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{appId}/{entitytype}

When a new entity is created, Usergrid will automatically create a corresponding collection if one does not already exist. The collection will automatically be named with the plural form of the entity type.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • entitytype (string)
    The entity type to create. (Specified in path).
  • entityproperty (CreateEntities)
    The properties of the entity. (Specified in body).

Responses

  • 200
    • Description: An array of created custom entity's info.
    • Schema: [Entity]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

Events

POST /{orgId}/{appId}/events

Create an event through providing both Id of organization and application.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • CreateEvent (CreateEvent)
    The required property of the event. (Specified in body).

Responses

  • 200
    • Description: An array of created event's info.
    • Schema: [Event]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

Groups

POST /{orgId}/{appId}/groups

Create a new group through providing both Id of organization and application.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • groupproperty (CreateGroup)
    The property of the created group. (Specified in body).

Responses

  • 200
    • Description: An array of created group's info.
    • Schema: [Group]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{appId}/groups/{groupId}/activities

Create an activity to a specific group. In this case the activity is created in the activities collection and is accessible at the /activities endpoint to users who have the permission to read that endpoint. In addition, a relationship is established between the activity and the group, and because of that, the activity will appear in the group’s feed. The group 'owns' the activity. Also, the activity will be published in the feed of all users that are members of the group.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • groupId (string)
    One of the group's identification which includes name or uuid. (Specified in path).
  • CreateActivity (CreateActivity)
    One or more sets of activity properties. (Specified in body).

Responses

  • 200
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{appId}/groups/{groupId}/users/{userId}

Add a user to a group through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • groupId (string)
    One of the group's identification which includes name or uuid. (Specified in path).
  • userId-3 (string)
    One of the user's identification which includes username or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of added user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

DELETE /{orgId}/{appId}/groups/{groupId}/users/{userId}

Delete user from a group through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • groupId (string)
    One of the group's identification which includes name or uuid. (Specified in path).
  • userId-3 (string)
    One of the user's identification which includes username or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of deleted user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{org_Id}/{app_Id}/groups/{groupId}

Get a group through through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • groupId (string)
    One of the group's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved group's info.
    • Schema: [Group]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

PUT /{org_Id}/{app_Id}/groups/{groupId}

Update a group through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • groupId (string)
    One of the group's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of updated group's info.
    • Schema: [Group]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

Notifications

POST /{orgId}/{applicationId}/devices

Create notifications for user through targeting by location and providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).
  • notification (CreateNotifications)
    These parameters are used when forming the notification portion of the request. (Specified in body).
  • queryStatement (string)
    The query statement of the location of the user. (Specified in query).

Responses

  • 200
    • Description: An array of created notification's info.
    • Schema: [Notification]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{applicationId}/devices/*/notifications

Create notifications for all devices. This request will target all device entities.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).
  • notification (CreateNotifications)
    These parameters are used when forming the notification portion of the request. (Specified in body).

Responses

  • 200
    • Description: An array of created notification's info.
    • Schema: [Notification]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{applicationId}/devices/{deviceId}/notifications

Create notifications for a single device. This request will target a specific device entity.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).
  • deviceId (string)
    One of the device's identification which includes name or uuid. (Specified in path).
  • notification (CreateNotifications)
    These parameters are used when forming the notification portion of the request. (Specified in body).

Responses

  • 200
    • Description: An array of created notification's info.
    • Schema: [Notification]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{applicationId}/groups/{path}/notifications

Create notifications for a group. This request will target all users associated with a specific group entity.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • path (string)
    The path of the group. (Specified in path).
  • notification (CreateNotifications)
    These parameters are used when forming the notification portion of the request. (Specified in body).

Responses

  • 200
    • Description: An array of created notification's info.
    • Schema: [Notification]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{applicationId}/notifications

Retrieve one or more notifications through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).

Responses

  • 200
    • Description: An array of retrieved notification's info.
    • Schema: [Notification]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

PUT /{orgId}/{applicationId}/notifications/{notificationId}

Update a Notification in order to cancel the notifcation or set a new expiration time.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).
  • notificationId (string)
    One of the notification's identification which includes name or uuid. (Specified in path).
  • notificationUpdate (NotificationUpdate)
    Object with Notification fields to be updated. (Specified in body).

Responses

  • 200
    • Description: An API Response object containing an entity of type Notification.
    • Schema: [Notification]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

DELETE /{orgId}/{applicationId}/notifications/{notificationId}

Delete an unsent Notification from the system.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).
  • notificationId (string)
    One of the notification's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: API Response containing Notification entity that was deleted.
    • Schema: [Notification]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{applicationId}/receipts

Retrieve one or more receipts through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).

Responses

  • 200
    • Description: An array of retrieved receipt's info.
    • Schema: [Receipt]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{applicationId}/users/{userId}/notifications

Create notifications for a user. This request will target a specific user entity.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).
  • userId-3 (string)
    One of the user's identification which includes username or UUID. (Specified in path).
  • notification (CreateNotifications)
    These parameters are used when forming the notification portion of the request. (Specified in body).

Responses

  • 200
    • Description: An array of created notification's info.
    • Schema: [Notification]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{applicationId}/{deviceId}/*/receipts

Retrieve receipts associated with one or more devices through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).
  • deviceId (string)
    One of the device's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved receipt's info.
    • Schema: [Receipt]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{applicationId}/{notificationId}/*/queue

Retrieve the list of devices associated with one or more notifications before the notifications are sent through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).
  • notificationId (string)
    One of the notification's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved device's info.
    • Schema: [Device]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{applicationId}/{notificationId}/*/receipts

Retrieve receipts for one or more notifications through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).
  • notificationId (string)
    One of the notification's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved receipt's info.
    • Schema: [Receipt]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{applicationId}/{receiptId}/*/notifications

Retrieve notifications associated with one or more receipts through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • applicationId (string)
    One of the application's identification which includes name or uuid (same as appId). (Specified in path).
  • receiptId (string)
    One of the receipt's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved notification's info.
    • Schema: [Notification]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

Organizations-Applications

POST /management/orgs

Create an organization through a form post.

Parameters

  • CreateOrg (CreateOrg)
    A set of organization properties supplied through a form. (Specified in body).

Responses

  • 200
    • Description: An array of created Organization.
    • Schema: [Organization]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/orgs/{orgId}

Retrieve an organization given a specified UUID or username.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of created Organization.
    • Schema: [Organization]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/orgs/{orgId}/activate

Activate an organization from a link provIded in an email notification.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • token (string)
    Activation token. (Specified in query).
  • confirm_email (boolean)
    Send confirmation email or not. (Specified in query).

Responses

  • 200
    • Description: An array of complete messages.
    • Schema: [Action]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/orgs/{orgId}/apps

Retrieve the applications in an organization through providing both Id of application and organization.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved application data.
    • Schema: [AppData]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

DELETE /management/orgs/{orgId}/apps/{appId}

Remove an application from an organization through providing both Id of application and organization.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of deleted application info.
    • Schema: [AppData]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/orgs/{orgId}/apps/{appId}/credentials

Retrieve the client Id and client secret credentials for an application in an organization.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved credentials info.
    • Schema: [Credential]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /management/orgs/{orgId}/apps/{appId}/credentials

Generate the client Id and client secret credentials for an application in an organization.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of generated credentials info.
    • Schema: [Credential]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/orgs/{orgId}/credentials

Retrieve the credentials for an organization client.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of Credential
    • Schema: [Credential]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /management/orgs/{orgId}/credentials

Generate whole new credentials for an organization client.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of Credential
    • Schema: [Credential]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/orgs/{orgId}/feed

Retrieve an organization's activity feed.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of the organization's ActivityFeed.
    • Schema: [ActivityFeed]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/orgs/{orgId}/reactivate

Reactivate an expired organization.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of complete messages.
    • Schema: [Action]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /management/users/{userId}/feed

Retrieve an admin user's activity feed.

Parameters

  • userId (string)
    One of the user's identification which includes username, real name, email address or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of user's activity
    • Schema: [ActivityFeed]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

Permissions-Roles

GET /{orgId}/{appId}/roles

Retrieve the roles in an application through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An array of retrieved role's info.
    • Schema: [Role]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{appId}/roles

Create a new role through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • roleproperty (AddRole)
    The required properties of the role. (Specified in body).

Responses

  • 200
    • Description: An array of created role's info.
    • Schema: [Role]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

DELETE /{orgId}/{appId}/roles/{roleId}/permissions

Remove permissions from a role.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • roleId (string)
    One of the role's identification which includes name or uuid. (Specified in path).
  • Permissions (Permissions)
    The query statement of the url pattern. (Specified in body).

Responses

  • 200
    • Description: Permissions object with array of the deleated Usergrid Permission strings.
    • Schema: [Permissions]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{appId}/roles/{roleId}/users

Retrieve the users in a role through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • roleId (string)
    One of the role's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: An API Response with a entities array of Users.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{appId}/roles/{roleId}/users/{userId}

Add a user to a role through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • roleId (string)
    One of the role's identification which includes name or uuid. (Specified in path).
  • userId-3 (string)
    One of the user's identification which includes username or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of added user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

DELETE /{orgId}/{appId}/roles/{roleId}/users/{userId}

Remove a user from a role through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • roleId (string)
    One of the role's identification which includes name or uuid. (Specified in path).
  • userId-3 (string)
    One of the user's identification which includes username or UUID. (Specified in path).

Responses

  • 200
    • Description: An array of deleted user's info.
    • Schema: [User]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

DELETE /{orgId}/{appId}/roles/{rolename}

Remove a role through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • rolename (string)
    The name of the role. (Specified in path).

Responses

  • 200
    • Description: An array of deleted role's info.
    • Schema: [Role]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

GET /{orgId}/{applicationId}/roles/{roleId}/permissions

Retrieve permissions for a Role.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • roleId (string)
    One of the role's identification which includes name or uuid. (Specified in path).

Responses

  • 200
    • Description: Permissions object with array of Usergrid Permission strings.
    • Schema: [Permissions]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

POST /{orgId}/{applicationId}/roles/{roleId}/permissions

Add permissions to a role through providing all the identifications.

Parameters

  • orgId (string)
    One of the organization's identification which includes name or uuid. (Specified in path).
  • appId (string)
    One of the application's identification which includes name or uuid. (Specified in path).
  • roleId (string)
    One of the role's identification which includes name or uuid. (Specified in path).
  • Permissions (Permissions)
    Permissions object with array of Usergrid Permission strings to be added. (Specified in body).

Responses

  • 200
    • Description: Permissions object with array of Usergrid Permission strings.
    • Schema: [Permission]
  • default
    • Description: Unexpected error.
    • Schema: [Error]

Default Entity Models

This section lists the properties for the following Usergrid Default Entities.

AccessTokenResponse

Properties

Name Type Description Required
access_token string Access-token that may be used on subsequent requests. false
expires_in number Time (in milliseconds) until access-token expires. false
user User User object if login was done as a user. false

Referring API Paths

/{orgId}/{appId}/token

/management/token

Action

Properties

Name Type Description Required
action string The requested action. false
status string The status of the requested action. false
timestamp number The timestamp of the requested action. false
duration number The duration of the requested action. false
token string The token required for getting an AdminUser. false

Referring API Paths

/management/orgs/{orgId}/reactivate

/management/users/{userId}/activate

/management/users/{userId}/reactivate

/management/orgs/{orgId}/activate

/management/users/{userId}/password

/management/users/resetpw

/{orgId}/{appId}/users/{user}/password

Referring Definitions

Receipt

Device

Notification

Role

Event

Group

Credential

Organization

AppData

User

ActivityFeed

ActivityFeed

Properties

Name Type Description Required
entityproperty Entity false
category string The category of the activity. false
metadataproperty Metadata false
objectproperty Object false
title string The title of the activity. false
verb string The verb of the activity. false
published number UTC timestamp of the feed publish time. false
completeMsg Action false

Referring API Paths

/{orgId}/{appId}/users/{userId}/feed

/{orgId}/{appId}/users/{userId}/activities

/management/orgs/{orgId}/feed

/management/users/{userId}/feed

/{orgId}/{appId}/groups/{groupId}/feed

/{orgId}/{appId}/groups/{groupId}/activities

AddRole

Properties

Name Type Description Required
title string The title of the role. true
role name string The name of the role. true

Referring API Paths

/{orgId}/{appId}/roles

AppData

Properties

Name Type Description Required
tester/sandbox string The UUID of tester/sandbox. false
tester/app1 string The UUID of tester/app1. false
tester/app2 string The UUID of tester/app2. false
completeMsg Action false

Referring API Paths

/management/orgs/{orgId}/apps/{appId}

/management/orgs/{orgId}/apps

Referring Definitions

Organization

CreateActivity

Properties

Name Type Description Required
displayName string true
uuid string true
username string true
image ImageModel false
verb string true
content string true

Referring API Paths

/{orgId}/{appId}/users/{userId}/activities

/{orgId}/{appId}/groups/{groupId}/activities

CreateAdminUser

Properties

Name Type Description Required
username string true
email string false
name string false
password string false

Referring API Paths

/management/users

CreateEntities

Properties

Name Type Description Required

Referring API Paths

/{orgId}/{appId}/{entitytype}

/{orgId}/{appId}/{collectionId}/{entityId}

CreateEvent

Properties

Name Type Description Required
timestamp string true

Referring API Paths

/{orgId}/{appId}/events

CreateGroup

Properties

Name Type Description Required
title string The title of the group. true
path string The path of the group. true

Referring API Paths

/{orgId}/{appId}/groups

CreateNotifications

An array of Notifications to be created.

Properties

Name Type Description Required

Referring API Paths

/{orgId}/{applicationId}/groups/{path}/notifications

/{orgId}/{applicationId}/devices/{deviceId}/notifications

/{orgId}/{applicationId}/devices/*/notifications

/{orgId}/{applicationId}/users/{userId}/notifications

/{orgId}/{applicationId}/devices

CreateOrg

Properties

Name Type Description Required
organization string true
username string true
name string true
email string true
password string true

Referring API Paths

/management/orgs

CreateUser

Properties

Name Type Description Required
username string true

Referring API Paths

/{orgId}/{appId}/users

Credential

Properties

Name Type Description Required
client_Id string The Id of the client. false
client_secret string The secret of the client. false
completeMsg Action false

Referring API Paths

/management/orgs/{orgId}/apps/{appId}/credentials

/management/orgs/{orgId}/credentials

/management/orgs/{orgId}/credentials

/management/orgs/{orgId}/apps/{appId}/credentials

Device

Represents a single Device that is registered for recieving of Push Notifications.

Properties

Name Type Description Required
uuid string Unique entity Id. false
type string Type of entity. false
name string Notifier display name. false
created number UTC timestamp in milliseconds of when the entity was created. false
modified number UTC timestamp in milliseconds of when the entity was last modified. false
metadata Metadata false
completeMsg Action false

Referring API Paths

/{orgId}/{applicationId}/{notificationId}/*/queue

Entity

Properties

Name Type Description Required
uuid string The UUID of the entity. false
type string The type of the entity. false
created number UTC timestamp of entity creation time. false
modified Actor UTC timestamp of entity modified time. false
metadata Metadata false
name string The name of the entity. false
message string false

Referring API Paths

/{orgId}/{appId}/users/{userId}/{relation}

/{orgId}/{appId}/{collectionId}

/{orgId}/{appId}/{collectionId}/{entityId}

/{orgId}/{appId}/{entitytype}

/{orgId}/{appId}/{collectionId}

/{orgId}/{appId}/{collectionId}/{entityId1}/{relation}/{entityId2}

/{orgId}/{appId}/{collectionId}/{entityId}

/{orgId}/{appId}/{collectionId}/{entityId}

/{orgId}/{appId}/{collectionId}/{entityId1}/{relation}/{entityId2}

Referring Definitions

Role

Event

ActivityFeed

Error

Properties

Name Type Description Required
code integer false
message string false
fields object false

Event

Properties

Name Type Description Required
applicationName string The application name of the event. false
entity Entity false
url string The url of the event. false
applicationId string The application UUID of the event. false
parameters string The parameters of the event. false
organization string The title of the organization. false
completeMsg Action false

Referring API Paths

/{orgId}/{appId}/events

Group

Properties

Name Type Description Required
uuid string The UUID of the group. false
type string The type of the group. false
created string The created Id for the group. false
modified string The modified Id for the group. false
path string The path of the group. false
metadata Metadata false
title string The title of the group. false
completeMsg Action false

Referring API Paths

/{org_Id}/{app_Id}/groups/{groupId}

/{orgId}/{appId}/groups

/{org_Id}/{app_Id}/groups/{groupId}

LoginCredentials

Properties

Name Type Description Required
grant_type string Grant-type must be 'password' or 'client_credentials'. false
username string Username of user attempting login, required only if grant_type is 'password'. false
password string Password of user attempting login, required only if grant_type is 'password'. false
client_id string Client-ID portion of credentials, required only if grant_type is 'client_credentials'. false
client_secret string Client-Secret portion of credentials, required only if grant_type is 'client_credentials'. false

Referring API Paths

/{orgId}/{appId}/token

/management/token

Notification

Represents a Push Notification that is either scheduled, finished or cancelled.

Properties

Name Type Description Required
uuid string Unique entity Id. false
type string Type of entity. false
created number UTC timestamp in milliseconds of when the entity was created. false
modified number UTC timestamp in milliseconds of when the entity was last modified. false
payloads string The push notifications to be delivered. true
errorMessage string Error message returned by the notification service (APNs or GCM) if the notification fails entirely. false
scheduled boolean Whether the notification is currently scheduled for delivery. false
state string The current delivery status of the notification 'FINISHED', 'SCHEDULED' or 'CANCELED'. false
metadata Metadata false
completeMsg Action false

Referring API Paths

/{orgId}/{applicationId}/notifications

/{orgId}/{applicationId}/groups/{path}/notifications

/{orgId}/{applicationId}/notifications/{notificationId}

/{orgId}/{applicationId}/devices/{deviceId}/notifications

/{orgId}/{applicationId}/devices/*/notifications

/{orgId}/{applicationId}/notifications/{notificationId}

/{orgId}/{applicationId}/{receiptId}/*/notifications

/{orgId}/{applicationId}/users/{userId}/notifications

/{orgId}/{applicationId}/devices

NotificationUpdate

Represents fields that may be updated on a Notification to cause changes in Push Notification processing.

Properties

Name Type Description Required
canceled boolean Setting this field to true will cancel a Notification, if it has not yet been sent. false
deliver number Specifies the UNIX timestamp time at which the Notification should be sent. false
expired number Specifies the UNIX timestamp time at which this Notification has expired. false

Referring API Paths

/{orgId}/{applicationId}/notifications/{notificationId}

Organization

Properties

Name Type Description Required
applicationId string The application Id of the owner. false
username string The username of the owner. false
name string The name of the owner. false
email string The email of the owner. false
activated boolean Indicate whether the account is activated or not. false
disabled boolean Indicate whether the account is disabled or not. false
uuid string The UUID of the owner. false
adminUser boolean Indicate whether the use is a adminUser or not. false
displayEmail string The display of the email of the owner. false
htmldisplayEmail string The HTML display of the email of the owner. false
orgname string The name of the organization. false
orguuId string The UUID of the organization. false
applicationdata AppData false
completeMsg Action false

Referring API Paths

/management/orgs

/management/orgs/{orgId}

Permissions

Represents a set of Permissions associated with a User or a Role, each being a Usergrid Permission String.

Properties

Name Type Description Required
application string The UUID of the associated application. false
applicationName string The name of the associated application. false
organization string The name of the associated organization. false
data array Array of strings each being a Usergrid Permission String. true

Referring API Paths

/{orgId}/{applicationId}/roles/{roleId}/permissions

/{orgId}/{appId}/roles/{roleId}/permissions

/{orgId}/{applicationId}/roles/{roleId}/permissions

Receipt

Represents response received from Notification service indicating success or failure.

Properties

Name Type Description Required
uuid string Unique entity Id. false
type string Type of entity. false
created number UTC timestamp in milliseconds of when the entity was created. false
modified number UTC timestamp in milliseconds of when the entity was last modified. false
payloads string The push notifications to be delivered. false
errorMessage string Error message returned by the notification service (APNs or GCM) if the notification fails entirely. false
errorCode string Error code returned by the notification service. false
sent number UTC timestamp in milliseconds for when the notification was sent. false
metadata Metadata false
completeMsg Action false

Referring API Paths

/{orgId}/{applicationId}/{notificationId}/*/receipts

/{orgId}/{applicationId}/receipts

/{orgId}/{applicationId}/{deviceId}/*/receipts

ResetPW

Properties

Name Type Description Required
password string true
newpassword string true

Referring API Paths

/management/users/{userId}/password

/{orgId}/{appId}/users/{user}/password

ResetPWMsg

Properties

Name Type Description Required
recaptcha_response string Parameters and value for the Captcha challenge. true
recaptcha_challenge string The admin user's response to the Captcha challenge. true
email string true

Referring API Paths

/management/users/resetpw

Role

Properties

Name Type Description Required
applicationName string The application name of the event. false
count number The numebr of the roles. false
entity Entity false
url string The url of the event. false
applicationId string The application UUID of the event. false
parameters string The parameters of the event. false
organization string The title of the organization. false
completeMsg Action false
path string The path of the role. false

Referring API Paths

/{orgId}/{appId}/roles

/{orgId}/{appId}/roles/{rolename}

/{orgId}/{appId}/roles

User

Represents a User account which may be a user within an Application's User collection, or may be an Admin User.

Properties

Name Type Description Required
applicationId string The application Id of a user. false
username string The username of a user. false
name string The name of a user. false
email string The email of a user. false
activated boolean Indicate whether the account is activated or not. false
disabled boolean Indicate whether the account is disabled or not. false
uuid string The UUID of a user. false
adminUser boolean Indicate whether the use is a adminUser or not. false
displayEmail string The display of the email of a user. false
htmldisplayEmail string The HTML display of the email of a user. false
organization string The organization of the user. false
picture string The uri of the user's picture. false
uri string The uri of the user. false
path string The path of the user. false
completeMsg Action false

Referring API Paths

/{orgId}/{appId}/users

/management/orgs/{orgId}/users/{userId}

/{orgId}/{appId}/users/{userId}

/{orgId}/{appId}/users/{userId}

/management/users

/management/orgs/{orgId}/users

/{orgId}/{appId}/users/{userId}

/{orgId}/{appId}/groups/{groupId}/users/{userId}

/management/users/{userId}

/{orgId}/{appId}/groups/{groupId}/users/{userId}

/{orgId}/{appId}/roles/{roleId}/users

/management/users/{userId}

/{orgId}/{appId}/roles/{roleId}/users/{userId}

/{orgId}/{appId}/users

/{orgId}/{appId}/roles/{roleId}/users/{userId}

Referring Definitions

AccessTokenResponse

Sub-types Referenced By Models

This section lists the properties for sub-types used in Usergrid Default Entities.

Collections

Properties

Name Type Description Required
activities string false
feed string false
roles string false
users string false

Referring Definitions

Metadata

ImageModel

Properties

Name Type Description Required
duration number false
height number false
url string false
wIdth integer false
email string false

Referring Definitions

CreateActivity

Metadata

Properties

Name Type Description Required
cursor string The cursor of the metadata. false
path string The path of the metadata. false
sets Sets false
collections Collections false

Referring Definitions

Receipt

Device

Notification

Notifier

Group

Entity

ActivityFeed

Object

Properties

Name Type Description Required
displayname string The display of the name of the object. false
objecttype string The type of the object. false
objectuuId string The UUID of the object. false
entitytype string The entitytype of the object. false

Referring Definitions

ActivityFeed

Sets

Properties

Name Type Description Required
rolenames string false
permissions string false

Referring Definitions

Metadata