1. Reference
2. Web API
3. 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 {WEAVY-URL}/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",
  "avatar_url": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "directory_id": "integer",
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "created_at": "string",
  "updated_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 {WEAVY-URL}/api/users/bugs-bunny
-H "Authorization: Bearer {API-KEY}"

Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema

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

Get authenticated user

Get the authenticated user.

GET /api/user

Example request

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

Response codes

200 OK
401 Unauthorized

Response schema

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "avatar_url": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "directory_id": "integer",
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "created_at": "string",
  "updated_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 {WEAVY-URL}/api/users/bugs-bunny
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'Bugs Bunny' }"

Response codes

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

Response schema

{
  "id": "integer",
  "uid": "string",
  "display_name": "string",
  "avatar_url": "string",
  "email": "string",
  "given_name": "string",
  "middle_name": "string",
  "name": "string",
  "family_name": "string",
  "nickname": "string",
  "phone_number": "string",
  "comment": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "metadata": "object",
  "tags": [
    "string"
  ],
  "presence": "string",
  "directory_id": "integer",
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "created_at": "string",
  "updated_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 {WEAVY-URL}/api/users/bugs-bunny
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'Bugs Bunny', 'email': 'bugs@acme.corp"

Response codes

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

Response schema

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

List users

List users.

GET /api/users

Query parameters

autocomplete boolean

true (default) to use "autocomplete" search, otherwise false.

bot boolean

Should bot users be listed or not.

directory string

Directory identifier (id or name), null lists users from all directories.

suspended boolean

Should suspended users be listed 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. "id" or "id+desc"

skip integer

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

take integer

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

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 {WEAVY-URL}/api/users?take=25
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 OK
401 Unauthorized

Response schema

{
  "data": [
    {
      "id": "integer",
      "uid": "string",
      "display_name": "string",
      "avatar_url": "string",
      "email": "string",
      "given_name": "string",
      "middle_name": "string",
      "name": "string",
      "family_name": "string",
      "nickname": "string",
      "phone_number": "string",
      "comment": "string",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "presence": "string",
      "directory_id": "integer",
      "created_at": "string",
      "updated_at": "string",
      "is_bot": "boolean",
      "is_suspended": "boolean",
      "is_trashed": "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 {WEAVY-URL}/api/users/bugs-bunny/tokens
-H "Authorization: Bearer {API-KEY}"
--json "{ 'expires_in': 7200 }"

Response codes

200 OK
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 {WEAVY-URL}/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 {WEAVY-URL}/api/users/bugs-bunny/trash
-H "Authorization: Bearer {API-KEY}"

Response codes

204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found

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 {WEAVY-URL}/api/users/bugs-bunny/restore
-H "Authorization: Bearer {API-KEY}"

Response codes

204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found