> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/developers/files-and-assets/comments.md).

# Comments

Read, add, reply to, resolve, and export comments on assets.

For video and audio, set `timestamp` (in seconds from the start) to pin a comment to a moment, and add `duration` to cover a range.

## Get all comments for an asset

> Get all comments for an asset

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"CommentDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Asset Id"},"content":{"type":"string","title":"Content"},"author":{"$ref":"#/components/schemas/UserDTOBase"},"created":{"type":"string","format":"date-time","title":"Created"},"updated":{"type":"string","format":"date-time","title":"Updated"},"resolved":{"type":"boolean","title":"Resolved"},"is_public":{"type":"boolean","title":"Is Public"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id"},"timestamp":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Timestamp"},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration"},"pdf_annotations":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationData"},{"type":"null"}]},"replies":{"items":{"$ref":"#/components/schemas/CommentDTO"},"type":"array","title":"Replies","default":[]},"mentions":{"items":{"$ref":"#/components/schemas/Mention"},"type":"array","title":"Mentions","default":[]},"reactions":{"items":{"$ref":"#/components/schemas/ReactionDTO"},"type":"array","title":"Reactions","default":[]},"anchor":{"anyOf":[{"$ref":"#/components/schemas/CommentAnchor"},{"type":"null"}]},"annotation":{"anyOf":[{"items":{"$ref":"#/components/schemas/CommentAnnotationPath"},"type":"array"},{"type":"null"}],"title":"Annotation"},"is_copied":{"type":"boolean","title":"Is Copied","default":false},"attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Attachments","default":[]}},"type":"object","required":["id","asset_id","content","author","created","updated","resolved","is_public","parent_id","timestamp","duration","anchor"],"title":"CommentDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"PdfAnnotationData":{"properties":{"page_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number"},"xfdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xfdf"},"annotation_type":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationType"},{"type":"null"}]},"selected_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Text"}},"type":"object","title":"PdfAnnotationData","description":"PDF annotation data for comments"},"PdfAnnotationType":{"type":"string","enum":["highlight","insert","remove","replace"],"title":"PdfAnnotationType"},"Mention":{"properties":{"user_id":{"type":"string","title":"User Id"},"text":{"type":"string","title":"Text"},"start_index":{"type":"integer","title":"Start Index"},"end_index":{"type":"integer","title":"End Index"},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Name","default":""}},"type":"object","required":["user_id","text","start_index","end_index"],"title":"Mention"},"ReactionDTO":{"properties":{"users":{"items":{"$ref":"#/components/schemas/UserDTOWithCommentId"},"type":"array","title":"Users"},"content":{"type":"string","title":"Content"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["users","content","count"],"title":"ReactionDTO"},"UserDTOWithCommentId":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"},"comment_id":{"type":"string","format":"uuid","title":"Comment Id"}},"type":"object","required":["id","name","email","avatar_url","user_type","comment_id"],"title":"UserDTOWithCommentId"},"CommentAnchor":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"}},"type":"object","required":["x","y"],"title":"CommentAnchor"},"CommentAnnotationPath":{"properties":{"tool":{"type":"string","title":"Tool"},"color":{"type":"string","title":"Color"},"size":{"type":"number","title":"Size"},"xs":{"items":{"type":"number"},"type":"array","title":"Xs"},"ys":{"items":{"type":"number"},"type":"array","title":"Ys"}},"type":"object","required":["tool","color","size","xs","ys"],"title":"CommentAnnotationPath","description":"A path in a comment annotation"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments":{"get":{"tags":["comments"],"summary":"Get all comments for an asset","description":"Get all comments for an asset","operationId":"getAssetComments","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"},{"name":"drive_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"}],"responses":{"200":{"description":"A list of all comments for the asset","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommentDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Add a comment to an asset

> Add a comment to an asset

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"AddAssetCommentRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"comment":{"type":"string","title":"Comment","description":"The comment to add to the asset"},"mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/Mention"},"type":"array"},{"type":"null"}],"title":"Mentions","description":"The mentions in the comment","default":[]},"timestamp":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Timestamp from start","description":"Seconds from the start of the video or audio to pin the comment to."},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration of the comment timestamp","description":"Length in seconds of the range the comment covers, starting at `timestamp`."},"is_public":{"type":"boolean","title":"Is Public Comment?","description":"Whether the comment is public or not","default":true},"url":{"type":"string","title":"Url of the comment","description":"Link to the comment, used in notification emails. Point it at the asset in the\nShade web app: `https://app.shade.inc/{workspace_domain}/a/{drive_identifier}/{asset_id}?commentId=REPLACE_COMMENT_ID_ON_SERVER`.\nShade replaces `REPLACE_COMMENT_ID_ON_SERVER` with the new comment's ID."},"anchor":{"anyOf":[{"$ref":"#/components/schemas/CommentAnchor"},{"type":"null"}],"title":"Anchor","description":"The anchor of the comment"},"annotation":{"anyOf":[{"items":{"$ref":"#/components/schemas/CommentAnnotationPath"},"type":"array"},{"type":"null"}],"title":"The annotation of the comment","description":"The annotation is a list of annotation paths"},"attachment_tokens":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Attachment tokens","description":"JWT tokens for attachments to link to this comment"},"pdf_annotations":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationData"},{"type":"null"}],"title":"PDF annotations","description":"PDF annotation data containing page_number, xfdf, annotation_type, selected_text"}},"type":"object","required":["comment","url"],"title":"AddAssetCommentRequest"},"Mention":{"properties":{"user_id":{"type":"string","title":"User Id"},"text":{"type":"string","title":"Text"},"start_index":{"type":"integer","title":"Start Index"},"end_index":{"type":"integer","title":"End Index"},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Name","default":""}},"type":"object","required":["user_id","text","start_index","end_index"],"title":"Mention"},"CommentAnchor":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"}},"type":"object","required":["x","y"],"title":"CommentAnchor"},"CommentAnnotationPath":{"properties":{"tool":{"type":"string","title":"Tool"},"color":{"type":"string","title":"Color"},"size":{"type":"number","title":"Size"},"xs":{"items":{"type":"number"},"type":"array","title":"Xs"},"ys":{"items":{"type":"number"},"type":"array","title":"Ys"}},"type":"object","required":["tool","color","size","xs","ys"],"title":"CommentAnnotationPath","description":"A path in a comment annotation"},"PdfAnnotationData":{"properties":{"page_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number"},"xfdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xfdf"},"annotation_type":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationType"},{"type":"null"}]},"selected_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Text"}},"type":"object","title":"PdfAnnotationData","description":"PDF annotation data for comments"},"PdfAnnotationType":{"type":"string","enum":["highlight","insert","remove","replace"],"title":"PdfAnnotationType"},"CommentDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Asset Id"},"content":{"type":"string","title":"Content"},"author":{"$ref":"#/components/schemas/UserDTOBase"},"created":{"type":"string","format":"date-time","title":"Created"},"updated":{"type":"string","format":"date-time","title":"Updated"},"resolved":{"type":"boolean","title":"Resolved"},"is_public":{"type":"boolean","title":"Is Public"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id"},"timestamp":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Timestamp"},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration"},"pdf_annotations":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationData"},{"type":"null"}]},"replies":{"items":{"$ref":"#/components/schemas/CommentDTO"},"type":"array","title":"Replies","default":[]},"mentions":{"items":{"$ref":"#/components/schemas/Mention"},"type":"array","title":"Mentions","default":[]},"reactions":{"items":{"$ref":"#/components/schemas/ReactionDTO"},"type":"array","title":"Reactions","default":[]},"anchor":{"anyOf":[{"$ref":"#/components/schemas/CommentAnchor"},{"type":"null"}]},"annotation":{"anyOf":[{"items":{"$ref":"#/components/schemas/CommentAnnotationPath"},"type":"array"},{"type":"null"}],"title":"Annotation"},"is_copied":{"type":"boolean","title":"Is Copied","default":false},"attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Attachments","default":[]}},"type":"object","required":["id","asset_id","content","author","created","updated","resolved","is_public","parent_id","timestamp","duration","anchor"],"title":"CommentDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"ReactionDTO":{"properties":{"users":{"items":{"$ref":"#/components/schemas/UserDTOWithCommentId"},"type":"array","title":"Users"},"content":{"type":"string","title":"Content"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["users","content","count"],"title":"ReactionDTO"},"UserDTOWithCommentId":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"},"comment_id":{"type":"string","format":"uuid","title":"Comment Id"}},"type":"object","required":["id","name","email","avatar_url","user_type","comment_id"],"title":"UserDTOWithCommentId"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments":{"post":{"tags":["comments"],"summary":"Add a comment to an asset","description":"Add a comment to an asset","operationId":"addAssetComment","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddAssetCommentRequest"}}}},"responses":{"200":{"description":"The comment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update a comment

> Update a comment

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"UpdateCommentRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this comment is in"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment","description":"The comment to add to the asset"},"mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/Mention"},"type":"array"},{"type":"null"}],"title":"Mentions","description":"The mentions in the comment"},"is_public":{"type":"boolean","title":"Is Public Comment?","description":"Whether the comment is public or not"},"url":{"type":"string","title":"Url of the comment","description":"The url of the comment"},"timestamp":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Timestamp from start","description":"The timestamp of the comment from the start of the video. delete with -1"},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration of the comment timestamp","description":"The duration of the comment timestamp in seconds (for range based comments). delete with -1"},"anchor":{"anyOf":[{"$ref":"#/components/schemas/CommentAnchor"},{"type":"null"}],"title":"Anchor","description":"The anchor position of the comment. Pass null to remove."},"annotation":{"anyOf":[{"items":{"$ref":"#/components/schemas/CommentAnnotationPath"},"type":"array"},{"type":"null"}],"title":"The annotation of the comment","description":"The annotation is a list of annotation paths. Pass empty list to remove."},"pdf_annotations":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationData"},{"type":"null"}],"title":"PDF annotations","description":"PDF annotation data containing page_number, xfdf, annotation_type, selected_text"}},"type":"object","required":["drive_id","url"],"title":"UpdateCommentRequest"},"Mention":{"properties":{"user_id":{"type":"string","title":"User Id"},"text":{"type":"string","title":"Text"},"start_index":{"type":"integer","title":"Start Index"},"end_index":{"type":"integer","title":"End Index"},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Name","default":""}},"type":"object","required":["user_id","text","start_index","end_index"],"title":"Mention"},"CommentAnchor":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"}},"type":"object","required":["x","y"],"title":"CommentAnchor"},"CommentAnnotationPath":{"properties":{"tool":{"type":"string","title":"Tool"},"color":{"type":"string","title":"Color"},"size":{"type":"number","title":"Size"},"xs":{"items":{"type":"number"},"type":"array","title":"Xs"},"ys":{"items":{"type":"number"},"type":"array","title":"Ys"}},"type":"object","required":["tool","color","size","xs","ys"],"title":"CommentAnnotationPath","description":"A path in a comment annotation"},"PdfAnnotationData":{"properties":{"page_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number"},"xfdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xfdf"},"annotation_type":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationType"},{"type":"null"}]},"selected_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Text"}},"type":"object","title":"PdfAnnotationData","description":"PDF annotation data for comments"},"PdfAnnotationType":{"type":"string","enum":["highlight","insert","remove","replace"],"title":"PdfAnnotationType"},"CommentDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Asset Id"},"content":{"type":"string","title":"Content"},"author":{"$ref":"#/components/schemas/UserDTOBase"},"created":{"type":"string","format":"date-time","title":"Created"},"updated":{"type":"string","format":"date-time","title":"Updated"},"resolved":{"type":"boolean","title":"Resolved"},"is_public":{"type":"boolean","title":"Is Public"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id"},"timestamp":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Timestamp"},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration"},"pdf_annotations":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationData"},{"type":"null"}]},"replies":{"items":{"$ref":"#/components/schemas/CommentDTO"},"type":"array","title":"Replies","default":[]},"mentions":{"items":{"$ref":"#/components/schemas/Mention"},"type":"array","title":"Mentions","default":[]},"reactions":{"items":{"$ref":"#/components/schemas/ReactionDTO"},"type":"array","title":"Reactions","default":[]},"anchor":{"anyOf":[{"$ref":"#/components/schemas/CommentAnchor"},{"type":"null"}]},"annotation":{"anyOf":[{"items":{"$ref":"#/components/schemas/CommentAnnotationPath"},"type":"array"},{"type":"null"}],"title":"Annotation"},"is_copied":{"type":"boolean","title":"Is Copied","default":false},"attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Attachments","default":[]}},"type":"object","required":["id","asset_id","content","author","created","updated","resolved","is_public","parent_id","timestamp","duration","anchor"],"title":"CommentDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"ReactionDTO":{"properties":{"users":{"items":{"$ref":"#/components/schemas/UserDTOWithCommentId"},"type":"array","title":"Users"},"content":{"type":"string","title":"Content"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["users","content","count"],"title":"ReactionDTO"},"UserDTOWithCommentId":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"},"comment_id":{"type":"string","format":"uuid","title":"Comment Id"}},"type":"object","required":["id","name","email","avatar_url","user_type","comment_id"],"title":"UserDTOWithCommentId"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments/{comment_id}":{"put":{"tags":["comments"],"summary":"Update a comment","description":"Update a comment","operationId":"updateComment","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset that the comment is on"},"description":"The id of the asset that the comment is on"},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The comment id","description":"The id of the comment to update"},"description":"The id of the comment to update"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCommentRequest"}}}},"responses":{"200":{"description":"The comment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete a comment

