Reference
Web API
Apps

Apps

The Apps API has methods for creating, and managing apps.

Create app

Create app with specified type and uid.

POST /api/apps

Body parameters

uid string required: A string that uniquely identifies the app, for instance a product id or URL (cannot contain whitespace and must contain at least one non-digit).

type string required: Type of app (chat, comments, files or posts.).

access string

Access level for non-members. Defaults to none.

none = non-members cannot access the app
read = non-members can see the app and it's content but can cannot contribute
write = non-members have access to the app and are allowed to create content

directory string: Id or name of a user directory. Used in combination with access to control who can access the app.

name string: Display name for the app.

description string: App description.

metadata object: Additional properties to associate with the app, e.g. { "color": "blue", "size": "XL" }.

picture string: An avatar picture. Can be a public URL, a base64 encoded data URI or a blob id.

tags array of strings: A list of tags to associate with the app.

Example request

curl https://{WEAVY-SERVER}/api/apps
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
--json "{ 'type': 'chat', 'uid': 'acme-chat', 'access': 'write' }"

Response codes

201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
422 Validation Failed

Response schema

{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "is_trashed": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "permissions": [
    "string"
  ]
}

Get app

Returns data for the specified app.

GET /api/apps/{app}

Path parameters

app string required: App identifier (id or uid).

Query parameters

trashed boolean: true to return app even if trashed, otherwise false.

Example request

curl https://{WEAVY-SERVER}/api/apps/acme-chat
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema

{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "is_trashed": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "permissions": [
    "string"
  ]
}

Update app

Update and return existing app.

PATCH /api/apps/{app}

Path parameters

app string required: App identifier (id or uid).

Body parameters

uid string: A string that uniquely identifies the app, for instance a product id or URL (cannot contain whitespace and must contain at least one non-digit).

access string

Access level for non-members. Defaults to none.

none = non-members cannot access the app
read = non-members can see the app and it's content but can cannot contribute
write = non-members have access to the app and are allowed to create content

directory string: Id or name of a user directory. Used in combination with access to control who can access the app.

name string: Display name for the app.

description string: App description.

metadata object: Additional properties to associate with the app, e.g. { "color": "blue", "size": "XL" }.

picture string: An avatar picture. Can be a public URL, a base64 encoded data URI or a blob id.

tags array of strings: A list of tags to associate with the app.

Example request

curl -X PATCH https://{WEAVY_SERVER}/api/apps/acme-chat
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
--json "{ 'description': 'Chat for ACME project' }"

Response codes

200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Validation Failed

Response schema

{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "is_trashed": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "permissions": [
    "string"
  ]
}

Upsert app

Update and return app with specified uid. If the app does not exist it is created.

PUT /api/apps/{uid}

Path parameters

uid string required: Unique app identifier.

Body parameters

type string required: Type of app (chat, comments, files or posts.).

uid string

access string

Access level for non-members. Defaults to none.

none = non-members cannot access the app
read = non-members can see the app and it's content but can cannot contribute
write = non-members have access to the app and are allowed to create content

directory string: Id or name of a user directory. Used in combination with access to control who can access the app.

name string: Display name for the app.

description string: App description.

metadata object: Additional properties to associate with the app, e.g. { "color": "blue", "size": "XL" }.

picture string: An avatar picture. Can be a public URL, a base64 encoded data URI or a blob id.

tags array of strings: A list of tags to associate with the app.

Example request

curl -X PUT https://{WEAVY-SERVER}/api/apps/acme-chat
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
--json "{ 'type': 'chat', 'access': 'write' }"

Response codes

200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
422 Validation Failed

Response schema

{
  "id": "integer",
  "type": "string",
  "uid": "string",
  "access": "string",
  "directory_id": "integer",
  "display_name": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "metadata": "object",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "tags": [
    "string"
  ],
  "created_at": "string",
  "updated_at": "string",
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "is_trashed": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "permissions": [
    "string"
  ]
}

