Download a single annotated submission with the API?

fayshaw

I am trying to download a single submission that has been annotated by a grader using the API. Does anyone know how to do this? I am using Python using the canvasapi and requests libraries to query the preview_url in the submission attachments.

import requests
from urllib.parse import urljoin

preview_url = submission.attachments[0].preview_url
url = urljoin(API_URL, preview_url)

# Set the request 
headers = {"Authorization": f"Bearer {API_TOKEN}"}

response = requests.get(url, headers=headers)

The response is html. In the html there is a sessionData dictionary with an attribute "annotated_pdf_download" that has the format "/1/sessions/...abc123 .../view/annotated.pdf"

Anyone know how to extract the direct link? I am also open to trying Postman, curl, and other ways.

Jeff_F

@fayshaw - I have built some interesting capabilities using Canvas Data, but I have not yet worked through extracting annotated markup from student submissions via the API. That is beyond my current API expertise, and I suspect most of us are not operating at that depth either. With that in mind, it may be worth using a GenAI tool to help reason through the problem. As one example, below is what Copilot surfaced when evaluating this question.

I hope this is useful,

Best, Jeff

——

Yes. The short version is that Canvas is redirecting you from the Canvas preview_url into a DocViewer session, and the annotated PDF download is handled by the DocViewer service using that session id. Your current approach returns HTML because you are landing on the DocViewer page, not requesting the actual annotated PDF file. [community....ucture.com]

What to do instead (the documented working pattern)

A long standing solution from the Canvas community is:

1. Call the preview_url, but do not automatically follow redirects. You need the Location header from the redirect response. [community....vaslms.com], [community....vaslms.com]
2. Take that redirect location URL, and replace the end of it from .../view?theme=dark (or similar) to .../annotated.pdf. [community....vaslms.com], [community....vaslms.com]
3. Then POST to .../annotated.pdf (no payload required) to initiate the merge process that produces the annotated PDF. [community....vaslms.com], [community....vaslms.com]

That community answer specifically notes POSTing to annotated.pdf and that no payload is needed. [community....vaslms.com], [community....vaslms.com]

Why POST matters

DocViewer has an annotation merging service behind the scenes. The DocViewer API describes a flow where a client initiates merging with:

• POST /1/sessions/{session_id}/annotated.pdf to start the merge [canvadocs-...udgate.net]

Then you can poll readiness:

• GET /1/sessions/{session_id}/annotated.pdf/is_ready to check whether the merge is complete [canvadocs-...udgate.net]

And finally download:

• GET /1/sessions/{session_id}/annotated.pdf to retrieve the merged annotated PDF [canvadocs-...udgate.net]

So, if you POST and immediately GET, you may occasionally race the merge. The DocViewer API explicitly documents the readiness check. [canvadocs-...udgate.net]

What this looks like in Python (requests)

Below is a concrete example that follows the patterns above. This is my implementation suggestion based on the documented endpoints and the community solution.

import timeimport requests
headers = {"Authorization": f"Bearer {API_TOKEN}"}
# 1) Hit preview_url but do not follow redirectr = requests.get(url, headers=headers, allow_redirects=False)
# Canvas should return a 302 with Location pointing to the docviewer session URLdocviewer_location = r.headers["Location"]
# 2) Convert that location to the annotated PDF endpoint# The community solution describes replacing the end of the location URL with annotated.pdf# Example: .../view?theme=dark  ->  .../annotated.pdfannotated_url = docviewer_location.replace("/view?theme=dark", "/annotated.pdf").replace("/view", "/annotated.pdf")
# 3) Initiate merge (POST)requests.post(annotated_url, headers=headers)
# 4) Optionally poll readinessready_url = annotated_url + "/is_ready"for _ in range(30):    chk = requests.get(ready_url, headers=headers)    if chk.status_code == 200 and chk.json().get("ready") is True:        break    time.sleep(1)
# 5) Download annotated PDF (GET)pdf = requests.get(annotated_url, headers=headers)pdf.raise_for_status()
with open("annotated.pdf", "wb") as f:    f.write(pdf.content)

What is explicitly supported by sources here:

• Replace the redirect location ending and POST to annotated.pdf with no payload. [community....vaslms.com], [community....vaslms.com]
• DocViewer API endpoints for initiating merge, readiness, and download. [canvadocs-...udgate.net]

Important practical notes

• Your bearer token header may not be the auth mechanism used by the DocViewer host in all configurations. In many cases it works because the DocViewer session URL is already authorized by the redirect, but if you get 401/403, you may need to preserve cookies from the initial request and reuse the same requests.Session(). This is a practical troubleshooting tip, not something explicitly stated in the sources.
• The HTML you saw containing sessionData and annotated_pdf_download matches the idea that the DocViewer page is providing a path like /1/sessions/.../view/annotated.pdf. That is consistent with the DocViewer API shape and the community solution. [canvadocs-...udgate.net]

If you paste the exact redirect Location value you see (redacting the session token), I can show you exactly what the transformed annotated URL should look like for your instance.