Reference
Web API
Users

Users

The Users API has methods for managing users.

Create user

Create a user account.

POST /api/users

Body parameters

uid string required: A unique user identifier (cannot contain whitespace and must contain at least one non-digit).

email string: Email address.

given_name string: Given/First name(s) of user. In some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

middle_name string: Middle name(s) of the user. In some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters.

name string: The full name in displayable form including all name parts, possibly including titles and suffixes.

family_name string: Family/Last name(s) of user. In some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

nickname string: The nickname, a casual name that may or may not be the same as the Weavy.Core.DTO.UserUp.GivenName. For instance, a person with given name "Michael" might have the nickname "Mike".

phone_number string: The user's preferred phone number.

comment string: Comment or other application-specific information about the user.

picture string: The user's profile picture. Can be a public URL, a base64 encoded data URI or a blob id.

directory string: Id or name of user directory.

metadata object: Additional metadata properties, e.g. { "color": "blue", "size": "XL" }.

tags array of strings: A list of tags to associate with the user.

is_suspended boolean: true to mark the user account as suspended, otherwise false.

is_bot boolean: true to indicate that the user is a bot, otherwise false.

Example request

curl https://{WEAVY-SERVER}/api/users
-H "Authorization: Bearer {API-KEY}"
--json "{ 'uid': 'bugs-bunny', 'name': 'Bugs Bunny', 'directory': 'acme' }"

Response codes

201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
422 Validation Failed

Response schema

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "directory_id": "integer",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_bot": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

Get user

Get user with specified identifier.

GET /api/users/{user}

Path parameters

user string required: User identifier (id or uid).

Query parameters

trashed boolean: true to return user even if trashed.

Example request

curl https://{WEAVY-SERVER}/api/users/bugs-bunny
-H "Authorization: Bearer {API-KEY}"

Response codes

200 Success
401 Unauthorized
404 Not Found

Response schema

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "directory_id": "integer",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_bot": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

Get authenticated user

Get the authenticated user.

GET /api/user

Example request

curl https://{WEAVY-SERVER}/api/user
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

200 Success
401 Unauthorized

Response schema

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "directory_id": "integer",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_bot": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

Update user

Update a user.

PATCH /api/users/{user}

Path parameters

user string required: User identifier (id or uid).

Body parameters

uid string: Unique user identifier (cannot contain whitespace and must contain at least one non-digit).

email string: Email address.

given_name string: Given/First name(s) of user. In some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

middle_name string: Middle name(s) of the user. In some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters.

name string: The full name in displayable form including all name parts, possibly including titles and suffixes.

family_name string: Family/Last name(s) of user. In some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

nickname string: The nickname, a casual name that may or may not be the same as the Weavy.Core.DTO.UserUp.GivenName. For instance, a person with given name "Michael" might have the nickname "Mike".

phone_number string: The user's preferred phone number.

comment string: Comment or other application-specific information about the user.

picture string: The user's profile picture. Can be a public URL, a base64 encoded data URI or a blob id.

directory string: Id or name of user directory.

metadata object: Additional metadata properties, e.g. { "color": "blue", "size": "XL" }.

tags array of strings: A list of tags to associate with the user.

is_suspended boolean: true to mark the user account as suspended, otherwise false.

is_bot boolean: true to indicate that the user is a bot, otherwise false.

Example request

curl -X PATCH https://{WEAVY_SERVER}/api/users/bugs-bunny
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'Bugs Bunny' }"

Response codes

200 Success
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Validation Failed

Response schema

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "directory_id": "integer",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_bot": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

Upsert user

Update and return user with specified uid. If the user does not exists it is created.

PUT /api/users/{uid}

Path parameters

uid string required: Unique user identifier.

Body parameters

uid string: Unique user identifier (cannot contain whitespace and must contain at least one non-digit).

email string: Email address.

given_name string: Given/First name(s) of user. In some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

middle_name string: Middle name(s) of the user. In some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters.

name string: The full name in displayable form including all name parts, possibly including titles and suffixes.

family_name string: Family/Last name(s) of user. In some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

nickname string: The nickname, a casual name that may or may not be the same as the Weavy.Core.DTO.UserUp.GivenName. For instance, a person with given name "Michael" might have the nickname "Mike".

phone_number string: The user's preferred phone number.

comment string: Comment or other application-specific information about the user.

picture string: The user's profile picture. Can be a public URL, a base64 encoded data URI or a blob id.

directory string: Id or name of user directory.

metadata object: Additional metadata properties, e.g. { "color": "blue", "size": "XL" }.

tags array of strings: A list of tags to associate with the user.

