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).

name string

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

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.

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".

email string

Email address.

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.

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",
  "name": "string",
  "given_name": "string",
  "middle_name": "string",
  "family_name": "string",
  "nickname": "string",
  "email": "string",
  "phone_number": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "presence": "string",
  "comment": "string",
  "tags": [
    "string"
  ],
  "metadata": "object",
  "created_at": "string",
  "updated_at": "string",
  "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",
  "name": "string",
  "given_name": "string",
  "middle_name": "string",
  "family_name": "string",
  "nickname": "string",
  "email": "string",
  "phone_number": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "presence": "string",
  "comment": "string",
  "tags": [
    "string"
  ],
  "metadata": "object",
  "created_at": "string",
  "updated_at": "string",
  "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",
  "name": "string",
  "given_name": "string",
  "middle_name": "string",
  "family_name": "string",
  "nickname": "string",
  "email": "string",
  "phone_number": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "presence": "string",
  "comment": "string",
  "tags": [
    "string"
  ],
  "metadata": "object",
  "created_at": "string",
  "updated_at": "string",
  "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).

name string

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

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.

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".

email string

Email address.

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.

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",
  "name": "string",
  "given_name": "string",
  "middle_name": "string",
  "family_name": "string",
  "nickname": "string",
  "email": "string",
  "phone_number": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "presence": "string",
  "comment": "string",
  "tags": [
    "string"
  ],
  "metadata": "object",
  "created_at": "string",
  "updated_at": "string",
  "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).

name string

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

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.

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".

email string

Email address.

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.

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",
  "name": "string",
  "given_name": "string",
  "middle_name": "string",
  "family_name": "string",
  "nickname": "string",
  "email": "string",
  "phone_number": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "directory": {
    "id": "integer",
    "name": "string"
  },
  "presence": "string",
  "comment": "string",
  "tags": [
    "string"
  ],
  "metadata": "object",
  "created_at": "string",
  "updated_at": "string",
  "is_trashed": "boolean"
}

List users

List user account.

GET /api/users
Query parameters
autocomplete boolean

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

bot boolean

Should bot users be listed or not? When unspecified all types of users are listed.

directory string

Directory identifier (id or name). When unspecified users from all directories are listed.

q string

A string used to find matching items by name, e.g. q=test.

tag string

List items with the specified tag.

trashed boolean

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

order_by string

Specifies the sort order and direction for the listing, e.g. order_by=id or order_by=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 count the number of matching items instead of listing them; when 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",
      "name": "string",
      "given_name": "string",
      "middle_name": "string",
      "family_name": "string",
      "nickname": "string",
      "email": "string",
      "phone_number": "string",
      "avatar_url": "string",
      "presence": "string",
      "comment": "string",
      "tags": [
        "string"
      ],
      "metadata": "object",
      "created_at": "string",
      "updated_at": "string",
      "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

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

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

Support

To access live chat with our developer success team you need a Weavy account.

Sign in or create a Weavy account