Timeliner MCP

Add one or more tags to a tag-kind custom column's vocabulary - for ONE brand, or shared. ONLY a column whose kind is tag in list_custom_columns: any other kind - a select column included - is a 400 naming the workspace's tag columns, and nothing is written. A select column's options cannot be added through the API at all (a person adds them in Timeliner); a select cell only takes one of its existing option ids. Tags are brand-scoped by default: pass brandId (a brand/client node id from list_brands - never a folder or a project id) and the tags apply only to that brand's tasks and are visible only to people who can see that brand. Pass brandId: null ONLY when the user explicitly wants a tag shared across every brand. Idempotent: a label that already exists in that scope is returned with created:false and its existing id, so re-sending a list is safe; labels are matched case-insensitively, trimmed, max 40 chars, up to 50 per call, 200 per column per brand. The recipe for "add these tags to <brand>": list_brands → list_custom_columns (pick the tag column) → create_custom_column_tags → then apply them to tasks with set_task_custom_values - whose `id` is the TASK's id, NOT this column's; the column id moves into its `values` map.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "labels": [
    "example"
  ]
}

Key scope: write:tasks

Create a task inside a project. For a variant of an existing task, set kind=variant and pass the parentTaskId of a regular or parent task together with THAT task's own projectId - a variant is always created in its parent's project (get_task and list_tasks return each task's projectId). A parentTaskId from another project, or one that is not a task in this workspace, is refused before anything is created, naming the project to use. Set internalDeadline / externalDeadline (YYYY-MM-DD) to schedule it at creation. A text-first social post (LinkedIn / Facebook) is a type=doc task created WITH its text in this one call - pass `text` (plain string, blank lines kept exactly) or `contentHtml`; then upload_file_from_url with the new taskId for an optional attachment, and schedule_post. Pass pricingTemplateId to price the task at creation (its pricing tag, default client price and editor pay); assign editors and tag their template roles afterwards with update_task (assigneeIds + assigneeRoles).

{
  "projectId": "2f6c1b9e-4a7d-4c3e-9b21-6d8e0f4a7c15",
  "title": "Launch reel 03 - 30s cut",
  "statusGroup": "toDo",
  "externalDeadline": "2026-11-20"
}

Key scope: write:tasks

Post a plain team comment on a task's review thread, authored by the API key's creator - or, with parentId, a REPLY inside that comment's thread (it shows nested under it in the app, at the same timecode and version; a reply to a reply joins the thread's first comment). A new top-level comment is left on the task's CURRENT version (its fileId), so it stays with that version and does not show on versions uploaded later. Silent - no one is notified (no @mentions). Returns the created comment.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "text": "example"
}

Key scope: write:tasks

Idempotently ensure ONE task has a working public review link at the given access level - the same link the task's Share button gives in the app, so it never mints a second one beside it. It opens only this task (its player and comments), not the project's board; a parent task's id shares all its variants, a variant's id just that variant. An active, unexpired link at that level is returned unchanged; a switched-off or expired one comes back with a NEW url, so always send the url from the latest response. No one is notified, but anyone holding the URL gets the chosen access - say so before creating one. Returns the share link with its public URL.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:tasks

DESTRUCTIVE. Move a task to Trash (soft-delete). The task and its files leave every active list and disappear from the client's view immediately; any running timer on it is stopped. Restorable from the app's Trash page, but treat it as irreversible when planning. CONFIRM WITH THE USER FOR EACH TASK, naming it; NEVER loop this tool over a list of tasks. Idempotent; no notifications fire. Deletes share one budget across the whole API: about 20 per minute per key, and daily ceilings per key and per workspace - over budget returns 429 with a Retry-After header. A 429 means STOP and tell the user; never wait-and-retry your way through a batch.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:tasks

Change PART of a task's rich-text content (a doc task's document body, or a media task's brief) without resending the whole thing - the right tool for any small change, and the only safe one on a large document. Each edit names where it goes: append / prepend (end / start of the document); replaceSection (a section = a top-level heading plus everything up to the next heading of the same or a higher level - html replaces the heading TOO, so start it with the heading to keep it, or send "" to delete the section); appendToSection (adds html at the end of that section); replaceText (find = an exact piece of the stored HTML as get_task_doc returns it, which must occur exactly once; html "" deletes it). Headings match on their visible text, case and spacing ignored. Edits apply in order and all or nothing, to whatever the document holds when the call lands - so you do NOT need a fresh rev, and someone editing another part of the document in the app meanwhile does not make this fail. Everything outside your edits is kept exactly as it is. A 422 means an anchor was not found or matched more than once (code anchorNotFound / anchorAmbiguous, index = which edit) and nothing was written: read the document with get_task_doc and pick an exact anchor. For doc tasks each call saves a restore point in the document's version history. Use update_task_doc only to rewrite the whole content.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "edits": [
    {
      "op": "append",
      "html": "example"
    }
  ]
}

Key scope: write:tasks

Get one task: title, statusGroup, customStatus ({id, name} of the workspace custom status it sits in - e.g. 'Legal sign-off' inside inProgress - or null), updatedAt (moves on any change, a status move included), kind (regular | parent | variant - a parent holds no file, its variants do), deadlines, brandId, media download links where available, externalMetadata, customValues, pricing (template, pricing tag, client price and each editor's role and pay - null without the finance read scope), and taskId (the permanent 'TL-1042' handle, null when the workspace has task IDs off). Takes the UUID - to go the other way, from a 'TL-1042' code someone quoted, call list_tasks with taskId first.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:tasks

Read ONE comment of a task's review thread - a team comment or a client's share-link comment - in the same full shape list_task_comments returns (timecode, frames, smpte, version, drawings, attachments, transcriptExcerpt…), plus replies: every reply in its thread, oldest first. A reply's own id returns that reply with replies []. 404 for another task's comment, a chat message or an unknown id. Use it to re-read one note in full before acting on it.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "commentId": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:tasks

Read a task's rich-text content - for a document task this is the document body (scripts, notes); for a media task it is the brief/description. Returns contentHtml (the raw HTML), type (doc | media), and rev (a version counter). To change part of it, read it once here and then use edit_task_doc - its edits are anchored on headings or exact HTML, so they need no fresh rev. Before update_task_doc (a full rewrite), ALWAYS call this and pass the returned rev back as baseRev so your write is rejected instead of silently overwriting an edit someone made in the app meanwhile.

{
  "id": "9b3e7a41-5c2d-4f8e-a6b0-1d7c3e9f2a64"
}

Key scope: read:tasks

Get ONE task's public review link - the link the task's Share button gives in the app, which opens only this task (its player and comments), not the project's board - or null if the task has never had one. Check isActive and expiresAt: a switched-off or expired link no longer opens; create_task_share_link returns a working one.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:tasks

Read the transcript of a media task's current video - the spoken words as plain text, plus language, word count and duration. Use it to analyze WHAT a video is about (who speaks, topics, places, products) before tagging it, summarizing it, or writing about it. status tells you what you got: ready (text present), none (never transcribed - generate_post_caption or suggest_task_tags with startTranscription:true starts one), pending/extracting/processing (in progress - retry in ~20s), no_speech, or failed. Read-only: never starts a transcription itself. 404 when the task has no media file (doc tasks, or nothing uploaded yet), and 404 code file_content_missing when the video was removed after the workspace's subscription ended (its transcript is hidden with it, and deleted with it once the file is permanently deleted). Text is bounded to the transcript's own length - long videos can be several thousand words.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:tasks

List the workspace's custom columns - the user-defined extra fields on tasks (e.g. a Dropbox link, a priority, a select, a tag). Each has an id, kind (text|date|priority|link|dateRange|select|tag), name, and - for select kinds - its options (id + label; to set a select cell send that option's id, never its label; options cannot be added through the API - a person adds them in Timeliner), or - for tag kinds - its tags (id + label + brandId). Only a tag kind column takes new labels (create_custom_column_tags / suggest_task_tags); any other kind there is a 400. A tag's brandId is null for a SHARED tag (usable on every brand) or a brand node id for a brand-scoped tag (usable only on tasks under that brand - resolve a task's brand via its project's brand). Use the column id with set_task_custom_values / create_custom_column_tags; read a task's current values from get_task's customValues. Not paginated (10 columns on most plans; unlimited on the higher plans).

{}

Key scope: read:tasks

