1. Reference
2. Web API
3. Directories

Directories

The Directories API has endpoints for managing user directories.

Create directory

Creates a user directory.

POST /api/directories

Body parameters

name string required

A unique directory name (cannot contain whitespace and must contain at least one non-digit).

Example request

curl {WEAVY-URL}/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 required

Directory identifier (id or name).

Example request

curl {WEAVY-URL}/api/directories/acme
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 OK
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 required

Directory identifier (id or name).

Body parameters

name string required

A unique directory name (cannot contain whitespace and must contain at least one non-digit).

Example request

curl -X PATCH {WEAVY-URL}/api/directories/acme
-H "Authorization: Bearer {API-KEY}"
--json "{ 'name': 'ACME_CORPORATION' }"

Response codes

200 OK
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 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/directories?take=25&q=acme
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 OK
401 Unauthorized

Response schema

{
  "data": [
    {
      "id": "integer",
      "name": "string"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

List directory members

List directory members.

GET /api/directories/{dir}/members

Path parameters

dir string required

Directory identifier (id or name).

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/directories/acme/members
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 OK
401 Unauthorized
404 Not Found

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

Delete directory

Delete a directory.

DELETE /api/directories/{dir}

Path parameters

dir string required

Directory identifier (id or name).

Example request

curl -X DELETE {WEAVY-URL}/api/directories/acme
-H "Authorization: Bearer {API-KEY}"

Response codes

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