1. Reference
  2. Web API
  3. Files

Files

The Files API has methods for managing files.

Create file

Creates a new file in the specified Files app.

POST /api/apps/{app}/files
Path parameters
app string required

App identifier (id or uid)

Body parameters
blob_id integer required

Id of blob containing content and metadata for the file.

name string

File name. When not specified the file will get the name of the underlying blob.

metadata object

Additional metadata properties, e.g. { "color": "blue", "size": "XL" }.

tags array of strings

A list of tags to associate with the file.

replace boolean

true to force an existing file with the same name to be overwritten (otherwise a 409 Conflict response will be produced).

Example request
curl {WEAVY-URL}/api/apps/acme-files/files
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
--json "{ 'blob_id': 1 }"
Response codes

200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
422 Validation Failed

Response schema
{
  "id": "integer",
  "rev": "integer",
  "app": {
    "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"
    ]
  },
  "parent": {
    "id": "integer",
    "type": "string"
  },
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "string",
  "raw": "string",
  "download_url": "string",
  "application_url": "string",
  "embed_url": "string",
  "external_url": "string",
  "preview_format": "string",
  "preview_url": "string",
  "thumbnail_url": "string",
  "created_at": "string",
  "created_by": {
    "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",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "updated_at": "string",
    "is_trashed": "boolean"
  },
  "updated_at": "string",
  "updated_by": {
    "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",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "updated_at": "string",
    "is_trashed": "boolean"
  },
  "comments": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

Get file

Get file metadata.

GET /api/files/{id}
Path parameters
id integer required

File id

Query parameters
trashed boolean

true to return file even if trashed.

Example request
curl {WEAVY-URL}/api/files/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema
{
  "id": "integer",
  "rev": "integer",
  "app": {
    "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"
    ]
  },
  "parent": {
    "id": "integer",
    "type": "string"
  },
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "string",
  "raw": "string",
  "download_url": "string",
  "application_url": "string",
  "embed_url": "string",
  "external_url": "string",
  "preview_format": "string",
  "preview_url": "string",
  "thumbnail_url": "string",
  "created_at": "string",
  "created_by": {
    "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",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "updated_at": "string",
    "is_trashed": "boolean"
  },
  "updated_at": "string",
  "updated_by": {
    "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",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "updated_at": "string",
    "is_trashed": "boolean"
  },
  "comments": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

Get file revision

Get file revision.

GET /api/files/{id}/versions/{rev}
Path parameters
id integer required

File id.

rev integer required

Revision number.

Example request
curl {WEAVY-URL}/api/files/1/versions/2
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema
{
  "id": "integer",
  "rev": "integer",
  "app": {
    "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"
    ]
  },
  "parent": {
    "id": "integer",
    "type": "string"
  },
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "string",
  "raw": "string",
  "download_url": "string",
  "application_url": "string",
  "embed_url": "string",
  "external_url": "string",
  "preview_format": "string",
  "preview_url": "string",
  "thumbnail_url": "string",
  "created_at": "string",
  "created_by": {
    "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",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "updated_at": "string",
    "is_trashed": "boolean"
  },
  "updated_at": "string",
  "updated_by": {
    "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",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "updated_at": "string",
    "is_trashed": "boolean"
  },
  "comments": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

List file revisions

List revision history of a file.

GET /api/files/{id}/versions
Path parameters
id integer required

File id.

