Annotations API

API endpoints for managing annotations and feedback in Moqup.

The Annotations API enables programmatic management of feedback on design files.

Endpoints

Method	Endpoint	Description
GET	`/files/{id}/annotations`	List file annotations
POST	`/files/{id}/annotations`	Create annotation
GET	`/annotations/{id}`	Get annotation
PATCH	`/annotations/{id}`	Update annotation
DELETE	`/annotations/{id}`	Delete annotation

List Annotations

Request

bash

GET /v1/files/{file_id}/annotations
Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`resolved`	boolean	Filter by resolved status: `true` or `false`

Response

json

{
  "data": [
    {
      "id": "abc123-def456",
      "file_id": "file_xyz",
      "author_name": "John Reviewer",
      "comment": "The button color should be darker",
      "x_percent": 45.5,
      "y_percent": 32.0,
      "resolved": false,
      "timestamp": null,
      "page_number": null,
      "parent_id": null,
      "replies": [
        {
          "id": "reply_1",
          "author_name": "Sarah Designer",
          "comment": "Good point, I'll update it",
          "created_at": "2025-01-10T11:00:00Z"
        }
      ],
      "created_at": "2025-01-10T10:00:00Z",
      "updated_at": "2025-01-10T14:00:00Z"
    }
  ],
  "meta": {
    "total": 7,
    "page": 1,
    "perPage": 20,
    "hasMore": false
  }
}

Create Annotation

Request

bash

POST /v1/files/{file_id}/annotations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "author_name": "John Reviewer",
  "comment": "Please increase the font size here",
  "x_percent": 50.0,
  "y_percent": 40.0
}

Parameters

Field	Type	Required	Description
`author_name`	string	Yes	Name of the commenter
`comment`	string	Yes	Comment text
`x_percent`	number	Yes	Horizontal position (0-100)
`y_percent`	number	Yes	Vertical position (0-100)
`timestamp`	number	No	Video timestamp in seconds
`page_number`	integer	No	PDF page number
`parent_id`	string	No	Parent annotation ID (for replies)

Position Format

Positions are specified as percentages (0-100) relative to the file dimensions:

x_percent: 0 = left edge
x_percent: 100 = right edge
y_percent: 0 = top edge
y_percent: 100 = bottom edge

Response

json

{
  "data": {
    "id": "abc123-def456",
    "file_id": "file_xyz",
    "author_name": "John Reviewer",
    "comment": "Please increase the font size here",
    "x_percent": 50.0,
    "y_percent": 40.0,
    "resolved": false,
    "created_at": "2025-01-10T15:00:00Z",
    "updated_at": "2025-01-10T15:00:00Z"
  }
}

Create Reply

To create a reply to an existing annotation, use the parent_id field:

bash

POST /v1/files/{file_id}/annotations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "author_name": "Sarah Designer",
  "comment": "Thanks for the feedback, I've made the change",
  "x_percent": 50.0,
  "y_percent": 40.0,
  "parent_id": "abc123-def456"
}

Get Annotation

Request

bash

GET /v1/annotations/{id}
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "data": {
    "id": "abc123-def456",
    "file_id": "file_xyz",
    "author_name": "John Reviewer",
    "comment": "The button color should be darker",
    "x_percent": 45.5,
    "y_percent": 32.0,
    "resolved": false,
    "file": {
      "id": "file_xyz",
      "title": "Homepage Hero",
      "project": {
        "id": "proj_123",
        "name": "Website Redesign",
        "workspace_id": "ws_456"
      }
    },
    "replies": [
      {
        "id": "reply_1",
        "author_name": "Sarah Designer",
        "comment": "Good point, I'll update it",
        "created_at": "2025-01-10T11:00:00Z"
      }
    ],
    "created_at": "2025-01-10T10:00:00Z",
    "updated_at": "2025-01-10T14:00:00Z"
  }
}

The response includes the file and project information, plus any replies.

Update Annotation

Request

bash

PATCH /v1/annotations/{id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "comment": "Updated comment text",
  "resolved": true
}

Parameters

Field	Type	Description
`comment`	string	Update comment text
`resolved`	boolean	Mark as resolved or unresolved

Response

json

{
  "data": {
    "id": "abc123-def456",
    "comment": "Updated comment text",
    "resolved": true,
    "updated_at": "2025-01-10T16:00:00Z"
  }
}

Delete Annotation

Requires write permission.

Request

bash

DELETE /v1/annotations/{id}
Authorization: Bearer YOUR_API_KEY

Response

Returns 204 No Content on success.

Resolve Annotation

To resolve an annotation, use the PATCH endpoint:

bash

PATCH /v1/annotations/{id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "resolved": true
}

To reopen a resolved annotation:

bash

PATCH /v1/annotations/{id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "resolved": false
}

Errors

Code	Description
400	Invalid parameters (missing author_name, comment, or invalid position)
401	Authentication required
403	Insufficient permissions
404	Annotation or file not found

Error Response

json

{
  "error": {
    "message": "author_name is required",
    "code": 400
  }
}

Examples

Create Annotation on Image

javascript

async function addAnnotation(fileId, author, comment, x, y) {
  const response = await fetch(
    `https://moqup.io/api/v1/files/${fileId}/annotations`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        author_name: author,
        comment: comment,
        x_percent: x,
        y_percent: y
      })
    }
  );
  return response.json();
}

// Add annotation at 50%, 30% position
await addAnnotation('file_123', 'John', 'Please fix this', 50, 30);

Create Annotation on Video

bash

POST /v1/files/file_123/annotations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "author_name": "Reviewer",
  "comment": "Transition too fast here",
  "x_percent": 50.0,
  "y_percent": 50.0,
  "timestamp": 45
}

Create Annotation on PDF

bash

POST /v1/files/file_123/annotations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "author_name": "Reviewer",
  "comment": "Typo in this paragraph",
  "x_percent": 30.0,
  "y_percent": 60.0,
  "page_number": 3
}

Get Open Annotations

bash

GET /v1/files/file_123/annotations?resolved=false
Authorization: Bearer YOUR_API_KEY

Resolve Multiple Annotations

javascript

async function resolveAnnotations(annotationIds) {
  const updates = annotationIds.map(id =>
    fetch(`https://moqup.io/api/v1/annotations/${id}`, {
      method: 'PATCH',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ resolved: true })
    })
  );
  return Promise.all(updates);
}

Next Steps

Files API - Manage files
Rate Limits - Understand usage limits