> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/platform/v4-experimental/api-reference/comments/create/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Create comment POST https://api.frame.io/v4/accounts/{account_id}/files/{file_id}/comments Content-Type: application/json Create a comment on a file. This endpoint has been added to `Current Version` of the API. Please see [https://developer.adobe.com/frameio/api/current/#tag/Comments/operation/comments.create](https://developer.adobe.com/frameio/api/current/#tag/Comments/operation/comments.create). Rate Limits: 100 calls per 1.00 minute(s) per account\_user Reference: https://next.developer.frame.io/platform/api-reference/comments/create ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `account_id` (string, required) - `file_id` (string, required) ### Query parameters - `timestamp_as_timecode` (boolean, optional) ### Body (application/json) This endpoint expects a CreateCommentParams. - `data` (CreateCommentParamsData, required) ## Response ### 201 Created - `data` (Comment, required) ## Errors ### 400 Bad Request Error Bad request - `errors` (list of BadRequestErrorsItems, required) ### 401 Unauthorized Error Unauthorized - `errors` (list of UnauthorizedErrorsItems, required) ### 403 Forbidden Error Forbidden - `errors` (list of ForbiddenErrorsItems, required) ### 404 Not Found Error Not found - `errors` (list of NotFoundErrorsItems, required) ### 409 Conflict Error Conflict - `errors` (list of ConflictErrorsItems, required) ### 422 Unprocessable Entity Error Unprocessable content - `errors` (list of UnprocessableContentErrorsItems, required) ### 429 Too Many Requests Error Too many requests - `errors` (list of TooManyRequestsErrorsItems, required) ## Types ### CreateCommentParamsData - `text` (string, required) — Comment text (required) - `anchor` (Anchor, optional, nullable) — Comment anchor location. \{(x, y) | 0 \<= x \<= 1, 0 \<= y \<= 1}. - `annotation` (string, optional, nullable) — JSON geometry for on-screen drawings. Allowed for document, image, video, or stream file types. JSON must be stringified - `attachments` (list of AttachmentInput, optional) — Optional attachments to create with the comment (max 6 attachments) - `completed` (boolean, optional, nullable) — Comment completion status - `duration` (integer, optional, nullable) — Duration of comment in frames. Requires presence of timestamp parameter - `links` (list of LinkParams, optional) — Comment text links. - `page` (integer, optional, nullable) — Document page. Only allowed when file type is a pdf document - `text_review_annotation` (TextReviewAnnotation, optional) — Text review annotation details for comments left on text documents. - `timestamp` (TimeStamp, optional) ### Comment - `annotation` (string, required, nullable) - `attachments` (list of CommentAttachment, required, nullable) — Attachments associated with this comment (0-6 attachments allowed) - `completed_at` (string, required, nullable) — Completion timestamp - `completer_id` (string, required, nullable) — ID of user who marked the comment as completed - `created_at` (string, required) — Creation timestamp - `duration` (integer, required, nullable) — Duration of comment in frames. Requires presence of timestamp parameter - `file_id` (string, required) — File ID - `id` (string, required) — Comment ID - `links` (list of Link, required) — Links - `mentions` (list of Mention, required) — Mentions - `page` (integer, required, nullable) — Document page - `text` (string, required) — Comment text - `text_edited_at` (string, required, nullable) — Text edited timestamp - `text_review_annotation` (TextReviewAnnotation, required, nullable) — Text review annotation details for comments left on text documents. - `timestamp` (TimeStamp, required) - `updated_at` (string, required) — Update timestamp - `anchor` (Anchor, optional, nullable) — Comment anchor location. \{(x, y) | 0 \<= x \<= 1, 0 \<= y \<= 1}. ### BadRequestErrorsItems - `detail` (string, required) - `source` (BadRequestErrorsItemsSource, optional) - `title` (string, optional) ### UnauthorizedErrorsItems - `detail` (string, required) - `source` (UnauthorizedErrorsItemsSource, optional) - `title` (string, optional) ### ForbiddenErrorsItems - `detail` (string, required) - `source` (ForbiddenErrorsItemsSource, optional) - `title` (string, optional) ### NotFoundErrorsItems - `detail` (string, required) - `source` (NotFoundErrorsItemsSource, optional) - `title` (string, optional) ### ConflictErrorsItems - `detail` (string, required) - `source` (ConflictErrorsItemsSource, optional) - `title` (string, optional) ### UnprocessableContentErrorsItems - `detail` (string, required) - `source` (UnprocessableContentErrorsItemsSource, optional) - `title` (string, optional) ### TooManyRequestsErrorsItems - `detail` (string, required) - `source` (TooManyRequestsErrorsItemsSource, optional) - `title` (string, optional) ### Anchor - `x` (float, required) — Horizontal comment anchor location. - `y` (float, required) — Vertical comment anchor location. ### AttachmentInput Input for creating a comment attachment - `file_size` (integer, required) — Attachment file size in bytes (up to 5TB) - `media_type` (string, required) — File media type - `name` (string, required) — Filename ### LinkParams - `end_index` (integer, required) — End index of link text - `start_index` (integer, required) — Start index of link text - `url` (string, required) — Link URL ### TextReviewAnnotation - `bounds` (list of TextReviewAnnotationBounds, required) — An array of bounds representing a multiline selection origin at the lower-left corner. - `selection_text` (string, required, nullable) — Selected text from the document. - `suggested_text` (string, required, nullable) — Suggested replacement or insertion text. - `text_review_annotation_type` (enum, required) — The type of text review annotation. - Allowed values: `highlight`, `insert`, `remove`, `replace` ### TimeStamp ### CommentAttachment - `created_at` (string, required) — Creation timestamp - `file_size` (integer, required) — Attachment file size in bytes (up to 5TB) - `id` (string, required) — Comment attachment ID - `media_type` (string, required, nullable) — File media type - `name` (string, required) — File name for the attachment - `upload_urls` (list of string, optional, nullable) — Comment attachment upload URLs. Number of URLs returned will vary depending on the file size. ### Link - `end_index` (integer, required) — End index of link text - `start_index` (integer, required) — Start index of link text - `text` (string, required) — Link text - `url` (string, required) — Link URL ### Mention - `end_index` (integer, required) — End index of mention text - `start_index` (integer, required) — Start index of mention text - `text` (string, required) — Mention text - `user_id` (string, required) — Mentioned user ID ### BadRequestErrorsItemsSource - `pointer` (string, optional) ### UnauthorizedErrorsItemsSource - `pointer` (string, optional) ### ForbiddenErrorsItemsSource - `pointer` (string, optional) ### NotFoundErrorsItemsSource - `pointer` (string, optional) ### ConflictErrorsItemsSource - `pointer` (string, optional) ### UnprocessableContentErrorsItemsSource - `pointer` (string, optional) ### TooManyRequestsErrorsItemsSource - `pointer` (string, optional) ### TextReviewAnnotationBounds - `height` (double, required) — Height of the rectangle - `width` (double, required) — Width of the rectangle - `x` (double, required) — Left corner position. - `y` (double, required) — Bottom corner position. ## Examples **Request** ```json { "data": { "text": "This is great!", "anchor": { "x": 0.5, "y": 0.5 }, "annotation": "[{\"tool\":\"rect\",\"color\":\"#F22237\",\"size\":8,\"x\":0.277726001863933,\"y\":0.12909555568499534,\"w\":0.3153168321877913,\"h\":0.5308131407269339,\"ix\":0.277726001863933,\"iy\":0.12909555568499534,\"radius\":8}]", "attachments": [ { "file_size": 1024000, "media_type": "image/png", "name": "screenshot.png" } ], "completed": false, "duration": 10, "links": [ { "end_index": 13, "start_index": 5, "url": "https://www.example.com" } ], "page": 4, "text_review_annotation": { "bounds": [ { "height": 42, "width": 130, "x": 12.5, "y": 24 } ], "selection_text": "existing copy", "suggested_text": "updated copy", "text_review_annotation_type": "replace" }, "timestamp": "00:00:02:12" } } ``` **Response** ```json { "data": { "annotation": "annotation", "attachments": [ { "created_at": "2024-02-02T21:19:24.828948Z", "file_size": 1024000, "id": "0d9398aa-62c5-4c55-90d8-b00bda4ec283", "media_type": "image/png", "name": "screenshot.png", "upload_urls": [ "https://s3.amazonaws.com/bucket/part1?signature=..." ] } ], "completed_at": null, "completer_id": null, "created_at": "2024-02-02T21:19:24.828948Z", "duration": 10, "file_id": "4ae08df1-b419-4897-aba5-560198a18237", "id": "a767587c-f8b3-4220-974f-b5a498606d24", "links": [ { "end_index": 13, "start_index": 5, "text": "Test User", "url": "https://www.example.com" } ], "mentions": [ { "end_index": 13, "start_index": 5, "text": "Test User", "user_id": "aaae24d8-7590-4af7-9f4e-821c07b099b0" } ], "page": 1, "text": "This is great!", "text_edited_at": "2024-02-02T21:19:24.828948Z", "text_review_annotation": { "bounds": [ { "height": 42, "width": 130, "x": 12.5, "y": 24 } ], "selection_text": "existing copy", "suggested_text": "updated copy", "text_review_annotation_type": "replace" }, "timestamp": 123, "updated_at": "2024-02-02T21:19:24.828948Z", "anchor": { "x": 0.5, "y": 0.5 } } } ``` **SDK Code** ```python import requests url = "https://api.frame.io/v4/accounts/260792e2-9790-4bc4-87fa-df1cff7d65a8/files/a380fd79-4df0-4e3c-963e-a7c7ff73a455/comments" payload = { "data": { "text": "This is great!", "anchor": { "x": 0.5, "y": 0.5 }, "annotation": "[{\"tool\":\"rect\",\"color\":\"#F22237\",\"size\":8,\"x\":0.277726001863933,\"y\":0.12909555568499534,\"w\":0.3153168321877913,\"h\":0.5308131407269339,\"ix\":0.277726001863933,\"iy\":0.12909555568499534,\"radius\":8}]", "attachments": [ { "file_size": 1024000, "media_type": "image/png", "name": "screenshot.png" } ], "completed": False, "duration": 10, "links": [ { "end_index": 13, "start_index": 5, "url": "https://www.example.com" } ], "page": 4, "text_review_annotation": { "bounds": [ { "height": 42, "width": 130, "x": 12.5, "y": 24 } ], "selection_text": "existing copy", "suggested_text": "updated copy", "text_review_annotation_type": "replace" }, "timestamp": "00:00:02:12" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.frame.io/v4/accounts/260792e2-9790-4bc4-87fa-df1cff7d65a8/files/a380fd79-4df0-4e3c-963e-a7c7ff73a455/comments'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"data":{"text":"This is great!","anchor":{"x":0.5,"y":0.5},"annotation":"[{\"tool\":\"rect\",\"color\":\"#F22237\",\"size\":8,\"x\":0.277726001863933,\"y\":0.12909555568499534,\"w\":0.3153168321877913,\"h\":0.5308131407269339,\"ix\":0.277726001863933,\"iy\":0.12909555568499534,\"radius\":8}]","attachments":[{"file_size":1024000,"media_type":"image/png","name":"screenshot.png"}],"completed":false,"duration":10,"links":[{"end_index":13,"start_index":5,"url":"https://www.example.com"}],"page":4,"text_review_annotation":{"bounds":[{"height":42,"width":130,"x":12.5,"y":24}],"selection_text":"existing copy","suggested_text":"updated copy","text_review_annotation_type":"replace"},"timestamp":"00:00:02:12"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.frame.io/v4/accounts/260792e2-9790-4bc4-87fa-df1cff7d65a8/files/a380fd79-4df0-4e3c-963e-a7c7ff73a455/comments" payload := strings.NewReader("{\n \"data\": {\n \"text\": \"This is great!\",\n \"anchor\": {\n \"x\": 0.5,\n \"y\": 0.5\n },\n \"annotation\": \"[{\\\"tool\\\":\\\"rect\\\",\\\"color\\\":\\\"#F22237\\\",\\\"size\\\":8,\\\"x\\\":0.277726001863933,\\\"y\\\":0.12909555568499534,\\\"w\\\":0.3153168321877913,\\\"h\\\":0.5308131407269339,\\\"ix\\\":0.277726001863933,\\\"iy\\\":0.12909555568499534,\\\"radius\\\":8}]\",\n \"attachments\": [\n {\n \"file_size\": 1024000,\n \"media_type\": \"image/png\",\n \"name\": \"screenshot.png\"\n }\n ],\n \"completed\": false,\n \"duration\": 10,\n \"links\": [\n {\n \"end_index\": 13,\n \"start_index\": 5,\n \"url\": \"https://www.example.com\"\n }\n ],\n \"page\": 4,\n \"text_review_annotation\": {\n \"bounds\": [\n {\n \"height\": 42,\n \"width\": 130,\n \"x\": 12.5,\n \"y\": 24\n }\n ],\n \"selection_text\": \"existing copy\",\n \"suggested_text\": \"updated copy\",\n \"text_review_annotation_type\": \"replace\"\n },\n \"timestamp\": \"00:00:02:12\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.frame.io/v4/accounts/260792e2-9790-4bc4-87fa-df1cff7d65a8/files/a380fd79-4df0-4e3c-963e-a7c7ff73a455/comments") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"data\": {\n \"text\": \"This is great!\",\n \"anchor\": {\n \"x\": 0.5,\n \"y\": 0.5\n },\n \"annotation\": \"[{\\\"tool\\\":\\\"rect\\\",\\\"color\\\":\\\"#F22237\\\",\\\"size\\\":8,\\\"x\\\":0.277726001863933,\\\"y\\\":0.12909555568499534,\\\"w\\\":0.3153168321877913,\\\"h\\\":0.5308131407269339,\\\"ix\\\":0.277726001863933,\\\"iy\\\":0.12909555568499534,\\\"radius\\\":8}]\",\n \"attachments\": [\n {\n \"file_size\": 1024000,\n \"media_type\": \"image/png\",\n \"name\": \"screenshot.png\"\n }\n ],\n \"completed\": false,\n \"duration\": 10,\n \"links\": [\n {\n \"end_index\": 13,\n \"start_index\": 5,\n \"url\": \"https://www.example.com\"\n }\n ],\n \"page\": 4,\n \"text_review_annotation\": {\n \"bounds\": [\n {\n \"height\": 42,\n \"width\": 130,\n \"x\": 12.5,\n \"y\": 24\n }\n ],\n \"selection_text\": \"existing copy\",\n \"suggested_text\": \"updated copy\",\n \"text_review_annotation_type\": \"replace\"\n },\n \"timestamp\": \"00:00:02:12\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.frame.io/v4/accounts/260792e2-9790-4bc4-87fa-df1cff7d65a8/files/a380fd79-4df0-4e3c-963e-a7c7ff73a455/comments") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"data\": {\n \"text\": \"This is great!\",\n \"anchor\": {\n \"x\": 0.5,\n \"y\": 0.5\n },\n \"annotation\": \"[{\\\"tool\\\":\\\"rect\\\",\\\"color\\\":\\\"#F22237\\\",\\\"size\\\":8,\\\"x\\\":0.277726001863933,\\\"y\\\":0.12909555568499534,\\\"w\\\":0.3153168321877913,\\\"h\\\":0.5308131407269339,\\\"ix\\\":0.277726001863933,\\\"iy\\\":0.12909555568499534,\\\"radius\\\":8}]\",\n \"attachments\": [\n {\n \"file_size\": 1024000,\n \"media_type\": \"image/png\",\n \"name\": \"screenshot.png\"\n }\n ],\n \"completed\": false,\n \"duration\": 10,\n \"links\": [\n {\n \"end_index\": 13,\n \"start_index\": 5,\n \"url\": \"https://www.example.com\"\n }\n ],\n \"page\": 4,\n \"text_review_annotation\": {\n \"bounds\": [\n {\n \"height\": 42,\n \"width\": 130,\n \"x\": 12.5,\n \"y\": 24\n }\n ],\n \"selection_text\": \"existing copy\",\n \"suggested_text\": \"updated copy\",\n \"text_review_annotation_type\": \"replace\"\n },\n \"timestamp\": \"00:00:02:12\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.frame.io/v4/accounts/260792e2-9790-4bc4-87fa-df1cff7d65a8/files/a380fd79-4df0-4e3c-963e-a7c7ff73a455/comments', [ 'body' => '{ "data": { "text": "This is great!", "anchor": { "x": 0.5, "y": 0.5 }, "annotation": "[{\\"tool\\":\\"rect\\",\\"color\\":\\"#F22237\\",\\"size\\":8,\\"x\\":0.277726001863933,\\"y\\":0.12909555568499534,\\"w\\":0.3153168321877913,\\"h\\":0.5308131407269339,\\"ix\\":0.277726001863933,\\"iy\\":0.12909555568499534,\\"radius\\":8}]", "attachments": [ { "file_size": 1024000, "media_type": "image/png", "name": "screenshot.png" } ], "completed": false, "duration": 10, "links": [ { "end_index": 13, "start_index": 5, "url": "https://www.example.com" } ], "page": 4, "text_review_annotation": { "bounds": [ { "height": 42, "width": 130, "x": 12.5, "y": 24 } ], "selection_text": "existing copy", "suggested_text": "updated copy", "text_review_annotation_type": "replace" }, "timestamp": "00:00:02:12" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.frame.io/v4/accounts/260792e2-9790-4bc4-87fa-df1cff7d65a8/files/a380fd79-4df0-4e3c-963e-a7c7ff73a455/comments"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"data\": {\n \"text\": \"This is great!\",\n \"anchor\": {\n \"x\": 0.5,\n \"y\": 0.5\n },\n \"annotation\": \"[{\\\"tool\\\":\\\"rect\\\",\\\"color\\\":\\\"#F22237\\\",\\\"size\\\":8,\\\"x\\\":0.277726001863933,\\\"y\\\":0.12909555568499534,\\\"w\\\":0.3153168321877913,\\\"h\\\":0.5308131407269339,\\\"ix\\\":0.277726001863933,\\\"iy\\\":0.12909555568499534,\\\"radius\\\":8}]\",\n \"attachments\": [\n {\n \"file_size\": 1024000,\n \"media_type\": \"image/png\",\n \"name\": \"screenshot.png\"\n }\n ],\n \"completed\": false,\n \"duration\": 10,\n \"links\": [\n {\n \"end_index\": 13,\n \"start_index\": 5,\n \"url\": \"https://www.example.com\"\n }\n ],\n \"page\": 4,\n \"text_review_annotation\": {\n \"bounds\": [\n {\n \"height\": 42,\n \"width\": 130,\n \"x\": 12.5,\n \"y\": 24\n }\n ],\n \"selection_text\": \"existing copy\",\n \"suggested_text\": \"updated copy\",\n \"text_review_annotation_type\": \"replace\"\n },\n \"timestamp\": \"00:00:02:12\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["data": [ "text": "This is great!", "anchor": [ "x": 0.5, "y": 0.5 ], "annotation": "[{\"tool\":\"rect\",\"color\":\"#F22237\",\"size\":8,\"x\":0.277726001863933,\"y\":0.12909555568499534,\"w\":0.3153168321877913,\"h\":0.5308131407269339,\"ix\":0.277726001863933,\"iy\":0.12909555568499534,\"radius\":8}]", "attachments": [ [ "file_size": 1024000, "media_type": "image/png", "name": "screenshot.png" ] ], "completed": false, "duration": 10, "links": [ [ "end_index": 13, "start_index": 5, "url": "https://www.example.com" ] ], "page": 4, "text_review_annotation": [ "bounds": [ [ "height": 42, "width": 130, "x": 12.5, "y": 24 ] ], "selection_text": "existing copy", "suggested_text": "updated copy", "text_review_annotation_type": "replace" ], "timestamp": "00:00:02:12" ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.frame.io/v4/accounts/260792e2-9790-4bc4-87fa-df1cff7d65a8/files/a380fd79-4df0-4e3c-963e-a7c7ff73a455/comments")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```