List the workspace's CUSTOM statuses - extra steps in the workflow such as "Legal sign-off" after In Progress. Each has an id, name, color, baseStatus (the built-in statusGroup it sits after and behaves like), brandId (null = every brand; set = that brand only) and hiddenForBrandIds (brands that turned a workspace-wide one off). Pass brandId to get only the statuses a task under that brand can use. Board order: each base, then its custom statuses. A task's current one shows as customStatus on get_task / list_tasks (null = the plain statusGroup); move a task into one with update_task's customStatusId. Not paginated (at most 15).

{}

Key scope: read:tasks

What happened in the workspace recently, oldest first: a new version uploaded to a task (version.uploaded), a comment added (comment.created) and a task approved (task.completed) - each the exact envelope a webhook subscriber receives (id, type, createdAt, data with the task title, comment text or version number). Built for a scheduled check: pass since = when you last checked, or better, the nextCursor from your previous call as cursor (it continues exactly after the last event you saw, never repeating one; it is returned even when nothing new arrived). hasMore: true means call again with nextCursor now. Default: the last 24 hours; nothing older than 30 days is returned. Events are recorded only while the workspace has an API key, and nothing from before this feature existed is included. Comment events include team-only (visibility: team) comments - never forward those to a client.

{}

Key scope: read:tasks

Read a task's full event history - created, moved between statuses, new version uploaded, commented, viewed, downloaded - oldest first, so it reads as a timeline. Use it for 'when did this go to the client?', 'how long was it in revision?', or 'who moved it?'. Each entry: createdAt, action, movedFrom/movedTo (+ the rename-proof movedFromStatusKey/movedToStatusKey), and the actor with the role they held at the time. Durations are the gap between consecutive `moved` entries - subtract the timestamps yourself. Filter with action=moved for status history alone. Pass a task id from list_tasks.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:tasks

Read a task's review thread - team/authed comments AND anonymous client comments (from share links), merged oldest-first. Each comment: id, text, author, isGuest (true = client/guest), type, visibility (public = the client sees it, team = internal), mentions ({id,name} of who was tagged), resolved, parentId (a reply's thread), createdAt, editedAt. WHERE: timecode / endTimecode (seconds; endTimecode null = a point), frames {start,end} (0-based frame numbers at the version's real fps) and smpte {start,end} (HH:MM:SS:FF), null when there is no timecode or the fps is unknown; page (a PDF comment's page). WHICH VERSION: fileId and version {fileId, number (V1, V2…), current, kind video|image|pdf|audio|other, width, height, duration, fps} - version null = a comment with no version, which shows on every version. transcriptExcerpt {text, turns[{speaker,text}], truncated}: the words spoken IN THE VIDEO during a range comment (on a thread's first comment; null otherwise). textAnchor {quotedText}: the passage a document or caption comment was left on. attachments (name, mimeType, size, a downloadUrl valid 7 days - fetch it to see an attached image or file; removed:true = purged, no link; a voice memo's transcript = what the REVIEWER said) and drawings (type freehand|rectangle|circle|arrow|pin, color, lineThickness, opacity, page, normalized 0-1 bounds on the picture with the letterbox excluded - x × the version's width is the source pixel; arrows add from/to, circles center/radius, pins point, freehand points ≤128). A comment can be ONLY a drawing or an attachment with empty text - read both before calling it empty. Filters: version (current, or a fileId from version.fileId), resolved (open | resolved - a reply follows its thread), sort (created | timecode = timeline order, each reply under its thread). Use it for 'what did the client say on this task?' and before editing from the notes. Pass a task id from list_tasks.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:tasks

List tasks across the workspace's projects, newest first. Filter to one project with projectId. When a person refers to a task by a short code like 'TL-1042', pass it as taskId to resolve it directly instead of scanning pages. Every task in the response carries its own taskId (null when the workspace has task IDs switched off), its customStatus ({id, name} of the workspace custom status it sits in inside its statusGroup, null when none - see list_custom_statuses) and its pricing (template, pricing tag, client price, each editor's pay - null without the finance read scope). Returns {data, nextBefore}; when nextBefore is non-null, call again with before=nextBefore for the next page.

{}

Key scope: read:tasks

Mark a task comment's thread resolved (resolved: true) or reopen it (resolved: false) - the check box on the thread in the app, as the API key's creator. Works on a team comment or a client's share-link comment, but only on a thread's FIRST comment (a reply → 400). 403 when the key's user is not allowed to resolve comments. Returns the updated comment.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "commentId": "00000000-0000-0000-0000-000000000000",
  "resolved": true
}

Key scope: write:tasks

Set one or more custom-column cell values on a task. Pass values as a map of columnId → value (get the column ids from list_custom_columns). Value by kind: text/date/priority → a string (date = YYYY-MM-DD; priority = critical|high|medium|low); link → a URL string (sets ONLY the URL - the raw files already linked in the cell stay), or { url?, items? } to link raw files: items is the FULL list of linked files/folders the cell should end up with - a full replace, not an add; [] removes them all - each { kind: projectFile | projectFolder | brandFile | brandFolder, id } with ids from list_project_raw_files (this task's own project) or list_brand_raw_files (its project's brand); any other id is a 400 and nothing is written; only the keys you send change; dateRange → { start, end }; select → the `id` of ONE of THAT column's `options` in list_custom_columns, sent as a plain string - never an array (only tag columns take arrays), never the whole option object, never the option's label, never another column's option (a wrong one is refused with the column's valid label = optionId pairs - retry with one of those); tag → an ARRAY of tagIds (multi-value - send the full set you want the cell to end up with, not a delta; a tag scoped to ANOTHER brand than the task's is a 400 - pick shared tags or the task's own brand's tags, creating missing ones with create_custom_column_tags first). Pass null for any column to clear it. Returns the task's full custom values after the write.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "values": {}
}

Key scope: write:tasks

Have Timeliner's AI read a task - title, brief, post caption and the video's transcript - and pick tags for ONE tag column from the brand's own vocabulary (shared tags + that brand's tags), proposing new labels only when nothing fits. Pass an instruction to steer WHAT to look for ("only the speakers", "products shown"). Default = proposals only: returns suggestions [{ label, tagId|null, isNew, reason, alreadyApplied }] plus which sources were read; apply:true also creates the new labels scoped to the task's brand and sets the cell to existing ∪ suggested. A video with no transcript is tagged from title/brief unless startTranscription:true, which starts one (spends transcription minutes) and returns {status:"transcribing"} - wait retryAfterSeconds and call again. 422 reason=insufficient_content when there is nothing to read. One AI generation per call; 60/hour per workspace (429). For a batch: list_tasks → suggest_task_tags per task with apply:true.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "columnId": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:tasks

Update a task's allow-listed fields - provide at least one. Changing statusGroup fires the same notification flow the UI uses (in-app, email, WhatsApp where configured). Move a task into one of the workspace's CUSTOM statuses with customStatusId (ids from list_custom_statuses; statusGroup follows its base - omit statusGroup or send that base), or pass customStatusId null to put it back in the plain base; a move inside one base notifies no one. Assign team members with assigneeIds (member ids from list_members) - this is a FULL REPLACE of the task's assignees: pass the complete list you want, [] to clear all, and to add one person read the task's current assigneeIds (from get_task) and send that list plus the new id. Newly-added members are notified the same way the UI does; guests cannot be assigned. Date fields use YYYY-MM-DD; pass null to clear them. Price the task with pricingTemplateId and say which template role each assignee fills with assigneeRoles - e.g. assigneeIds [nimat] + assigneeRoles [{memberId: nimat, roleLabel: 'Online Editor'}] + pricingTemplateId assigns, tags and prices in one call; their pay then shows in get_pricing_payables. Changing assigneeIds on a priced task recomputes its pay, as in the app. Refused (409) once money has moved on the task.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:tasks

Rewrite the rich-text content of a task - the document body of a doc task, or the brief/description of a media task. contentHtml is a FULL REPLACE of the existing content (send the complete HTML you want, not a fragment; simple tags like <h2>, <p>, <ul>/<li>, <strong> render as in the in-app editor). To change only part of it - add a paragraph, append to the end, replace or extend one section, fix one passage - use edit_task_doc instead: it sends just the change and is not blocked by someone editing another part of the document in the app. To put an image or a file in the content, call upload_doc_attachment_from_url first and paste the embedHtml it returns into contentHtml. For doc tasks a restore point is saved to the document's version history on every write, so edits are revertible in the app. Pass baseRev (the rev from get_task_doc) for a safe write: a 409 means the app copy changed since you read it - re-read with get_task_doc and merge before retrying. Every successful write returns the new rev; use that as baseRev for your next write to the same task. Omit baseRev to force-overwrite. Before writing, confirm WITH THE USER which task (and, for a new deliverable, which brand/project) the content belongs to, and whether to create a new task or update an existing one - don't guess placement.

