Version: May 2025

Live Timecode Notes

This is the API documentation to our tool "Live Timecode Notes", "Timecode Notes" and Live Notes (iOS/macOS) app. It allows to create and edit projects and to create and manage time related notes.

We welcome your feedback! Is there a feature you need to access via API? If so, please let us know, along with the workflow you are trying to create.

Create Project

This endpoint is used to create a new project on the server.

Endpoint

POST https://api.editingtools.io/v2/livenotes/project

Authentication

This endpoint requires Basic Authentication using the personal API key. The `Authorization` header should be set with the Base64 encoded string of `apikey:YOUR_API_KEY`.

Authorization: Basic <base64Encoded(apikey:YOUR_API_KEY)>

Headers

Content-Type: application/json

Specifies the format of the request body.

Authorization: Basic <base64EncodedString>

Authentication credential (as described above).

Request Body (JSON)

The request body should be a JSON object containing the following parameters:

Parameter Type Required Description
name String Yes The name of the project (String 3-50 characters).
color String No The color of the project. If there is no value set, "pink" will be used as default value.
Allowed colors: blue, cyan, fuchsia, green, lavender, lemon, mint, orange, pink, purple, red, sky, yellow, white
tone String No The Endpoint accepts tone as alternative parameter for color.
framerate String No The framerate of the project (e.g., "25", "30"). If there is no value set, "25" will be used as default value.
type String No The value defines the project type. Default value is: live for live timecode and time of day.
Alternative: custom for individual manual timecode
location String No Location information (e.g. Studio 1)
shootingDay String No Shooting day information (e.g. Day or Date)
loggerName String No The name of the person creating the project.
isArchived Boolean No Sets a flag to archive the project. Default value is false.
false = active project, true = Archived project
quickActions Object No Optional object with quick action buttons for advanced requests.
Parameter Type Required Description
name String Yes Name of the button.
comment String Yes The comment that will be added in the note.
color String No The color of the button. If there is no value set, "pink" will be used as default value.
Allowed colors: blue, cyan, fuchsia, green, lavender, lemon, mint, orange, pink, purple, red, sky, yellow, white
tone String No The API accepts tone as alternative parameter for color.
order Int No Optional order of button.
hotkey Char No Optional hotkey for the button (not supported in iOS/macOS app). One letter/number to be used with either CTRL+ALT+{hotkey} or CTRL+SHIFT+{hotkey}. (For example 1 for "CTRL+ALT+1" and "CTRL+SHIFT+1).
tagGroups Object No Optional object with tag groups for advanced requests.
Parameter Type Required Description
tagGroup.name String Yes Name of the tag group/category.
tags Object Yes Object with tags. Can contain one or more entries.
Parameter Type Required Description
text String Yes Text content of the tag.
order Int No Optional order of tag element inside tags.
name String No Optional display name of tag (not supported in iOS/macOS app).
color String No Optional color of tag (not supported in iOS/macOS app). Allowed colors: blue, cyan, fuchsia, green, lavender, lemon, mint, orange, pink, purple, red, sky, yellow, white

Example Request Body 1 - only required parameters

{
    "name": "My New Project"
}

Example Request Body 2 - simple

{
    "name": "My New Project",
    "color": "green",
    "framerate": "30",
    "location": "Studio A",
    "shootingDay": "Day 1",
    "loggerName": "John Doe"
}

Example Request Body 3 - with quickActions and tagGroups

{
    "name": "My New Project",
    "color": "green",
    "framerate": "30",
    "location": "Studio A",
    "shootingDay": "Day 1",
    "loggerName": "John Doe",
    "isArchived": "0",
    "quickActions" : [
    	{"name" : "Action", "color" : "green", "comment" : "Action" },
    	{"name" : "Cut", "color" : "red", "comment" : "Cut"}
    ],
    "tagGroups" : [
    	{ "tagGroup" : 
    		{ "name" : "Cameras" },
          "tags" : [
          	{ "text" : "Camera 1" },
          	{ "text" : "Camera 2" }
          ] 
        },
        { "tagGroup" : 
        	{ "name" : "Actors" },
          "tags" : [
          	{ "text" : "Anna" },
          	{ "text" : "Steve" }
          ]
        }
    ]
}

cURL Examples

The following examples show how to use the API with cURL commands. If you are using a different language, we recommend using https://curlconverter.com to convert the commands for other languages like: PHP, JavaScript, Python, Ruby, Rust, Ansible, C , C#, ColdFusion, Clojure, Dart, Elixir, Go, HAR, HTTP, HTTPie, Java, JSON, Kotlin, MATLAB, Node.js, Objective-C, OCaml, PowerShell, R, Swift and more.

cURL Request Example 1 - only required parameters

curl -X POST https://api.editingtools.io/v2/livenotes/project \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Project"
}'

cURL Request Example 2 - all basic parameters

curl -X POST https://api.editingtools.io/v2/livenotes/project \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Project",
    "color": "green",
    "framerate": 30,
    "location": "Studio A",
    "shootingDay": "Day 1",
    "loggerName": "John Doe"
}'

cURL Request Example 3 - with quickActions and tagGroups

curl -X POST https://api.editingtools.io/v2/livenotes/project \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Project",
    "color": "green",
    "framerate": 30,
    "location": "Studio A",
    "shootingDay": "Day 1",
    "loggerName": "John Doe",
    "isArchived": false,
    "quickActions" : [
    	{"name" : "Action", "color" : "green", "comment" : "Action" },
    	{"name" : "Cut", "color" : "red", "comment" : "Cut"}
    ],
    "tagGroups" : [
    	{ "tagGroup" : 
    		{ "name" : "Cameras" },
          "tags" : [
          	{ "text" : "Camera 1" },
          	{ "text" : "Camera 2" }
          ] 
        },
        { "tagGroup" : 
        	{ "name" : "Actors" },
          "tags" : [
          	{ "text" : "Anna" },
          	{ "text" : "Steve" }
          ]
        }
    ]
}'

Responses

Success (HTTP 201 Created)

If the request is successful, the API will return a 201 Created status code with a JSON object containing the project id and keys.

Field Type Description
code String HTTP status code.
status String Status message.
timestamp String Server time of the request (ISO 8601).
data Object An object containing details about the created project.
data.projectId String A unique identifier for the project.
data.projectKey String A key associated with the project.
data.projectApiKey String An API key for the project.
data.creationDate String Timestamp of project creation (ISO 8601).

Example

{
    "code": "201",
    "status": "The project was successfully created.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": {
        "projectId": "rcwo9binm0xo8wt9vpfz16pt5pypju",
        "projectKey": "ivn39cgw4qhz4qs20uov3e006r",
        "projectApiKey": "2b74e223b49d7c138cf485c",
        "creationDate": "2025-01-01T19:10:00Z"
    }
}

Error Responses (Example)

Error responses will typically include an appropriate HTTP status code (e.g., 400 Bad Request, 401 Unauthorized) and a JSON body with an error message.

It's recommended that the content of the "status" field be shown to end users as it can contain useful information. For example, it could be shown in an error dialog.

