Threads and folders

A thread follows one subject for days or weeks; folders group threads and can sit inside other folders.

The thread object

• title: the thread’s name as the app shows it. A thread still called New thread shows the first line of its first note, without the @name it was sent to. An Add only connection, which can’t read notes, gets the stored name, so such a thread comes as New thread.
• description: plain text under the title, with line breaks; empty when there is none. An Add only connection sees titles only and gets no description.
• status: the key of a status in the workspace’s list, and status_name, its word. active, waiting and done are the keys of the three a workspace starts with; any other key is a UUID.
• archived, trashed, folder ({id, name}, or null at the top level), revision, url.
• shared: true when the owner shares the thread with other people. See Shared threads and folders.
• last_activity_at: when a note in the thread last changed. It can lag up to 60 seconds behind someone typing, so it is no change cursor: use a note’s updated_at, webhooks or the pull feed.

Threads have no manual order through the API.

List and read threads

GET /threads lists the threads in the connection’s scope. state is active (the default), archived, trash or all; folder_id lists one folder.

List threads this connection can see

GET /api/integrations/v1/threads

Answer 200.

curl -m 30 "https://thread.page/api/integrations/v1/threads" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN"

Errors: read_not_allowed 403, context_changed 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Get one thread

GET /api/integrations/v1/threads/{thread_id}

Answer 200.

curl -m 30 "https://thread.page/api/integrations/v1/threads/$THREAD_ID" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN"

Errors: read_not_allowed 403, unavailable 404.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Create a thread and add its first note

Create the thread, then add a note with its id. folder_id: null puts the thread at the top level, which needs access to All threads. Read and add or Edit and organize.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors https://thread.page/api/integrations/v1/threads \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"title": "Release 413", "folder_id": "'"$FOLDER_ID"'"}'

The ChangeReceipt names the new thread in target.id. Use a new Operation-Id for the note.

Create a thread

POST /api/integrations/v1/threads

The MCP tool create_thread. folder_id null puts it at the top level, which needs access to All threads. Read and add, Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 201: Accepted, or the same receipt again.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X POST "https://thread.page/api/integrations/v1/threads" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"title":"Release notes","folder_id":"7d1e4c90-3b2a-4f58-a6c1-0e9d8b7f2a53"}'

Errors: write_not_allowed 403, 409, invalid_json 400, unsupported_media_type 415, operation_id_reused 409, shared_place_write 409, target_deleted 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Rename a thread, or change its description or status

PATCH /threads/{thread_id} takes only what changes: title (1 to 200 characters), description (up to 500 characters, line breaks allowed; "" clears it) or status.

{"status": "waiting"}

status is a key from GET /statuses. A key that has been deleted lands on its replacement, and the receipt says the final value. Anything else is invalid_request with details.statuses, the list you may use.

Rename a thread or change its description or status

PATCH /api/integrations/v1/threads/{thread_id}

The MCP tool update_thread; only what changes. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 200. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X PATCH "https://thread.page/api/integrations/v1/threads/$THREAD_ID" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"status":"waiting"}'

Errors: organize_not_allowed 403, unavailable 404, invalid_json 400, unsupported_media_type 415, operation_id_reused 409, request_open 409, shared_place_write 409, entity_deleted 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Archive a thread

Archive keeps a finished thread out of the active list; it stays readable. Unarchive brings it back.

Archive a thread

POST /api/integrations/v1/threads/{thread_id}/archive

The MCP tool archive_thread: it leaves the active list and stays readable. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 200. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X POST "https://thread.page/api/integrations/v1/threads/$THREAD_ID/archive" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP"

Errors: organize_not_allowed 403, unavailable 404, operation_id_reused 409, request_open 409, shared_place_write 409, entity_deleted 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Unarchive a thread

POST /api/integrations/v1/threads/{thread_id}/unarchive

The MCP tool unarchive_thread. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 200. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X POST "https://thread.page/api/integrations/v1/threads/$THREAD_ID/unarchive" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP"

Errors: organize_not_allowed 403, unavailable 404, operation_id_reused 409, shared_place_write 409, entity_deleted 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Move a thread into a folder

folder_id: null moves it to the top level, which needs access to All threads.

Move a thread into a folder

POST /api/integrations/v1/threads/{thread_id}/move

The MCP tool move_thread; folder_id null is the top level, which needs access to All threads. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 200. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X POST "https://thread.page/api/integrations/v1/threads/$THREAD_ID/move" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":"7d1e4c90-3b2a-4f58-a6c1-0e9d8b7f2a53"}'

Errors: organize_not_allowed 403, unavailable 404, invalid_json 400, unsupported_media_type 415, operation_id_reused 409, request_open 409, shared_place_write 409, entity_deleted 409, target_deleted 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Move a thread to Trash and restore it

Trash takes the thread with its notes; restore brings them back into its folder. A thread with an unfinished request stays where it is: 409 request_open. Archiving such a thread is refused the same way.

Move a thread to Trash

POST /api/integrations/v1/threads/{thread_id}/trash

The MCP tool trash_thread: the thread and its notes; restore brings them back. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 200. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X POST "https://thread.page/api/integrations/v1/threads/$THREAD_ID/trash" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP"

Errors: organize_not_allowed 403, unavailable 404, operation_id_reused 409, request_open 409, shared_place_write 409, entity_deleted 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Restore a thread