Upsert members

Add or update multiple app members.

PUT /api/apps/{app}/members

Path parameters

app string required: App identifier (id or uid).

Body parameters

array of objects required: Members to add/update.

Example request

curl https://{WEAVY-SERVER}/api/apps/acme-chat/members
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
--json "[ { 'uid': 'acme-user' }, { 'uid': 'daffy-duck', 'access': 'read' } ]"

Response codes

200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
422 Validation Failed

List apps

Returns a list of apps.

GET /api/apps

Query parameters

contextual boolean: true to lists contextual apps, false to list non-contextual apps; when not specified both types are listed. Default value is true.

type array of strings: Guids of app types to list. Can be used to return only conversations of a specified type. When not specied all types of apps are returned.

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 https://{WEAVY-SERVER}/api/apps?take=25
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

200 OK
401 Unauthorized

Response schema

{
  "data": [
    {
      "id": "integer",
      "type": "string",
      "uid": "string",
      "access": "string",
      "directory_id": "integer",
      "display_name": "string",
      "name": "string",
      "description": "string",
      "archive_url": "string",
      "avatar_url": "string",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "created_at": "string",
      "updated_at": "string",
      "is_trashed": "boolean",
      "is_starred": "boolean",
      "is_subscribed": "boolean",
      "permissions": [
        "string"
      ]
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Upsert member

Add or update an app member.

PUT /api/apps/{app}/members/{user}

Path parameters

app string required: App identifier (id or uid).

user string required: User identifier (id or uid).

Body parameters

access string

Optional access level for member. Defaults to write when not specified.

none = cannot access the app
read = can see the app and it's content but can cannot contribute
write = access to the app and is allowed to create content
admin = can manage the app, including deleting and managing members.

Example request

curl -X PUT https://{WEAVY_SERVER}/api/apps/acme-chat/members/acme-user
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
--json "{ 'access': 'read' }"

Response codes

200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
422 Validation Failed

List members

List users who are members of, or have access to, an app. Can also be used for finding users who are not members of an app.

GET /api/apps/{app}/members

Path parameters

app string required: App identifier (id or uid).

Query parameters

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

bot boolean: Should bot users be listed or not.

member boolean: When true (default), only app members are listed, false returns users that are not members, and null returns users with access to the app regardless if they are members or not.

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 https://{WEAVY-SERVER}/api/apps/acme-chat/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",
      "access": "string",
      "marked_at": "string",
      "marked_id": "integer",
      "presence": "string",
      "is_bot": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Remove member

Remove an app member.

DELETE /api/apps/{app}/members/{user}

Path parameters

app string required: App identifier (id or uid).

user string required: User identifier (id or uid).

Example request

curl -X DELETE https://{WEAVY_SERVER}/api/apps/acme-chat/members/bugs-bunny
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

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

Remove members

Remove multiple app members.

DELETE /api/apps/{app}/members

Path parameters

app string required: App identifier (id or uid).

Body parameters

array of strings required: User identifiers (id or uid) of members to remove.

Example request

curl -X DELETE https://{WEAVY_SERVER}/api/apps/acme-chat/members
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
--json "['bugs-bunny', 'daffy-duck']"

Response codes

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

Trash app

Move an app to the trash.

POST /api/apps/{app}/trash

Path parameters

app string required: App identifier (id or uid).

Example request

curl -X POST https://{WEAVY_SERVER}/api/apps/acme-chat/trash
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

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

Restore app

Restore an app from the trash.

POST /api/apps/{app}/restore

Path parameters

app string required: App identifier (id or uid).

Example request

curl -X POST https://{WEAVY_SERVER}/api/apps/acme-chat/restore
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

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

Delete app

Permanently deletes an app and all it's content.

DELETE /api/apps/{app}

Path parameters

app string required: App identifier (id or uid).

Example request

curl -X DELETE https://{WEAVY_SERVER}/api/apps/acme-chat
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Response codes

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