> Delete a comment

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments/{comment_id}":{"delete":{"tags":["comments"],"summary":"Delete a comment","description":"Delete a comment","operationId":"deleteComment","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset that the comment is on"},"description":"The id of the asset that the comment is on"},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The comment id","description":"The id of the comment to delete"},"description":"The id of the comment to delete"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this comment is in"},"description":"The id of the drive this comment is in"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"null"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update a comment to be resolved or not

> Update a comment's resolve status

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"ResolveCommentRequest":{"properties":{"drive_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"The drive id","description":"The id of the drive this comment is in"},"resolved":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Resolved","description":"Whether the comment is resolved"},"url":{"type":"string","title":"Url of the comment","description":"The url of the comment with REPLACE_COMMENT_ID_ON_SERVER placeholder"}},"type":"object","required":["url"],"title":"ResolveCommentRequest"},"CommentDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Asset Id"},"content":{"type":"string","title":"Content"},"author":{"$ref":"#/components/schemas/UserDTOBase"},"created":{"type":"string","format":"date-time","title":"Created"},"updated":{"type":"string","format":"date-time","title":"Updated"},"resolved":{"type":"boolean","title":"Resolved"},"is_public":{"type":"boolean","title":"Is Public"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id"},"timestamp":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Timestamp"},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration"},"pdf_annotations":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationData"},{"type":"null"}]},"replies":{"items":{"$ref":"#/components/schemas/CommentDTO"},"type":"array","title":"Replies","default":[]},"mentions":{"items":{"$ref":"#/components/schemas/Mention"},"type":"array","title":"Mentions","default":[]},"reactions":{"items":{"$ref":"#/components/schemas/ReactionDTO"},"type":"array","title":"Reactions","default":[]},"anchor":{"anyOf":[{"$ref":"#/components/schemas/CommentAnchor"},{"type":"null"}]},"annotation":{"anyOf":[{"items":{"$ref":"#/components/schemas/CommentAnnotationPath"},"type":"array"},{"type":"null"}],"title":"Annotation"},"is_copied":{"type":"boolean","title":"Is Copied","default":false},"attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Attachments","default":[]}},"type":"object","required":["id","asset_id","content","author","created","updated","resolved","is_public","parent_id","timestamp","duration","anchor"],"title":"CommentDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"PdfAnnotationData":{"properties":{"page_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number"},"xfdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xfdf"},"annotation_type":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationType"},{"type":"null"}]},"selected_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Text"}},"type":"object","title":"PdfAnnotationData","description":"PDF annotation data for comments"},"PdfAnnotationType":{"type":"string","enum":["highlight","insert","remove","replace"],"title":"PdfAnnotationType"},"Mention":{"properties":{"user_id":{"type":"string","title":"User Id"},"text":{"type":"string","title":"Text"},"start_index":{"type":"integer","title":"Start Index"},"end_index":{"type":"integer","title":"End Index"},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Name","default":""}},"type":"object","required":["user_id","text","start_index","end_index"],"title":"Mention"},"ReactionDTO":{"properties":{"users":{"items":{"$ref":"#/components/schemas/UserDTOWithCommentId"},"type":"array","title":"Users"},"content":{"type":"string","title":"Content"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["users","content","count"],"title":"ReactionDTO"},"UserDTOWithCommentId":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"},"comment_id":{"type":"string","format":"uuid","title":"Comment Id"}},"type":"object","required":["id","name","email","avatar_url","user_type","comment_id"],"title":"UserDTOWithCommentId"},"CommentAnchor":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"}},"type":"object","required":["x","y"],"title":"CommentAnchor"},"CommentAnnotationPath":{"properties":{"tool":{"type":"string","title":"Tool"},"color":{"type":"string","title":"Color"},"size":{"type":"number","title":"Size"},"xs":{"items":{"type":"number"},"type":"array","title":"Xs"},"ys":{"items":{"type":"number"},"type":"array","title":"Ys"}},"type":"object","required":["tool","color","size","xs","ys"],"title":"CommentAnnotationPath","description":"A path in a comment annotation"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments/{comment_id}/resolve":{"put":{"tags":["comments"],"summary":"Update a comment to be resolved or not","description":"Update a comment's resolve status","operationId":"resolveComment","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset that the comment is on"},"description":"The id of the asset that the comment is on"},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The comment id","description":"The id of the comment to update"},"description":"The id of the comment to update"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveCommentRequest"}}}},"responses":{"200":{"description":"The comment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Reply to a comment

> Reply to a comment

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"ReplyToCommentRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this comment is in"},"content":{"type":"string","title":"Comment content","description":"The content of the comment to add to the asset"},"mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/Mention"},"type":"array"},{"type":"null"}],"title":"Mentions","description":"The mentions in the comment","default":[]},"url":{"type":"string","title":"Url of the comment","description":"The url of the comment"}},"type":"object","required":["drive_id","content","url"],"title":"ReplyToCommentRequest"},"Mention":{"properties":{"user_id":{"type":"string","title":"User Id"},"text":{"type":"string","title":"Text"},"start_index":{"type":"integer","title":"Start Index"},"end_index":{"type":"integer","title":"End Index"},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Name","default":""}},"type":"object","required":["user_id","text","start_index","end_index"],"title":"Mention"},"CommentDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Asset Id"},"content":{"type":"string","title":"Content"},"author":{"$ref":"#/components/schemas/UserDTOBase"},"created":{"type":"string","format":"date-time","title":"Created"},"updated":{"type":"string","format":"date-time","title":"Updated"},"resolved":{"type":"boolean","title":"Resolved"},"is_public":{"type":"boolean","title":"Is Public"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id"},"timestamp":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Timestamp"},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration"},"pdf_annotations":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationData"},{"type":"null"}]},"replies":{"items":{"$ref":"#/components/schemas/CommentDTO"},"type":"array","title":"Replies","default":[]},"mentions":{"items":{"$ref":"#/components/schemas/Mention"},"type":"array","title":"Mentions","default":[]},"reactions":{"items":{"$ref":"#/components/schemas/ReactionDTO"},"type":"array","title":"Reactions","default":[]},"anchor":{"anyOf":[{"$ref":"#/components/schemas/CommentAnchor"},{"type":"null"}]},"annotation":{"anyOf":[{"items":{"$ref":"#/components/schemas/CommentAnnotationPath"},"type":"array"},{"type":"null"}],"title":"Annotation"},"is_copied":{"type":"boolean","title":"Is Copied","default":false},"attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Attachments","default":[]}},"type":"object","required":["id","asset_id","content","author","created","updated","resolved","is_public","parent_id","timestamp","duration","anchor"],"title":"CommentDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"PdfAnnotationData":{"properties":{"page_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number"},"xfdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xfdf"},"annotation_type":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationType"},{"type":"null"}]},"selected_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Text"}},"type":"object","title":"PdfAnnotationData","description":"PDF annotation data for comments"},"PdfAnnotationType":{"type":"string","enum":["highlight","insert","remove","replace"],"title":"PdfAnnotationType"},"ReactionDTO":{"properties":{"users":{"items":{"$ref":"#/components/schemas/UserDTOWithCommentId"},"type":"array","title":"Users"},"content":{"type":"string","title":"Content"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["users","content","count"],"title":"ReactionDTO"},"UserDTOWithCommentId":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"},"comment_id":{"type":"string","format":"uuid","title":"Comment Id"}},"type":"object","required":["id","name","email","avatar_url","user_type","comment_id"],"title":"UserDTOWithCommentId"},"CommentAnchor":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"}},"type":"object","required":["x","y"],"title":"CommentAnchor"},"CommentAnnotationPath":{"properties":{"tool":{"type":"string","title":"Tool"},"color":{"type":"string","title":"Color"},"size":{"type":"number","title":"Size"},"xs":{"items":{"type":"number"},"type":"array","title":"Xs"},"ys":{"items":{"type":"number"},"type":"array","title":"Ys"}},"type":"object","required":["tool","color","size","xs","ys"],"title":"CommentAnnotationPath","description":"A path in a comment annotation"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments/{comment_id}/reply":{"post":{"tags":["comments"],"summary":"Reply to a comment","description":"Reply to a comment","operationId":"replyToComment","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset that the comment is on"},"description":"The id of the asset that the comment is on"},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The comment id","description":"The id of the comment to reply to"},"description":"The id of the comment to reply to"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyToCommentRequest"}}}},"responses":{"200":{"description":"The comment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## React to a comment

> React to a comment

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"ReactToCommentRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this comment is in"},"reaction_to_add":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reaction to add","description":"The reaction to add to the comment. Either pass this or reaction_to_remove"},"reaction_to_remove":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Reaction id to remove","description":"The id of the reaction to remove. Either pass this or reaction_to_add"}},"type":"object","required":["drive_id"],"title":"ReactToCommentRequest"},"CommentDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Asset Id"},"content":{"type":"string","title":"Content"},"author":{"$ref":"#/components/schemas/UserDTOBase"},"created":{"type":"string","format":"date-time","title":"Created"},"updated":{"type":"string","format":"date-time","title":"Updated"},"resolved":{"type":"boolean","title":"Resolved"},"is_public":{"type":"boolean","title":"Is Public"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id"},"timestamp":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Timestamp"},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration"},"pdf_annotations":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationData"},{"type":"null"}]},"replies":{"items":{"$ref":"#/components/schemas/CommentDTO"},"type":"array","title":"Replies","default":[]},"mentions":{"items":{"$ref":"#/components/schemas/Mention"},"type":"array","title":"Mentions","default":[]},"reactions":{"items":{"$ref":"#/components/schemas/ReactionDTO"},"type":"array","title":"Reactions","default":[]},"anchor":{"anyOf":[{"$ref":"#/components/schemas/CommentAnchor"},{"type":"null"}]},"annotation":{"anyOf":[{"items":{"$ref":"#/components/schemas/CommentAnnotationPath"},"type":"array"},{"type":"null"}],"title":"Annotation"},"is_copied":{"type":"boolean","title":"Is Copied","default":false},"attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Attachments","default":[]}},"type":"object","required":["id","asset_id","content","author","created","updated","resolved","is_public","parent_id","timestamp","duration","anchor"],"title":"CommentDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"PdfAnnotationData":{"properties":{"page_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number"},"xfdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xfdf"},"annotation_type":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationType"},{"type":"null"}]},"selected_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Text"}},"type":"object","title":"PdfAnnotationData","description":"PDF annotation data for comments"},"PdfAnnotationType":{"type":"string","enum":["highlight","insert","remove","replace"],"title":"PdfAnnotationType"},"Mention":{"properties":{"user_id":{"type":"string","title":"User Id"},"text":{"type":"string","title":"Text"},"start_index":{"type":"integer","title":"Start Index"},"end_index":{"type":"integer","title":"End Index"},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Name","default":""}},"type":"object","required":["user_id","text","start_index","end_index"],"title":"Mention"},"ReactionDTO":{"properties":{"users":{"items":{"$ref":"#/components/schemas/UserDTOWithCommentId"},"type":"array","title":"Users"},"content":{"type":"string","title":"Content"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["users","content","count"],"title":"ReactionDTO"},"UserDTOWithCommentId":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"},"comment_id":{"type":"string","format":"uuid","title":"Comment Id"}},"type":"object","required":["id","name","email","avatar_url","user_type","comment_id"],"title":"UserDTOWithCommentId"},"CommentAnchor":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"}},"type":"object","required":["x","y"],"title":"CommentAnchor"},"CommentAnnotationPath":{"properties":{"tool":{"type":"string","title":"Tool"},"color":{"type":"string","title":"Color"},"size":{"type":"number","title":"Size"},"xs":{"items":{"type":"number"},"type":"array","title":"Xs"},"ys":{"items":{"type":"number"},"type":"array","title":"Ys"}},"type":"object","required":["tool","color","size","xs","ys"],"title":"CommentAnnotationPath","description":"A path in a comment annotation"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments/{comment_id}/react":{"put":{"tags":["comments"],"summary":"React to a comment","description":"React to a comment","operationId":"reactToComment","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset that the comment is on"},"description":"The id of the asset that the comment is on"},{"name":"comment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The comment id","description":"The id of the comment to react to"},"description":"The id of the comment to react to"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReactToCommentRequest"}}}},"responses":{"200":{"description":"The comment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Start the upload process for a comment attachment

> Start the upload process for a comment attachment

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"StartCommentAttachmentUploadRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to create the attachment for"},"name":{"type":"string","title":"The name of the attachment","description":"The name of the attachment to be created"},"mime_type":{"type":"string","title":"The mime type of the attachment","description":"The mime type of the attachment to be created"},"size":{"type":"integer","title":"The size of the attachment","description":"The size of the attachment to be created"},"comment_id":{"type":"string","format":"uuid","title":"The comment id","description":"The id of the comment to attach to"}},"type":"object","required":["drive_id","name","mime_type","size","comment_id"],"title":"StartCommentAttachmentUploadRequest"},"AttachmentToUploadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"upload_url":{"type":"string","title":"Upload Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","upload_url"],"title":"AttachmentToUploadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments/attachments":{"post":{"tags":["comments"],"summary":"Start the upload process for a comment attachment","description":"Start the upload process for a comment attachment","operationId":"startCommentAttachmentUpload","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to create the attachment for"},"description":"The id of the asset to create the attachment for"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartCommentAttachmentUploadRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentToUploadDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Mark the upload of a comment attachment as complete