{
  "id": "9b3e7a41-5c2d-4f8e-a6b0-1d7c3e9f2a64",
  "contentHtml": "<p>Hook: the first 2 seconds show the product.</p>",
  "baseRev": 12
}

Key scope: write:tasks

Put an IMAGE or a FILE inside a document - an HQ item's Document tab, a doc task's body, or a task brief. Give us a publicly reachable http(s) URL; we download it server-side and return embedHtml, a ready-made snippet to paste into the document HTML. Two steps: (1) call this tool, (2) include the returned embedHtml inside the contentHtml you send to write_hq_item_doc or update_task_doc - those tools REPLACE the whole body, so keep the rest of the existing HTML around it. Images render inline, videos as an inline player, audio as a chip with a play button, everything else as a download chip. Allowed: JPEG/PNG/GIF/WebP/TIFF/BMP/HEIC (max 10 MB), MP4/WebM/MOV/OGG (max 95 MB), audio such as sound effects - MP3/WAV/AIFF/AAC/M4A/FLAC/OGG (max 50 MB), PDF/Word/PowerPoint/Excel (max 25 MB), plain text (max 1 MB), DaVinci Resolve project files and XML timelines .xml/.fcpxml (max 25 MB, download only). The URL must be reachable without authentication; private, internal and localhost addresses are refused. Only a URL works - bytes from your own machine have to go through the app. This is NOT a task deliverable and NOT a project file (use upload_file_from_url for those), and NOT the HQ item's Files tab; it is document content only.

{
  "url": "https://example.com/file.mp4"
}

Key scope: write:tasks

Grant an EXISTING workspace team member access to a brand. memberId is a member id from list_members; role defaults to editor (admin/supervisor/editor). The grant cascades to the brand's projects. Guests are NOT added here - they go through the invite flow. Returns the brand id, the granted role, and the member. 409 if they already have access.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "memberId": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:projects

Create a top-level brand or client in the workspace (type defaults to brand). socialLinks are free-form named links - social platforms or anything else (Website, Drive, ...). Returns the full brand detail.

{
  "name": "example"
}

Key scope: write:projects

Idempotently ensure the brand has a working client-portal share link at the given access level - one URL that opens EVERY project of the brand to anyone holding it. An active, unexpired link at that level is returned unchanged; a switched-off or expired one is turned back on with a NEW url. It is the same link the brand's Share dialog shows. Returns the share link with its public URL.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:projects

Create a project under a brand or folder Node (nodeId - find it via list_brands or get_project). Optionally pre-create up to 20 top-level folders by name; folder failures do not roll back the project. Returns the project with its created folders.

{
  "name": "example",
  "nodeId": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:projects

Idempotently ensure the project has an active public share link for external reviewers. If one already exists it is reactivated (and its access level updated) instead of minting a new token. Returns the share link with its public URL.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:projects

DESTRUCTIVE. Move a project to Trash (soft-delete) and CASCADE: every active task in the project is trashed with it, and all of them - plus their files - disappear from the client's view immediately. Restorable from the app's Trash page, but a restore is a manual, workspace-wide operation, so treat this as irreversible when planning. CONFIRM WITH THE USER FOR EACH PROJECT, naming it; NEVER loop this tool over a list of projects. Idempotent; no notifications fire. Deletes share one budget across the whole API: about 20 per minute per key, and daily ceilings per key and per workspace - over budget returns 429 with a Retry-After header. A 429 means STOP and tell the user; never wait-and-retry your way through a batch.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:projects

Get a brand's full detail: identity fields, socialLinks, externalMetadata, connected socialAccounts (the brand's social channels - platform, handle, displayName, avatar, follower count, status; credentials excluded), the effective intakeForm (brand brief), and shareLink - the brand's working client-portal share link, or null (create one with create_brand_share_link).

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:projects

Read a brand's header in one call: guidelines/brief, docs, links, attached docs, the raw brand files (bounded), and the header card list (the canvas). Pass the brand id from list_brands.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:projects

Get the brand's client-portal share link - ONE public URL that shows the client every project of the brand (the link the brand's Share dialog shows) - or null if none has been created yet. Check isActive and expiresAt: a switched-off or expired link no longer opens.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:projects

Read a brand's writing-style profile: freeform voice instructions (how this brand titles, tags, and captions its content) plus optional per-platform notes (e.g. YouTube title conventions vs Instagram caption register). ALWAYS read this before composing captions, titles, or descriptions for the brand and follow it. Empty instructions with updatedAt:null = no profile saved yet - compose from the brand's published posts instead (Timeliner's own caption AI also mines those) and consider offering to save the user's preferences via update_brand_voice. The same profile is injected into Timeliner's own caption generation (generate_post_caption and the in-app composer).

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:projects

Get one project plus its active folders, sorted by name.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:projects

Read a project's header in one call: the brief, every doc (guidelines / moodboard), links, attached docs, the raw files (Assets, bounded), and the header card list (the canvas - which sections exist). Pass the project id from list_projects.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:projects

Get the project's public task-board share link, or null if none has been created yet.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:projects

Who currently has access to a brand, with each member's brand-level role. Use this before add_brand_member to see who is already on the brand - adding someone who already has access returns 409, which tells you nothing about anyone else. Each entry has `automatic: true` when the access comes from the member being a workspace ADMIN (admins get every brand automatically) rather than from an explicit assignment. Team members only by default.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:projects

List a brand header's RAW files (the brand's Raw files & Assets) one folder level at a time. Each file: id, name, size (bytes), mimeType, folderId, durationSeconds (null when not media or not known yet), createdAt, hasTranscript (a ready transcript exists) and transcriptStatus (none | pending | extracting | processing | ready | no_speech | failed). The level's subfolders come on the first page (folders[]: id, name, parentId) - pass a folder's id as folderId to open it. Newest file first; when nextBefore is not null, call again with before = nextBefore for the next page. A task can link a brand file only when its project sits directly under this brand: a link column value { items: [{ kind: "brandFile", id }] } (a folder: kind "brandFolder").

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:projects

List the workspace's brands and clients (Nodes of type brand or client), newest first. Use type to restrict to one kind. Brand ids are the nodeId values create_project expects. Each brand includes its connected socialAccounts (the social channels - platform, handle, displayName, avatar, status - with credentials excluded), so you can answer which channels are connected to which brand in one call. Returns {data, nextBefore}; when nextBefore is non-null, call again with before=nextBefore for the next page.

{}

Key scope: read:projects

List a project's RAW files (Raw files & Assets) one folder level at a time - the footage of a shoot, never its task files (deliverables, versions, project-file backups are not listed). Each file: id, name, size (bytes), mimeType, folderId, durationSeconds (null when not media or not known yet), createdAt, hasTranscript (a ready transcript exists) and transcriptStatus (none | pending | extracting | processing | ready | no_speech | failed). The level's subfolders come on the first page (folders[]: id, name, parentId) - pass a folder's id as folderId to open it. Newest file first; when nextBefore is not null, call again with before = nextBefore for the next page. Link a file to a task with set_task_custom_values: a link column value { items: [{ kind: "projectFile", id }] } (a folder: kind "projectFolder"). Read what a video says with get_file_transcript.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:projects

List the workspace's projects, newest first. Returns {data, nextBefore}; when nextBefore is non-null, call again with before=nextBefore for the next page.

{}

Key scope: read:projects

Revoke a team member's access to a brand - the undo for add_brand_member. Scoped to the brand: access granted directly on one of its projects is left alone. Workspace ADMINS cannot be removed from a single brand (409 - they hold every brand automatically; change their workspace role instead), and guests must be removed in the Timeliner app (400 - revoking a guest also rotates their share link). 404 if that member has no access to the brand. Deletes share one budget across the whole API: about 20 per minute per key, and daily ceilings per key and per workspace - over budget returns 429 with a Retry-After header. A 429 means STOP and tell the user; never wait-and-retry your way through a batch.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "memberId": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:projects

