Reference
Web API
Apps

Apps

The Apps API has methods for creating, and managing apps. Each app has a type which controls its functionality. In API responses, app types are always identified with their guid, but in requests (for instance when creating apps) you can also specify their type name.

`name`	`guid`
`agent_chat`	`2352a1c6-abc6-420e-8b85-ca7d5aed8779`
`chat`	`d65dd4bc-418e-403c-9f56-f9cf4da931ed`
`chat_room`	`edb400ac-839b-45a7-b2a8-6a01820d1c44`
`comments`	`88f96a08-c6c1-4eac-a0bd-5bf8fba1a3fd`
`files`	`523edd88-4bbf-4547-b60f-2859a6d2ddc1`
`posts`	`5ebfa152-de85-48da-82dd-30a1b560c313`
`private_chat`	`7e14f418-8f15-46f4-b182-f619b671e470`

Create app

Create app of specified type.

POST /api/apps

Body parameters

type string required: Type of app (name or guid).

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

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.

members array of strings: User identifiers (id or uid) of users to set as members when creating the app.

access string

Default access level for users that are not members. Defaults to none.

none = only members can access the app
read = authenticated users can see the app and it's content but only members can contribute
write = authenticated users 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.

Example request

curl {WEAVY-URL}/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",
  "rev": "integer",
  "type": "string",
  "uid": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "last_message": {
    "id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "is_starred": "boolean",
    "is_subscribed": "boolean",
    "is_trashed": "boolean",
    "created_at": "string",
    "updated_at": "string"
  },
  "metadata": "object",
  "tags": [
    "string"
  ],
  "access": "string",
  "directory_id": "integer",
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "created_at": "string",
  "updated_at": "string",
  "is_pinned": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_unread": "boolean",
  "permissions": [
    "string"
  ]
}

Get app

Get details 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 (default is false).

Example request

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

Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema

{
  "id": "integer",
  "rev": "integer",
  "type": "string",
  "uid": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "last_message": {
    "id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "is_starred": "boolean",
    "is_subscribed": "boolean",
    "is_trashed": "boolean",
    "created_at": "string",
    "updated_at": "string"
  },
  "metadata": "object",
  "tags": [
    "string"
  ],
  "access": "string",
  "directory_id": "integer",
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "created_at": "string",
  "updated_at": "string",
  "is_pinned": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_unread": "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).

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.

access string

Default access level for users that are not members. Defaults to none.

none = only members can access the app
read = authenticated users can see the app and it's content but only members can contribute
write = authenticated users 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.

Example request

curl -X PATCH {WEAVY-URL}/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",
  "rev": "integer",
  "type": "string",
  "uid": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "last_message": {
    "id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "is_starred": "boolean",
    "is_subscribed": "boolean",
    "is_trashed": "boolean",
    "created_at": "string",
    "updated_at": "string"
  },
  "metadata": "object",
  "tags": [
    "string"
  ],
  "access": "string",
  "directory_id": "integer",
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "created_at": "string",
  "updated_at": "string",
  "is_pinned": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_unread": "boolean",
  "permissions": [
    "string"
  ]
}

Upsert app

Update or insert app with specified uid and type. If a matching app exists, it is updated, otherwise it is created.

PUT /api/apps/{uid}

Path parameters

uid string required: Unique app identifier.

Body parameters

type string required: Type of app (name or guid).

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

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.

access string

Default access level for users that are not members. Defaults to none.

none = only members can access the app
read = authenticated users can see the app and it's content but only members can contribute
write = authenticated users 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.

Example request

