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

Id 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 required

Id or name of directory.

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 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). Specify null 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 and 100. Default is 25.

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 the count 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 required

Id 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). Specify null 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 and 100. Default is 25.

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 the count 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 required

Id 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