Update a brand's writable fields - provide at least one. description is the brand's brief / guidelines text (a brand header doc card that still shows the description - usually Guidelines - follows it until that card is written on its own with update_header_card) - a full text replace; pass "" to clear it, null to leave it untouched. externalMetadata is a FULL-OBJECT REPLACE (read the current value with get_brand and merge client-side before sending; null clears it). socialLinks is the brand's Brand Links card - any label, not just social (Website, Drive, instagram) - and is likewise a FULL-ARRAY REPLACE: read the current list with get_brand, add to it, and send the WHOLE array, or you will wipe the links you left out. [] or null clears them all. Writing description notifies no one. adminApprovalMode is this brand's Admin Approval override. On the Agency + 2 approvers workflow "on" forces the stage, "off" removes it, null inherits the workspace setting; on the Agency, Agency + End Client and Internal workflows "on" ADDS the stage after Supervisor Approval for this brand alone, and null/"off" leave it out. Turning it OFF does NOT move tasks already sitting in Admin Approval; they stay in a stage the brand no longer shows, so prefer the in-app Edit Brand → Workflow flow, which moves them back to Supervisor Approval first. guestAllStagesVisible is this brand's "Show clients every workflow stage" override - true lets the brand's clients (in-app and on its share links) see tasks in every stage, to-do and in-progress included, as VIEW-ONLY cards (stage, deadlines, planned posting time, a thumbnail if any; early-stage media is not playable, commentable or approvable until it reaches client review - except for a guest the task reaches through an assignment, who keeps its pre-setting rights); false hides them; null inherits the workspace setting. guestEarlyStageDocAccess decides how far a DOCUMENT in such a stage goes: placeholder (default) | view | comment | edit; null inherits. Widening either is plan-gated (403 - relay the message verbatim). Suggest these when a client asks to see their whole pipeline or planned work.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:projects

Save or refine a brand's writing-style profile - the durable memory every caption/title generation for the brand obeys (yours via update_post, Timeliner's via generate_post_caption, and the team's in-app composer). Use it when the user teaches you their style ('my YouTube titles are always under 60 chars, curiosity-gap, no clickbait words') so the preference persists beyond this conversation. instructions REPLACES the whole freeform text (read get_brand_voice first and merge - don't drop what's there; ≤4000 chars; "" clears). platformNotes merges per key: string sets that platform's note (≤1000 chars), null (or "") deletes it, omitted platforms are untouched. Write plain prose rules, not JSON. Confirm with the user before overwriting a non-empty existing profile.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:projects

Write the content of ONE card on a brand's or project's header canvas. Get the card id from get_project_header / get_brand_header (`cards[].id`) - one endpoint serves both scopes. Two card types are writable: a `doc` card (send html - a FULL REPLACE of its rich text; simple tags like <h2>, <p>, <ul>/<li>, <strong> render as in the in-app editor; "" clears it) and a `links` card (send links - a FULL REPLACE of the whole list, so include the entries you want to keep; [] clears it). Sending the wrong field for the card's type is a 400. assets/timeline/intake cards render live from other data and fileAttach needs a real upload, so none of them are writable. A PROJECT's Brief card is not writable here (409) - it's a live view of the project's description: use update_project's description instead. Any other doc card, including a brand card still showing the brand description, is written on its own: that one card gets its own text and stops following the description. Silent - no one is notified.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:projects

Update a project's allow-listed fields - name, description, externalMetadata. Send at least one of them - a call with only the id (or only argument names this tool does not define, which are dropped) is refused before it runs and saves nothing. Returns the updated project with its active folders.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "example"
}

Key scope: write:projects

Discard an in-progress upload: the parts already stored are freed and the file record is marked failed. Use it when the part PUTs cannot be made at all - for example your network blocks *.r2.cloudflarestorage.com - so a half-started upload does not linger against the storage plan. Refused (409) once the upload has completed - trash the file instead. Safe to repeat and safe to call after a failed upload: if nothing is in progress under that id it simply succeeds (204).

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:files

Move storage into Trash to free space - NOTHING is deleted permanently (items stay in Trash 30 days and are restorable there). Two modes, exactly one per call: `rule` runs ONE batch (≤500 items) of a cleanup rule and returns remainingCount (repeat until 0); `selection` trashes explicit file/brandFile/task ids from list_storage_items (a task's CURRENT file can only be reclaimed by trashing the whole task via taskIds). Set dryRun=true first to preview counts and freed bytes without changing anything. DESTRUCTIVE: everything it moves leaves the client's view at once. Always dry-run first and show the user the counts before running for real. Requires a write-scope key.

{}

Key scope: write:files

Finish a multipart upload once every part has been PUT. Pass the {partNumber, etag} pairs from the PUT responses. taskId attaches the file as that task's new version (fires version automations, notifies reviewers, lands in the Activity Log) - a regular task or a variant, never a kind=parent task, which holds no file of its own; folderId files a project upload into a folder (never together with taskId). Returns the same UploadedFile shape as upload_file_from_url. Safe to retry: an already-completed upload returns 200 with the same result.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "parts": [
    {
      "partNumber": 1,
      "etag": "example"
    }
  ]
}

Key scope: write:files