curl -X PUT {WEAVY-URL}/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",
  "rev": "integer",
  "type": "string",
  "uid": "string",
  "name": "string",
  "description": "string",
  "archive_url": "string",
  "avatar_url": "string",
  "picture": {
    "id": "integer",
    "name": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "thumbnail_url": "string",
    "raw": "string"
  },
  "last_message": {
    "id": "integer",
    "text": "string",
    "html": "string",
    "plain": "string",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "is_starred": "boolean",
    "is_subscribed": "boolean",
    "is_trashed": "boolean",
    "created_at": "string",
    "updated_at": "string"
  },
  "metadata": "object",
  "tags": [
    "string"
  ],
  "access": "string",
  "directory_id": "integer",
  "members": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "created_at": "string",
  "updated_at": "string",
  "is_pinned": "boolean",
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean",
  "is_unread": "boolean",
  "permissions": [
    "string"
  ]
}

Upsert member

Add or update app membership for the specified user.

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

Path parameters

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

user string required: User identifier (id or uid) of member to add.

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

Upsert members

Add or update app membership for multiple users.

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 {WEAVY-URL}/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 matching the query parameters.

GET /api/apps

Query parameters

archived boolean: true lists archived apps, false lists unarchived apps. When unspecified apps are listed regardless of their archived status.

member string: User identifier (id or uid). Used to list apps where specified user is member.

type array of strings: Can be used to list apps of a specified type (name or guid). When unspecifed all types of apps are listed.

uid boolean: true lists apps with a uid, false lists apps without uid. By default apps are listed whether they have a uid or not.

unread boolean: true lists apps with unread messages, false lists apps where all messages are read. When unspecified apps are listed whether they have unread messages or not.

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

Response codes

200 OK
401 Unauthorized

Response schema

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

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.

agent boolean: Should AI agents 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.

system boolean: Include system users in the result?

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/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",
      "name": "string",
      "avatar_url": "string",
      "access": "string",
      "marked_at": "string",
      "marked_id": "integer",
      "presence": "string",
      "comment": "string",
      "is_agent": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Remove app

Remove the authenticated user's copy of an app.

POST /api/apps/{app}/remove

Path parameters

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

Example request

curl -X POST {WEAVY-URL}/api/apps/acme-chat/remove
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

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

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) of member to remove.

Example request

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

Indicate typing

Indicate that the authenticated user is typing a message.

PUT /api/apps/{app}/typing

Path parameters

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

Example request

curl -X PUT {WEAVY-URL}/api/app/acme-chat/typing
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

Set marker

Sets the read marker for the authenticated user, i.e mark app as read.

PUT /api/apps/{app}/mark

Path parameters

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

Query parameters

message_id integer: Optional id of last seen message. When not specified the read marker is moved to the last message, marking the entire app as read.

Example request

curl -X PUT {WEAVY-URL}/api/apps/acme-chat/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

Remove marker

Removes the read marker for the authenticated user, i.e mark the app as unread.

DELETE /api/apps/{app}/mark

Path parameters

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

Example request

curl -X DELETE {WEAVY-URL}/api/apps/acme-chat/mark
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

Archive app

Mark app as archived by the authenticated user.

PUT /api/apps/{app}/archive

Path parameters

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

Example request

curl -X PUT {WEAVY-URL}/api/apps/acme-chat/archive
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

Pin app

Mark app as pinned by the authenticated user.

PUT /api/apps/{app}/pin

Path parameters

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

Example request

curl -X PUT {WEAVY-URL}/api/apps/acme-chat/pin
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

Unarchive app

Mark app as unarchived by the authenticated user.

DELETE /api/apps/{app}/archive

Path parameters

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

Example request

curl -X DELETE {WEAVY-URL}/api/apps/acme-chat/archive
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
404 Not Found

Unpin app

Remove pin for the authenticated user.

DELETE /api/apps/{app}/pin

Path parameters

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

Example request

curl -X DELETE {WEAVY-URL}/api/apps/acme-chat/pin
-H "Authorization: Bearer {ACCESS-TOKEN}"

Response codes

204 No Content
401 Unauthorized
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 {WEAVY-URL}/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 {WEAVY-URL}/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 delete 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 {WEAVY-URL}/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