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",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "is_trashed": "boolean"
}

Get user

Get user account 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",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "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",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "is_trashed": "boolean"
}

Update user

Update a user account.

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",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "is_trashed": "boolean"
}

Upsert user

Update or insert user account. If an account with the specified uid is found it is updated, otherwise it is created.

PUT /api/users/{uid}
Path parameters
uid string required

Unique 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",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "is_trashed": "boolean"
}

List users

List user accounts.

GET /api/users
Query parameters
autocomplete boolean

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

agent boolean

Should AI agents 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.

system boolean

Include system users in the result?

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",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "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 account.

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 account to the trash.

POST /api/users/{user}/trash
Path parameters
user string required

Identifier (id or uid) of 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 account from the trash.

POST /api/users/{user}/restore
Path parameters
user string required

Identifier (id or uid) of 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

Delete user

Permanently delete a user account and all profile data. Content that isn't considered profile information won’t be removed (this includes comments, files, messages and other data that the user has created or shared).

DELETE /api/users/{user}
Path parameters
user string required

Identifier (id or uid) of user to delete.

Example request
curl -X DELETE {WEAVY-URL}/api/users/bugs-bunny
-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