Get a short-lived (about 1 hour) presigned download URL for a file. type picks the rendition: original (default), preview, thumbnail, or variant (an MP4 of a transcoded height - height is REQUIRED with type=variant and must be one of the file's media.availableHeights, e.g. 480, 1080, 2160). A variant's MP4 is made on first request: the call then returns status 'generating' with retryAfterSeconds - wait that long and call again until it returns a url. Set downloadName to force a browser download under that filename.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:files

Read the transcript of a RAW file (a project or brand raw file id from list_project_raw_files / list_brand_raw_files) as plain text, with the same statuses as get_task_transcript: ready (text is set), none (never transcribed - start one with start_file_transcription), pending / extracting / processing (being made - call again in ~20s), no_speech, failed. Never starts a transcription. Use it to understand what each video says before writing briefs or tagging.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:files

Rule-based cleanup picks with reclaimable byte totals: oldVersions (superseded versions of delivered tasks), approvedOldTasks, archivedTaskMedia, oldProjectRawFiles, largeStaleFiles. The synthetic `_total` row is the DISTINCT union across rules - quote THAT as the reclaimable figure (rules overlap; summing rows double-counts). Feed a ruleKey into cleanup_storage to act on one.

{}

Key scope: read:files

Read the workspace's storage picture: bytes used vs the plan's capacity plus the per-brand / per-project byte breakdown split by category - deliverableCurrent (tasks' current files), versionOld (superseded task versions, usually the biggest reclaimable chunk), raw (project raw files & assets), headerAttachment, brandFile, commentAttachment, and trashed (already in Trash, purged 30 days after trashing). Matches the in-app Storage page's figures.

{}

Key scope: read:files

List stored files (project + brand) with size, media metadata (duration, fps, width/height), storage category, and task lifecycle context (status, approvedAt/postedAt/archivedAt). Filter by brandId, projectId, category (comma-separated), mimeClass (video|image|audio|doc|other), size and date cutoffs; sort defaults to size_desc (heaviest first). Keyset-paginated via the opaque `cursor`; totalCount/totalBytes describe the FULL filtered set (first page only). Item ids feed cleanup_storage's explicit selection.

{}

Key scope: read:files

Move an existing RAW file (Raw files & assets) to another place: into a project (projectId), into a brand header's Raw files & assets (brandId), or only into a folder of the project or brand it is already in (folderId alone; null = its top level). Add folderId with projectId / brandId to land it in a folder there. The SAME file moves - same id, its comments, its transcript and its share link come along; nothing is downloaded, re-uploaded or copied, and storage is not counted twice. Get the file id from get_project_header or get_brand_header (files[].id). Task files - a deliverable or version (media.fileId from get_task), a task's project-file backup - are refused (409 task_file): download and re-upload those. A file used as a post cover, a published post's file, or in a link column / task hand-off moves only between projects or between brands, never across (409 file_in_use). A name already used at the destination gets a " (1)" suffix (renamed: true). The file shows in the app through the destination header's Raw files & Assets card: when that header has none (a brand starts without one) the move adds it (rawFilesCard.added: true), and a card an admin hid is shown again (rawFilesCard.restored: true) - tell the user when either happened. Who can see the file follows the destination (a brand's guests see its brand files). Silent - no one is notified. Move files one at a time, in sequence - never in parallel.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:files

Re-presign PUT URLs for parts that have not been sent yet (up to 100 per call). Part URLs expire 6 hours after start_file_upload; a large file on a slow link needs fresh ones. The fresh URLs point at the same Cloudflare R2 host (*.r2.cloudflarestorage.com), not at timeliner.io - re-presigning does not help a caller whose network blocks that host.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "partNumbers": [
    1
  ]
}

Key scope: write:files

Start the transcription of a RAW video or audio file, under the same plan and credit rules as the app's Transcribe button (it spends the workspace's transcription minutes). Answers status pending / extracting with started: true; a file that already has a transcript (or one being made) starts nothing and answers its status with started: false - so calling it twice is safe. Then poll get_file_transcript every ~20s until status is ready. Only start the files you actually need to read, one at a time.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:files

Begin a multipart upload for a file the agent can read LOCALLY (a render on this machine, a file in a watched folder) - the counterpart to upload_file_from_url for bytes that are not on a public URL. Pass projectId for a raw project file or taskId for a task's new version (the project is derived). taskId must be a regular task or a variant, never a parent: a task whose kind is "parent" (get_task and list_tasks return kind) is a container with no file of its own - each of its variants carries its own. To upload to one, call list_tasks with that projectId and kind=variant and use a variant whose parentTaskId is the parent's id (none yet → create_task with kind=variant and that parentTaskId). A parent's id is refused with 400. Returns presigned PUT URLs (valid 6h): PUT each part's bytes to its url (every part except the last must be at least 5 MiB; use recommendedPartBytes), record the ETag response header of each PUT, then call complete_file_upload with those {partNumber, etag} pairs. NETWORK REQUIREMENT: those part URLs point at Cloudflare R2 (https://<bucket>.<account>.r2.cloudflarestorage.com), NOT at timeliner.io - the app never proxies bytes - so that host must be reachable from wherever you run. If you are sandboxed behind an outbound allowlist, get *.r2.cloudflarestorage.com allowed BEFORE calling this, or this call and complete_file_upload will both succeed while every PUT fails with your proxy's error; if that happens, call abort_file_upload and ask the user to allow the host or to upload the file in the app. Omit parts to let the server pick a count from size. The file counts toward the workspace's storage plan like any upload.

{
  "fileName": "example",
  "size": 1
}

Key scope: write:files

Put a file INTO Timeliner by giving us a publicly reachable http(s) URL - we download it server-side and attach it. Two destinations: pass taskId to attach it as the task's NEW VERSION (the deliverable - same as a person dragging the file onto the task: it becomes the current version, fires version automations, notifies reviewers, and lands in the Activity Log), or pass projectId alone to save it as a project raw file (optionally inside a folder with folderId). taskId must be a regular task or a variant, never a parent: a task whose kind is "parent" (get_task and list_tasks return kind) is a container with no file of its own - each of its variants carries its own. To upload to one, call list_tasks with that projectId and kind=variant and use a variant whose parentTaskId is the parent's id (none yet → create_task with kind=variant and that parentTaskId). A parent's id is refused with 400. To set a post's cover image: upload the image with projectId, then pass the returned id to update_post as thumbnailFileId. The file must be reachable without authentication and at most 100 MB - bigger deliverables (full 4K exports) still go through the app's own uploader. Private, internal and localhost addresses are refused. fileName overrides the name we infer from the URL; a name already used in the project gets a " (1)" suffix.

{
  "url": "https://files.example.com/exports/launch-reel-03-v2.mp4",
  "taskId": "9b3e7a41-5c2d-4f8e-a6b0-1d7c3e9f2a64",
  "fileName": "launch-reel-03-v2.mp4"
}

Key scope: write:files

Have Timeliner's AI write a post's copy from the task's own material: the video's transcript (or its images for static/carousel posts) plus the brand's previously published posts for voice-matching and any dated corrections the team gave on earlier drafts. Set `field` to choose what to write - 'caption' (default, any network), 'title' (the YouTube video title), or 'tags' (the YouTube tag list); title and tags require platform:'youtube'. Captions are platform-tuned (short for TikTok/Reels, longer for IG feed, written in the source material's language, no emojis/hashtags by design. If the draft already has text in that field, the call REWRITES that text instead (same subject and facts, better wording) and reads nothing from the video, title or brief - no transcription, no transcribing status. Each call costs one AI generation - for a batch, loop task by task. If the video isn't transcribed yet, the call auto-starts transcription and returns {status:"transcribing", retryAfterSeconds} - retry the SAME call after that many seconds until it flips to {status:"ok"} (usually under a minute or two). {status:"failed"} is terminal for the task's current material (reason: no_speech, transcript_failed, transcripts_unavailable, no_visuals, insufficient_content). reason:transcript_failed means an EARLIER transcription of this video failed; its message says why. Calling again unchanged will always fail the same way - pass retryTranscription:true ONCE to re-run the transcription (spends minutes) and get {status:"transcribing"} back, then poll as above. If it fails again with the same reason the video cannot be transcribed as it stands: stop calling, tell the user, and either replace the file or write the caption without a transcript. reason:ai_unavailable (HTTP 503) means Timeliner's AI is temporarily out of capacity: every call fails the same way until it recovers, so stop calling, tell the user, and try again later. Read the result from `text` (`caption` is a deprecated alias kept for older clients). apply:true saves the result into the post draft (the shared caption, `platform`'s override, or the YouTube options for title/tags) so the team sees it in the composer - same side effect as update_post: a caption change resets the client's caption approval. apply defaults to false (the copy is only returned). Never schedules or publishes anything. Fails 400 for title/tags without platform:'youtube' and 409 when apply:true targets an already-published post. On a workspace whose plan does not include social posting the call is refused before it runs and returns {"available": false, "reason": "planDoesNotIncludeSocialPosting"} - a final answer, not data and not a retryable error: relay it and stop calling this tool.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:posts

Learn WHAT WORKED on social: the published posts that beat and trailed their platform's typical engagement rate, each joined with its hook (first caption line + what the video says in its first 8 seconds, from the transcript), a transcript excerpt (≤600 chars), duration, format and metrics - plus pattern findings (hook length, question hooks, duration, format, caption length, best weekday/hour vs the median), each with sampleSize and lowConfidence. engagementRate = (likes+comments)/views; relativeToMedian = that rate ÷ the platform's median (1.8 = 80% above typical). Only posts published ≥24 h ago with views are scored, and a platform needs ≥3 such posts. Pattern buckets: hookLength short|medium|long (≤8 / 9-15 / >15 words); questionHook question|statement; duration under15|15to30|30to60|60to180|over180 (seconds); captionLength short|medium|long (<100 / 100-300 / >300 chars); weekday 0-6 = Mon-Sun; hour 0-23 in timeZone. Say 'low confidence' whenever lowConfidence is true; never overstate a pattern. Defaults to the last 90 days; same filters as get_social_analytics. Posts imported from outside Timeliner (source:'external', taskId null) are ranked too - their hook is the caption and they never carry a transcript. On a workspace whose plan does not include social posting the call is refused before it runs and returns {"available": false, "reason": "planDoesNotIncludeSocialPosting"} - a final answer: relay it and stop.

{}

Key scope: read:posts

Official statements from the social platforms themselves (Instagram, Facebook, TikTok, YouTube, LinkedIn, X, Threads) on third-party scheduling & reach, original vs reposted content, trial reels, collaborators, audio, posting limits, required disclosures and API deprecations - newest first. Every item carries title, summary, sourceUrl + sourceTitle (always an official platform domain), publishedAt (the source's own date, may be null) and fetchedAt (when it was read). DEFAULT scope 'workspace' answers 'any platform changes I should know about?' for THIS workspace: only its connected networks (connectedPlatforms), each item's affects.accounts (handle, brandName) and affects.posts (its upcoming + last-30-days posts; postCount = all), developer / API notices left out (developerNoticesOmitted - Timeliner handles them), and accountsNeedingAttention = accounts whose connection expired or was revoked (the user must reconnect them). Answer per item with the account handles and affected post titles, or say none of their posts is affected; when `note` is set (nothing connected / nothing new for their networks) say exactly that - never a generic list. scope 'all' = every network's guidance (a network they have not connected, or the rules in general). ALWAYS cite title + URL + date when you use an item. If no item covers the question, say plainly that no official source settles it - never fill the gap with blog folklore. source:'seed' = the built-in verified set (no newer collection yet).

{}

Key scope: read:posts

Read the social-performance bundle for reports. KPIs also carry shares / saves (+ previous window) and followsGained / followsLost when a network reported them (null, never 0, otherwise); posts[].metrics carry followsGained / followsLost (YouTube subscribers gained/lost, Instagram feed follows). YouTube's audience is SUBSCRIBERS - say 'subscribers', never 'followers', for YouTube. followersDeltaSince (kpis + channels) is set when growth is measured from the first day an account was tracked inside the window - say 'since <date>'. To explain WHY posts worked, pair this with the content-insights tool (hooks + transcripts). VIEWS-BASED metric model: every platform reports views today (YouTube/IG/TikTok view counts; Meta calls its impressions 'views'), so lead reports with views / likes / comments / shares (where reported) + engagementRate = (likes + comments) / views; reach/impressions remain on rows as legacy Meta-only fields - don't lead with them (always null on YouTube). Returns: KPIs (views / engagement / engagementRate / posts published, each with previous-window comparison + follower delta), per-day trend (views + engagement per platform), per-channel breakdown, post performance rows (with permalinks + editorIds, the member(s) who produced each post's task), a byEditor breakdown (per-editor postsPublished + views / videoViews / engagement / likes / comments, split evenly across each post's editors so per-editor sums reconcile to the KPI totals; editorId:null = the unattributed bucket), top posts, engagement heatmap (weekday×hour), content mix, video watch-time analytics (per-post totalWatchTimeSeconds / avgWatchTimeSeconds / avgViewPercentage + trafficSources, null on platforms without a watch-time signal; Instagram Reels also populate watch-time, and posts carry Instagram rich signals skipRate (Reels) + storyNavigation/storyReplies/storyLinkClicks (Stories)), an accountInsights array (per Instagram account: profileVisits / follows / unfollows / websiteClicks over the window + daysWithData - account-level only, never per post; empty when no IG data, never zeros), publishing funnel, planned-content pipeline (drafts / pending approval / scheduled / failed / missed + next post), and follower trend. Same numbers as the in-app Analytics → Social section. posts[] (and so KPIs / trend / channels / top posts / heatmap / content mix) also include posts published OUTSIDE Timeliner, imported from each connected account (source:'external' - taskId / scheduledPostId null, no editors, never in byEditor / funnel / planned; duplicates of Timeliner posts are removed); every other row is source:'timeliner'. For account-level daily history and audience demographics use get_social_history. HONESTY CONTRACT: entries with metricsAvailable:false carry metrics:null - that platform's numbers were never fetched (manual posts, or no metrics integration yet) - report 'no data', NEVER zeros. hasEverPublished:false = nothing was ever published through Timeliner and no history was imported (empty state - say so instead of inventing a report). Defaults to the last 30 days; scope with from/to, brandId, projectId, accountId, or platforms. This is distinct from get_analytics (business/production analytics), which is not plan-gated. On a workspace whose plan does not include social posting the call is refused before it runs and returns {"available": false, "reason": "planDoesNotIncludeSocialPosting"} - a final answer, not data and not a retryable error: relay it and stop calling this tool.

{}

Key scope: read:posts

Account-level social HISTORY per connected account: daily points (UTC day) with followers (YouTube: SUBSCRIBERS, reconstructed backwards from the live count - say 'estimated'), followersGained / followersLost, views, reach, impressions, engagement, likes, comments, shares, saves, profileVisits, websiteClicks, watchMinutes and postsPublished (Timeliner + posts published outside Timeliner); the latest audience demographics per account (gender / age / country / city shares 0-1; basis 'followers' on Instagram, 'viewers' on YouTube; empty below a network's privacy threshold, e.g. Instagram needs 100+ followers); and importStatus per account (state idle|queued|running|done|error|unsupported, importedPosts, historyFrom, unsupportedReason tiktokApproval|linkedinApproval|reconnectRequired). HONESTY: a metric a network does not report is null - say 'no data', never 0; history only exists once the import has run for that account (state done/running) - while it is queued/idle say it is still importing. Posts themselves (including the imported ones) are in get_social_analytics posts[] (source:'external'). Defaults to the last 30 days; same filters as get_social_analytics. On a workspace whose plan does not include social posting the call is refused before it runs and returns {"available": false, "reason": "planDoesNotIncludeSocialPosting"} - a final answer: relay it and stop.

{}

Key scope: read:posts

The connected-vs-manual channel map, per brand - use it BEFORE scheduling to tell the user which platforms will auto-post and which they'll have to post manually. Every platform is listed for every brand with: connected (a live connected account exists - its posts auto-publish), autoPublishSupported (false = always manual), and account (handle/displayName/followerCount; also present with status 'expired'/'revoked' when a reconnect is needed - say so). Optional brandId narrows to one brand. Channels connect in-app (brand dialog → Connected accounts, or a client connect link) - you cannot connect accounts via the API.

{}

Key scope: read:posts

Read the social-posting calendar: the workspace's scheduled/published posts, newest first. A post is a task with a scheduling status. Each post carries brandId + projectId; assigneeIds (the team-member ids assigned to the post's task - resolve names via list_members; answers 'which editor made this post' without a get_task per post, [] when unassigned); the deliverable approval stage (statusGroup - inRevision = sent back/rejected, approved/posted = signed off); overallStatus (the publish rollup: draft|pending|manual|published|failed|missed); scheduledAt; a review object (guest per-element sign-off: caption/thumbnail/schedule approved-at timestamps, null = not approved); media + customThumbnail (presigned download/thumbnail/preview URLs you can open to SEE the media); and a networks array - one entry per social network with its caption, status, scheduledAt/publishedAt, permalink (the live post URL once posted), the connected account it publishes to (account: handle/displayName/avatar/platform), per-network media override, and platformOptions (e.g. YouTube title/tags/visibility, IG format). Times are UTC instants - interpret them in the response's top-level timezone (the workspace IANA zone, also on get_workspace). Filter by taskId (a post is keyed by its task - there is no get_post), projectId, brandId, overall status, or a calendar window with scheduledFrom/scheduledTo. Returns {data, nextBefore}; when nextBefore is non-null, call again with before=nextBefore for the next page.

{}

Key scope: read:posts

Schedule a task as a social post - a media task, or a regular DOCUMENT task (a text-first post: the document is the post text, and the task's one file, if it has one, is the attachment): set the slot (scheduledAt, must be in the future) + target platforms. Full-replace semantics (also reschedules and re-arms a 'missed' post); draft:true places a calendar draft that never enters the publish queue. The response tells you what will ACTUALLY happen - always relay it: `channels` lists each leg as auto (a connected account publishes it) or manual (not connected - so the team posts it themselves), and `approvalGate` says whether the post will auto-publish at the slot. IMPORTANT: when the workspace requires approval before posting (the default) and the task is not 'approved'/'posted', the schedule still succeeds but the post will NOT fire - at the slot it is marked 'missed' and held (it never auto-publishes late; it must be rescheduled). Relay the approvalGate.warning and ASK the user whether to move the task to 'approved' now - if yes, call update_task with statusGroup:'approved' (a deliberate, notifying, hard-to-undo step; never do it silently). Routing through 'clientApproval' instead does NOT publish - the client must approve (reaching 'approved') before the slot. Compose content first (update_post / generate_post_caption) and check list_channels to pick platforms. Fires the same post-plan notification as an in-app schedule (guests only see it once the task is at clientApproval or later) and the partner post.status_changed webhook. Fails 409 on an already-published post and 400 for past slots, for a parent or document-variant task, and for a text-only document post (no file attached) aimed at a network that needs media - only LinkedIn and Facebook take text-only posts; attach media first with upload_file_from_url and the same taskId. A document post that was approved and then changed is held at its slot until it is approved again. On a workspace whose plan does not include social posting the call is refused before it runs and returns {"available": false, "reason": "planDoesNotIncludeSocialPosting"} - a final answer, not data and not a retryable error: relay it and stop calling this tool.

{
  "id": "9b3e7a41-5c2d-4f8e-a6b0-1d7c3e9f2a64",
  "scheduledAt": "2026-11-02T15:00:00.000Z",
  "platforms": [
    "instagram",
    "tiktok"
  ]
}

Key scope: write:posts

Remove a post from the publish queue: clears the slot and the scheduling status (the platform selection is kept so re-scheduling doesn't re-pick networks). Use it to cancel a scheduled/draft/manual/missed post before it goes out. Fails 409 when the post isn't scheduled or is already published (a live post can't be unscheduled - deleting it from the network stays in-app). On a workspace whose plan does not include social posting the call is refused before it runs and returns {"available": false, "reason": "planDoesNotIncludeSocialPosting"} - a final answer, not data and not a retryable error: relay it and stop calling this tool. Deletes share one budget across the whole API: about 20 per minute per key, and daily ceilings per key and per workspace - over budget returns 429 with a Retry-After header. A 429 means STOP and tell the user; never wait-and-retry your way through a batch.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:posts

Write or rewrite a post's content - the shared caption, per-network caption overrides, the custom cover (thumbnailFileId - a file already uploaded to the post's project; changing it resets the client's thumbnail approval), and/or the per-network settings via platformOptions: YouTube metadata (title, tags, visibility, isShorts), Instagram (format feed/reel/story, collaborator - up to 3 handles, really invited at publish), first comment), Facebook (first comment; format only accepts 'post' for now), LinkedIn (postAs personal/company - also covers Company Page legs, targetAudience [stored but not applied at publish yet], first comment), and TikTok (privacyLevel, allowComments/Duet/Stitch, commercial-content toggles). Manual steps: collaborators on LinkedIn / YouTube (videos and Shorts) / TikTok / Facebook and an in-app audioNote (Instagram, TikTok, Facebook Reels, YouTube Shorts) make that network's leg a manual hand-off - the team is reminded at posting time instead of it auto-publishing; Instagram trialReel is refused (422) until enabled for the deployment. This is the content-crafting tool: read the post (list_posts with taskId) or the task's media (get_task) for context, draft the copy, and save it here. Read the brand's voice profile first (get_brand_voice) and write in that style. A post is keyed by its task; writing content for a media task that isn't planned on the calendar yet is allowed and simply pre-fills the composer for the team. On a DOCUMENT post (a regular doc task) the shared caption IS the document: do not send `caption` here (409 captionFromDoc) - change the text with update_task_doc, and the post follows it; platformCaptions, platformOptions (e.g. LinkedIn firstComment) and thumbnailFileId work as usual. This tool NEVER schedules, moves, or publishes anything - use schedule_post for the slot + networks - and it fires no notifications. platformCaptions merges per key: a string sets that network's override, null (or "") removes it so the network falls back to the shared caption; omitted networks are untouched. platformOptions deep-merges per platform - unpatched fields (thumbnails, covers, A/B state - not writable via the API) survive. Captions are capped at 5000 characters (stricter per-network limits are enforced by the composer); YouTube titles at 100; first comments at 2200. TikTok commercial-content legality combos are clamped at publish against the creator's live options. Editing the caption of an already-client-approved post resets its caption approval (the client re-reviews), exactly like an in-app edit. Fails with 409 on published posts (frozen). Send at least one of caption, platformCaptions, platformOptions or thumbnailFileId - a call with only the id (or only argument names this tool does not define, which are dropped) is refused before it runs and saves nothing. On a workspace whose plan does not include social posting the call is refused before it runs and returns {"available": false, "reason": "planDoesNotIncludeSocialPosting"} - a final answer, not data and not a retryable error: relay it and stop calling this tool.

{
  "id": "9b3e7a41-5c2d-4f8e-a6b0-1d7c3e9f2a64",
  "caption": "Our new collection is live. Link in bio."
}

Key scope: write:posts

Post a message into a chat channel, authored by the API key's creator. Silent - nothing beyond the channel's own unread badge fires. Find the channel with list_chat_channels first. NOT for social publishing.

{
  "scopeType": "global",
  "text": "example"
}

Key scope: write:chat

Post a message in a task's chat, authored by the API key's creator. Silent - no one is notified. Use create_task_comment instead for timecoded review feedback on a cut.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "text": "example"
}

Key scope: write:chat

List the CHAT channels the API key's creator can see in Discussions: the workspace-wide channel and standalone channels like #marketing. Each: scopeType, scopeId, name, visibility (private/team/client, standalone only), archived. Private channels the key's creator isn't a member of are omitted. NOT social posting accounts - that's list_channels.

{}

Key scope: read:chat

Read recent messages in one chat channel, oldest-first. scopeType is 'global' (no scopeId), or 'brand' / 'project' / 'dm' / 'custom' with the matching id - get standalone channel ids from list_chat_channels. Each message: id, text, author, isSystem, teamOnly, createdAt.

{
  "scopeType": "global"
}

Key scope: read:chat

Read a task's CHAT - the conversation about the task (updates, questions, decisions). Returns the NEWEST posts (default 30, max 100 via `limit`), presented oldest-first. This is NOT the timecoded review thread: use list_task_comments for feedback on a specific frame. Pass a task id from list_tasks.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:chat

Per-member profitability for ANY pay type - the 'was this hire/freelancer worth it?' dataset: total cost (per-task pay + fixed project fees + prorated salary), what's been paid out, BOOKED client revenue attributed to them (billing-mode aware: task prices split across a task's editors; fixed/legacy project prices allocated by delivered share), delivered + in-progress counts, cost per video, a strong/thin/underwater ROI verdict, and - over the same window - viewsAttributed + engagementAttributed (the video views and engagement their published videos earned, even-split per editor; null when the workspace has no social-distribution data). Answers 'what did this editor cost me and how many views did their videos get?' in one call. `payType` reports the member's model over the window: perTask | perProject | monthly | mixed (both task pay and project fees). Optional from/to (ISO date) filter by task creation date; optional memberId narrows to one member; includeProjects=true appends members[].projects[] - the per-(member, project) breakdown (pay model there, fee, per-task buckets, tagged/delivered counts, and the days span from first task to last delivery).

{}

Key scope: read:finance

What the agency owes its team (editors) - split approved vs pending and paid vs unpaid, per editor, plus workspace totals. Members on a monthly salary are reported under `salaries` instead of the per-task buckets: each row carries windowCost (prorated salary), delivered, activeCount (still in progress/revisions), costPerVideo, and attributedRevenue (booked client money credited to their work). To judge whether a hire is worth it, compare attributedRevenue vs windowCost (≥2x = healthy, <1x = losing money) and check costPerVideo against what the client pays per deliverable. Optional from/to (ISO date) filter by task creation date. The numbers match the in-app Payments Dashboard and the analytics Cost tab.

{}

Key scope: read:finance

What each brand/client owes the agency - split approved vs pending and paid vs outstanding, per brand, plus workspace totals and net + projected margin. Includes project-level prices (retainer/package deals) folded into the totals and itemized under `projects`. Optional from/to (ISO date) filter by task creation date. The numbers match the in-app Analytics Financial Summary.

{}

Key scope: read:finance

One project's profit & loss - billing-mode-aware revenue (a fixed project price IS the revenue; otherwise task prices bill), team cost (per-task pay or fixed member fees, plus salary allocated by delivered share), realized margin and margin %. `unpricedTasks` > 0 means the margin is an 'at least' figure. Optional from/to (ISO date) filter by task creation date. Matches the in-app Project Profitability card.

{
  "id": "example"
}

Key scope: read:finance

The append-only payment ledger - what money ACTUALLY moved, with real business dates (including backdates). Each row carries `voided` (true when a reversal cancelled it) and reversal rows carry `reverses`. Filter by direction ('out' = paid to members, 'in' = received from brands), counterparty (editor/node), project, or a paid_at date window. Matches the in-app Payment history blocks.

{}

Key scope: read:finance

List the workspace's reusable pricing models/templates - name, pricingMode (flat/rules/profitShare/hourly), default client price + editor pay, and badge. Use these to understand how deliverables are priced.

{}

Key scope: read:finance

Record ONE payment in the append-only ledger - money paid OUT to a team member (memberId required) or received IN from a brand/client (nodeId required). Partial amounts are fine; backdate with paidAt when the money moved earlier. Does NOT mark owed tasks/prices as settled. Pass idempotencyKey to make retries safe (a replay returns the original row with duplicate=true). Corrections go through void_payment, never edits.

{
  "direction": "in",
  "amount": 1
}

Key scope: write:finance

Settle client money: mark specific tasks' client prices (taskIds) OR one project's project-level price (projectId - retainers / fixed billing) as received or outstanding. Exactly one of taskIds/projectId. Marking received writes dated 'in' ledger entries with the brand counterparty (backdate with paidAt); marking outstanding voids them by reversal. Same engine as the in-app brand tab.

{
  "paid": true
}

Key scope: write:finance

Settle team money: mark per-task pay rows (editorPayIds - TaskEditorPay ids from get_pricing_payables) and/or per-member project fees (memberFeeIds) as paid or unpaid. Marking paid writes dated 'out' entries in the append-only ledger (backdate with paidAt when the money went out earlier); marking unpaid voids them by reversal. Idempotent on retry. Same engine as the in-app checkboxes.

{
  "paid": true
}

Key scope: write:finance

Configure a project's two independent billing axes - client side: 'perTask' (task prices bill) or 'fixedPrice' (one project price IS the revenue; amount required, optional label); team side: 'perTask' (per-task pay rows) or 'fixedProject' (one fee per member; memberFees replaces the fee list - absent unpaid rows are removed, paid rows survive). For SINGLE-member fee changes ('pay Alex $1,500 for this project') use team.feeUpdates instead - a merge that upserts each listed member's fee (amount null = remove), valid on ANY team mode (the fee becomes that member's pay of record in this project; their per-task pay there stops counting). Any combination is valid. Existing task prices/pay rows are KEPT but stop counting per the mode - switching back restores them; nothing is destroyed. Paid fees are payment records and refuse edits (409).

{
  "id": "example"
}

Key scope: write:finance

Apply a pricing template to ONE task and/or set which template split role each assigned editor fills - e.g. two editors on a task but only the one tagged 'Online Editor' is paid: pass editorRoles [{memberId: <online editor>, role: 'Online Editor'}, {memberId: <other>, role: null}]. role null is 'No role (not paid)' - an opt-out that zeroes that editor's pay, NOT a clear; to return an editor to untagged send {memberId, role: null, untag: true}. To undo a change, re-send only the editors you changed: their previous role, or untag: true where the result's roleSource was null - never role null for them. A role one editor holds is never auto-given to another, and editors sharing one role split its share. Prices are recomputed by the in-app engine and the result lists every editor's role, roleSource and amount. Template ids come from list_pricing_templates, member ids from list_members / get_task. Refused (409) once money has moved on the task (a payout marked paid, the client price received, or a recorded payment).

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:finance

Cancel one ledger payment by recording its reversal (the ledger is append-only - nothing is deleted; the history keeps both entries). Voiding an already-voided payment returns a 409 conflict; reversal rows themselves cannot be voided.

{
  "id": "example"
}

Key scope: write:finance

Create an Automations Center rule - e.g. the backward-scheduling recipe: trigger publishDateScheduled + setDateColumn/setDeadline/setStartDate actions with NEGATIVE offsetDays counting back from the publish date (-21 = 21 days before publish). The same recipe works from a client's intake answer: trigger intakeApproved with anchorQuestionId set to a DATE question on the request form, and every offset counts back from the date the client asked for. Under status/stage triggers, offsets count from the moment the rule fires instead. Max 25 rules per SCOPE (50 on Scale and Enterprise) - pack up to 20 actions into one rule rather than one rule per action. Pass brandId to scope the rule to one brand (from list_brands) instead of the whole workspace; a brand-scoped rule runs only on that brand's tasks AND only if that brand is set to use its own automations, so tell the user to check the brand's Automations settings. Pass hqBoardId INSTEAD to scope the rule to an HQ board (from list_hq_boards): the trigger and every action must then come from the hq* vocabulary, and the rule runs on that board's items only - brandId and hqBoardId are mutually exclusive. Two recipes worth knowing on a board: hqDueDateReached with a NEGATIVE offsetDays nudges before a card is due (reminders are armed when a due date is set or changed, so already-overdue cards are never flushed), and createHqItem on a DELIVERABLE rule drops a card on a board when a task lands - one card per (board, task), so it is safe on a status a task reaches repeatedly. Read list_automation_rules first; if the response's automationsCenterEnabled is false, warn the user the rule is saved but dormant until Settings → Automations is switched on. Requires an upgraded plan. NOT update_automations (review/workflow timeout scalars).

{
  "trigger": {
    "type": "hqItemCreated"
  },
  "actions": [
    {
      "type": "hqMoveToStage",
      "target": "next"
    }
  ]
}

Key scope: write:automations

Create a new named intake (deliverable-request) form. Give a name; the authoring language can be any language Timeliner supports and defaults to 'en'. The first form (or setAsDefault:true) becomes the workspace default. The questions + catalog are then built in the app. Returns the created form. (Plan-gated feature; supervisor+.)

{
  "name": "example"
}

Key scope: write:automations

Permanently delete an Automations Center rule. Its run history is kept, but the rule cannot be restored - confirm with the user which rule dies before calling. To pause a rule instead, use update_automation_rule with enabled:false. Deletes share one budget across the whole API: about 20 per minute per key, and daily ceilings per key and per workspace - over budget returns 429 with a Retry-After header. A 429 means STOP and tell the user; never wait-and-retry your way through a batch.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:automations

Read the workspace's automations: the review/workflow timeouts (auto-advance variant review, auto-revert-after-comment, auto-submit-for-review, the guest revert windows) AND the read-only notification automations (quiet hours, anti-spam batching, the scheduled catch-up digest).

{}

Key scope: read:automations

Read one intake form in full: its sections (goal / central message / deadline / catalog / …), the question builder, the catalog items (deliverables with prices/badges), and the post-submission settings. Pass a form id from list_intake_forms.

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: read:automations

Read the workspace's Automations Center rules - the 'when X happens → do Y' rules. TWO VOCABULARIES, never mixed inside one rule. DELIVERABLE rules (hqBoardId null): triggers status/stage change, posting time scheduled, a date column set, a version uploaded with optional media conditions, a client request approved, a client request coming in; actions move stage, set status, assign/unassign, set deadlines/dates/posting time/project deadline, send to brand, notify, apply a pricing template, add a card to an HQ board (createHqItem). HQ BOARD rules (hqBoardId set): triggers hqItemCreated, hqStageChanged, hqItemAssigned, hqDueDateSet, hqDueDateReached, hqFieldChanged, hqDocUpdated, hqFileAttached; actions hqMoveToStage, hqSetField, hqAssign, hqUnassign, hqSetDueDate, hqNotify, and hqSetSourceTaskStatus (moves the deliverable a card was spawned from). Use this to answer 'what automations do we have?' - and ALWAYS before create/update/delete_automation_rule. The response's automationsCenterEnabled is the master toggle: false means every rule is dormant. Each rule's brandId says which brand it is scoped to and hqBoardId which HQ board; both null means workspace-global. Pass brandId to list one brand's rules ('none' = only the workspace-global ones), or hqBoardId to list one board's ('none' = only the deliverable rules). Requires an upgraded plan. Not to be confused with get_automations (review/workflow timeouts).

{}

Key scope: read:automations

List the workspace's intake (deliverable-request) forms - the Typeform-style request forms clients fill in to request work. Returns each form's id, name, language, and whether it's the workspace default. (Plan-gated feature.)

{}

Key scope: read:automations

Edit an Automations Center rule: change its recipe (pass BOTH trigger and actions - they must come together) and/or flip enabled. Get rule ids from list_automation_rules. A rule's SCOPE is fixed - a board rule stays on its board and its replacement recipe must still use the hq* vocabulary; moving a rule between scopes means creating a new one. Enabled-only changes work on any plan; recipe edits need an upgraded plan. NOT update_automations (review/workflow timeout scalars).

{
  "id": "00000000-0000-0000-0000-000000000000"
}

Key scope: write:automations

Change one or more REVIEW/WORKFLOW automations. Minutes: 0 = off. Guest windows: 0 = off, -1 = forever, else minutes. The notification automations (quiet/batch/catch-up) are read-only here - change those in the app. Returns the full updated automations.

{}

Key scope: write:automations

Create a workload block for a team member: a shoot day / location scout ('production'), a vacation or public holiday ('timeOff' - reduces their capacity), or 'other'. Applies to every calendar day in the range, weekends included (a Saturday shoot is the point). minutesPerDay is the daily amount (480 = 8h).