{
    "code": "400",
    "status": "Missing required parameter: name",
    "timestamp": "2025-01-01T19:10:00Z",
}
{
    "code": "401",
    "status": "Invalid API Key",
    "timestamp": "2025-01-01T19:10:00Z"
}

Get Projects (List of all projects)

This endpoint allows to get a list of all projects with the associated user account on EditingTools.io.

Endpoint

GET https://api.editingtools.io/v2/livenotes/projects

Headers

Content-Type: application/json

Specifies the format of the request body.

Authorization: Basic <base64EncodedString>

Authentication credential using your `YOUR_API_KEY`.

cURL Request Example 1

curl -X GET https://api.editingtools.io/v2/livenotes/projects \
-u "apikey:YOUR_API_KEY"

Responses

Success (HTTP 200 OK)

If the projects were successfully loaded, the API will return a 200 OK status code with a JSON object containing all existing projects.

Field Type Description
code String HTTP status code.
status String Status message.
timestamp String Server time of the request (ISO 8601).
data Object An object containing details about the projects.
Field Type Description
name String The name of the project.
color String The color of the project.
tone String The color of the project (alternative parameter for color).
framerate String The framerate of the project.
type String Type of project: live for live timecode and time of day, custom for individual manual timecode projects
location String Location information (e.g. Studio 1).
shootingDay String Shooting day information (e.g. Day or Date).
loggerName String The name of the person creating the project.
totalNotes Int Counter of notes in project.
isArchived Boolean Status of project. true = Archived project, false = Active project
projectId String A unique identifier for the project.
projectKey String A key associated with the project.
projectApiKey String An API key for the project.
url String Share Url to open the project in web browser.
lastUpdate String Timestamp of project update (ISO 8601).
creationDate String Timestamp of project creation (ISO 8601).

Example

{
    "code": "200",
    "status": "The projects were successfully loaded.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": [
        {
            "name": "My Project 398",
            "color": "green",
            "tone": "green",
            "framerate": 30,
            "type": "live",
            "location": "Studio A",
            "shootingDay": "Day 1",
            "loggerName": "John Doe",
            "totalNotes": 52,
            "isArchived": false,
            "projectId": "6u00p3lz1ycwixs3g2kq0nx3qkroskxiw8o578wx99dor8zn",
            "projectKey": "6p3qrsul3tgi0gu3kegiuk68w7b2o204zz0za8vlff37w7u",
            "projectApiKey": "xdaxhff1rb3b8qvs",
            "url": "https://editingtools.io/demo/url",
            "lastUpdate": "2025-05-17T09:17:52Z",
            "createdDate": "2025-05-01T08:20:00Z"
        },
        {
            "name": "My Project 983",
            "color": "blue",
            "tone": "blue",
            "framerate": 25,
            "type": "custom",
            "location": "Studio A",
            "shootingDay": "Day 1",
            "loggerName": "John Doe",
            "totalNotes": 147,
            "isArchived": true,
            "projectId": "nz1thfewx86pirs8etj51huxnfk6sbaytmlb62lghyt64kvs",
            "projectKey": "z00cv3wtq8j7rcyo0pj55qmo3ob3ilh94hd290p2iafybca",
            "projectApiKey": "84jw24oba2kvhayp",
            "url": "https://editingtools.io/demo/url",
            "lastUpdate": "2025-05-12T10:00:34Z",
            "createdDate": "2025-05-01T10:20:52Z"
        }
    ]
    
}

Error Responses

Error responses will typically include an appropriate HTTP status code and a JSON body with an error message.

{
    "code": "404",
    "status": "No projects were found.",
    "timestamp": "2025-01-01T19:10:00Z"
}

Get Project (Details about a specific project)

This endpoint retrieves all details of a project. The projectId and projectKey must be specified directly in the URL path.

(!) This endpoint can also be used with the project API key.

Endpoint

GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}

Replace {projectId} with the project's unique ID and {projectKey} with the project's specific key.

Headers

Content-Type: application/json

Specifies the format of the request body.

Authorization: Basic <base64EncodedString>

Authentication credential using your `YOUR_API_KEY` or `PROJECT_API_KEY`.

Path Parameters

Parameter Type Description
projectId String The unique identifier of the project.
projectKey String The specific key associated with the project.

cURL Request Example 1 - using Personal API Key

curl -X GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey} \
  -u "apikey:YOUR_API_KEY"

cURL Request Example 2 - using Project API Key

curl -X GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey} \
  -u "projectapikey:PROJECT_API_KEY"

Responses

Success (HTTP 200 OK)

If the project is successfully updated, the API will return a 200 OK status code with a JSON object containing the project details.

Field Type Description
code String HTTP status code.
status String A descriptive message about the update.
timestamp String Server time of the request (ISO 8601).
data Object Contains an object with the project details.

Data Object

The data contains the same (necessary) information as a project transfer file.