is_suspended boolean: true to mark the user account as suspended, otherwise false.

is_bot boolean: true to indicate that the user is a bot, otherwise false.

Example request

curl -X PUT https://{WEAVY_SERVER}/api/users/bugs-bunny
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'Bugs Bunny', 'email': 'bugs@acme.corp"

Response codes

200 Success
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
422 Validation Failed

Response schema

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "directory_id": "integer",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_bot": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

List users

List users.

GET /api/users

Query parameters

bot boolean: Indicates whether to list bot users or not.

directory_id integer: List users in the specified directory, null lists users from all directories.

suspended boolean: Indicates whether to list suspended users or not.

q string: A query used to find matching items.

tag string: List items with the specified tag.

trashed boolean: Indicates whether trashed items should be listed (default is false). Specify null to return both trashed and non-trashed items.

order_by string: Specifies the sort order and direction for the listing, e.g. "name" or "name+desc"

top integer: Maximum number of items to return in the listing. Should be a value between 1 and 100. Default is 25.

skip integer: The number of items to skip. Used together with top to return a specific range of items (for pagination).

count_only boolean: true to only return the number of matching items; when this is specified the response will only contain the count property.

Example request

curl https://{WEAVY-SERVER}/api/users?top=20
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 Success
401 Unauthorized

Response schema

{
  "data": [
    {
      "id": "integer",
      "uid": "string",
      "display_name": "string",
      "email": "string",
      "given_name": "string",
      "middle_name": "string",
      "name": "string",
      "family_name": "string",
      "nickname": "string",
      "phone_number": "string",
      "comment": "string",
      "directory_id": "integer",
      "picture_id": "integer",
      "avatar_url": "string",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "presence": "string",
      "created_at": "string",
      "modified_at": "string",
      "is_bot": "boolean",
      "is_suspended": "boolean",
      "is_trashed": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

List users (autocomplete)

List users based on autocomplete search.

GET /api/users/autocomplete

Query parameters

q string: The search phrase to use.

skip integer: Gets or sets the number of items to skip before returning, defaults to 0.

top integer: Max number of items to return, defaults to 5.

count boolean: Count the total number of search results, defaults to false.

id integer: Optional app id. When set, the result contains a property indicating whether the listed users are member of the specified app or not.

Example request

curl https://{WEAVY-SERVER}/api/users/autocomplete?q=john
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 Success
401 Unauthorized

Response schema

{
  "data": [
    {
      "id": "integer",
      "uid": "string",
      "display_name": "string",
      "avatar_url": "string",
      "presence": "string",
      "access": "string",
      "is_member": "boolean",
      "is_bot": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Issue access token

If a user with the with the specified uid does not exists, this endpoint first creates the user and then issues an access_token.

POST /api/users/{user}/tokens

Path parameters

user string required: User identifier (id or uid).

Body parameters

expires_in integer: The lifetime of the access token in seconds, defaults to 3600 seconds (1 hour) when not specified.

Example request

curl https://{WEAVY-SERVER}/api/users/bugs-bunny/tokens
-H "Authorization: Bearer {API-KEY}"
--json "{ 'expires_in': 7200 }"

Response codes

200 Success
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found

Response schema

{
  "access_token": "string",
  "expires_in": "integer"
}

Revoke access token

Revoke all access tokens for the specified user.

DELETE /api/users/{user}/tokens

Path parameters

user string required: User identifier (id or uid).

Example request

curl -X DELETE https://{WEAVY_SERVER}/api/users/bugs-bunny/tokens
-H "Authorization: Bearer {API-KEY}"

Response codes

204 No Content
401 Unauthorized
403 Forbidden
404 Not Found

Trash user

Move a user to the trash.

POST /api/users/{user}/trash

Path parameters

user string required: User identifier (id or uid) of the user to trash.

Example request

curl -X POST https://{WEAVY_SERVER}/api/users/bugs-bunny/trash
-H "Authorization: Bearer {API-KEY}"

Response codes

200 Success
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found

Response schema

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "directory_id": "integer",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_bot": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}

Restore user

Restore a user from the trash.

POST /api/users/{user}/restore

Path parameters

user string required: User identifier (id or uid) of the user to restore.

Example request

curl -X POST https://{WEAVY_SERVER}/api/users/bugs-bunny/restore
-H "Authorization: Bearer {API-KEY}"

Response codes

200 Success
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found

Response schema

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "directory_id": "integer",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "picture_id": "integer",
  "avatar_url": "string",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "created_at": "string",
  "modified_at": "string",
  "is_bot": "boolean",
  "is_suspended": "boolean",
  "is_trashed": "boolean"
}