Skip to content
Sursa Developers

GET/v1/files/{file_id}/preview

Preview a file

preview_file

Preview without downloading. PDF: the file itself with Content-Disposition: inline (the browser's built-in viewer). XLSX and CSV: JSON with the first 50 rows of the first sheet (sheet selects another sheet of the workbook). DOCX: the first 3000 characters of text. Markdown: the text itself. Returns 410 if the file has expired.

Authentication

Send an API key in the Authorization header: Authorization: Bearer <key>.

Path parameters

  • file_idstringrequired

Query parameters

  • sheetstring | null

    Sheet of the XLSX workbook (the first sheet by default).

Header parameters

  • X-View-Asstring

    For API keys with the admin role only. Makes the request as the data profile <profile>[:viewer|verifier|editor], for example employee:viewer. The installation key cannot use this header (403).

Cookie parameters

  • kb_view_asstring

    Cookie of the “View as” mode for a session. POST /auth/view-as sets it and DELETE /auth/view-as clears it.

Responses

200A table or text (`FilePreview`) for XLSX, CSV, DOCX and MD; the file itself, `inline`, for PDF.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: FilePreview

One of

  • object
    • captionstring | null
    • columnsarray of stringrequired
    • kind"table"required
    • rowsarray of array of string | integer | booleanrequired
    • sheetstring | nullrequired
    • sheetsarray of stringrequired
    • total_rowsinteger | nullrequired
    • truncatedbooleanrequired
  • object
    • formatstringrequired

      Allowed values: plainmarkdown

    • kind"text"required
    • textstringrequired
    • truncatedbooleanrequired

application/pdf

string (binary)
401No credentials were sent (neither a session cookie nor an API key), or the key was not found.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

403The action is not allowed: the role is insufficient, there is no access to the collection or card, the request runs in “View as” mode, or the organization is suspended or deleted (`detail` is an object with `code: org_suspended | org_deleted`).

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

404The object does not exist or is not available to you. The API does not confirm that a restricted object exists.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

410The object existed but is no longer available: the link was used or has expired, or the file was deleted at the end of its retention period.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

422Validation error: the body or parameters do not match the schema (`detail` is a list of validation errors), or a parameter value is out of range (`detail` is a message).

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

429Too many requests (`api.rate_limited`), the organization's quota for the minute, day or month is used up (`api.quota_exceeded`; `error.details` holds `quota`, `limit` and `reset_at`), the organization's limit is reached, or the answer service is busy (`answers.engine_busy`). Wait for the time in the `Retry-After` header.

Response headers

  • Retry-After

    Number of seconds to wait before you retry the request.

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

Error codes

Codes this endpoint can return in error.code, besides the general codes of every request.

Rate limits

Responses carry the RateLimit and RateLimit-Policy headers and the earlier X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 response has Retry-After in seconds: wait and retry.

← files · API reference