Field Type Description
name String The name of the project.
color String The color of the project.
tone String The color of the project (alternative parameter for color).
framerate String The framerate of the project.
type String Type of project: live for live timecode and time of day, custom for individual manual timecode projects
location String Location information (e.g. Studio 1).
shootingDay String Shooting day information (e.g. Day or Date).
loggerName String The name of the person creating the project.
totalNotes Int Counter of notes in project.
isArchived Boolean Status of project. true = Archived project, false = Active project
projectId String A unique identifier for the project.
projectKey String A key associated with the project.
projectApiKey String An API key for the project.
url String Share Url to open the project in web browser.
lastUpdate String Timestamp of project update (ISO 8601).
creationDate String Timestamp of project creation (ISO 8601).
quickActions Object Object with quick action buttons.
Field Type Description
name String Name of the button.
comment String The comment that will be added in the note.
color String The color of the button.
tone String The color of the button (alternative parameter for color).
hotkey Char Optional hotkey for the button (not supported in iOS/macOS app). One letter/number to be used with either CTRL+ALT+{hotkey} or CTRL+SHIFT+{hotkey}. (For example 1 for "CTRL+ALT+1" and "CTRL+SHIFT+1).
createdAt Double (This parameter is only used in iOS/macOS app.) For online projects it returns 0.
order Int Value to change order of object. Default: 0
sessionId Int (This parameter is used on in iOS/macOS app). For online projects it returns 0.
tagGroups Object Object with tag groups.
Field Type Description
tagGroup.name String Name of the group.
tagGroup.id Int Group Id
tagGroup.sessionId Int (This parameter is used on in iOS/macOS app). For online projects it returns 0.
tagGroup.createdAt Int (This parameter is used on in iOS/macOS app). For online projects it returns 0.
tags Object Object with tags. Can contain one or more entries.
Field Type Description
text String Name of tag.
name String Optional display name of tag (not supported in iOS/macOS app).
color String Optional color of tag (not supported in iOS/macOS app).
createdAt Double (This parameter is used on in iOS/macOS app). For online projects it returns 0.
order Int Alternative tag order set by user
tagGroupId Int GroupId
notes Object Object with new or updated notes. It is only returned when the notes have been updated. It only contains the changes.
Field Type Description
noteId String The noteID provided by the server.
isDeleted Boolean If a note is requested to be deleted. true = deleted, false = exists
lastUpdate String Timestamp of last note update (ISO 8601) on server.
creationDate String Timestamp of note creation (ISO 8601) on server.
note Object Object with tags. Can contain one or more entries.
Field Type Description
timecode String The timecode (SMPTE HH:MM:SS:FF).
comment String The comment.
loggerName String Name of the Commenter.
name String Name of the note.
color String Color of note. If not set, default color "blue".
tone String Color (alternative for color parameter).
createdAt Double (This parameter is used on in iOS/macOS app). For online projects it returns 0.
sessionId Int (This parameter is used on in iOS/macOS app). For online projects it returns 0.
tags Object Object with tags. Can contain one or more entries.
Field Type Description
text String Name of tag.
tagGroupId Int GroupId
order Int Value to change order of object. Default: 0
createdAt Double This parameter is used in offline projects. For online projects it usually returns "0".

Example

{
    "code": "200",
    "status": "The project has been loaded successfully.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": {
        "name": "My Project 398",
        "color": "green",
        "tone": "green",
        "framerate": 30,
        "type": "live",
        "location": "Studio A",
        "shootingDay": "Day 1",
        "loggerName": "John Doe",
        "totalNotes": 52,
        "isArchived": false,
        "projectId": "6u00p3lz1ycwixs3g2kq0nx3qkroskxiw8o578wx99dor8zn",
        "projectKey": "6p3qrsul3tgi0gu3kegiuk68w7b2o204zz0za8vlff37w7u",
        "projectApiKey": "xdaxhff1rb3b8qvs",
        "url": "https://editingtools.io/demo/url",
        "lastUpdate": "2025-05-17T09:17:52Z",
        "createdDate": "2025-05-01T08:20:00Z",
        "quickActions": [
            {
                "name": "Action",
                "color": "green",
                "tone": "green",
                "comment": "Action",
                "hotkey" : "",
                "createdAt": 0,
                "order": 0,
                "sessionId": 0
            },
            {
                "name": "Cut",
                "color": "red",
                "tone": "red",
                "comment": "Cut",
                "hotkey" : "",
                "createdAt": 0,
                "order": 0,
                "sessionId": 0
            }
        ],
        "tagGroups": [
            {
                "tagGroup": {
                    "name": "Cameras",
                    "id": 1,
                    "sessionId": 0,
                    "createdAt": 0
                },
                "tags": [
                    {
                        "text": "Camera 1",
                        "name": "Camera 1",
                        "color": "",
                        "createdAt": 0,
                        "order": 0,
                        "tagGroupId": 1
                    },
                    {
                        "text": "Camera 2",
                        "name": "Camera 2",
                        "color": "",
                        "createdAt": 0,
                        "order": 0,
                        "tagGroupId": 1
                    }
                ]
            },
            {
                "tagGroup": {
                    "name": "Actors",
                    "id": 2,
                    "sessionId": 0,
                    "createdAt": 0
                },
                "tags": [
                    {
                        "text": "Anna",
                        "name": "Anna",
                        "color": "",
                        "createdAt": 0,
                        "order": 0,
                        "tagGroupId": 2
                    },
                    {
                        "text": "Steve",
                        "name": "Steve",
                        "color": "",
                        "createdAt": 0,
                        "order": 0,
                        "tagGroupId": 2
                    }
                ]
            }
        ],
        "notes": [
            {
                "noteId": "4slmgcppqjnt07ag7hhobzi88tc0oo2yefixfjyr8oi9qez",
                "isDeleted": 0,
                "lastUpdate": "2025-05-17T08:54:50Z",
                "creationDate": "2025-05-17T08:54:50Z",
                "note": {
                	"timecode": "19:08:18:09",
                    "name": "Race Start",
                    "comment": "Race Start",
                    "color": "sky",
                    "tone": "sky",
                    "loggerName": "David",
                    "createdAt": 0,
                    "sessionId": 0,
                },
                "tags": [
                    {
                        "text": "Camera 2",
                        "createdAt": 0,
                        "tagGroupId": 1,
                        "order": 0
                    }
                ]
            }
        ]
    }
}

Error Responses

Error responses will typically include an appropriate HTTP status code and a JSON body with an error message.

{
    "code": "404",
    "status": "The project could not be found.",
    "timestamp": "2025-01-01T19:10:00Z"
}

Update Project

This endpoint allows to partially update an existing project. The projectId and projectKey have to be specify directly in the URL path. Only the fields that should be changed have to be send. If one of the parameters in quickActions or tagGroups should be changed, the complete object (all buttons/all tags) needs to be send.

Endpoint

PATCH https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}

Replace {projectId} with the project's unique ID and {projectKey} with the project's specific key.

Headers

Content-Type: application/json

Specifies the format of the request body.

Authorization: Basic <base64EncodedString>

Authentication credential using your `YOUR_API_KEY`.

Path Parameters

Parameter Type Description
projectId String The unique identifier of the project to update.
projectKey String The specific key associated with the project. This acts as an additional identifier/security measure in the URL.

Request Body (JSON)

The request body should be a JSON object containing only the fields you want to update. Any fields not included will retain their current values. All parameters listed are optional for a `PATCH` operation, but at least one must be provided.

(!) To update one quick action button, the whole quickActions object needs to be send, containing all buttons.

(!) To update one tag, the whole tagGroups object needs to be send, containing all tag groups and all tags.

