Documents · DocViewer API

{
  id: string
  user_id: string
  name: string
  pdf_url: string // Location of the converted/optimized PDF
  source_url: string // Location of the original document
  renders: [
    {
      id: string
      plugin: string // Which service was used to create this render.  Only pdfjs is currently supported.
      status: string // Can be: pending, done, error, deleted
      started_at: string // ISO format - Example: '2018-02-06T20:59:31.528Z'
      created_at: number
    }
  ]
  created_at: string // ISO format - Example: '2018-02-06T20:59:31.528Z'
  events: [] // Only used by the Admin Panel
  panda_push: {} // Only used by the Admin Panel
}

Create a Document
Download a Document
Get all Documents
Get a Document
Update a Document
Rotate a Document Page
Remove a Document Record
Remove Document Files
Single Re-render
Batch Re-render
Reload Crocodoc Annotations

Intro

DocViewer keeps a Document record for every document that is converted or rendered. The Document record is simply a listing of information about the document, with an ID and a URL for accessing the file itself. In order to view a file in DocViewer, the client must first Create a Document, then Create a Session, and then Download the PDF. The other endpoints listed below are used primarily by the Admin Panel.

Create a Document

POST /1/documents

Creates a Document Record in DocViewer and starts document conversion. This is the first step of viewing a document in DocViewer. This endpoint returns before the document finishes conversion; status will be queued.

Parameters

This endpoint requires authorization

Headers:

Content-Type: application/json
Authorization: Token KEY_HERE

Body:

{
  url: string
  name: string
  preferred_plugin: string
  region: string // The AWS region the call is originating from.  Used in conjunction with Canvas to identify records that are in different Canvas and DocViewer regions.
}

Responses

200

Returns a Document Object

Example Call

POST http://canvadocs.docker/1/documents

Content-Type: application/json
Authorization: Token apikey

{
  "name": "pdf.pdf",
  "preferred_plugin": "pdfjs",
  "url": "http://www.pdf995.com/samples/pdf.pdf",
  "region": "us-east-1"
}


200 OK
{
  "type": "document",
  "id": "ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ",
  "name": "pdf.pdf",
  "source_url": "http://www.pdf995.com/samples/pdf.pdf",
  "created_at": "2018-04-11T19:23:25.000Z",
  "renders": [
    {
      "plugin": "pdfjs",
      "status": "queued",
      "started_at": "2018-04-11T19:23:25.090Z",
      "created_at": 1523474605
    }
  ]
}

Download a Document

GET /1/sessions/{session_id}/file/{filename}

Downloads the converted PDF specified by the session_id jwt and the filename (the name property on the Document Object). This endpoint requires that the client first launch a session. This is used by clients (including the DocViewer Client) to get the PDF and display it to the user.

Parameters

Query:

session_id: string
filename: string // The name of the file to download, as specified in the Document Object

Responses

200

Returns the converted .pdf file

Example Call

GET http://canvadocs.docker/1/sessions/eyJhbGciOiJI.../file/file.pdf

200 OK
// The .pdf file was then downloaded

Get all Documents

GET /1/documents

Returns a list of documents in the current environment. The list is paginated. This endpoint is used by the Admin Panel to display the list of recent documents.

Parameters

This endpoint requires authorization

Headers:

Authorization: Token KEY_HERE

Responses

200

Returns an array of Document Objects

{
  "document_collection": {
    "entries": [
      Document Object
    ]
  },
  "startKey": string,
  "documentCount": number
}

Example Call

GET http://canvadocs.docker/1/documents

Authorization: Token apikey


