Grist attachments API
Documents may include attached files. Data records can refer to these using a column of type `Attachments`.
OpenAPI Specification
openapi: 3.0.0
info:
description: 'An API for manipulating Grist sites, workspaces, and documents.
# Authentication
<SecurityDefinitions />
'
version: 1.0.1
title: Grist attachments API
servers:
- url: https://{gristhost}/api
variables:
subdomain:
description: The team name, or `docs` for personal areas
default: docs
security:
- ApiKey: []
tags:
- name: attachments
description: Documents may include attached files. Data records can refer to these using a column of type `Attachments`.
paths:
/docs/{docId}/attachments:
get:
operationId: listAttachments
tags:
- attachments
summary: List metadata of all attachments in a doc
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- $ref: '#/components/parameters/filterQueryParam'
- $ref: '#/components/parameters/sortQueryParam'
- $ref: '#/components/parameters/limitQueryParam'
- $ref: '#/components/parameters/sortHeaderParam'
- $ref: '#/components/parameters/limitHeaderParam'
responses:
200:
description: List of attachment metadata records. Note that the list may temporarily include records for attachments that are stored in the document but not referenced by any Attachments type cell.
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentMetadataList'
post:
operationId: uploadAttachments
tags:
- attachments
summary: Upload attachments to a doc
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
description: the files to add to the doc
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/AttachmentUpload'
required: true
responses:
200:
description: IDs of attachments added, one per file.
content:
application/json:
schema:
$ref: '#/components/schemas/RowIds'
/docs/{docId}/attachments/{attachmentId}:
get:
operationId: getAttachmentMetadata
tags:
- attachments
summary: Get the metadata for an attachment
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: path
name: attachmentId
schema:
$ref: '#/components/schemas/AttachmentId'
required: true
responses:
200:
description: Attachment metadata
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentMetadata'
/docs/{docId}/attachments/{attachmentId}/download:
get:
operationId: downloadAttachment
tags:
- attachments
summary: Download the contents of an attachment
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: path
name: attachmentId
schema:
$ref: '#/components/schemas/AttachmentId'
required: true
responses:
200:
description: Attachment contents, with suitable Content-Type.
/docs/{docId}/attachments/archive:
get:
operationId: downloadAttachments
tags:
- attachments
summary: Download all attachments
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: format
schema:
type: string
enum:
- zip
- tar
responses:
200:
description: Archive of all attachments, in either .zip or .tar format.
post:
operationId: uploadMissingAttachments
tags:
- attachments
summary: Upload missing attachments
description: Restores attachments which are missing from external storage.
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
description: A .tar file downloaded from Grist, containing all the document's attachments.
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: The .tar file. Must have `Content-Type=application/x-tar` set.
responses:
200:
description: Summary of attachments used
content:
application/json:
schema:
type: object
properties:
added:
type: integer
description: Total files added to external storage.
errored:
type: integer
description: Total files that errored when attempting to process them.
unused:
type: integer
description: Total files that aren't needed, or don't match an existing attachment.
/docs/{docId}/attachments/store:
get:
operationId: getDocumentAttachmentStore
tags:
- attachments
summary: Get external store
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Document's current external storage setting
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentStoreSetting'
post:
operationId: setDocumentAttachmentStore
tags:
- attachments
summary: Set external store
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentStoreSetting'
responses:
200:
description: The ID of the store the document's store
content:
application/json:
schema:
type: object
properties:
store:
$ref: '#/components/schemas/DocumentStoreId'
/docs/{docId}/attachments/stores:
get:
operationId: listAttachmentStores
tags:
- attachments
summary: List external attachment stores
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Document's current external storage setting
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentStoreSetting'
/docs/{docId}/attachments/transferAll:
post:
operationId: startAttachmentTransfer
tags:
- attachments
summary: Start transferring attachments
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Transfer status
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentsTransferStatus'
/docs/{docId}/attachments/transferStatus:
get:
operationId: getAttachmentTransferStatus
tags:
- attachments
summary: Get attachment transfer status
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Transfer status
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentsTransferStatus'
/docs/{docId}/attachments/removeUnused:
post:
operationId: removeUnusedAttachments
tags:
- attachments
summary: Delete unused attachments from the document
description: 'When an uploaded attachment is no longer used in a Grist document, it''s retained for a period of time in case it''s needed again (e.g. to facilitate an "undo").
This removes all of these retained attachments, reducing the amount of storage used. This is particularly useful if a document has hit its attachment storage limit.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: expiredOnly
schema:
type: boolean
description: Only remove attachments that haven't been used for a period of time. This duration is set by host of the Grist instance.
responses:
200:
description: Success
/docs/{docId}/attachments/updateUsed:
post:
operationId: updateUsedAttachments
tags:
- attachments
summary: Update attachment usage tracking
description: 'Recalculate which attachments are in use by scanning the document.
This is mostly used for testing and maintenance.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Success
/docs/{docId}/attachments/verifyFiles:
post:
operationId: verifyAttachmentFiles
tags:
- attachments
summary: Verify attachment file integrity
description: 'Verify that attachment records match the actual stored files.
This is a maintenance endpoint to check for data consistency.
Only document owners can call this endpoint.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Verification passed
components:
parameters:
sortHeaderParam:
in: header
name: X-Sort
schema:
type: string
description: Same as `sort` query parameter.
example: pet,-age
required: false
docIdPathParam:
in: path
name: docId
schema:
type: string
description: A string id (UUID)
required: true
sortQueryParam:
in: query
name: sort
schema:
type: string
description: 'Order in which to return results. If a single column name is given (e.g. `pet`), results are placed in ascending order of values in that column. To get results in an order that was previously prepared manually in Grist, use the special `manualSort` column name. Multiple columns can be specified, separated by commas (e.g. `pet,age`). For descending order, prefix a column name with a `-` character (e.g. `pet,-age`). To include additional sorting options append them after a colon (e.g. `pet,-age:naturalSort;emptyLast,owner`). Available options are: `orderByChoice`, `naturalSort`, `emptyLast`. Without the `sort` parameter, the order of results is unspecified.'
example: pet,-age
required: false
filterQueryParam:
in: query
name: filter
schema:
type: string
description: 'This is a JSON object mapping column names to arrays of allowed values. For example, to filter column `pet` for values `cat` and `dog`, the filter would be `{"pet": ["cat", "dog"]}`. JSON contains characters that are not safe to place in a URL, so it is important to url-encode them. For this example, the url-encoding is `%7B%22pet%22%3A%20%5B%22cat%22%2C%20%22dog%22%5D%7D`. See https://rosettacode.org/wiki/URL_encoding for how to url-encode a string, or https://www.urlencoder.org/ to try some examples. Multiple columns can be filtered. For example the filter for `pet` being either `cat` or `dog`, AND `size` being either `tiny` or `outrageously small`, would be `{"pet": ["cat", "dog"], "size": ["tiny", "outrageously small"]}`.'
example: '{"pet": ["cat", "dog"]}'
required: false
limitQueryParam:
in: query
name: limit
schema:
type: number
description: Return at most this number of rows. A value of 0 is equivalent to having no limit.
example: '5'
required: false
limitHeaderParam:
in: header
name: X-Limit
schema:
type: number
description: Same as `limit` query parameter.
example: '5'
required: false
schemas:
DocumentStoreId:
type: string
nullable: true
example: 83395209-fc3b-4d02-8934-b2619efec712-filesystem
AttachmentUpload:
type: object
properties:
upload:
type: array
items:
type: string
format: binary
RowIds:
type: array
example:
- 101
- 102
- 103
items:
type: integer
DocumentAttachmentsLocation:
type: string
description: The current location of attachment files in the document
enum:
- none
- internal
- mixed
- external
example: mixed
AttachmentsTransferStatus:
type: object
properties:
status:
type: object
properties:
pendingTransferCount:
type: integer
description: Remaining transfers be performed
example: 19
isRunning:
type: boolean
description: Are files actively being transferred?
example: true
locationSummary:
$ref: '#/components/schemas/DocumentAttachmentsLocation'
AttachmentId:
type: number
description: An integer ID
DocumentStoreSetting:
type: object
properties:
type:
type: string
enum:
- external
- internal
AttachmentMetadataList:
type: object
required:
- records
properties:
records:
type: array
items:
type: object
required:
- id
- fields
properties:
id:
type: number
example: 1
fields:
$ref: '#/components/schemas/AttachmentMetadata'
AttachmentMetadata:
type: object
properties:
fileName:
type: string
example: logo.png
fileSize:
type: number
example: 12345
timeUploaded:
type: string
example: '2020-02-13T12:17:19.000Z'
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: 'Authorization: Bearer XXXXXXXXXXX'
description: Access to the Grist API is controlled by an Authorization header, which should contain the word 'Bearer', followed by a space, followed by your API key.