API reference | Workspace files

Method	Path	Summary
GET	…/files	List files attached to the workspace
GET	…/files/search	Search workspace files by attributes
POST	…/files/move	Move a workspace file to a different folder or location
GET	…/files/{fileId}/download	Generate a time-limited download URL for a workspace file

Paths start with /workspaces/{workspaceId}. GET endpoints need workspace-files:read, the others workspace-files:write.

The WorkspaceFile object

firestoreIdstringrequired

creationobjectrequired

When and by whom the resource was created.

Show 2 child fields

creationDateTimestringdate-timerequired

Date and time when the resource was created.

createdBystring

ID of the user who created the resource, when recorded.

workspaceIdstringrequired

ID of the workspace.

sizeintegerrequired

mimeTypestringrequired

filenamestringrequired

gcsPathstringrequired

Show all 14 fields

extensionstringrequired

checksumMd5string

checksumCrc32cstring

customMetadataRecord<string, string | boolean | number | null>required

scopestringrequired

Valuesworkspace_attachmentbank_account_attachmentbank_transaction_attachmentbank_transaction_importbank_transaction_exportdraft_payment_attachmentinitiated_payment_attachmentinvoice_attachment

targetDocumentPathstring

targetDocumentIdstring

The WorkspaceFile object

{
  "firestoreId": "string",
  "creation": {
    "creationDateTime": "2026-03-02T09:15:00.000Z",
    "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
  },
  "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
  "size": 0,
  "mimeType": "string",
  "filename": "string",
  "gcsPath": "string",
  "extension": "string",
  "checksumMd5": "string",
  "checksumCrc32c": "string",
  "customMetadata": {
    "key": "string"
  },
  "scope": "workspace_attachment",
  "targetDocumentPath": "string",
  "targetDocumentId": "Hk2xNq8vR4tYw6ZbPj3c"
}

GET/workspaces/{workspaceId}/files

List files attached to the workspace

Scopeworkspace-files:read

Path parameters

workspaceIdstringrequired

ID of the workspace.

Query parameters

limitinteger

Maximum number of items to return, from 1 to 100. A missing, invalid or non-positive value falls back to 20, and a larger value to 100.

Default20

startAfterstring

Cursor of the page to return: the nextCursor of the previous page.

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

idsstring[]

Comma-separated IDs of the items to return, up to 30. When set, limit, startAfter and the filters are ignored.

Returns

200

List of items

dataWorkspaceFile[]required

Items of the page, in list order.

limitintegerrequired

Page size of the request, or the number of requested ids.

nextCursorstring

Cursor of the next page, to pass as startAfter. Absent when the page holds fewer items than limit; a full last page still has one, and the page it points to is empty.

curl 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files', {
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
  },
});
console.log(await response.json());

import os

import requests

response = requests.get(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.json())

{
  "data": [
    {
      "firestoreId": "string",
      "creation": {
        "creationDateTime": "2026-03-02T09:15:00.000Z",
        "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
      },
      "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
      "size": 0,
      "mimeType": "string",
      "filename": "string",
      "gcsPath": "string",
      "extension": "string",
      "checksumMd5": "string",
      "checksumCrc32c": "string",
      "customMetadata": {
        "key": "string"
      },
      "scope": "workspace_attachment",
      "targetDocumentPath": "string",
      "targetDocumentId": "Hk2xNq8vR4tYw6ZbPj3c"
    }
  ],
  "limit": 0,
  "nextCursor": "string"
}

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

GET/workspaces/{workspaceId}/files/search

Search workspace files by attributes

Scopeworkspace-files:read

Path parameters

workspaceIdstringrequired

ID of the workspace.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

querystringrequired

pageinteger

Default0

sizeinteger

Default20

Returns

200

Successful response

dataWorkspaceFile[]required

curl 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files/search?query=string' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files/search?query=string', {
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
  },
});
console.log(await response.json());

import os

import requests

response = requests.get(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files/search?query=string",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.json())

{
  "data": [
    {
      "firestoreId": "string",
      "creation": {
        "creationDateTime": "2026-03-02T09:15:00.000Z",
        "createdBy": "Xq3vT9mB2kLpR7sN4wYc8dZf1aHj"
      },
      "workspaceId": "Wk7fQ2xR9bLm4tZp8sNv",
      "size": 0,
      "mimeType": "string",
      "filename": "string",
      "gcsPath": "string",
      "extension": "string",
      "checksumMd5": "string",
      "checksumCrc32c": "string",
      "customMetadata": {
        "key": "string"
      },
      "scope": "workspace_attachment",
      "targetDocumentPath": "string",
      "targetDocumentId": "Hk2xNq8vR4tYw6ZbPj3c"
    }
  ]
}

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

POST/workspaces/{workspaceId}/files/move

Move a workspace file to a different folder or location

Scopeworkspace-files:write

Path parameters

workspaceIdstringrequired

ID of the workspace.

Request body

oldPathstringrequired

newPathstringrequired

Returns

204

No content

curl -X POST 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files/move' \
  -H "Authorization: Bearer $SWAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "oldPath": "string",
  "newPath": "string"
}'

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files/move', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "oldPath": "string",
    "newPath": "string"
  }),
});
console.log(response.status);

import os

import requests

response = requests.post(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files/move",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
    json={
        "oldPath": "string",
        "newPath": "string",
    },
)
print(response.status_code)

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

GET/workspaces/{workspaceId}/files/{fileId}/download

Generate a time-limited download URL for a workspace file

Scopeworkspace-files:read

Path parameters

workspaceIdstringrequired

ID of the workspace.

fileIdstringrequired

ID of the workspace file.

Query parameters

fieldsstring

Comma-separated property paths to include in the response, or in each item of a list. Use dots for nested paths.

Returns

200

Successful response

dataFileDownloadUrlrequired

Show 2 child fields

downloadUrlstringrequired

Time-limited URL to download the file.

expiresAtstringrequired

Instant after which downloadUrl stops working.

curl 'https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files/Fl1qS6hV3nTx8mPc5wZr/download' \
  -H "Authorization: Bearer $SWAY_API_KEY"

const response = await fetch('https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files/Fl1qS6hV3nTx8mPc5wZr/download', {
  headers: {
    Authorization: `Bearer ${process.env.SWAY_API_KEY}`,
  },
});
console.log(await response.json());

import os

import requests

response = requests.get(
    "https://api.business.swayapp.io/v1/workspaces/Wk7fQ2xR9bLm4tZp8sNv/files/Fl1qS6hV3nTx8mPc5wZr/download",
    headers={"Authorization": f"Bearer {os.environ['SWAY_API_KEY']}"},
)
print(response.json())

{
  "data": {
    "downloadUrl": "string",
    "expiresAt": "2026-03-02T09:30:00.000Z"
  }
}

{
  "error": {
    "code": "invalid-argument",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired credentials"
  }
}

{
  "error": {
    "code": "permission-denied",
    "message": "Missing required scope: invoices:read"
  }
}

{
  "error": {
    "code": "not-found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "internal",
    "message": "An internal error occurred"
  }
}

Cookies, with your consent

Workspace files

The WorkspaceFile object

List files attached to the workspace

Path parameters

Query parameters

Returns

Search workspace files by attributes

Path parameters

Query parameters

Returns

Move a workspace file to a different folder or location

Path parameters

Request body

Returns

Generate a time-limited download URL for a workspace file

Path parameters

Query parameters

Returns

Start building on your own data.