Parameter Type Required Description
name String Yes The name of the project (String 3-50 characters).
color String No The color of the project. If there is no value set, "pink" will be used as default value.
Allowed colors: blue, cyan, fuchsia, green, lavender, lemon, mint, orange, pink, purple, red, sky, yellow, white
tone String No The Endpoint accepts tone as alternative parameter for color.
framerate String No The framerate of the project (e.g., "25", "30"). If there is no value set, "25" will be used as default value.
location String No Location information (e.g. Studio 1)
shootingDay String No Shooting day information (e.g. Day or Date)
loggerName String No The name of the person creating the project.
isArchived Boolean No Sets a flag to archive the project. Default value is false.
false = active project, true = Archived project
quickActions Object No Optional object with quick action buttons for advanced requests.
Parameter Type Required Description
name String Yes Name of the button.
comment String Yes The comment that will be added in the note.
color String No The color of the button. If there is no value set, "pink" will be used as default value.
Allowed colors: blue, cyan, fuchsia, green, lavender, lemon, mint, orange, pink, purple, red, sky, yellow, white
tone String No The API accepts tone as alternative parameter for color.
order Int No Optional order of button.
hotkey Char No Optional hotkey for the button (not supported in iOS/macOS app). One letter/number to be used with either CTRL+ALT+{hotkey} or CTRL+SHIFT+{hotkey}. (For example 1 for "CTRL+ALT+1" and "CTRL+SHIFT+1).
tagGroups Object No Optional object with tag groups for advanced requests.
Parameter Type Required Description
tagGroup.name String Yes Name of the tag group/category.
tags Object Yes Object with tags. Can contain one or more entries.
Parameter Type Required Description
text String Yes Text content of the tag.
order Int No Optional order of tag element inside tags.
name String No Optional display name of tag (not supported in iOS/macOS app).
color String No Optional color of tag (not supported in iOS/macOS app). Allowed colors: blue, cyan, fuchsia, green, lavender, lemon, mint, orange, pink, purple, red, sky, yellow, white

Example Request Body 1 - update name and color

{
    "name": "Project Alpha - Revised",
    "color": "yellow"
}

Example Request Body 2 - update quick action buttons

{
    "quickActions" : [
    	{"name" : "Explosion", "color" : "red", "comment" : "Big Boom" },
    	{"name" : "Cut", "color" : "red", "comment" : "Cut"}
    ]
}

Example Request Body 3 - update tags

{
    "tagGroups" : [
    	{ "tagGroup" : 
    		{ "name" : "Cameras" },
          "tags" : [
          	{ "text" : "Camera 1" },
          	{ "text" : "Camera 2" },
          	{ "text" : "Camera 3" },
          	{ "text" : "Camera 4" },
          	{ "text" : "GoPro" }
          
          ]
        },
        { "tagGroup" : 
        	{ "name" : "Actors" },
          "tags" : [
          	{ "text" : "Anna" },
          	{ "text" : "Marek" },
          	{ "text" : "Tom" }
          ]
        }
    ]
}

cURL Examples

The following examples show how to use the API with cURL commands. If you are using a different language, we recommend using https://curlconverter.com to convert the commands for other languages like: PHP, JavaScript, Python, Ruby, Rust, Ansible, C , C#, ColdFusion, Clojure, Dart, Elixir, Go, HAR, HTTP, HTTPie, Java, JSON, Kotlin, MATLAB, Node.js, Objective-C, OCaml, PowerShell, R, Swift and more.

cURL Request Example 1 - update name and color

curl -X PATCH https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey} \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Alpha - Revised",
    "color": "yellow"
}'

cURL Request Example 2 - update quick action buttons

curl -X PATCH https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey} \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quickActions" : [
    	{"name" : "Explosion", "color" : "red", "comment" : "Big Boom" },
    	{"name" : "Cut", "color" : "red", "comment" : "Cut"}
    ]
}'

cURL Request Example 3 - update tags

curl -X PATCH https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey} \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tagGroups" : [
    	{ "tagGroup" : 
    		{ "name" : "Cameras" },
          "tags" : [
          	{ "text" : "Camera 1" },
          	{ "text" : "Camera 2" },
          	{ "text" : "Camera 3" },
          	{ "text" : "Camera 4" },
          	{ "text" : "GoPro" }
          
          ]
        },
        { "tagGroup" : 
        	{ "name" : "Actors" },
          "tags" : [
          	{ "text" : "Anna" },
          	{ "text" : "Marek" },
          	{ "text" : "Tom" }
          ]
        }
    ]
}'

Responses

Success (HTTP 200 OK)

If the project is successfully updated, the API will return a 200 OK status code with a JSON object confirming the update.

{
    "code": "200",
    "status": "The project was successfully updated.",
    "timestamp": "2025-01-01T19:10:00Z"
}
Field Type Description
code String HTTP status code.
status String A descriptive message about the update.

Error Responses

Error responses will typically include an appropriate HTTP status code and a JSON body with an error message.

{
    "code": "400",
    "status": "The project was not updated.",
    "timestamp": "2025-01-01T19:10:00Z"
}

Delete Project

This endpoint is used to delete a project from server. The project is identified by its projectId and projectKey in the URL path.

For safety reasons, this endpoint is disabled by default, which means projects cannot be deleted from the server using the API. Instead use the website to delete projects. If you need this feature, please contact support, to get your API KEY unlocked for this endpoint.

Endpoint

DELETE https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}

Replace {projectId} with the project's unique ID and {projectKey} with the project's specific key.

Headers

Content-Type: application/json

Specifies the format of the request body.

Authorization: Basic <base64EncodedString>

Authentication credential using `YOUR_API_KEY`.

Path Parameters

Parameter Type Description
projectId String The unique identifier of the project.
projectKey String The specific key associated with the project.

cURL Request Example

curl -X DELETE https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey} \
  -u "apikey:YOUR_API_KEY"

Responses

Success (HTTP 200 OK)

If the project was successfully deleted, the API will return a 200 OK status code with a JSON object confirming the update and the updated project details.

{
    "code": "200",
    "status": "The project has been successfully deleted.",
    "timestamp": "2025-01-01T19:10:00Z"
}

Error Responses

Error responses will typically include an appropriate HTTP status code and a JSON body with an error message.

{
    "code": "400",
    "status": "Project could not be deleted.",
    "timestamp": "2025-01-01T19:10:00Z"
}

Create Note(s) / Update Note(s)

This endpoint can be used to:

  • create one or multiple new notes
  • update one or multiple notes
  • delete one or multiple notes
The project is identified by its projectId and projectKey in the URL path.

Endpoint

POST https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/notes

Replace {projectId} with the project's unique ID and {projectKey} with the project's specific key.

Headers

Content-Type: application/json

Specifies the format of the request body.

Authorization: Basic <base64EncodedString>

Authentication credential using `PROJECT_API_KEY` or `YOUR_API_KEY`.

Path Parameters

Parameter Type Description
projectId String The unique identifier of the project to which the note will be added.
projectKey String The specific key associated with the project.

Request Body (JSON)

The request body should be a JSON object containing the details of the note to be added.

Parameter Type Required Description
noteId String No/Yes The noteID is only required if a note should be updated. If noteId is empty, the note will created as new note.
timecode String Yes The timecode (SMPTE HH:MM:SS:FF).
comment String Yes The comment itself.
loggerName String Yes Name of the Commenter.
name String No Name of the note.
color String No Color of note. If not set, default color "pink".
tone String No Color (accepted as alternative for color parameter).
localId String No Optional localId of note to resolve the response.
isDeleted Boolean No Request note to be deleted with next update. If set to true the note will marked as deleted.
tags Object/String No An optional list of tags associated with the note (e.g., ["B-roll", "Interview"]).

Example 1 - create one new note (minimal requirements)

Create a note with the minimum requirements: "timecode," "comment," and "loggerName." Also add "localId" with your local storage ID. This value will be included in the response with the note ID provided by the server. The localId will not be stored on the server.

Request Body

{
    "timecode": "10:01:30:15",
    "comment": "Subject A enters frame. Good interview moment.",
    "loggerName": "John",
    "localId": 23
}

cURL Request

curl -X POST https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/notes \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timecode": "10:01:30:15",
    "comment": "Subject A enters frame. Good interview moment.",
    "loggerName": "John",
    "localId": 23
}'

Response (HTTP 200 OK)

If the request was successfully, the API will return a 200 status code with a JSON object.

The noteId is provided together with the localId. Its recommended to store the noteId and noteKey, as it is required to update the note later.