Example request
curl {WEAVY-URL}/api/files/1/versions
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema
{
  "data": [
    {
      "id": "integer",
      "rev": "integer",
      "name": "string",
      "kind": "string",
      "media_type": "string",
      "width": "integer",
      "height": "integer",
      "size": "integer",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "provider": "string",
      "raw": "string",
      "download_url": "string",
      "application_url": "string",
      "embed_url": "string",
      "external_url": "string",
      "preview_format": "string",
      "preview_url": "string",
      "thumbnail_url": "string",
      "created_at": "string",
      "updated_at": "string",
      "is_starred": "boolean",
      "is_subscribed": "boolean",
      "is_trashed": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Update file

Update file metadata.

PATCH /api/files/{id}
Path parameters
id integer required

Id of file.

Body parameters
blob_id integer

Id of blob containing content and metadata for the file.

name string

The file name.

metadata object

Additional metadata properties, e.g. { "color": "blue", "size": "XL" }.

tags array of strings

A list of tags to associate with the file.

backup boolean

true to add previous version to version history, otherwise false (default).

Example request
curl -X PATCH {WEAVY-URL}/api/files/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
--json "{ 'name': 'filename.txt' }"
Response codes

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

Response schema
{
  "id": "integer",
  "rev": "integer",
  "app": {
    "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"
    ]
  },
  "parent": {
    "id": "integer",
    "type": "string"
  },
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "string",
  "raw": "string",
  "download_url": "string",
  "application_url": "string",
  "embed_url": "string",
  "external_url": "string",
  "preview_format": "string",
  "preview_url": "string",
  "thumbnail_url": "string",
  "created_at": "string",
  "created_by": {
    "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",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "updated_at": "string",
    "is_trashed": "boolean"
  },
  "updated_at": "string",
  "updated_by": {
    "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",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "created_at": "string",
    "updated_at": "string",
    "is_trashed": "boolean"
  },
  "comments": {
    "data": [
      "object"
    ],
    "start": "integer",
    "end": "integer",
    "count": "integer"
  },
  "is_starred": "boolean",
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

List files

List files.

GET /api/files
Query parameters
around integer

A file id. Used to find results "around" a specific file.

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/files
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

200 OK
401 Unauthorized

Response schema
{
  "data": [
    {
      "id": "integer",
      "rev": "integer",
      "name": "string",
      "kind": "string",
      "media_type": "string",
      "width": "integer",
      "height": "integer",
      "size": "integer",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "provider": "string",
      "raw": "string",
      "download_url": "string",
      "application_url": "string",
      "embed_url": "string",
      "external_url": "string",
      "preview_format": "string",
      "preview_url": "string",
      "thumbnail_url": "string",
      "created_at": "string",
      "updated_at": "string",
      "is_starred": "boolean",
      "is_subscribed": "boolean",
      "is_trashed": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

List app files

List files in the specified Files app.

GET /api/apps/{app}/files
Path parameters
app string required

App identifier (id or uid)

Query parameters
around integer

A file id. Used to find results "around" a specific file.

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

200 OK
401 Unauthorized
404 Not Found

Response schema
{
  "data": [
    {
      "id": "integer",
      "rev": "integer",
      "name": "string",
      "kind": "string",
      "media_type": "string",
      "width": "integer",
      "height": "integer",
      "size": "integer",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "provider": "string",
      "raw": "string",
      "download_url": "string",
      "application_url": "string",
      "embed_url": "string",
      "external_url": "string",
      "preview_format": "string",
      "preview_url": "string",
      "thumbnail_url": "string",
      "created_at": "string",
      "updated_at": "string",
      "is_starred": "boolean",
      "is_subscribed": "boolean",
      "is_trashed": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

List post attachments

List files attached to the specified post.

GET /api/posts/{id}/attachments
Path parameters
id integer required

Post id.

Query parameters
around integer

A file id. Used to find results "around" a specific file.

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/posts/1/attachments
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema
{
  "data": [
    {
      "id": "integer",
      "rev": "integer",
      "name": "string",
      "kind": "string",
      "media_type": "string",
      "width": "integer",
      "height": "integer",
      "size": "integer",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "provider": "string",
      "raw": "string",
      "download_url": "string",
      "application_url": "string",
      "embed_url": "string",
      "external_url": "string",
      "preview_format": "string",
      "preview_url": "string",
      "thumbnail_url": "string",
      "created_at": "string",
      "updated_at": "string",
      "is_starred": "boolean",
      "is_subscribed": "boolean",
      "is_trashed": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

List comment attachments

List files attached to the specified comment.

GET /api/comments/{id}/attachments
Path parameters
id integer required

Comment id.

Query parameters
around integer

A file id. Used to find results "around" a specific file.

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/comments/1/attachments
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema
{
  "data": [
    {
      "id": "integer",
      "rev": "integer",
      "name": "string",
      "kind": "string",
      "media_type": "string",
      "width": "integer",
      "height": "integer",
      "size": "integer",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "provider": "string",
      "raw": "string",
      "download_url": "string",
      "application_url": "string",
      "embed_url": "string",
      "external_url": "string",
      "preview_format": "string",
      "preview_url": "string",
      "thumbnail_url": "string",
      "created_at": "string",
      "updated_at": "string",
      "is_starred": "boolean",
      "is_subscribed": "boolean",
      "is_trashed": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

List message attachments

List files attached to the specified message.

GET /api/messages/{id}/attachments
Path parameters
id integer required

Message id.

Query parameters
around integer

A file id. Used to find results "around" a specific file.

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/messages/1/attachments
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

200 OK
401 Unauthorized
404 Not Found

Response schema
{
  "data": [
    {
      "id": "integer",
      "rev": "integer",
      "name": "string",
      "kind": "string",
      "media_type": "string",
      "width": "integer",
      "height": "integer",
      "size": "integer",
      "metadata": "object",
      "tags": [
        "string"
      ],
      "provider": "string",
      "raw": "string",
      "download_url": "string",
      "application_url": "string",
      "embed_url": "string",
      "external_url": "string",
      "preview_format": "string",
      "preview_url": "string",
      "thumbnail_url": "string",
      "created_at": "string",
      "updated_at": "string",
      "is_starred": "boolean",
      "is_subscribed": "boolean",
      "is_trashed": "boolean"
    }
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}

Trash file

Move a file to the trash.

POST /api/files/{id}/trash
Path parameters
id integer required

Id of the file to trash.

Example request
curl -X POST {WEAVY-URL}/api/files/1/trash
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

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

Restore file

Restore a file from the trash.

POST /api/files/{id}/restore
Path parameters
id integer required

Id of the file to restore.

Example request
curl -X POST {WEAVY-URL}/api/files/1/restore
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

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

Restore file version

Restore a previous revision of a file to be the current. This will create a new revision with the contents of the previous revision, but preserves all existing revisions.

POST /api/files/{id}/versions/{rev}/restore
Path parameters
id integer required

File id.

rev integer required

Revision number.

Example request
curl -X POST {WEAVY-URL}/api/files/1/versions/2/restore
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

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

Delete file

Delete a file.

DELETE /api/files/{id}
Path parameters
id integer required

Id of the file.

Example request
curl -X DELETE {WEAVY-URL}/api/files/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

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

Delete file revision

Delete file revision.

DELETE /api/files/{id}/versions/{rev}
Path parameters
id integer required

File id.

rev integer required

File revision.

Example request
curl -X DELETE {WEAVY-URL}/api/files/1/versions/2
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Response codes

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

Support
Book a demo

To access live chat with our developer success team you need a Weavy account.

Sign in or create a Weavy account