List Files

GET 
/files

Retrieves a paginated list of all files uploaded by the client or user. From API client version 3.7.0 the list is paged with an opaque cursor and returns pagination { limit, has_more, next_cursor } without totals: pass next_cursor as cursor, with the same order_by and filters, until has_more is false. Sending page, an invalid cursor, or a cursor with a different order_by or filters returns a 400. Older API client versions page with page and get total_pages and total_results.

Request

Query Parameters

limit string

Default value: 50

GET /files parameter

page string

The page to return. Default 1. Only for API client versions below 3.7.0, which page with cursor instead and reject page.

cursor string

Requires API client version 3.7.0. The next_cursor of the previous page. Send the same order_by and filters as the request that returned it. Omit for the first page.

order_by string

Possible values: [desc, asc]

The files are ordered by creation date, newest first by default.

start_date date-time

Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?)?Z?$

The earliest creation date of the files to return.

end_date date-time

Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?)?Z?$

The latest creation date of the files to return.

mime_type string

Possible values: [application/pdf, image/png, image/jpg]

Filters the file list for the specific mimetype.

lookup_key string

The lookup key of the files to return

Responses

200

GET /files Successful response

application/json

Schema

Schema

version stringrequired

Possible values: [1.0]

The version of the response schema

result_type stringrequired

Possible values: [paginated_list]

A paginated list of the file resource.

resource_type stringrequired

Possible values: [file]

Data contains the file resource.

data object[]required
The resource data
Array [
id cuidrequired
The unique identifier of the file
resource_type stringrequired
Possible values: [file]
filename stringrequired
Possible values: non-empty
The complete filename including the file extension
mime_type stringrequired
Possible values: non-empty
The mime type of the file
url url
The signed read url of the file
metadata object
lookup_key stringrequired
A provided lookup key provided by you to help you identify the file.
created_at stringrequired
UTC datetime ISO string
updated_at stringrequired
UTC datetime ISO string
]
pagination object required

Contains the pagination meta data. From API client version 3.7.0 lists are paged with a cursor and have no totals.

oneOf

MOD1

limit int64required

Possible values: <= 9007199254740991

The maximum number of items per page

total_pages int64required

Possible values: <= 9007199254740991

The total number of pages

page int64required

Possible values: <= 9007199254740991

The current page number

total_results int64required

Possible values: <= 9007199254740991

The total number of results

MOD2

limit int64required

Possible values: <= 9007199254740991

The requested limit, or the number of items on this page when it is non-empty and holds fewer items than requested

has_more booleanrequired

Whether there are more items after this page

next_cursor stringnullablerequired

Pass as cursor, with the same order_by and filters, to get the next page. Null when there are no more items.

Example (from schema)

{
  "version": "1.0",
  "result_type": "paginated_list",
  "resource_type": "file",
  "data": [
    {
      "id": "cnmrjiuebamsmek40myexample",
      "resource_type": "file",
      "filename": "my-file.pdf",
      "mime_type": "application/pdf",
      "url": "https://zigned.se",
      "metadata": {
        "lookup_key": "file_tag"
      },
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {}
}

400

GET /files Error response

application/json

Schema

Schema

status stringrequired

Possible values: [error]

error objectrequired
type stringrequired
Possible values: [input_validation_error, bad_request, authorization_error, forbidden_error, not_found_error, conflict_error, internal_server_error]
input_validation_error (400): the request input is invalid. bad_request (400): the request cannot be processed. authorization_error (401): the access token is missing or invalid. forbidden_error (403): the client is not allowed to perform the request. not_found_error (404): the resource does not exist. conflict_error (409): a concurrent change made the request invalid, e.g. the agreement stopped being editable while the request was processed. Re-fetch the resource before retrying. internal_server_error (500): an unexpected error occurred.
code int64required
Possible values: >= 400 and <= 599
message stringrequired
request_id uuidrequired

Example (from schema)

{
  "status": "error",
  "error": {
    "type": "input_validation_error",
    "code": 0,
    "message": "string",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Loading...