200 OK
{
  "document_collection": {
    "entries": [
      {
        "renders": [
          {
            "started_at": "2018-04-10T19:17:46.476Z",
            "created_at": 1523387866,
            "id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_-pdfjs",
            "plugin": "pdfjs",
            "status": "done"
          }
        ],
        "user_id": "dev",
        "name": "pdf.pdf",
        "created_at": 1523387866,
        "pdf_url": "s3://canvadocs-assets/e6EUKt08fSxUOtML-rfI4EgPifNjw_/file.pdf",
        "id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_",
        "source_url": "http://www.pdf995.com/samples/pdf.pdf"
      },
      ...
    ]
  },
  "startKey": "{\"user_id\":\"dev\",\"created_at\":1522358228,\"id\":\"kF52gK9ch5tuaGTEc77eJ7YaGfH3Cr\"}",
  "documentCount": 222
}

Get a Document

GET /1/documents/{document_id}

Returns information about a single document. This endpoint is used by the Admin Panel to generate a document's info page.

Parameters

This endpoint requires authorization

Headers:

Authorization: Token KEY_HERE

Query:

document_id: string

Responses

200

Returns a Document Object

Example Call

GET http://canvadocs.docker/1/documents/e6EUKt08fSxUOtML-rfI4EgPifNjw_

Authorization: Token apikey


200 OK
{
  "type": "document",
  "id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_",
  "name": "pdf.pdf",
  "source_url": "http://www.pdf995.com/samples/pdf.pdf",
  "pdf_url": "s3://canvadocs-assets/e6EUKt08fSxUOtML-rfI4EgPifNjw_/file.pdf",
  "created_at": "2018-04-10T19:17:46.000Z",
  "renders": [
    {
      "started_at": "2018-04-10T19:17:46.476Z",
      "created_at": 1523387866,
      "id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_-pdfjs",
      "plugin": "pdfjs",
      "status": "done"
    }
  ],
  "events": [...],
  "panda_push": {...}
}

Update a Document

PUT /1/documents/{document_id}

Updates the information on a Document Record. Used by the Admin Panel to update a document's source URL.

Parameters

This endpoint requires authorization

Headers:

Content-Type: application/json
Authorization: Token KEY_HERE

Query:

document_id: string

Body:

Requires all or part of a Document Object

Responses

200

Returns a Document Object

Example Call

PUT http://canvadocs.docker/1/documents/e6EUKt08fSxUOtML-rfI4EgPifNjw_

Content-Type: application/json
Authorization: Token apikey

{ "source_url": "s3://canvadocs-assets/Kyox5NbveINdJ9mXv26lxrD_Ph1W7W/uploadedOriginal" }


200 OK
{
  "renders": [
    {
      "started_at": "2018-04-10T19:17:46.476Z",
      "created_at": 1523387866,
      "id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_-pdfjs",
      "plugin": "pdfjs",
      "status": "done"
    }
  ],
  "user_id": "dev",
  "name": "pdf.pdf",
  "created_at": 1523387866,
  "pdf_url": "s3://canvadocs-assets/e6EUKt08fSxUOtML-rfI4EgPifNjw_/file.pdf",
  "id": "e6EUKt08fSxUOtML-rfI4EgPifNjw_",
  "source_url": "s3://canvadocs-assets/Kyox5NbveINdJ9mXv26lxrD_Ph1W7W/uploadedOriginal"
}

Rotate a Document Page

PUT /1/sessions/{session_id}/documents/{document_id}/rotate

Saves a rotation on the document record. Acceptable rotation degrees are: 0, 90, 180, 270.

Parameters

Query:

pageNumber: number
rotationDegrees: number

Responses

200

Returns a Document Object

403

{
  "error": "cannot rotate the page because the page contains annotations"
}

Example Call

PUT http://canvadocs.docker/1/sessions/eyJhb.../documents/e6EUKt08fSxUOtML-rfI4EgPifNjw_/rotate

Content-Type: application/json

200 OK
{
  "pageNumber": 0,
  "rotationDegrees": 90
}

Remove a Document Record

DELETE /1/documents/{document_id}

Deletes the document record. Does not remove any of the actual files.

Parameters

This endpoint requires authorization

Headers:

Authorization: Token KEY_HERE

Query:

document_id: string

Responses

204

Example Call

PUT http://canvadocs.docker/1/documents/e6EUKt08fSxUOtML-rfI4EgPifNjw_

Authorization: Token apikey

204 No Content

Remove Document Files

DELETE /1/documents/{document_id}/s3

Deletes the converted PDF file, and marks the document record as deleted. Used by the Admin Panel when deleting documents.

Parameters

This endpoint requires authorization

Headers:

Authorization: Token KEY_HERE

Query:

document_id: string

Responses

204

Example Call

PUT http://canvadocs.docker/1/documents/e6EUKt08fSxUOtML-rfI4EgPifNjw_/s3

Authorization: Token apikey

204 No Content

Single Re-render

POST /1/documents/{document_id}/retry?plugin={plugin}

Starts the rendering process for a single document. Used by the Admin Panel for re-rendering documents.

Parameters

This endpoint requires authorization

Headers:

Content-Type: application/json
Authorization: Token KEY_HERE

Query:

document_id: string
plugin: string // The only supported value is "pdfjs"

Responses

202

Returns a Document Object

Example Call

POST http://canvadocs.docker/1/documents/RiTsY3DfuJiehyjdvYSkeXEuHyl3M6/retry?plugin=pdfjs

Content-Type: application/json
Authorization: Token apikey

202 Accepted
{
    "type": "document",
    "id": "RiTsY3DfuJiehyjdvYSkeXEuHyl3M6",
    "name": "pdf.pdf",
    "source_url": "s3://canvadocs-assets/RiTsY3DfuJiehyjdvYSkeXEuHyl3M6/uploadedOriginal",
    "pdf_url": "s3://canvadocs-assets/RiTsY3DfuJiehyjdvYSkeXEuHyl3M6/file.pdf",
    "created_at": "2018-04-11T20:11:39.000Z",
    "renders": [
        {
            "plugin": "pdfjs",
            "status": "queued",
            "started_at": "2018-04-11T20:14:59.312Z"
        }
    ]
}

Batch Re-render

POST /1/render_documents

Starts the rendering process for several documents. Useful when needing to re-render an entire assignment worth of documents. See the Re-rendering Canvas Files page for details on gathering the information needed for this call.

Parameters

This endpoint requires authorization

Headers:

Content-Type: application/json
Authorization: Token KEY_HERE

Body:

;[
  {
    document_id: string
  }
]

Responses

202

;[
  {
    document_id: string,
    status: string // should be "queued"
  }
]

Example Call

POST http://canvadocs.docker/1/render_documents

Content-Type: application/json
Authorization: Token apikey

[
  { "document_id":"RiTsY3DfuJiehyjdvYSkeXEuHyl3M6" },
  { "document_id":"ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ" }
]

202 Accepted
[
    {
        "document_id": "RiTsY3DfuJiehyjdvYSkeXEuHyl3M6",
        "status": "queued"
    },
    {
        "document_id": "ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ",
        "status": "queued"
    }
]

Reload Crocodoc Annotations

POST /1/documents/{document_id/reloadCrocAnnotations}

At some time in the distant past, DocViewer used a Crocodoc client rather than the DocViewer Client. Annotations were saved by Crocodoc in a different format. When we switched over to the DocViewer Client we started converting Crocodoc annotations to DocViewer annotations, on demand. If for some reason the conversion did not work well, this endpoint can be used to re-run the conversion. The Admin Panel has an option for this.

Parameters

This endpoint requires authorization

Headers:

Content-Type: application/json
Authorization: Token KEY_HERE

Query:

document_id: string
plugin: string // The only supported value is "pdfjs"

Responses

200

Example Call

POST http://canvadocs.docker/1/documents/ffRrKECYxXyHvpJMPLPfUKdcL3fsEQ/reloadCrocAnnotations

Authorization: Token apikey

200 OK
"No Crocodoc data exists for this document"