{
    "code": "200",
    "status": "The notes in the project have been successfully updated.",
    "data": [
        {
            "localId": 23,
            "noteId": "4slmgcppqjnt07ag7hhobzi88tc0oo2yefixfjyr8oi9qez8",
            "noteKey": "cbtew87wt87gsdzsdibcuduit",
            "status": "added",
            "creationDate": "2025-05-17T16:16:23Z"
        }
    ]
}
Field Type Description
code String HTTP status code.
status String A descriptive message about the note creation.
timestamp String Server time of the request (ISO 8601).
data Object An object containing the details of the newly created note.
data.noteId String A unique identifier for the newly created note.
data.noteKey String The Key for the newly created note.
data.localId String LocalId gets returned if send.
data.status String Status of action: created, updated, deleted

Example 2 - create one new note

Create a note with tags and color.

Request Body

{
    "timecode": "10:01:30:15",
    "comment": "Subject A enters frame. Good interview moment.",
    "name": "Interview",
    "color": "yellow",
    "loggerName": "John",
    "localId": 23,
    "tags": ["Interview", "GoodTake", "Camera 1"]
}

cURL Request

curl -X POST https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/notes \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timecode": "10:01:30:15",
    "comment": "Subject A enters frame. Good interview moment.",
    "name": "Interview",
    "color": "yellow",
    "loggerName": "John",
    "localId": 23,
    "tags": ["Interview", "GoodTake", "Camera 1"]
}'

Response (HTTP 200 OK)

If the request was successfully, the API will return a 200 status code with a JSON object.

{
    "code": "200",
    "status": "The notes were updated successfully.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": [
        {
            "localId": 23,
            "noteId": "4slmgcppqjnt07ag7hhobzi88tc0oo2yefixfjyr8oi9qez8",
            "status": "updated",
        }
    ]
}

Example 3 - create multiple notes

Create multiple note with different values.

Request Body

[{
    "timecode": "10:01:30:15",
    "comment": "Subject A enters frame. Good interview moment.",
    "name": "Interview",
    "color": "yellow",
    "loggerName": "John",
    "localId": 23,
    "tags": ["Interview", "GoodTake", "Camera 1"]
},{
    "timecode": "10:01:32:15",
    "comment": "test 2",
    "name": "Interview",
    "color": "red",
    "loggerName": "John",
    "localId": 24
}]

cURL Request

curl -X POST https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/notes \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{
    "timecode": "10:01:30:15",
    "comment": "Subject A enters frame. Good interview moment.",
    "name": "Interview",
    "color": "yellow",
    "loggerName": "John",
    "localId": 23,
    "tags": ["Interview", "GoodTake", "Camera 1"]
},{
    "timecode": "10:01:32:15",
    "comment": "test 2",
    "name": "Interview",
    "color": "red",
    "loggerName": "John",
    "localId": 24
}]'

Response (HTTP 200 OK)

If the request was successfully, the API will return a 200 status code with a JSON object.

{
    "code": "200",
    "status": "The notes were updated successfully.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": [
        {
            "localId": 23,
            "noteId": "4slmgcppqjnt07ag7hhobzi88tc0oo2yefixfjyr8oi9qez8",
            "status": "created"
        },
        {
            "localId": 24,
            "noteId": "0oo2yefixfjyr8oi9qez84slmgcppqjnt07ag7hhobzi88tc",
            "status": "created"
        }
    ]
}

Example 4 - update a note

Update an existing note by providing the noteId in the request.

Request Body

{
    "noteId": "4slmgcppqjnt07ag7hhobzi88tc0oo2yefixfjyr8oi9qez8",                   
    "timecode": "10:01:30:20",
    "comment": "Changed the comment text",
    "name": "Interview",
    "color": "yellow",
    "loggerName": "John",
    "tags": ["Interview", "GoodTake", "Camera 1"]
}

cURL Request

curl -X POST https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/notes \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "noteId": "4slmgcppqjnt07ag7hhobzi88tc0oo2yefixfjyr8oi9qez8",                   
    "timecode": "10:01:30:20",
    "comment": "Changed the comment text",
    "name": "Interview",
    "color": "yellow",
    "loggerName": "John",
    "tags": ["Interview", "GoodTake", "Camera 1"]
}'

Response (HTTP 200 OK)

If the request was successfully, the API will return a 200 status code with a JSON object.

{
    "code": "200",
    "status": "The notes were updated successfully.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": [
        {
            "noteId": "4slmgcppqjnt07ag7hhobzi88tc0oo2yefixfjyr8oi9qez8",
            "status": "updated"
        }
    ]
}

Example 5 - delete a note

A note can be deleted from server by providing the noteId and set the value isDeleted to 1.

Request Body

{
    "noteId": "4slmgcppqjnt07ag7hhobzi88tc0oo2yefixfjyr8oi9qez8",                   
    "isDeleted": true
}

cURL Request

curl -X POST https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/notes \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "noteId": "4slmgcppqjnt07ag7hhobzi88tc0oo2yefixfjyr8oi9qez8",                   
    "isDeleted": true
}'

Response (HTTP 200 OK)

If the request was successfully, the API will return a 200 status code with a JSON object.

{
    "code": "200",
    "status": "The notes were updated successfully.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": [
        {
            "noteId": "4slmgcppqjnt07ag7hhobzi88tc0oo2yefixfjyr8oi9qez8",
            "status": "deleted"
        }
    ]
}

Error Responses

Error responses will typically include an appropriate HTTP status code and a JSON body with an error message.

{
    "code": "400",
    "status": "Could not save changes.",
    "timestamp": "2025-01-01T19:10:00Z"
}

Get Updates

This endpoint is used to get updates from a project from a specific timestamp. It can return changes regarding the project details but also changes in tags and notes. The project is identified by its projectId and projectKey in the URL path.

Endpoint

GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/updates/{timestamp}

Replace {projectId} with the project's unique ID and {projectKey} with the project's specific key. Set the {timestamp} from the last call, to fetch all changes in between.

Headers

Content-Type: application/json

Specifies the format of the request body.

Authorization: Basic <base64EncodedString>

Authentication credential using `PROJECT_API_KEY` or `YOUR_API_KEY`.

Path Parameters

Parameter Type Description
projectId String The unique identifier of the project containing the note.
projectKey String The specific key associated with the project.
timestamp String Timestamp of last project update (ISO 8601). Example value: "2025-05-17T15:48:35Z". Set 0 to load all.

cURL Request Example 1 - using Personal API Key

curl -X GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/updates/{timestamp} \
  -u "apikey:YOUR_API_KEY"

cURL Request Example 2 - using Project API Key

curl -X GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/updates/{timestamp} \
  -u "projectapikey:PROJECT_API_KEY"

Responses

Field Type Description
code String HTTP status code.
status String A descriptive message about the update.
timestamp String Server time of the request (ISO 8601).
data Object Contains an object with the project details.

Data Object

