1. Reference
  2. Web API
  3. Files

Files

The Files API has methods for managing files.

Create a file (files app)

Creates a new file in the specified Files app.

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

App id

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

Response codes

200 Success

{
  "id": "integer",
  "app_id": "integer",
  "version": "integer",
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "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",
  "modified_at": "string",
  "modified_by_id": "integer",
  "comment_count": "integer",
  "comments": [
    "object"
  ],
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

201 Created

{
  "id": "integer",
  "app_id": "integer",
  "version": "integer",
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "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",
  "modified_at": "string",
  "modified_by_id": "integer",
  "comment_count": "integer",
  "comments": [
    "object"
  ],
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

400 Bad Request

404 Not Found

409 Conflict

Code sample
curl https://{WEAVY-SERVER}/api/apps/1/files
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
-H "Content-Type: application/json"
-d "{ 'blob_id': 1 }"

List files (files app)

List files in the specified Files app.

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

App id.

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 0 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 boolean

false to skip counting the total number of matching items; default is true.

count_only boolean

true to only return the number of matching items; when this is specified the response will only contain the count property.

Response codes

200 Success

{
  "data": [
    "object"
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}
Code sample
curl https://{WEAVY-SERVER}/api/apps/1/files?top=30
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Get file metadata

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.

Response codes

200 Success

{
  "id": "integer",
  "app_id": "integer",
  "version": "integer",
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "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",
  "modified_at": "string",
  "modified_by_id": "integer",
  "comment_count": "integer",
  "comments": [
    "object"
  ],
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}
Code sample
curl https://{WEAVY-SERVER}/api/files/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Update file

Update a file.

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

Response codes

204 No Content

404 Not Found

400 Bad Request

Code sample
$ curl -X PATCH {WEAVY_SERVER}/api/files/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
-H "Content-Type: application/json"
-d "{ 'name': 'Updated file name' }"

Delete file

Delete a file.

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

Id of the file.

Response codes

204 No Content

Code sample
$ curl -X DELETE {WEAVY_SERVER}/api/files/1
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Get file version

Get specific version of a file.

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

File id.

version integer required

Version number.

Response codes

200 Success

{
  "id": "integer",
  "app_id": "integer",
  "version": "integer",
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "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",
  "modified_at": "string",
  "modified_by_id": "integer",
  "comment_count": "integer",
  "comments": [
    "object"
  ],
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}
Code sample
curl https://{WEAVY-SERVER}/api/files/1/versions/2
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Delete file version

Delete specific version of a file.

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

File id.

version integer required

Version number.

Response codes

204 No Content

Code sample
$ curl -X DELETE {WEAVY_SERVER}/api/files/1/versions/2
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

List file versions

List version history for the specified file.

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

File id.

Response codes

200 Success

[
  {
    "id": "integer",
    "app_id": "integer",
    "version": "integer",
    "name": "string",
    "kind": "string",
    "media_type": "string",
    "width": "integer",
    "height": "integer",
    "size": "integer",
    "metadata": "object",
    "tags": [
      "string"
    ],
    "provider": "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",
    "modified_at": "string",
    "modified_by_id": "integer",
    "comment_count": "integer",
    "comments": [
      "object"
    ],
    "is_subscribed": "boolean",
    "is_trashed": "boolean"
  }
]

404 Not Found

Code sample
curl https://{WEAVY-SERVER}/api/files/1/versions
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Subscribe to file

Subscribe to notifications for activity on a file.

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

Id of the file.

Response codes

200 Success

{
  "id": "integer",
  "app_id": "integer",
  "version": "integer",
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "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",
  "modified_at": "string",
  "modified_by_id": "integer",
  "comment_count": "integer",
  "comments": [
    "object"
  ],
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}
Code sample
$ curl -X POST {WEAVY_SERVER}/api/files/1/subscribe
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Unsubscribe to file

Unsubscribe to notifications for activity on a file.

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

Id of the file.

Response codes

200 Success

{
  "id": "integer",
  "app_id": "integer",
  "version": "integer",
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "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",
  "modified_at": "string",
  "modified_by_id": "integer",
  "comment_count": "integer",
  "comments": [
    "object"
  ],
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}
Code sample
$ curl -X POST {WEAVY_SERVER}/api/files/1/unsubscribe
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Trash file

Move a file to the trash.

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

Id of the file to trash.

Response codes

200 Success

{
  "id": "integer",
  "app_id": "integer",
  "version": "integer",
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "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",
  "modified_at": "string",
  "modified_by_id": "integer",
  "comment_count": "integer",
  "comments": [
    "object"
  ],
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}

404 Not Found

400 Bad Request

Code sample
$ curl -X POST {WEAVY_SERVER}/api/files/1/trash
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Restore file

Restore a file from the trash.

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

Id of the file to restore.

Response codes

200 Success

{
  "id": "integer",
  "app_id": "integer",
  "version": "integer",
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "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",
  "modified_at": "string",
  "modified_by_id": "integer",
  "comment_count": "integer",
  "comments": [
    "object"
  ],
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}
Code sample
$ curl -X POST {WEAVY_SERVER}/api/files/1/restore
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Restore file version

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

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

File id.

version integer required

Version number.

Response codes

200 Success

{
  "id": "integer",
  "app_id": "integer",
  "version": "integer",
  "name": "string",
  "kind": "string",
  "media_type": "string",
  "width": "integer",
  "height": "integer",
  "size": "integer",
  "metadata": "object",
  "tags": [
    "string"
  ],
  "provider": "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",
  "modified_at": "string",
  "modified_by_id": "integer",
  "comment_count": "integer",
  "comments": [
    "object"
  ],
  "is_subscribed": "boolean",
  "is_trashed": "boolean"
}
Code sample
$ curl -X POST {WEAVY_SERVER}/api/files/1/versions/2/restore
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

List files (comment)

List files attached to the specified comment.

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

Comment id.

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 0 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 boolean

false to skip counting the total number of matching items; default is true.

count_only boolean

true to only return the number of matching items; when this is specified the response will only contain the count property.

Response codes

200 Success

{
  "data": [
    "object"
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}
Code sample
curl https://{WEAVY-SERVER}/api/comments/1/attachments
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

List files (message)

List files attached to the specified message.

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

Message id.

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 0 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 boolean

false to skip counting the total number of matching items; default is true.

count_only boolean

true to only return the number of matching items; when this is specified the response will only contain the count property.

Response codes

200 Success

{
  "data": [
    "object"
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}
Code sample
curl https://{WEAVY-SERVER}/api/messages/1/attachments
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

List files (post)

List files attached to the specified post.

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

Post id.

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 0 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 boolean

false to skip counting the total number of matching items; default is true.

count_only boolean

true to only return the number of matching items; when this is specified the response will only contain the count property.

Response codes

200 Success

{
  "data": [
    "object"
  ],
  "start": "integer",
  "end": "integer",
  "count": "integer"
}
Code sample
curl https://{WEAVY-SERVER}/api/posts/1/attachments
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"
Weavy Docs