Directories
The Directories API has endpoints for managing user directories.
Create directory
Creates a user directory.
POST /api/directories
Body parameters
name
string
requiredA unique directory name (cannot contain whitespace and must contain at least one non-digit).
Example request
curl https://{WEAVY-SERVER}/api/directories
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'acme' }"
Response codes
201 Created
401 Unauthorized
403 Forbidden
409 Conflict
422 Validation Failed
Response schema
{
"id": "integer",
"name": "string",
"members": {
"data": [
"object"
],
"start": "integer",
"end": "integer",
"count": "integer"
}
}
Get directory
Get a directory.
GET /api/directories/{dir}
Path parameters
dir
string
requiredId or name of directory.
Example request
curl https://{WEAVY-SERVER}/api/directories/acme
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes
200 Success
401 Unauthorized
404 Not Found
Response schema
{
"id": "integer",
"name": "string",
"members": {
"data": [
"object"
],
"start": "integer",
"end": "integer",
"count": "integer"
}
}
Update directory
Update (rename) a directory.
PATCH /api/directories/{dir}
Path parameters
dir
string
requiredId or name of directory.
Body parameters
name
string
requiredA unique directory name (cannot contain whitespace and must contain at least one non-digit).
Example request
curl -X PATCH https://{WEAVY_SERVER}/api/directories/acme
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'ACME_CORPORATION' }"
Response codes
200 Success
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Validation Failed
Response schema
{
"id": "integer",
"name": "string",
"members": {
"data": [
"object"
],
"start": "integer",
"end": "integer",
"count": "integer"
}
}
List directories
List directories.
GET /api/directories
Query parameters
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
). Specifynull
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
and100
. Default is25
.
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 thecount
property.
Example request
curl https://{WEAVY-SERVER}/api/directories?top=10&q=acme
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes
200 Success
401 Unauthorized
Response schema
{
"data": [
{
"id": "integer",
"name": "string"
}
],
"start": "integer",
"end": "integer",
"count": "integer"
}
List members
List the members of a directory.
GET /api/directories/{dir}/members
Path parameters
dir
string
requiredId or name of directory.
Query parameters
suspended
boolean
Indicates whether to list suspended members or not,
null
returns all members.
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
). Specifynull
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
and100
. Default is25
.
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 thecount
property.
Example request
curl https://{WEAVY-SERVER}/api/directories/acme/members
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes
200 Success
401 Unauthorized
404 Not Found
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"
}
Delete directory
Delete a directory.
DELETE /api/directories/{dir}
Path parameters
dir
string
requiredId or name of directory.
Example request
curl -X DELETE https://{WEAVY_SERVER}/api/directories/acme
-H "Authorization: Bearer {API-KEY}"
Response codes
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found