Field Type Description
name String The name of the project.
isArchived Boolean Status of project. true = Archived project, false = Active project
quickActions Object Object with quick action buttons.
Field Type Description
name String Name of the button.
comment String The comment that will be added in the note.
color String The color of the button.
tone String The color of the button (alternative parameter for color).
hotkey Char Optional hotkey for the button (not supported in iOS/macOS app). One letter/number to be used with either CTRL+ALT+{hotkey} or CTRL+SHIFT+{hotkey}. (For example 1 for "CTRL+ALT+1" and "CTRL+SHIFT+1).
createdAt Double (This parameter is only used in iOS/macOS app.) For online projects it returns 0.
order Int Value to change order of object. Default: 0
sessionId Int (This parameter is used on in iOS/macOS app). For online projects it returns 0.
tagGroups Object Object with tag groups.
Field Type Description
tagGroup.name String Name of the group.
tagGroup.id Int Group Id
tagGroup.sessionId Int (This parameter is used on in iOS/macOS app). For online projects it returns 0.
tagGroup.createdAt Int (This parameter is used on in iOS/macOS app). For online projects it returns 0.
tags Object Object with tags. Can contain one or more entries.
Field Type Description
text String Name of tag.
name String Optional display name of tag (not supported in iOS/macOS app).
color String Optional color of tag (not supported in iOS/macOS app).
createdAt Double (This parameter is used on in iOS/macOS app). For online projects it returns 0.
order Int Alternative tag order set by user
tagGroupId Int GroupId
notes Object Object with new or updated notes. It is only returned when the notes have been updated. It only contains the changes.
Field Type Description
noteId String The noteID provided by the server.
isDeleted Boolean If a note is requested to be deleted. true = deleted, false = exists
lastUpdate String Timestamp of last note update (ISO 8601) on server.
creationDate String Timestamp of note creation (ISO 8601) on server.
note Object Object with tags. Can contain one or more entries.
Field Type Description
timecode String The timecode (SMPTE HH:MM:SS:FF).
comment String The comment.
loggerName String Name of the Commenter.
name String Name of the note.
color String Color of note. If not set, default color "blue".
tone String Color (alternative for color parameter).
createdAt Double (This parameter is used on in iOS/macOS app). For online projects it returns 0.
sessionId Int (This parameter is used on in iOS/macOS app). For online projects it returns 0.
tags Object Object with tags. Can contain one or more entries.
Field Type Description
text String Name of tag.
tagGroupId Int GroupId
order Int Value to change order of object. Default: 0
createdAt Double This parameter is used in offline projects. For online projects it usually returns "0".

Success (HTTP 200 OK)

If the changes are successfully loaded, the API will return a 200 status code with a JSON object containing the changes.

(!) The response will only contain objects if an update was provided. Otherwise, the data object is empty.

(!) Before adding notes from this response to a local list, check to see if the note with the given note ID already exists. If so, replace it, as it may have changed.

(!) If a note contains "isDeleted" = 1" it means the user deleted the note locally. It's recommended that you remove the note as well.

(!) If a project isArchived= true, there will likely be no more updates. It's recommend to stop any more update requests.

Example Response 1 - no update

{
    "code": "200",
    "status": "The latest updates were successfully loaded.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": []
}

Example Response 2 - two notes added/updated

{
    "code": "200",
    "status": "The latest updates were successfully loaded.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": {
        "notes": [
            {
                "noteId": "jlg72c8jx054g0tz2x5zuri3wpyz3pe4a13007gw9240l1hw",
                "isDeleted": 0,
                "creationDate": "2025-05-17T15:48:35Z",
                "note": {
                    "name": "Crew Chief",
                    "color": "sky",
                    "tone": "sky",
                    "comment": "Crew Chief",
                    "timecode": "19:08:18:09",
                    "createdAt": 0,
                    "sessionId": 0
                },
                "tags": [
                    {
                        "text": "Camera 2",
                        "createdAt": 0,
                        "tagGroupId": 1,
                        "order": 0
                    }
                ]
            },
            {
                "noteId": "hw4ttre09qqtxh0lhr9cxwan2s53h1ucuaj85sjfsh8gdmhj",
                "isDeleted": 0,
                "creationDate": "2025-05-17T15:48:35Z",
                "note": {
                    "name": "Crew Chief",
                    "color": "sky",
                    "tone": "sky",
                    "comment": "Crew Chief",
                    "timecode": "19:08:20:09",
                    "createdAt": 0,
                    "sessionId": 0
                },
                "tags": [
                    {
                        "text": "Camera 2",
                        "createdAt": 0,
                        "tagGroupId": 1,
                        "order": 0
                    }
                ]
            }
        ]
    }
}

Example Response 3 - tags updated and one note removed

{
    "code": "200",
    "status": "The latest updates were successfully loaded.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": {
        "tagGroups": [
            {
                "tagGroup": {
                    "name": "Cameras",
                    "id": 1,
                    "sessionId": 0,
                    "createdAt": 0
                },
                "tags": [
                    {
                        "text": "Camera 1",
                        "createdAt": 0,
                        "order": 0,
                        "tagGroupId": 1
                    },
                    {
                        "text": "Camera 2",
                        "createdAt": 0,
                        "order": 0,
                        "tagGroupId": 1
                    }
                ]
            },
            {
                "tagGroup": {
                    "name": "Actors",
                    "id": 2,
                    "sessionId": 0,
                    "createdAt": 0
                },
                "tags": [
                    {
                        "text": "Anna",
                        "createdAt": 0,
                        "order": 0,
                        "tagGroupId": 2
                    },
                    {
                        "text": "Steve",
                        "createdAt": 0,
                        "order": 0,
                        "tagGroupId": 2
                    }
                ]
            }
        ],
        "notes": [
            {
                "noteId": "jlg72c8jx054g0tz2x5zuri3wpyz3pe4a13007gw9240l1hw",
                "isDeleted": 1
            }
        ]
    }
}

Example Response 4 - the project name updated and project archived

(!) If a project isArchived=1, there will likely be no more updates. It's recommend to stop any more update requests.

{
    "code": "200",
    "status": "The latest updates were successfully loaded.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": {
    	"name": "Project 1",
    	"isArchived": true
    }
}

Error Responses

Error responses will typically include an appropriate HTTP status code and a JSON body with an error message.

{
    "code": "400",
    "status": "Updates could not be loaded.",
    "timestamp": "2025-01-01T19:10:00Z",
}

Get Notes (multiple)

This endpoint is used to get notes from a specific project. The project is identified by its projectId and projectKey in the URL path.

Endpoint

GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/notes

Replace {projectId} with the project's unique ID and {projectKey} with the project's specific key.

Headers

Content-Type: application/json

Specifies the format of the request body.

Authorization: Basic <base64EncodedString>

Authentication credential using `PROJECT_API_KEY` or `YOUR_API_KEY`.

Path Parameters

Parameter Type Description
projectId String The unique identifier of the project.
projectKey String The specific key associated with the project.
noteId String The unique identifier of the note.

cURL Request Example 1 - using Personal API Key

curl -X GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/notes \
  -u "apikey:YOUR_API_KEY"

cURL Request Example 2 - using Project API Key

curl -X GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/notes \
  -u "projectapikey:PROJECT_API_KEY"

Responses

Field Type Description
code String HTTP status code.
status String A descriptive message about the update.
timestamp String Server time of the request (ISO 8601).
data Object Contains an object with the project details.
Field Type Description
noteId String The noteID provided by the server.
isDeleted Boolean If a note is requested to be deleted. true = deleted, false = exists
lastUpdate String Timestamp of last note update (ISO 8601) on server.
creationDate String Timestamp of note creation (ISO 8601) on server.
note Object Object with tags. Can contain one or more entries.
Field Type Description
timecode String The timecode (SMPTE HH:MM:SS:FF).
comment String The comment.
loggerName String Name of the Commenter.
name String Name of the note.
color String Color of note. If not set, default color "blue".
tone String Color (alternative for color parameter).
createdAt Double (This parameter is used on in iOS/macOS app). For online projects it returns 0.
sessionId Int (This parameter is used on in iOS/macOS app). For online projects it returns 0.
tags Object Object with tags. Can contain one or more entries.
Field Type Description
text String Name of tag.
tagGroupId Int GroupId
order Int Value to change order of object. Default: 0
createdAt Double This parameter is used in offline projects. For online projects it usually returns "0".

Success (HTTP 200 OK)

If the notes are successfully loaded, the API will return a 200 status code with a JSON object.

{
    "code": "200",
    "status": "The notes were successfully loaded.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": [
        {
            "noteId": "x0ll2qzvm9pygk3jt8woigbosb744odfky7leap6c3wequd5",
            "isDeleted": false,
            "lastUpdate": "2025-05-17T19:08:18Z",
            "creationDate": "2025-05-17T19:08:18Z",
            "note": {
                "timecode": "19:08:18:09",
                "color": "sky",
                "tone": "sky",
                "name": "Director",
                "comment": "check",
                "loggerName": "Dave",
                "createdAt": 0,
                "sessionId": 0
            },
            "tags": [
                {
                    "text": "Camera 1",
                    "createdAt": 0,
                    "tagGroupId": 1,
                    "order": 0
                }
            ]
        },
        {
            "noteId": "uo0p44cpgupftgdw40gswpjf54yuuomfdb0b9hstosjgaaq1",
            "isDeleted": false,
            "lastUpdate": "2025-05-17T19:08:50Z",
            "creationDate": "2025-05-17T19:08:50Z",
            "note": {
                "timecode": "19:08:20:49",
                "color": "blue",
                "tone": "blue",
                "name": "Producer",
                "comment": "Have a look at",
                "loggerName": "Tom",
                "createdAt": 0,
                "sessionId": 0
            },
            "tags": [
                {
                    "text": "Camera 2",
                    "createdAt": 0,
                    "tagGroupId": 1,
                    "order": 0
                },
                {
                    "text": "John",
                    "createdAt": 0,
                    "tagGroupId": 2,
                    "order": 0
                }
            ]
        }
    ]
}

Error Responses

Error responses will typically include an appropriate HTTP status code and a JSON body with an error message.

{
    "code": "400",
    "status": "Notes could not be loaded.",
    "timestamp": "2025-01-01T19:10:00Z"
}

Get Note (specific)

This endpoint is used to get a specific note within a project. You identify the project using projectId and projectKey, and the specific note using noteId.

Endpoint

GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/note/{noteId}

Replace {projectId} with the project's unique ID, {projectKey} with the project's specific key and {noteId} with the noteId.

Headers

Content-Type: application/json

Specifies the format of the request body.

Authorization: Basic <base64EncodedString>

Authentication credential using `PROJECT_API_KEY` or `YOUR_API_KEY`.

Path Parameters

Parameter Type Description
projectId String The unique identifier of the project.
projectKey String The specific key associated with the project.
noteId String The unique identifier of the note.

cURL Request Example 1 - using Personal API Key

curl -X GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/note/{noteId} \
  -u "apikey:YOUR_API_KEY"

cURL Request Example 2 - using Project API Key

curl -X GET https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/note/{noteId} \
  -u "projectapikey:PROJECT_API_KEY"

Responses

Field Type Description
code String HTTP status code.
status String A descriptive message about the update.
timestamp String Server time of the request (ISO 8601).
data Object Contains an object with the project details.
Field Type Description
noteId String The noteID provided by the server.
isDeleted Boolean If a note is requested to be deleted. true = deleted, false = exists
lastUpdate String Timestamp of last note update (ISO 8601) on server.
creationDate String Timestamp of note creation (ISO 8601) on server.
note Object Object with tags. Can contain one or more entries.
Field Type Description
timecode String The timecode (SMPTE HH:MM:SS:FF).
comment String The comment.
loggerName String Name of the Commenter.
name String Name of the note.
color String Color of note. If not set, default color "blue".
tone String Color (alternative for color parameter).
createdAt Double (This parameter is used on in iOS/macOS app). For online projects it returns 0.
sessionId Int (This parameter is used on in iOS/macOS app). For online projects it returns 0.
tags Object Object with tags. Can contain one or more entries.
Field Type Description
text String Name of tag.
tagGroupId Int GroupId
order Int Value to change order of object. Default: 0
createdAt Double This parameter is used in offline projects. For online projects it usually returns "0".

Success (HTTP 200 OK)

If the note is successfully loaded, the API will return a 200 status code with a JSON object.

{
    "code": "200",
    "status": "The note was successfully loaded.",
    "timestamp": "2025-01-01T19:10:00Z",
    "data": {
        "noteId": "x0ll2qzvm9pygk3jt8woigbosb744odfky7leap6c3wequd5",
        "isDeleted": false,
        "lastUpdate": "2025-05-17T19:08:18Z",
        "creationDate": "2025-05-17T19:08:18Z",
        "note": {
            "timecode": "19:08:18:09",
            "color": "sky",
            "tone": "sky",
            "name": "Director",
            "comment": "check",
            "loggerName": "Dave",
            "createdAt": 0,
            "sessionId": 0
        },
        "tags": [
            {
                "text": "Camera 1",
                "createdAt": 0,
                "tagGroupId": 1,
                "order": 0
            }
        ]
    }
}

Error Responses

Error responses will typically include an appropriate HTTP status code and a JSON body with an error message.

{
    "code": "400",
    "status": "Note could not be loaded.",
    "timestamp": "2025-01-01T19:10:00Z"
}

Update Note

A Note can be updated by using the "Create Note" endpoint (see Example 4) or by using this endpoint.

This endpoint can be used to update an existing note within a specific project. Identify the project using projectId and projectKey, and the specific note using noteId.

Endpoint

PATCH https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/note/{noteId}

Replace {projectId} with the project's unique ID, {projectKey} with the project's specific key, and {noteId} with the ID of the note to update.

Headers

Content-Type: application/json

Specifies the format of the request body.

Authorization: Basic <base64EncodedString>

Authentication credential using `PROJECT_API_KEY` or `YOUR_API_KEY`.

Path Parameters

Parameter Type Description
projectId String The unique identifier of the project.
projectKey String The specific key associated with the project.
noteId String The unique identifier of the note.

Request Body (JSON)

The request body should be a JSON object containing only the fields that should be updated. Any fields not included will retain their current values. All parameters are optional for a `PATCH` operation, but at least one must be provided.

Parameter Type Optional Description
timecode String The timecode (SMPTE HH:MM:SS:FF).
name String Name of the note.
comment String The comment.
loggerName String Name of the Commenter.
color String Color of note.
tone String Color (alternative for color parameter).
tags Object/String An optional list of tags associated with the note (e.g., ["B-roll", "Interview"]).

Example

Change timecode and tags for a note.

{                 
    "timecode": "10:01:31:20",
    "tags": ["Interview", "Camera 1"]
}

cURL Request

curl -X POST https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/note/{noteId} \
  -u "apikey:YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{                 
    "timecode": "10:01:31:20",
    "tags": ["Interview", "Camera 1"]
}'