> Mark the upload of a comment attachment as complete

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"MarkCommentAttachmentUploadedRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive to mark the attachment uploaded for"}},"type":"object","required":["drive_id"],"title":"MarkCommentAttachmentUploadedRequest"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments/attachments/{attachment_id}":{"post":{"tags":["comments"],"summary":"Mark the upload of a comment attachment as complete","description":"Mark the upload of a comment attachment as complete","operationId":"markCommentAttachmentUploaded","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to mark the attachment uploaded for"},"description":"The id of the asset to mark the attachment uploaded for"},{"name":"attachment_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The attachment id","description":"The id of the attachment to mark as uploaded"},"description":"The id of the attachment to mark as uploaded"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkCommentAttachmentUploadedRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Paste comments from another asset

> Paste comments from source asset to target asset.\
> \
> Pastes all the source asset's comments, or only the specified comments\
> when source\_comment\_ids is provided. Source and target may be on different\
> drives when source\_drive\_id is provided.

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"PasteAssetCommentsRequest":{"properties":{"source_asset_id":{"type":"string","format":"uuid","title":"The source asset id","description":"The id of the asset to copy comments from"},"drive_id":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the target drive"},"source_drive_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"The source drive id","description":"The id of the drive containing the source asset. Omit when source and target share a drive."},"source_comment_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"The source comment ids","description":"If provided, only these comments (and their threads) are pasted"}},"type":"object","required":["source_asset_id","drive_id"],"title":"PasteAssetCommentsRequest"},"CommentDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Asset Id"},"content":{"type":"string","title":"Content"},"author":{"$ref":"#/components/schemas/UserDTOBase"},"created":{"type":"string","format":"date-time","title":"Created"},"updated":{"type":"string","format":"date-time","title":"Updated"},"resolved":{"type":"boolean","title":"Resolved"},"is_public":{"type":"boolean","title":"Is Public"},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id"},"timestamp":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Timestamp"},"duration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration"},"pdf_annotations":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationData"},{"type":"null"}]},"replies":{"items":{"$ref":"#/components/schemas/CommentDTO"},"type":"array","title":"Replies","default":[]},"mentions":{"items":{"$ref":"#/components/schemas/Mention"},"type":"array","title":"Mentions","default":[]},"reactions":{"items":{"$ref":"#/components/schemas/ReactionDTO"},"type":"array","title":"Reactions","default":[]},"anchor":{"anyOf":[{"$ref":"#/components/schemas/CommentAnchor"},{"type":"null"}]},"annotation":{"anyOf":[{"items":{"$ref":"#/components/schemas/CommentAnnotationPath"},"type":"array"},{"type":"null"}],"title":"Annotation"},"is_copied":{"type":"boolean","title":"Is Copied","default":false},"attachments":{"items":{"$ref":"#/components/schemas/AttachmentToDownloadDTO"},"type":"array","title":"Attachments","default":[]}},"type":"object","required":["id","asset_id","content","author","created","updated","resolved","is_public","parent_id","timestamp","duration","anchor"],"title":"CommentDTO"},"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"PdfAnnotationData":{"properties":{"page_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number"},"xfdf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xfdf"},"annotation_type":{"anyOf":[{"$ref":"#/components/schemas/PdfAnnotationType"},{"type":"null"}]},"selected_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Selected Text"}},"type":"object","title":"PdfAnnotationData","description":"PDF annotation data for comments"},"PdfAnnotationType":{"type":"string","enum":["highlight","insert","remove","replace"],"title":"PdfAnnotationType"},"Mention":{"properties":{"user_id":{"type":"string","title":"User Id"},"text":{"type":"string","title":"Text"},"start_index":{"type":"integer","title":"Start Index"},"end_index":{"type":"integer","title":"End Index"},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Name","default":""}},"type":"object","required":["user_id","text","start_index","end_index"],"title":"Mention"},"ReactionDTO":{"properties":{"users":{"items":{"$ref":"#/components/schemas/UserDTOWithCommentId"},"type":"array","title":"Users"},"content":{"type":"string","title":"Content"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["users","content","count"],"title":"ReactionDTO"},"UserDTOWithCommentId":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"},"comment_id":{"type":"string","format":"uuid","title":"Comment Id"}},"type":"object","required":["id","name","email","avatar_url","user_type","comment_id"],"title":"UserDTOWithCommentId"},"CommentAnchor":{"properties":{"x":{"type":"number","title":"X"},"y":{"type":"number","title":"Y"}},"type":"object","required":["x","y"],"title":"CommentAnchor"},"CommentAnnotationPath":{"properties":{"tool":{"type":"string","title":"Tool"},"color":{"type":"string","title":"Color"},"size":{"type":"number","title":"Size"},"xs":{"items":{"type":"number"},"type":"array","title":"Xs"},"ys":{"items":{"type":"number"},"type":"array","title":"Ys"}},"type":"object","required":["tool","color","size","xs","ys"],"title":"CommentAnnotationPath","description":"A path in a comment annotation"},"AttachmentToDownloadDTO":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"drive_id":{"type":"string","format":"uuid","title":"Drive Id"},"uploader_id":{"type":"string","format":"uuid","title":"Uploader Id"},"uploaded":{"type":"boolean","title":"Uploaded"},"name":{"type":"string","title":"Name"},"mime_type":{"type":"string","title":"Mime Type"},"size":{"type":"integer","title":"Size"},"download_url":{"type":"string","title":"Download Url"}},"type":"object","required":["id","drive_id","uploader_id","uploaded","name","mime_type","size","download_url"],"title":"AttachmentToDownloadDTO"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments/paste":{"post":{"tags":["comments"],"summary":"Paste comments from another asset","description":"Paste comments from source asset to target asset.\n\nPastes all the source asset's comments, or only the specified comments\nwhen source_comment_ids is provided. Source and target may be on different\ndrives when source_drive_id is provided.","operationId":"pasteAssetComments","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The target asset id","description":"The id of the asset to paste comments to"},"description":"The id of the asset to paste comments to"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasteAssetCommentsRequest"}}}},"responses":{"200":{"description":"List of newly created comments","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CommentDTO"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Export comments in various formats

> Export all comments for an asset in the specified format

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"ExportType":{"type":"string","enum":["csv","txt","avid_xml","edl"],"title":"ExportType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/comments/export":{"get":{"tags":["comments"],"summary":"Export comments in various formats","description":"Export all comments for an asset in the specified format","operationId":"exportComments","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to export comments for"},"description":"The id of the asset to export comments for"},{"name":"type","in":"query","required":true,"schema":{"$ref":"#/components/schemas/ExportType","title":"Export type","description":"The type of export to generate"},"description":"The type of export to generate"},{"name":"drive_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"},{"name":"authorization","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The authorization token"},"description":"Your API key, for clients that can't set headers, such as an `<img>` or `<video>` tag. Prefer the `Authorization` header, since URLs end up in logs and browser history."}],"responses":{"200":{"description":"Exported comments file","content":{"application/octet-stream":{"schema":{"type":"string"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get all mentionable users on comments for an asset

> Get all mentionable users on comments for an asset

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"UserDTOBase":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"avatar_url":{"type":"string","title":"Avatar Url"},"user_type":{"$ref":"#/components/schemas/UserType"}},"type":"object","required":["id","name","email","avatar_url","user_type"],"title":"UserDTOBase"},"UserType":{"type":"string","enum":["regular","group"],"title":"UserType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/assets/{asset_id}/mentionable-users":{"get":{"tags":["comments"],"summary":"Get all mentionable users on comments for an asset","description":"Get all mentionable users on comments for an asset","operationId":"getAssetMentionableUsers","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"The asset id","description":"The id of the asset to retrieve"},"description":"The id of the asset to retrieve"},{"name":"drive_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"The drive id","description":"The id of the drive this asset is in"},"description":"The id of the drive this asset is in"}],"responses":{"200":{"description":"A list of mentionable users on comments for the asset","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserDTOBase"}}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Initiate attachment upload

> Initiate an attachment upload by generating a presigned URL and signed token.\
> \
> This is phase 1 of the two-phase attachment flow:\
> 1\. Call this endpoint to get presigned URL and token\
> 2\. Upload file to the presigned URL\
> 3\. Pass token(s) when creating the entity (e.g., comment) to link attachments

```json
{"openapi":"3.1.0","info":{"title":"Shade API","version":"dev"},"tags":[{"name":"comments","description":"Read, add, reply to, resolve, and export comments on assets.\n\nFor video and audio, set `timestamp` (in seconds from the start) to pin a\ncomment to a moment, and add `duration` to cover a range."}],"servers":[{"url":"https://api.shade.inc","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your Shade API key, sent as-is with no `Bearer` prefix. Create one under\n**Settings → Integrate → API keys**.\n"}},"schemas":{"StartAttachmentUploadRequest":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"Drive ID","description":"The ID of the drive to upload the attachment to"},"size":{"type":"integer","title":"File size","description":"The size of the file in bytes"},"mime_type":{"type":"string","title":"MIME type","description":"The MIME type of the file"},"file_name":{"type":"string","title":"File name","description":"The original filename"},"entity":{"$ref":"#/components/schemas/AttachmentEntity","title":"Entity","description":"The entity that will own this attachment (e.g., 'comments')"}},"type":"object","required":["drive_id","size","mime_type","file_name","entity"],"title":"StartAttachmentUploadRequest"},"AttachmentEntity":{"type":"string","enum":["comments","assets","individuals"],"title":"AttachmentEntity"},"AttachmentUploadResponse":{"properties":{"presigned_url":{"type":"string","title":"Presigned Url"},"token":{"type":"string","title":"Token"}},"type":"object","required":["presigned_url","token"],"title":"AttachmentUploadResponse","description":"Response from attachment upload initiation."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/attachments/upload":{"post":{"tags":["comments"],"summary":"Initiate attachment upload","description":"Initiate an attachment upload by generating a presigned URL and signed token.\n\nThis is phase 1 of the two-phase attachment flow:\n1. Call this endpoint to get presigned URL and token\n2. Upload file to the presigned URL\n3. Pass token(s) when creating the entity (e.g., comment) to link attachments","operationId":"startAttachmentUpload","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartAttachmentUploadRequest"}}}},"responses":{"200":{"description":"Presigned URL and token for uploading an attachment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentUploadResponse"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://academy.shade.inc/developers/files-and-assets/comments.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
