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

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

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