Suggestions

Suggestions propose replacing a specific text range in a document. The document owner can accept (applying the change) or reject each suggestion.

Suggestion object

{
  "id": "suggestion-uuid",
  "document_id": "doc-uuid",
  "author_id": "user-uuid",
  "original_text": "Hello World",
  "suggested_text": "Greetings World",
  "anchor_start": 2,
  "anchor_end": 13,
  "status": "pending",
  "resolved_at": null,
  "resolved_by": null,
  "created_at": "2026-03-13T12:00:00.000Z",
  "updated_at": "2026-03-13T12:00:00.000Z",
  "author": {
    "id": "user-uuid",
    "display_name": "Jane Doe",
    "avatar_url": null
  }
}

Field	Type	Description
id	UUID	Suggestion identifier
document_id	UUID	Parent document
author_id	UUID or null	Suggestion author (null for anonymous)
original_text	string	The text to be replaced
suggested_text	string	The proposed replacement
anchor_start	int or null	Character offset start
anchor_end	int or null	Character offset end
status	string	"pending", "accepted", or "rejected"
resolved_at	ISO 8601 or null	When accepted/rejected
resolved_by	UUID or null	Who accepted/rejected
author	object	Embedded author profile

---

List suggestions

GET /api/documents/:id/suggestions

Returns all suggestions on a document, sorted by created_at ascending.

Request

curl https://notebind.com/api/documents/DOC_ID/suggestions \
  -H "Authorization: Bearer nb_sk_YOUR_KEY"

Response 200 OK

{
  "data": [
    {
      "id": "suggestion-uuid",
      "original_text": "Hello World",
      "suggested_text": "Greetings World",
      "status": "pending",
      "author": { "display_name": "Jane", "avatar_url": null },
      "created_at": "2026-03-13T12:00:00.000Z"
    }
  ],
  "error": null
}

Share token access

Any share token can list suggestions:

curl "https://notebind.com/api/documents/DOC_ID/suggestions?share_token=TOKEN"

---

Create a suggestion

POST /api/documents/:id/suggestions

Request body

Field	Type	Required	Description
original_text	string	Yes	The text to replace
suggested_text	string	Yes	The proposed replacement
anchor_start	int	No	Character offset start
anchor_end	int	No	Character offset end

Request

curl -X POST https://notebind.com/api/documents/DOC_ID/suggestions \
  -H "Authorization: Bearer nb_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "original_text": "Hello World",
    "suggested_text": "Greetings World",
    "anchor_start": 2,
    "anchor_end": 13
  }'

Response 201 Created

Returns the created suggestion with embedded author.

Share token access

Only edit share tokens can create suggestions:

curl -X POST "https://notebind.com/api/documents/DOC_ID/suggestions?share_token=EDIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"original_text": "old text", "suggested_text": "new text"}'

---

Get a single suggestion

GET /api/documents/:id/suggestions/:sid

Returns a single suggestion. Requires document owner or suggestion author access.

curl https://notebind.com/api/documents/DOC_ID/suggestions/SUGGESTION_ID \
  -H "Authorization: Bearer nb_sk_YOUR_KEY"

---

Accept or reject a suggestion

PATCH /api/documents/:id/suggestions/:sid

Note

Only the document owner can accept or reject suggestions.

Request body

Field	Type	Required	Values
action	string	Yes	"accept" or "reject"

Accept a suggestion

When accepted, the original_text is replaced with suggested_text in the document content.

curl -X PATCH https://notebind.com/api/documents/DOC_ID/suggestions/SUGGESTION_ID \
  -H "Authorization: Bearer nb_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "accept"}'

Response 200 OK

{
  "data": {
    "id": "suggestion-uuid",
    "status": "accepted",
    "resolved_at": "2026-03-13T12:10:00.000Z",
    "resolved_by": "user-uuid"
  },
  "error": null
}

Reject a suggestion

curl -X PATCH https://notebind.com/api/documents/DOC_ID/suggestions/SUGGESTION_ID \
  -H "Authorization: Bearer nb_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "reject"}'

Conflict handling

If the document has been edited since the suggestion was created and the original_text can no longer be found:

{
  "data": null,
  "error": {
    "message": "Original text no longer found in document. The document may have been edited since this suggestion was created.",
    "code": "TEXT_NOT_FOUND"
  }
}

Status: 409 Conflict

---

Delete a suggestion

DELETE /api/documents/:id/suggestions/:sid

Request

curl -X DELETE https://notebind.com/api/documents/DOC_ID/suggestions/SUGGESTION_ID \
  -H "Authorization: Bearer nb_sk_YOUR_KEY"

Response 200 OK

{
  "data": { "deleted": true },
  "error": null
}

Permissions

• Document owner can delete any suggestion
• Suggestion author can delete their own suggestions

---

Error responses

Status	Code	Description
400	VALIDATION_ERROR	Missing required fields or invalid action
400	ALREADY_RESOLVED	Suggestion already accepted or rejected
401	UNAUTHORIZED	Missing or invalid credentials
403	FORBIDDEN	Only document owner can accept/reject
404	NOT_FOUND	Suggestion or document not found
409	TEXT_NOT_FOUND	Original text no longer in document