Response (HTTP 200 OK)

If the request was successfully, the API will return a 200 status code with a JSON object.

{
    "code": "200",
    "status": "The note was updated successfully.",
    "timestamp": "2025-01-01T19:10:00Z"
}

Delete Note

A Note can be deleted by using the "Create Note" endpoint (see Example 5) or by using this endpoint.

This endpoint is used to delete an existing note from a specific project. Identify the project using projectId and projectKey, and the note to delete using noteId.

Endpoint

DELETE https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/note/{noteId}

Replace {projectId} with the project's unique ID, {projectKey} with the project's specific key, and {noteId} with the ID of the note to delete.

Headers

Authorization: Basic <base64EncodedString>

Authentication credential using `PROJECT_API_KEY` or `YOUR_API_KEY`.

Path Parameters

Parameter Type Description
projectId String The unique identifier of the project.
projectKey String The specific key associated with the project.
noteId String The unique identifier of the note.

Request Body

This endpoint does not require a request body. You only need to send the DELETE request with the correct URL and authentication.

cURL Request Example 1 - using Personal API Key

curl -X DELETE https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/note/{noteId} \
		-u "apikey:YOUR_API_KEY"

cURL Request Example 2 - using Project API Key

curl -X DELETE https://api.editingtools.io/v2/livenotes/project/{projectId}/{projectKey}/note/{noteId} \
		-u "projectapikey:PROJECT_API_KEY"