POST /api/integrations/v1/threads/{thread_id}/restore

The MCP tool restore_thread: the thread and the notes trashed with it, into its folder. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 200. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X POST "https://thread.page/api/integrations/v1/threads/$THREAD_ID/restore" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP"

Errors: organize_not_allowed 403, unavailable 404, operation_id_reused 409, shared_place_write 409, parent_deleted 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Folders

A folder has id, name, parent_id (null at the top level, or when the parent is outside the connection’s scope), revision, trashed and shared. Every folder write needs Edit and organize.

List folders

GET /api/integrations/v1/folders

Folders within this connection's content, a page at a time. Read only, Read and add, Edit and organize.

Answer 200.

curl -m 30 "https://thread.page/api/integrations/v1/folders" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN"

Errors: read_not_allowed 403, context_changed 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Create a folder

POST /api/integrations/v1/folders

The MCP tool create_folder; parent_id null is the top level, which needs access to All threads. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 201: Accepted, or the same receipt again. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X POST "https://thread.page/api/integrations/v1/folders" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"name":"Work","parent_id":null}'

Errors: organize_not_allowed 403, invalid_json 400, unsupported_media_type 415, operation_id_reused 409, shared_place_write 409, target_deleted 409, folder_name_conflict 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Rename a folder

PATCH /api/integrations/v1/folders/{folder_id}

The MCP tool rename_folder. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 200. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X PATCH "https://thread.page/api/integrations/v1/folders/$FOLDER_ID" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"name":"Clients"}'

Errors: organize_not_allowed 403, unavailable 404, invalid_json 400, unsupported_media_type 415, operation_id_reused 409, shared_place_write 409, entity_deleted 409, folder_name_conflict 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Move a folder

A folder moves with everything in it. The folder, what it holds and the destination must all be within the connection’s scope. A folder that holds threads needs a confirmation, as below.

Move a folder with everything in it

POST /api/integrations/v1/folders/{folder_id}/move

The MCP tool move_folder: all of it and the destination must be within this connection's content. A folder that holds threads needs a confirmation: the first call answers 409 confirmation_required with details {folder, threads, folders, confirm}; the same call with that confirm (valid 10 minutes) proceeds. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 200. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X POST "https://thread.page/api/integrations/v1/folders/$FOLDER_ID/move" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"parent_id":null}'

Errors: organize_not_allowed 403, unavailable 404, invalid_json 400, unsupported_media_type 415, operation_id_reused 409, request_open 409, shared_place_write 409, confirmation_required 409, entity_deleted 409, target_deleted 409, folder_cycle 409, folder_name_conflict 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Move a folder to Trash

POST /folders/{folder_id}/trash takes contents:

A folder that holds at least one thread, in it or in its subfolders, needs a confirmation:

1. The first call answers 409 confirmation_required. details has the folder ({id, name}), how many threads and folders it holds, and a confirm value.
2. Show those numbers to the person if one is waiting, then send the same call with confirm added, exactly as you got it. It stays valid for 10 minutes, for this connection, this action and the folder as it was.

{"contents": "trash", "confirm": ".eJyrVkrOz0vOLEotSc1VslJKzs8tKMovL0pNUaoFAD3oBpg:1vHkQ2:Jr4m0bX2a9cQe1Lw7Kc8sT4yNbA0dVhJ6uGoIzR5aPq"}

confirm is opaque: don’t parse it or build one.

If the folder changed in between, the second call answers a new 409 confirmation_required.

This guards an honest client against a mistake. It is not a security control: a script can repeat the call. Trash and Restore from Trash… in the connection’s details are the control.

Move a folder to Trash

POST /api/integrations/v1/folders/{folder_id}/trash

contents trash: the MCP tool trash_folder, the folder and everything in it. contents move_up: the MCP tool delete_folder_container (the app's Delete folder only), the folder alone; what it holds moves up to its parent. A folder that holds threads needs a confirmation: the first call answers 409 confirmation_required with details {folder, threads, folders, confirm}; the same call with that confirm (valid 10 minutes) proceeds. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 200. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X POST "https://thread.page/api/integrations/v1/folders/$FOLDER_ID/trash" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"contents":"trash"}'

Errors: organize_not_allowed 403, unavailable 404, invalid_json 400, unsupported_media_type 415, operation_id_reused 409, request_open 409, shared_place_write 409, confirmation_required 409, entity_deleted 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Restore a folder

POST /api/integrations/v1/folders/{folder_id}/restore

The MCP tool restore_folder: the folder and what it held, into its parent. Edit and organize. Scope, shared places (shared_place_write) and the open-request rule (request_open) apply to every write.

Answer 200. Its fields are those under Create a thread.

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X POST "https://thread.page/api/integrations/v1/folders/$FOLDER_ID/restore" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP"

Errors: organize_not_allowed 403, unavailable 404, operation_id_reused 409, shared_place_write 409, parent_deleted 409, folder_name_conflict 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

In shared threads and folders

A connection that reads writes into a shared thread or folder, or a folder that holds one, only where the owner allowed it.

• Threads: creating one in a shared place, and renaming, describing, setting the status of, archiving, unarchiving, trashing, restoring and moving a shared thread, into or out of a shared place.
• Folders: every write on a folder that is shared, holds a shared place or sits inside one.

Otherwise the write answers 409 shared_place_write with details.place. See Shared threads and folders.

If it fails

Next

• Notes
• Reminders