Skip to Content
APIResourcesAdmin APIItems

Items

Unified resource for folders and markups. Same endpoints for get, list children, rename, delete. Scoped by API key workspace.

Get Item

GET /api/v2/items/:id

Get a single item by ID. Returns a folder (with ancestors) or a markup (project); response shape varies by type.

GET /api/v2/items/:id
curl "https://api.markup.io/api/v2/items/669be337-25e5-4a53-8985-fa9df4703220" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json"
200 OK
{
  "data": {
    "id": "982fb9b6-bff8-4b9f-8fe5-77ddbd8e4d23",
    "createdAt": "2026-06-11T11:43:35.935Z",
    "modifiedAt": "2026-06-11T11:43:35.936Z",
    "type": "webpage",
    "name": "MarkUp.io",
    "markupUrl": "https://app.markup.io/markup/f289b90a-1166-4f63-aef3-a0cce4543413",
    "thumbnailUrl": "https://media.markup.io/thumbnails/markup/9b339cd0-546d-4292-a54b-6e128ce6113e",
    "activeThreads": 10,
    "readOnly": true,
    "status": "editing",
    "note": {
      "id": "uuid",
      "projectId": "uuid",
      "note": "Internal note",
      "showNoteOnProjectOpen": true
    },
    "projectReviews": [
      {
        "projectId": "uuid",
        "userId": "uuid",
        "comment": "Looks good",
        "createdAt": 1705312800000
      }
    ],
    "scopes": [
      "update-project-read-only",
      "delete-project"
    ],
    "url": "https://markup.io"
  }
}

Response Body - [FolderWithAncestorsResponse | MarkupResponse](#folderwithancestorsresponse | markupresponse)

Request Path Params IdRequestParam

OptionType
id string

List Child Items

GET /api/v2/items/:id/items

List contents of a folder (folders and markups). Use GET /workspace to get archiveFolderId; then GET /items/:archiveFolderId/items to list archived items. Supports cursor-based pagination via query params: limit, since, before, ttl.

GET /api/v2/items/:id/items
curl "https://api.markup.io/api/v2/items/48263f3b-64f0-4811-af43-1c934b970a46/items" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json"
Response
204 No Content

Request Path Params IdRequestParam

OptionType
id string

Request Query Params FolderItemsRequest

OptionType
order optional
page optionalnumber
limit optionalnumber
before optionalstring
since optionalstring
ttl optionalnumber

Create Folder

POST /api/v2/items

Create a new folder under the given parent. Body: parentFolderId, name, optional fallbackName.

POST /api/v2/items
curl "https://api.markup.io/api/v2/items" \
    -X POST \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" \
	--data '{
    "parentFolderId": "c16cf7d3-b870-4203-b0eb-fd296ed7b01e",
    "name": "some name"
}'
Response
204 No Content

Request Body CreateFolderRequest

OptionType
parentFolderId string
name string
fallbackName optionalstring

Archive Items

PATCH /api/v2/items/archive

Move folder items (folders and markups) to the workspace archive. Body: folderItemIds, optional withPath (“0”|“1”).

PATCH /api/v2/items/archive
curl "https://api.markup.io/api/v2/items/archive" \
    -X PATCH \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" \
	--data '{
    "folderItemIds": "bad0ed83-384a-4698-823d-30518a3c5228"
}'
Response
204 No Content

Request Body ArchiveFolderItemsRequest

OptionType
folderItemIds string[]

Restore Items

PATCH /api/v2/items/restore

Restore folder items from the workspace archive to the root. Body: folderItemIds, optional withPath (“0”|“1”).

PATCH /api/v2/items/restore
curl "https://api.markup.io/api/v2/items/restore" \
    -X PATCH \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" \
	--data '{
    "folderItemIds": "3cddcf61-d20f-4cd0-ab62-3e64a378e03f"
}'
Response
204 No Content

Request Body ArchiveFolderItemsRequest

OptionType
folderItemIds string[]

Update Item

PATCH /api/v2/items/:id

Rename a folder or markup. Body: name. Same endpoint for both types.

PATCH /api/v2/items/:id
curl "https://api.markup.io/api/v2/items/26d6ba01-4187-4d26-b068-9972aa3fc2bb" \
    -X PATCH \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" \
	--data '{
    "name": "some name"
}'
Response
204 No Content

Request Path Params IdRequestParam

OptionType
id string

Request Body UpdateItemRequest

OptionType
name string

Delete Item

DELETE /api/v2/items/:id

Delete a folder or markup by ID. Same endpoint for both types; no need to call different APIs.

DELETE /api/v2/items/:id
curl "https://api.markup.io/api/v2/items/beb52dc9-8bcd-4800-b199-99c41e55f2c0" \
    -X DELETE \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json"
Response
204 No Content

Request Path Params IdRequestParam

OptionType
id string

FolderItemOrder

OptionType
FolderItemOrder `az` | `za` | `activity` | `created`

FolderWithAncestorsResponse | MarkupResponse

OptionType
FolderWithAncestorsResponse | MarkupResponse

WebpageMarkupResponse

OptionType
id string
createdAt Iso8601Timestamp
modifiedAt Iso8601Timestamp
deletedAt Iso8601Timestamp
type ProjectType
name string
markupUrl string
thumbnailUrl string
activeThreads number
readOnly boolean
status ProjectStatus
note ProjectNoteResponse
projectReviews ProjectReviewResponse[]
scopes string[]
url string

ImageMarkupResponse

OptionType
id string
createdAt Iso8601Timestamp
modifiedAt Iso8601Timestamp
deletedAt Iso8601Timestamp
type ProjectType
name string
markupUrl string
thumbnailUrl string
activeThreads number
readOnly boolean
status ProjectStatus
note ProjectNoteResponse
projectReviews ProjectReviewResponse[]
scopes string[]
originalMimeType string
images MarkupImage[]
isReady boolean

Some of the files need to be converted before Markup is ready for reviewing. After the conversion is done, this flag will be set to true and the markup_ready webhook will be sent.

VideoMarkupResponse

OptionType
id string
createdAt Iso8601Timestamp
modifiedAt Iso8601Timestamp
deletedAt Iso8601Timestamp
type ProjectType
name string
markupUrl string
thumbnailUrl string
activeThreads number
readOnly boolean
status ProjectStatus
note ProjectNoteResponse
projectReviews ProjectReviewResponse[]
scopes string[]
video MarkupVideo
isReady boolean

Some of the files need to be converted before Markup is ready for reviewing. After the conversion is done, this flag will be set to true and the markup_ready webhook will be sent.

Last updated on
VersioningMarkup