Creating a new Note to an existing version with REST API


I’ve been pulling projects, playlists, versions from shotgun without any problems with the REST APIs, but I’m not stuck trying to create a new Note to a specific version.

I’m able to successfully create a new project entity with

{ "name":"test project", "sg_status":"Active", "users":[ {"type":"HumanUser", "id":18} ] }

But if i go to the appropriate version (version id=7255), and try something similar, it fails:

{ "name": "new comment from API!!!!!", "sg_status":"Active", "users":[ {"type":"HumanUser", "id":89} ] }

with the error:
{ "errors": [ { "id": "2e3153322c3b31408849f85abb8b64b0", "status": 400, "code": 103, "title": "Request Parameters invalid.", "source": { "revive": [ "revive is missing", "revive must be true" ] }, "detail": null, "meta": null } ] }

I also tried adding the query param revive=true, and don’t get errors, but the create Note on version 7255 is not working, with this response:
{ "data": { "type": "Version", "id": 7255 }, "links": { "self": "/api/v1/entity/versions/7255" }, "meta": { "did_revive": false } }

I’m sure I’m missing something simple here, but I’m just getting started with the REST APIs.

Any suggestions on what I’m doing wrong?

Thanks in advance!


Hi @kkoechley,

Welcome to the forum and thanks for posting !

Sorry you are seeing the issue and let me ping the tech support team to help you out. In the meanwhile, check out the REST API doc below and see if it helps you.


Hi @Ben_xzj,

Thanks for the quick response! I’ve gone through the REST API v1 document already, but I find the doc to be a bit vague at times, and thus still stuck.

It would be great to have a reference for errors, and how to fix them (like what to do with revive=true error - that’s not mentioned anywhere in the doc).

Thanks again for your help! I’m sure I’m missing something simple, but i’ve hit the wall.


Hi @kkoechley,

If you want to create a note, the url is


Body is

    "subject": "new comment from API!!!!!", 
    "project":{ "type": "Project", "id":142 },
    "note_links": [{"type": "Version", "id":11620}]

Hope it is helpful



Hi @jing.liu,

Thanks for your help.

I used the POST to the endpoint you provided to create a new Note to a version, and it looked like it worked.

I verified that the Note was created with:


and verified it exists by hitting the endpoint:


I discovered looking up the notes schema


endpoint to help shed some light on what can be set. That was a big part of my problem.

After looking at the proper schema, I discovered that you also need to set content key:param in the body .json ie: "content":"whatever text you want in the note" so it will display properly in the media center app.

I still have a remaining items:

  1. I’m not able to see the notes created by the API in the “Notes App”. Is there an additional param that needs to be set so it will show up there so these notes can be included in note review?

  2. setting the param "read_by_current_user":"unread" in the create body .json doesn’t seem to have any effect.

Thanks again for the help! This has been very helpful!


1 Like

Hi @kkoechley,

What I did just an example. To create full note, you still need to add extra field for additional information. You could always go to note entity or field entity to check which fields you need. You have figure it out.

Is Notes App Review Notes? I could see it without any addtional params.

read_by_current_user is always used by current login user. That means when you use API user to set it as read. The current user is the API user. A human user has separate value. If you want to set it as read, the human user needs to read it. No cheat. In Python API, you could use sudo_as that the parameter will assume the login user is a human user. But Rest API doesn’t have that param.

Hope it explains.