Responses

Success (HTTP 200 OK)

If the note is successfully deleted, the API will return a 200 OK status code with a JSON object confirming the deletion.

{
		    "code": "200",
		    "status": "Note deleted successfully.",
		    "timestamp": "2025-01-01T19:10:00Z"
		}
Field Type Description
code String HTTP status code.
status String A descriptive message about the deletion.
timestamp String Timestamp of server.

Endpoint URL

https://api.editingtools.io/v2/livenotes

Authentication

This API has one special exception for authentication: A project can be accessed using a project-specific API key, which is created when the project is created.

The personal API key from EditingTools.io can be used for all requests to the API. An personal API key can be generated at editingtools.io/account/api.

This API requires Basic Authentication. The `Authorization` header should be set with the Base64 encoded string of `apikey:YOUR_API_KEY`.

Authorization: Basic <base64Encoded(apikey:YOUR_API_KEY)>

To allow others (guests) to retrieve and send notes to the project without sharing the personal API key, the project API key can be used to access project data and add, modify, or delete notes. However, the project API key cannot be used to create, update, or delete projects. A project API key is generated upon project creation.

Authorization: Basic <base64Encoded(projectapikey:PROJECT_API_KEY)>

Action Table

Action Personal API Key (Owner) Project API Key (Guests)
Create Project ✓ ✗
Get Projects (List) ✓ ✗
Get Project (Details) ✓ ✓
Update Project ✓ ✗
Delete Project ✗ ✗
Get Updates ✓ ✓
Get Notes (multiple) ✓ ✓
Get Notes (specific) ✓ ✓
Create Note ✓ ✓
Update Note ✓ ✓
Delete Note ✓ ✓

Authentication

This API requires Basic Authentication. The "Authorization" header should be set with the Base64 encoded string of "apikey:YOUR_API_KEY".

Authorization: Basic <base64Encoded(apikey:YOUR_API_KEY)>

Data Handling

Request parameters must be UTF-8 encoded. Results are returned as UTF-8-encoded JSON. By default, datasets will be inside the data tag.

Error Handling

This API service uses standard HTTP response codes to indicate whether a method was completed successfully. HTTP response codes in the 2XX range indicate success. Responses in the 4XX range indicate some sort of failure, while responses in the 5XX range indicate an internal system error that cannot be resolved by the user. The following error codes are used by the API:

Code Description
200 OK. The request was successful.
201 Created. The entity was created.
202 Accepted. The request was accepted.
400 Bad request. Please check error message.
401 Unauthorized: Username or Api Key is not valid.
402 Upgrade Required: This feature requires an active Pro subscription.
403 Forbidden: The request is understood, but it has been refused or access is not allowed.
404 Not found: The URI requested is invalid or the resource does not exist.
422 Unprocessable Entity. A process failed.
429 Too Many Requests. Try again in some seconds.
500 Internal Server Error. Something is broken.
502 Bad Gateway. API is down.
503 Service Unavailable. API is up but overloaded with requests.
504 Gateway Timeout: API is up but requests reached timout.

Rate Limits

To prevent abuse and spam, the API has limits at various levels. If you receive error code 429 (Too Many Requests), it means you have reached a rate limit.

If you receive a rate limit error, you should stop making requests temporarily. If the retry-after response header is present, you should not retry your request until after that many seconds has elapsed. To prevent rate-errors, we recommend to wait 300 ms to 800 ms between requests to the same endpoint.

Also there is a general limit to the api and all requests made:

Limit Requests
General limit per minute 50
General limit per hour 1000
Recommended wait time between requests > 200 ms
Recommended wait time between requests to one endpoint > 600 ms

The general limits per minute and per hour can be changed upon request.

Upload Limits

The maximum upload size for any single request — including file uploads — is 100 MB. This is a hard limit and applies regardless of your API plan or usage level.

If your request exceeds this size, it will be rejected before reaching our servers. To ensure successful uploads:

  • Make sure uploaded files are under 100 MB.
  • For larger media, consider splitting files before upload.
  • Requests close to the limit may still fail due to encoding or header overhead.

Timezone

This API endpoint returns the time as an ISO 8601 timestamp in the UTC time zone. These timestamps look like 2025-01-10T15:05:06Z.

Localization and Languages

This API supports multiple languages. For instance, it can display the text of a status message in a different language.

Accept-Language: LANGUAGE

Example

To set the preferred response language to Spanish, add this header:

Accept-Language: es

cURL Example

To apply the language in a cURL request, add the following header:

-H "Accept-Language: es"

Available Languages

The following list contains all the currently available languages. Note that setting a language header does not guarantee a translated response, as not all texts are translated. If no language is set or a translation is unavailable, the default response will be in English.

Code Language
en English
de German
fr French
es Spanish
ru Russian
it Italian
el Greek
pl Polish
pt Portuguese
lt Lithuanian
ko Korean
ja Japanese
zh Chinese
id Indonesian
tr Turkish
nl Dutch
ro Romanian
fi Finnish
cs Czech
hu Hungarian
ar Arabic
nb Norwegian Bokmål
sk Slovak
sl Slovenian
sv Swedish
lv Latvian
et Estonian
bg Bulgarian
uk Ukrainian
da Danish