Back to DropboxPaper - Docs - List
Return the list of all Paper docs according to the argument specifications. To iterate over through the full pagination, pass the cursor to :route:docs/list/continue
.
Input
type: object
properties:
data:
type: object
description: >
filter_by: Allows user to specify how the Paper docs should be filtered.
sort_by: Allows user to specify how the Paper docs should be sorted.
sort_order: Allows user to specify the sort order of the result.
limit: Size limit per batch. The maximum number of docs that can be
retrieved per batch is 1000. Higher value results in invalid arguments
error.
properties:
sort_by:
type: object
description: |
accessed: Sorts the Paper docs by the time they were last accessed.
modified: Sorts the Paper docs by the time they were last modified.
created: Sorts the Paper docs by the creation time.
other: None
properties:
.tag:
title: Choice of ListPaperDocsSortBy
type: string
enum:
- accessed
- modified
- created
- other
sort_order:
type: object
description: |
ascending: Sorts the search result in ascending order.
descending: Sorts the search result in descending order.
other: None
properties:
.tag:
title: Choice of ListPaperDocsSortOrder
type: string
enum:
- ascending
- descending
- other
limit:
type: number
description: >-
Size limit per batch. The maximum number of docs that can be retrieved
per batch is 1000. Higher value results in invalid arguments error.
filter_by:
type: object
description: >
docs_accessed: Fetches all Paper doc IDs that the user has ever
accessed.
docs_created: Fetches only the Paper doc IDs that the user has
created.
other: None
properties:
.tag:
title: Choice of ListPaperDocsFilterBy
type: string
enum:
- docs_accessed
- docs_created
- other
title: Data
Output
type: object
description: >
doc_ids: The list of Paper doc IDs that can be used to access the given Paper
docs or supplied to other API methods. The list is sorted in the order
specified by the initial call to :route:`docs/list`.
cursor: Pass the cursor into :route:`docs/list/continue` to paginate through
all files. The cursor preserves all properties as specified in the original
call to :route:`docs/list`.
has_more: Will be set to True if a subsequent call with the provided cursor to
:route:`docs/list/continue` returns immediately with some results. If set to
False please allow some delay before making another call to
:route:`docs/list/continue`.
properties:
cursor:
type: object
description: >
value: The actual cursor value.
expiration: Expiration time of :field:`value`.
Some cursors might have expiration time assigned. This is a UTC value
after which the cursor is no longer valid and the API starts returning an
error. If cursor expires a new one needs to be obtained and pagination
needs to be restarted. Some cursors might be short-lived some cursors
might be long-lived.
This really depends on the sorting type and order, e.g.:
1. on one hand, listing docs created by the user, sorted by the created
time ascending will have undefinite expiration because the results cannot
change while the iteration is happening. This cursor would be suitable for
long term polling.
2. on the other hand, listing docs sorted by the last modified time will
have a very short expiration as docs do get modified very often and the
modified time can be changed while the iteration is happening thus
altering the results.
properties:
expiration:
type: string
description: >-
Expiration time of :field:`value`.
Some cursors might have expiration time assigned. This is a UTC value
after which the cursor is no longer valid and the API starts returning
an error. If cursor expires a new one needs to be obtained and
pagination needs to be restarted. Some cursors might be short-lived
some cursors might be long-lived.
This really depends on the sorting type and order, e.g.:
1. on one hand, listing docs created by the user, sorted by the
created time ascending will have undefinite expiration because the
results cannot change while the iteration is happening. This cursor
would be suitable for long term polling.
2. on the other hand, listing docs sorted by the last modified time
will have a very short expiration as docs do get modified very often
and the modified time can be changed while the iteration is happening
thus altering the results.
value:
type: string
description: The actual cursor value.
has_more:
type: boolean
description: >-
Will be set to True if a subsequent call with the provided cursor to
:route:`docs/list/continue` returns immediately with some results. If set
to False please allow some delay before making another call to
:route:`docs/list/continue`.
doc_ids:
type: array
description: >-
The list of Paper doc IDs that can be used to access the given Paper docs
or supplied to other API methods. The list is sorted in the order
specified by the initial call to :route:`docs/list`.
items:
type: string