Complete MCP tool reference

The human-readable contract for every public Tareno Remote MCP tool. Runtime clients should still treattools/list as the source of truth for the current JSON Schema.

Endpoint
https://tareno.co/api/mcp

Tools

50 items

Batch maximum

15 minutes

Approval TTL

60/minute

Burst default

Supported social channels

Core account, post, draft, scheduling and publishing workflows cover all ten channels. Public-video extraction is intentionally narrower and only available where the Tareno extraction backend supports the provider.

Channel	Core MCP	Transcript	Video download
Bluesky	yes	—	—
Facebook	yes	yes	yes
Instagram	yes	yes	yes
LinkedIn	yes	—	yes
Mastodon	yes	—	—
Pinterest	yes	yes	yes
Threads	yes	yes	yes
TikTok	yes	yes	yes
X / Twitter	yes	—	yes
YouTube	yes	yes	yes

Transcript: Facebook, Instagram, Pinterest, Threads, TikTok and YouTube. Download: those six plus LinkedIn and X/Twitter. Only public HTTPS posts are accepted.

Execution and approval rules

Read tools and draft tools execute immediately.
Scheduling, publishing, scheduled edits, rescheduling, and deletion only create a pending action.
No connector or post mutation occurs before dashboard approval.
Approval status is one of: pending, executing, succeeded, failed, rejected, expired.
Every risky batch is limited to 50 items.
Risky writes require an idempotencyKey with 8–128 trimmed characters.
After approval, the executor rechecks ownership, key, plan, scopes, and platform rules.
Mixed provider results use partial_failure and expose each item result.

Scope matrix

Scope	Tools
workspaces:read	list_workspaces
accounts:read	list_accounts, get_platform_schema, get_platform_options
posts:read	list_posts, get_post
posts:draft	create_drafts
posts:update	update_draft, reschedule_post, update_scheduled_post
posts:schedule	schedule_posts, reschedule_post, update_scheduled_post
posts:publish	publish_posts
posts:delete	delete_post
media:read	list_media, get_social_media_transcript, get_social_video_download
media:write	upload_media_from_url
analytics:read	get_analytics_overview, get_platform_analytics, get_content_strategy
actions:read	get_action_status

Legacy read, write, and publish API-key scopes are expanded server-side into these granular scopes.

`pinterest_boards`

Load this option after list_accounts and get_platform_schema; the account platform must match.

Request

{
  "accountId": "pinterest-account-uuid",
  "option": "pinterest_boards"
}

Response

{
  "status": "ok",
  "option": "pinterest_boards",
  "items": [
    {
      "value": "board-id",
      "label": "Summer ideas",
      "description": "Campaign board"
    }
  ]
}

`tiktok_creator_info`

Load this option after list_accounts and get_platform_schema; the account platform must match.

Request

{
  "accountId": "tiktok-account-uuid",
  "option": "tiktok_creator_info"
}

Response

{
  "status": "ok",
  "option": "tiktok_creator_info",
  "creator": {
    "creator_nickname": "Acme",
    "privacy_level_options": [
      "PUBLIC_TO_EVERYONE"
    ],
    "max_video_post_duration_sec": 60
  }
}

Tool contracts

list_workspaces

Lists workspaces owned by or shared with the authenticated user.

workspacesworkspaces:readdirect

Input fields

Field	Type	Required	Details
No input fields.

Request

{}

Success response

{
  "status": "ok",
  "count": 1,
  "workspaces": [
    {
      "id": "workspace-uuid",
      "name": "Acme",
      "slug": "acme",
      "ownerId": "user-uuid",
      "updatedAt": "2026-07-13T09:00:00.000Z",
      "_count": {
        "workspaceAccounts": 3,
        "members": 2
      }
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

list_accounts

Lists connected social accounts, optionally filtered by workspace or platform.

accountsaccounts:readdirect

Input fields

Field	Type	Required	Details
workspaceId	string	no	Optional workspace filter.
platform	string	no	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube.

Request

{
  "platform": "instagram"
}

Success response

{
  "status": "ok",
  "count": 1,
  "accounts": [
    {
      "id": "account-uuid",
      "platform": "instagram",
      "platformAccountId": "provider-id",
      "username": "acme",
      "displayName": "Acme",
      "profilePicture": "https://cdn.example.com/avatar.jpg",
      "health": {
        "status": "healthy",
        "reason": null,
        "action": null,
        "publishingDisabled": false
      },
      "connectedAt": "2026-07-13T09:00:00.000Z"
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
WORKSPACE_NOT_FOUND	The workspace is not owned by or shared with the authenticated user.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_platform_schema

Returns server-derived platform capabilities and publishing requirements for one account.

accountsaccounts:readdirect

Input fields

Field	Type	Required	Details
accountId	string (UUID)	yes	Connected account to inspect.

Request

{
  "accountId": "account-uuid"
}

Success response

{
  "status": "ok",
  "account": {
    "id": "account-uuid",
    "platform": "pinterest",
    "username": "acme",
    "healthStatus": "healthy"
  },
  "capabilities": {
    "contentTypes": {
      "text": {
        "requiresMedia": true
      }
    }
  },
  "requirements": {
    "accountId": true,
    "mediaRequired": true,
    "pinterestBoardRequired": true,
    "dynamicOptions": [
      "pinterest_boards"
    ]
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_platform_options

Loads whitelisted dynamic options from Pinterest or TikTok.

accountsaccounts:readdirect

Input fields

Field	Type	Required	Details
accountId	string (UUID)	yes	Connected Pinterest or TikTok account.
option	string	yes	Either pinterest_boards or tiktok_creator_info.

Request

{
  "accountId": "pinterest-account-uuid",
  "option": "pinterest_boards"
}

Success response

{
  "status": "ok",
  "option": "pinterest_boards",
  "items": [
    {
      "value": "board-id",
      "label": "Summer ideas",
      "description": "Campaign board"
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
OPTION_PLATFORM_MISMATCH	The option does not belong to the selected account's platform.	no
ACCOUNT_RECONNECT_REQUIRED	The provider token is missing or expired.	no
PROVIDER_ERROR	A connected platform returned an upstream failure.	yes
UNSUPPORTED_OPTION	The option is not on the allowlist.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

list_posts

Lists posts for the authenticated user's account or workspace.

postsposts:readdirect

Input fields

Field	Type	Required	Details
workspaceId	string	no	Optional workspace filter.
status	string	no	draft, scheduled, processing, published, or failed.
platform	string	no	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube.
accountId	string (UUID)	no	Optional account filter.
from	string (ISO 8601 with offset)	no	Optional inclusive start time.
to	string (ISO 8601 with offset)	no	Optional inclusive end time.
limit	integer	no	Maximum number of posts. 1–100. Default: 50.

Request

{
  "status": "scheduled",
  "limit": 20
}

Success response

{
  "status": "ok",
  "count": 1,
  "posts": [
    {
      "id": "post-uuid",
      "platform": "instagram",
      "status": "scheduled",
      "start": "2026-07-14T09:00:00.000Z",
      "content": "Launch update"
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
WORKSPACE_NOT_FOUND	The workspace is not owned by or shared with the authenticated user.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_post

Returns the full stored post record when it belongs to the user or an accessible workspace.

postsposts:readdirect

Input fields

Field	Type	Required	Details
postId	string (UUID)	yes	Post to retrieve.

Request

{
  "postId": "post-uuid"
}

Success response

{
  "status": "ok",
  "post": {
    "id": "post-uuid",
    "platform": "linkedin",
    "status": "draft",
    "content": "Launch update"
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
POST_NOT_FOUND	The post is not accessible to the authenticated user.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

create_drafts

Creates one to 50 drafts. Draft creation does not schedule or publish anything.

postsposts:draftdirect

Input fields

Field	Type	Required	Details
items	array of post objects	yes	Draft items. 1–50 items; each item uses the post fields below.
idempotencyKey	string	no	Optional replay key. 8–128 trimmed characters.
accountId	string (UUID)	no	Connected account used for the post. Required for scheduling and publishing; optional only for an unassigned draft.
platform	string	yes	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube. Required for every item and must match accountId when an account is supplied.
title	string	no	Optional post title. Maximum 200 characters.
text	string	no	Optional post body. Maximum 20,000 characters; omit only for a platform-valid media-only post.
mediaUrls	array	no	An object with required url and optional kind, thumbnailUrl, and altText. Maximum 35 items; URLs must be valid; remote imports require public HTTPS. Omit when no media is needed; platform rules are validated after account lookup.
format	string	no	Optional publishing format. post, carousel, reel, story, video, or shorts.
workspaceId	string	no	Optional workspace to associate with the post.
pinterestBoardId	string	no	Pinterest Board ID. Required only for platform=pinterest; retrieve it with get_platform_options using option=pinterest_boards.
blueskyThread	array of strings	no	Optional Bluesky replies after the root post. Accepted only for platform=bluesky. Maximum 24 replies; each maximum 300 characters.

Request

{
  "items": [
    {
      "accountId": "account-uuid",
      "platform": "instagram",
      "text": "Draft caption",
      "mediaUrls": []
    }
  ]
}

Success response

{
  "status": "ok",
  "count": 1,
  "posts": [
    {
      "id": "post-uuid",
      "platform": "instagram",
      "status": "draft"
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
ACCOUNT_PLATFORM_MISMATCH	The account and requested platform differ.	no
UNSUPPORTED_PLATFORM	The platform is not supported.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

update_draft

Updates editable fields on an existing draft without approval.

postsposts:updatedirect

Input fields

Field	Type	Required	Details
postId	string (UUID)	yes	Draft to update.
title	string	no	Optional replacement title. Maximum 200 characters.
text	string	no	Optional replacement body. Maximum 20,000 characters.
mediaUrls	array	no	An object with required url and optional kind, thumbnailUrl, and altText. Maximum 35 items; URLs must be valid; remote imports require public HTTPS.
tags	array of strings	no	Optional tags. Maximum 50 tags; each maximum 100 characters.
pinterestBoardId	string	no	Optional Pinterest Board ID; supply only for a Pinterest draft.
blueskyThread	array of strings	no	Optional Bluesky replies; supply only for a Bluesky draft. Maximum 24 replies; each maximum 300 characters.

Request

{
  "postId": "post-uuid",
  "text": "Updated draft copy",
  "tags": [
    "launch"
  ]
}

Success response

{
  "status": "ok",
  "post": {
    "id": "post-uuid",
    "status": "draft",
    "content": "Updated draft copy"
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
POST_NOT_FOUND	The post is not accessible to the authenticated user.	no
POST_NOT_DRAFT	The post is not a draft.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

schedule_posts

Validates and prepares one to 50 future posts for dashboard approval; no post mutation occurs before approval.

postsposts:scheduleapproval required

Input fields

Field	Type	Required	Details
items	array of scheduled post objects	yes	Posts to schedule. 1–50 items; accountId, scheduledAt and all post fields apply.
idempotencyKey	string	yes	Required replay key. 8–128 trimmed characters.
scheduledAt	string (ISO 8601 with offset)	yes	Future publication time for each item.
timezone	string	no	IANA timezone used for display and metadata. Default: UTC.
accountId	string (UUID)	no	Connected account used for the post. Required for scheduling and publishing; optional only for an unassigned draft.
platform	string	yes	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube. Required for every item and must match accountId when an account is supplied.
title	string	no	Optional post title. Maximum 200 characters.
text	string	no	Optional post body. Maximum 20,000 characters; omit only for a platform-valid media-only post.
mediaUrls	array	no	An object with required url and optional kind, thumbnailUrl, and altText. Maximum 35 items; URLs must be valid; remote imports require public HTTPS. Omit when no media is needed; platform rules are validated after account lookup.
format	string	no	Optional publishing format. post, carousel, reel, story, video, or shorts.
workspaceId	string	no	Optional workspace to associate with the post.
pinterestBoardId	string	no	Pinterest Board ID. Required only for platform=pinterest; retrieve it with get_platform_options using option=pinterest_boards.
blueskyThread	array of strings	no	Optional Bluesky replies after the root post. Accepted only for platform=bluesky. Maximum 24 replies; each maximum 300 characters.

Request

{
  "items": [
    {
      "accountId": "account-uuid",
      "platform": "linkedin",
      "text": "Scheduled update",
      "scheduledAt": "2026-07-14T09:00:00+02:00",
      "timezone": "Europe/Berlin"
    }
  ],
  "idempotencyKey": "schedule-20260714-01"
}

Success response

{
  "status": "approval_required",
  "actionId": "action-uuid",
  "expiresAt": "2026-07-13T09:15:00.000Z",
  "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid"
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
INVALID_SCHEDULE_TIME	scheduledAt is not a future ISO 8601 timestamp with offset.	no
INVALID_TIMEZONE	timezone is not a valid IANA timezone.	no
IDEMPOTENCY_KEY_REUSED	The key is reused with different input.	no
PROVIDER_ERROR	A connected platform returned an upstream failure.	yes
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

publish_posts

Validates and prepares one to 50 immediate publications for dashboard approval; no connector call occurs before approval.

postsposts:publishapproval required

Input fields

Field	Type	Required	Details
items	array of post objects	yes	Posts to publish. 1–50 items; accountId is required per item.
idempotencyKey	string	yes	Required replay key. 8–128 trimmed characters.
accountId	string (UUID)	no	Connected account used for the post. Required for scheduling and publishing; optional only for an unassigned draft.
platform	string	yes	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube. Required for every item and must match accountId when an account is supplied.
title	string	no	Optional post title. Maximum 200 characters.
text	string	no	Optional post body. Maximum 20,000 characters; omit only for a platform-valid media-only post.
mediaUrls	array	no	An object with required url and optional kind, thumbnailUrl, and altText. Maximum 35 items; URLs must be valid; remote imports require public HTTPS. Omit when no media is needed; platform rules are validated after account lookup.
format	string	no	Optional publishing format. post, carousel, reel, story, video, or shorts.
workspaceId	string	no	Optional workspace to associate with the post.
pinterestBoardId	string	no	Pinterest Board ID. Required only for platform=pinterest; retrieve it with get_platform_options using option=pinterest_boards.
blueskyThread	array of strings	no	Optional Bluesky replies after the root post. Accepted only for platform=bluesky. Maximum 24 replies; each maximum 300 characters.

Request

{
  "items": [
    {
      "accountId": "account-uuid",
      "platform": "instagram",
      "text": "Live launch post",
      "mediaUrls": [
        {
          "url": "https://cdn.example.com/launch.jpg",
          "kind": "image"
        }
      ]
    }
  ],
  "idempotencyKey": "publish-20260713-01"
}

Success response

{
  "status": "approval_required",
  "actionId": "action-uuid",
  "expiresAt": "2026-07-13T09:15:00.000Z",
  "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid"
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
ACCOUNT_PLATFORM_MISMATCH	The account and requested platform differ.	no
UNSUPPORTED_PLATFORM	The platform is not supported.	no
IDEMPOTENCY_KEY_REUSED	The key is reused with different input.	no
PROVIDER_ERROR	A connected platform returned an upstream failure.	yes
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

reschedule_post

Prepares a new time for an existing scheduled post and requires dashboard approval.

postsposts:update, posts:scheduleapproval required

Input fields

Field	Type	Required	Details
postId	string (UUID)	yes	Scheduled post to move.
scheduledAt	string (ISO 8601 with offset)	yes	New future time.
timezone	string	no	IANA timezone. Default: UTC.
idempotencyKey	string	yes	Required replay key. 8–128 trimmed characters.

Request

{
  "postId": "post-uuid",
  "scheduledAt": "2026-07-15T10:00:00+02:00",
  "timezone": "Europe/Berlin",
  "idempotencyKey": "reschedule-20260715-01"
}

Success response

{
  "status": "approval_required",
  "actionId": "action-uuid",
  "expiresAt": "2026-07-13T09:15:00.000Z",
  "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid"
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
POST_NOT_FOUND	The post is not accessible to the authenticated user.	no
POST_NOT_SCHEDULED	Only scheduled posts can be rescheduled.	no
INVALID_SCHEDULE_TIME	The new time is not in the future.	no
INVALID_TIMEZONE	timezone is not a valid IANA timezone.	no
IDEMPOTENCY_KEY_REUSED	The key is reused with different input.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

update_scheduled_post

Prepares content or media changes for an existing scheduled post and requires dashboard approval.

postsposts:update, posts:scheduleapproval required

Input fields

Field	Type	Required	Details
postId	string (UUID)	yes	Scheduled post to update.
title	string	no	Optional replacement title. Maximum 200 characters.
text	string	no	Optional replacement body. Maximum 20,000 characters.
mediaUrls	array	no	An object with required url and optional kind, thumbnailUrl, and altText. Maximum 35 items; URLs must be valid; remote imports require public HTTPS.
pinterestBoardId	string	no	Optional Pinterest Board ID; supply only for a Pinterest scheduled post.
blueskyThread	array of strings	no	Optional Bluesky replies; supply only for a Bluesky scheduled post. Maximum 24 replies; each maximum 300 characters.
idempotencyKey	string	yes	Required replay key. 8–128 trimmed characters.

Request

{
  "postId": "post-uuid",
  "text": "Updated scheduled copy",
  "idempotencyKey": "scheduled-edit-20260713-01"
}

Success response

{
  "status": "approval_required",
  "actionId": "action-uuid",
  "expiresAt": "2026-07-13T09:15:00.000Z",
  "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid"
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
POST_NOT_FOUND	The post is not accessible to the authenticated user.	no
POST_NOT_SCHEDULED	Only scheduled posts can be updated.	no
INVALID_SCHEDULE_TIME	The existing scheduled time is no longer valid.	no
IDEMPOTENCY_KEY_REUSED	The key is reused with different input.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

delete_post

Prepares deletion of a draft or scheduled post and requires dashboard approval.

postsposts:deleteapproval required

Input fields

Field	Type	Required	Details
postId	string (UUID)	yes	Draft or scheduled post to delete.
idempotencyKey	string	yes	Required replay key. 8–128 trimmed characters.

Request

{
  "postId": "post-uuid",
  "idempotencyKey": "delete-20260713-01"
}

Success response

{
  "status": "approval_required",
  "actionId": "action-uuid",
  "expiresAt": "2026-07-13T09:15:00.000Z",
  "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid"
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
POST_NOT_FOUND	The post is not accessible to the authenticated user.	no
POST_NOT_DELETABLE	Only draft or scheduled posts can be deleted.	no
IDEMPOTENCY_KEY_REUSED	The key is reused with different input.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

list_media

Lists media assets in the authenticated user's media library.

mediamedia:readdirect

Input fields

Field	Type	Required	Details
folder	string	no	Optional folder filter. Maximum 100 characters.
type	string	no	image or video.
limit	integer	no	Maximum number of assets. 1–100. Default: 50.

Request

{
  "folder": "campaigns",
  "type": "image",
  "limit": 20
}

Success response

{
  "status": "ok",
  "count": 1,
  "media": [
    {
      "id": "media-uuid",
      "name": "launch.jpg",
      "url": "https://cdn.example.com/launch.jpg",
      "type": "image",
      "size": 245760,
      "folder": "campaigns",
      "tags": [
        "launch"
      ]
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_social_media_transcript

Extracts a real spoken transcript and provider timestamps from a public social video URL.

mediamedia:readdirect

Input fields

Field	Type	Required	Details
platform	string	yes	Source platform. facebook, instagram, pinterest, threads, tiktok, or youtube.
url	string (URI)	yes	Public HTTPS video URL matching the selected platform. Maximum 2,048 characters; private or login-gated videos are unavailable.
includeTimestamps	boolean	no	Return timestamp segments when available. Default: true.
maxCharacters	integer	no	Maximum transcript characters returned. 1,000–50,000. Default: 24,000.

Request

{
  "platform": "youtube",
  "url": "https://www.youtube.com/watch?v=example",
  "includeTimestamps": true,
  "maxCharacters": 24000
}

Success response

{
  "status": "ok",
  "platform": "youtube",
  "sourceUrl": "https://www.youtube.com/watch?v=example",
  "source": "youtube-bridge",
  "transcript": "First spoken sentence.\nSecond spoken sentence.",
  "language": "en",
  "lineCount": 2,
  "characterCount": 46,
  "returnedCharacters": 46,
  "truncated": false,
  "segments": [
    {
      "text": "First spoken sentence.",
      "startSeconds": 0,
      "durationSeconds": 2.4
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
INVALID_SOCIAL_MEDIA_URL	The URL is not public HTTPS or does not match the selected platform.	no
TRANSCRIPT_UNAVAILABLE	No real spoken transcript can be extracted from the public video.	no
MEDIA_BACKEND_UNAVAILABLE	The extraction backend is unavailable or not configured.	yes
MEDIA_BACKEND_TIMEOUT	The extraction backend does not complete within the MCP timeout.	yes
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_social_video_download

Resolves a public social video into an ephemeral download URL without importing it into the media library.

mediamedia:readdirect

Input fields

Field	Type	Required	Details
platform	string	yes	Source platform. facebook, instagram, linkedin, pinterest, threads, tiktok, twitter, or youtube.
url	string (URI)	yes	Public HTTPS video URL matching the selected platform. Maximum 2,048 characters; the post must contain downloadable video.

Request

{
  "platform": "instagram",
  "url": "https://www.instagram.com/reel/example/"
}

Success response

{
  "status": "ok",
  "platform": "instagram",
  "sourceUrl": "https://www.instagram.com/reel/example/",
  "downloadUrl": "https://tareno.co/api/tools/instagram-download/proxy?url=example",
  "thumbnailUrl": "https://cdn.example.com/thumbnail.jpg",
  "resolvedVia": "bridge-fetch",
  "mediaType": "video",
  "ephemeral": true,
  "note": "Download the file promptly because provider URLs can expire."
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
INVALID_SOCIAL_MEDIA_URL	The URL is not public HTTPS or does not match the selected platform.	no
VIDEO_DOWNLOAD_UNAVAILABLE	The public post has no downloadable video or cannot be accessed.	no
MEDIA_BACKEND_UNAVAILABLE	The extraction backend is unavailable or not configured.	yes
MEDIA_BACKEND_TIMEOUT	The extraction backend does not complete within the MCP timeout.	yes
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

upload_media_from_url

Downloads an allowed public HTTPS image or video into the user's media library.

mediamedia:writedirect

Input fields

Field	Type	Required	Details
url	string (URI)	yes	Public HTTPS source URL. Private IPs, local hosts, unsafe redirects, unsupported MIME types and files over 50 MB are rejected.
fileName	string	no	Optional output filename. Maximum 200 characters.
folder	string	no	Destination folder. Maximum 100 characters. Default: uploads.
tags	array of strings	no	Optional asset tags. Maximum 50 tags; each maximum 100 characters. Default: [].

Request

{
  "url": "https://cdn.example.com/launch.mp4",
  "fileName": "launch.mp4",
  "folder": "campaigns",
  "tags": [
    "launch",
    "video"
  ]
}

Success response

{
  "status": "ok",
  "media": {
    "id": "media-uuid",
    "name": "launch.mp4",
    "url": "https://cdn.tareno.co/launch.mp4",
    "type": "video",
    "size": 5242880,
    "folder": "campaigns"
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
UNSAFE_MEDIA_URL	The URL is non-HTTPS, local, private, or resolves to a private address.	no
MEDIA_REDIRECT_REJECTED	The redirect chain is invalid or exceeds three redirects.	no
UNSUPPORTED_MEDIA_TYPE	The response MIME type is not allowlisted.	no
MEDIA_TOO_LARGE	The download exceeds 50 MB.	no
MEDIA_DOWNLOAD_FAILED	The remote server cannot be downloaded.	yes
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_analytics_overview

Returns the cross-platform analytics overview for a period.

analyticsanalytics:readdirect

Input fields

Field	Type	Required	Details
period	string	no	day, week, month, or quarter. Default: month.

Request

{
  "period": "month"
}

Success response

{
  "status": "ok",
  "analytics": {
    "period": "month",
    "impressions": 12400,
    "engagements": 860,
    "followers": 3200
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_platform_analytics

Returns cached analytics for one platform and optionally one account.

analyticsanalytics:readdirect

Input fields

Field	Type	Required	Details
platform	string	yes	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube.
accountId	string (UUID)	no	Optional account filter.
period	string	no	day, week, month, or quarter. Default: month.

Request

{
  "platform": "instagram",
  "period": "week"
}

Success response

{
  "status": "ok",
  "platform": "instagram",
  "count": 1,
  "analytics": [
    {
      "period": "week",
      "impressions": 4200,
      "engagements": 310,
      "cachedAt": "2026-07-13T09:00:00.000Z"
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_content_strategy

Returns analytics-backed content recommendations for the user, platform, or account.

analyticsanalytics:readdirect

Input fields

Field	Type	Required	Details
platform	string	no	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube.
accountId	string (UUID)	no	Optional account filter.
period	string	no	day, week, month, or quarter. Default: month.

Request

{
  "platform": "tiktok",
  "period": "month"
}

Success response

{
  "status": "ok",
  "strategy": {
    "period": "month",
    "recommendations": [
      "Repurpose the top tutorial into a short video series."
    ],
    "repurposingOpportunities": []
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_action_status

Returns approval status and per-item results for an MCP action.

actionsactions:readdirect

Input fields

Field	Type	Required	Details
actionId	string	yes	Action ID returned by an approval-required tool.

Request

{
  "actionId": "action-uuid"
}

Success response

{
  "status": "ok",
  "action": {
    "id": "action-uuid",
    "toolName": "publish_posts",
    "status": "pending",
    "expiresAt": "2026-07-13T09:15:00.000Z",
    "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid",
    "output": null,
    "error": null
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
ACTION_NOT_FOUND	The action does not belong to the authenticated user or does not exist.	no

Stable error envelope

{
  "isError": true,
  "structuredContent": {
    "status": "error",
    "code": "VALIDATION_ERROR",
    "message": "scheduledAt must be in the future.",
    "retryable": false,
    "fieldErrors": {
      "scheduledAt": [
        "Must be in the future and include an explicit UTC offset."
      ]
    }
  },
  "content": [
    {
      "type": "text",
      "text": "<same JSON as structuredContent>"
    }
  ]
}

Success responses mirror the same object in structuredContent and the JSON text fallback.

The complete known application error-code set is: VALIDATION_ERROR, INSUFFICIENT_SCOPE, MONTHLY_API_LIMIT_REACHED, WORKSPACE_NOT_FOUND, ACCOUNT_NOT_FOUND, ACCOUNT_PLATFORM_MISMATCH, ACCOUNT_RECONNECT_REQUIRED, OPTION_PLATFORM_MISMATCH, UNSUPPORTED_OPTION, UNSUPPORTED_PLATFORM, POST_NOT_FOUND, POST_NOT_DRAFT, POST_NOT_SCHEDULED, POST_NOT_DELETABLE, INVALID_SCHEDULE_TIME, INVALID_TIMEZONE, IDEMPOTENCY_KEY_REUSED, PROVIDER_ERROR, UNSAFE_MEDIA_URL, MEDIA_REDIRECT_REJECTED, UNSUPPORTED_MEDIA_TYPE, MEDIA_TOO_LARGE, MEDIA_DOWNLOAD_FAILED, INVALID_SOCIAL_MEDIA_URL, TRANSCRIPT_UNAVAILABLE, VIDEO_DOWNLOAD_UNAVAILABLE, MEDIA_BACKEND_UNAVAILABLE, MEDIA_BACKEND_TIMEOUT, ACTION_NOT_FOUND, ACTION_ALREADY_DECIDED, ACTION_EXPIRED, API_KEY_MISSING, API_KEY_REVOKED, API_KEY_EXPIRED, PLAN_ACCESS_REVOKED, APPROVAL_REQUIRED, TOOL_NOT_EXECUTABLE, UNKNOWN_TOOL.

Inspector and curl smoke test

export TARENO_API_KEY="tk_live_…"

# Protocol initialize
curl -i https://tareno.co/api/mcp \
  -H "Authorization: Bearer $TARENO_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-check","version":"1.0"}}}'

# List tools
curl -sS https://tareno.co/api/mcp \
  -H "Authorization: Bearer $TARENO_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Get a timestamped transcript
curl -sS https://tareno.co/api/mcp \
  -H "Authorization: Bearer $TARENO_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_social_media_transcript","arguments":{"platform":"youtube","url":"https://www.youtube.com/watch?v=…","includeTimestamps":true}}}'

# Resolve a public video download
curl -sS https://tareno.co/api/mcp \
  -H "Authorization: Bearer $TARENO_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_social_video_download","arguments":{"platform":"instagram","url":"https://www.instagram.com/reel/…"}}}'

# MCP Inspector
npx @modelcontextprotocol/inspector
# Connect with Streamable HTTP URL and Authorization: Bearer $TARENO_API_KEY

Never put the key in the URL, commit it, or paste it into chat. Anonymous requests should return 401; an Origin outside the configured allowlist should return 403.

ChatGPT OAuth is intentionally not part of Phase 1. The production endpoint uses Bearer authentication only.

← MCP setup

Complete MCP tool reference

The human-readable contract for every public Tareno Remote MCP tool. Runtime clients should still treattools/list as the source of truth for the current JSON Schema.

Endpoint
https://tareno.co/api/mcp

Tools

50 items

Batch maximum

15 minutes

Approval TTL

60/minute

Burst default

Supported social channels

Channel	Core MCP	Transcript	Video download
Bluesky	yes	—	—
Facebook	yes	yes	yes
Instagram	yes	yes	yes
LinkedIn	yes	—	yes
Mastodon	yes	—	—
Pinterest	yes	yes	yes
Threads	yes	yes	yes
TikTok	yes	yes	yes
X / Twitter	yes	—	yes
YouTube	yes	yes	yes

Transcript: Facebook, Instagram, Pinterest, Threads, TikTok and YouTube. Download: those six plus LinkedIn and X/Twitter. Only public HTTPS posts are accepted.

Execution and approval rules

Read tools and draft tools execute immediately.
Scheduling, publishing, scheduled edits, rescheduling, and deletion only create a pending action.
No connector or post mutation occurs before dashboard approval.
Approval status is one of: pending, executing, succeeded, failed, rejected, expired.
Every risky batch is limited to 50 items.
Risky writes require an idempotencyKey with 8–128 trimmed characters.
After approval, the executor rechecks ownership, key, plan, scopes, and platform rules.
Mixed provider results use partial_failure and expose each item result.

Scope matrix

Scope	Tools
workspaces:read	list_workspaces
accounts:read	list_accounts, get_platform_schema, get_platform_options
posts:read	list_posts, get_post
posts:draft	create_drafts
posts:update	update_draft, reschedule_post, update_scheduled_post
posts:schedule	schedule_posts, reschedule_post, update_scheduled_post
posts:publish	publish_posts
posts:delete	delete_post
media:read	list_media, get_social_media_transcript, get_social_video_download
media:write	upload_media_from_url
analytics:read	get_analytics_overview, get_platform_analytics, get_content_strategy
actions:read	get_action_status

Legacy read, write, and publish API-key scopes are expanded server-side into these granular scopes.

`pinterest_boards`

Load this option after list_accounts and get_platform_schema; the account platform must match.

Request

{
  "accountId": "pinterest-account-uuid",
  "option": "pinterest_boards"
}

Response

{
  "status": "ok",
  "option": "pinterest_boards",
  "items": [
    {
      "value": "board-id",
      "label": "Summer ideas",
      "description": "Campaign board"
    }
  ]
}

`tiktok_creator_info`

Load this option after list_accounts and get_platform_schema; the account platform must match.

Request

{
  "accountId": "tiktok-account-uuid",
  "option": "tiktok_creator_info"
}

Response

{
  "status": "ok",
  "option": "tiktok_creator_info",
  "creator": {
    "creator_nickname": "Acme",
    "privacy_level_options": [
      "PUBLIC_TO_EVERYONE"
    ],
    "max_video_post_duration_sec": 60
  }
}

Tool contracts

list_workspaces

Lists workspaces owned by or shared with the authenticated user.

workspacesworkspaces:readdirect

Input fields

Field	Type	Required	Details
No input fields.

Request

{}

Success response

{
  "status": "ok",
  "count": 1,
  "workspaces": [
    {
      "id": "workspace-uuid",
      "name": "Acme",
      "slug": "acme",
      "ownerId": "user-uuid",
      "updatedAt": "2026-07-13T09:00:00.000Z",
      "_count": {
        "workspaceAccounts": 3,
        "members": 2
      }
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

list_accounts

Lists connected social accounts, optionally filtered by workspace or platform.

accountsaccounts:readdirect

Input fields

Field	Type	Required	Details
workspaceId	string	no	Optional workspace filter.
platform	string	no	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube.

Request

{
  "platform": "instagram"
}

Success response

{
  "status": "ok",
  "count": 1,
  "accounts": [
    {
      "id": "account-uuid",
      "platform": "instagram",
      "platformAccountId": "provider-id",
      "username": "acme",
      "displayName": "Acme",
      "profilePicture": "https://cdn.example.com/avatar.jpg",
      "health": {
        "status": "healthy",
        "reason": null,
        "action": null,
        "publishingDisabled": false
      },
      "connectedAt": "2026-07-13T09:00:00.000Z"
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
WORKSPACE_NOT_FOUND	The workspace is not owned by or shared with the authenticated user.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_platform_schema

Returns server-derived platform capabilities and publishing requirements for one account.

accountsaccounts:readdirect

Input fields

Field	Type	Required	Details
accountId	string (UUID)	yes	Connected account to inspect.

Request

{
  "accountId": "account-uuid"
}

Success response

{
  "status": "ok",
  "account": {
    "id": "account-uuid",
    "platform": "pinterest",
    "username": "acme",
    "healthStatus": "healthy"
  },
  "capabilities": {
    "contentTypes": {
      "text": {
        "requiresMedia": true
      }
    }
  },
  "requirements": {
    "accountId": true,
    "mediaRequired": true,
    "pinterestBoardRequired": true,
    "dynamicOptions": [
      "pinterest_boards"
    ]
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_platform_options

Loads whitelisted dynamic options from Pinterest or TikTok.

accountsaccounts:readdirect

Input fields

Field	Type	Required	Details
accountId	string (UUID)	yes	Connected Pinterest or TikTok account.
option	string	yes	Either pinterest_boards or tiktok_creator_info.

Request

{
  "accountId": "pinterest-account-uuid",
  "option": "pinterest_boards"
}

Success response

{
  "status": "ok",
  "option": "pinterest_boards",
  "items": [
    {
      "value": "board-id",
      "label": "Summer ideas",
      "description": "Campaign board"
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
OPTION_PLATFORM_MISMATCH	The option does not belong to the selected account's platform.	no
ACCOUNT_RECONNECT_REQUIRED	The provider token is missing or expired.	no
PROVIDER_ERROR	A connected platform returned an upstream failure.	yes
UNSUPPORTED_OPTION	The option is not on the allowlist.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

list_posts

Lists posts for the authenticated user's account or workspace.

postsposts:readdirect

Input fields

Field	Type	Required	Details
workspaceId	string	no	Optional workspace filter.
status	string	no	draft, scheduled, processing, published, or failed.
platform	string	no	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube.
accountId	string (UUID)	no	Optional account filter.
from	string (ISO 8601 with offset)	no	Optional inclusive start time.
to	string (ISO 8601 with offset)	no	Optional inclusive end time.
limit	integer	no	Maximum number of posts. 1–100. Default: 50.

Request

{
  "status": "scheduled",
  "limit": 20
}

Success response

{
  "status": "ok",
  "count": 1,
  "posts": [
    {
      "id": "post-uuid",
      "platform": "instagram",
      "status": "scheduled",
      "start": "2026-07-14T09:00:00.000Z",
      "content": "Launch update"
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
WORKSPACE_NOT_FOUND	The workspace is not owned by or shared with the authenticated user.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_post

Returns the full stored post record when it belongs to the user or an accessible workspace.

postsposts:readdirect

Input fields

Field	Type	Required	Details
postId	string (UUID)	yes	Post to retrieve.

Request

{
  "postId": "post-uuid"
}

Success response

{
  "status": "ok",
  "post": {
    "id": "post-uuid",
    "platform": "linkedin",
    "status": "draft",
    "content": "Launch update"
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
POST_NOT_FOUND	The post is not accessible to the authenticated user.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

create_drafts

Creates one to 50 drafts. Draft creation does not schedule or publish anything.

postsposts:draftdirect

Input fields

Field	Type	Required	Details
items	array of post objects	yes	Draft items. 1–50 items; each item uses the post fields below.
idempotencyKey	string	no	Optional replay key. 8–128 trimmed characters.
accountId	string (UUID)	no	Connected account used for the post. Required for scheduling and publishing; optional only for an unassigned draft.
platform	string	yes	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube. Required for every item and must match accountId when an account is supplied.
title	string	no	Optional post title. Maximum 200 characters.
text	string	no	Optional post body. Maximum 20,000 characters; omit only for a platform-valid media-only post.
mediaUrls	array	no	An object with required url and optional kind, thumbnailUrl, and altText. Maximum 35 items; URLs must be valid; remote imports require public HTTPS. Omit when no media is needed; platform rules are validated after account lookup.
format	string	no	Optional publishing format. post, carousel, reel, story, video, or shorts.
workspaceId	string	no	Optional workspace to associate with the post.
pinterestBoardId	string	no	Pinterest Board ID. Required only for platform=pinterest; retrieve it with get_platform_options using option=pinterest_boards.
blueskyThread	array of strings	no	Optional Bluesky replies after the root post. Accepted only for platform=bluesky. Maximum 24 replies; each maximum 300 characters.

Request

{
  "items": [
    {
      "accountId": "account-uuid",
      "platform": "instagram",
      "text": "Draft caption",
      "mediaUrls": []
    }
  ]
}

Success response

{
  "status": "ok",
  "count": 1,
  "posts": [
    {
      "id": "post-uuid",
      "platform": "instagram",
      "status": "draft"
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
ACCOUNT_PLATFORM_MISMATCH	The account and requested platform differ.	no
UNSUPPORTED_PLATFORM	The platform is not supported.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

update_draft

Updates editable fields on an existing draft without approval.

postsposts:updatedirect

Input fields

Field	Type	Required	Details
postId	string (UUID)	yes	Draft to update.
title	string	no	Optional replacement title. Maximum 200 characters.
text	string	no	Optional replacement body. Maximum 20,000 characters.
mediaUrls	array	no	An object with required url and optional kind, thumbnailUrl, and altText. Maximum 35 items; URLs must be valid; remote imports require public HTTPS.
tags	array of strings	no	Optional tags. Maximum 50 tags; each maximum 100 characters.
pinterestBoardId	string	no	Optional Pinterest Board ID; supply only for a Pinterest draft.
blueskyThread	array of strings	no	Optional Bluesky replies; supply only for a Bluesky draft. Maximum 24 replies; each maximum 300 characters.

Request

{
  "postId": "post-uuid",
  "text": "Updated draft copy",
  "tags": [
    "launch"
  ]
}

Success response

{
  "status": "ok",
  "post": {
    "id": "post-uuid",
    "status": "draft",
    "content": "Updated draft copy"
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
POST_NOT_FOUND	The post is not accessible to the authenticated user.	no
POST_NOT_DRAFT	The post is not a draft.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

schedule_posts

Validates and prepares one to 50 future posts for dashboard approval; no post mutation occurs before approval.

postsposts:scheduleapproval required

Input fields

Field	Type	Required	Details
items	array of scheduled post objects	yes	Posts to schedule. 1–50 items; accountId, scheduledAt and all post fields apply.
idempotencyKey	string	yes	Required replay key. 8–128 trimmed characters.
scheduledAt	string (ISO 8601 with offset)	yes	Future publication time for each item.
timezone	string	no	IANA timezone used for display and metadata. Default: UTC.
accountId	string (UUID)	no	Connected account used for the post. Required for scheduling and publishing; optional only for an unassigned draft.
platform	string	yes	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube. Required for every item and must match accountId when an account is supplied.
title	string	no	Optional post title. Maximum 200 characters.
text	string	no	Optional post body. Maximum 20,000 characters; omit only for a platform-valid media-only post.
mediaUrls	array	no	An object with required url and optional kind, thumbnailUrl, and altText. Maximum 35 items; URLs must be valid; remote imports require public HTTPS. Omit when no media is needed; platform rules are validated after account lookup.
format	string	no	Optional publishing format. post, carousel, reel, story, video, or shorts.
workspaceId	string	no	Optional workspace to associate with the post.
pinterestBoardId	string	no	Pinterest Board ID. Required only for platform=pinterest; retrieve it with get_platform_options using option=pinterest_boards.
blueskyThread	array of strings	no	Optional Bluesky replies after the root post. Accepted only for platform=bluesky. Maximum 24 replies; each maximum 300 characters.

Request

{
  "items": [
    {
      "accountId": "account-uuid",
      "platform": "linkedin",
      "text": "Scheduled update",
      "scheduledAt": "2026-07-14T09:00:00+02:00",
      "timezone": "Europe/Berlin"
    }
  ],
  "idempotencyKey": "schedule-20260714-01"
}

Success response

{
  "status": "approval_required",
  "actionId": "action-uuid",
  "expiresAt": "2026-07-13T09:15:00.000Z",
  "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid"
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
INVALID_SCHEDULE_TIME	scheduledAt is not a future ISO 8601 timestamp with offset.	no
INVALID_TIMEZONE	timezone is not a valid IANA timezone.	no
IDEMPOTENCY_KEY_REUSED	The key is reused with different input.	no
PROVIDER_ERROR	A connected platform returned an upstream failure.	yes
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

publish_posts

Validates and prepares one to 50 immediate publications for dashboard approval; no connector call occurs before approval.

postsposts:publishapproval required

Input fields

Field	Type	Required	Details
items	array of post objects	yes	Posts to publish. 1–50 items; accountId is required per item.
idempotencyKey	string	yes	Required replay key. 8–128 trimmed characters.
accountId	string (UUID)	no	Connected account used for the post. Required for scheduling and publishing; optional only for an unassigned draft.
platform	string	yes	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube. Required for every item and must match accountId when an account is supplied.
title	string	no	Optional post title. Maximum 200 characters.
text	string	no	Optional post body. Maximum 20,000 characters; omit only for a platform-valid media-only post.
mediaUrls	array	no	An object with required url and optional kind, thumbnailUrl, and altText. Maximum 35 items; URLs must be valid; remote imports require public HTTPS. Omit when no media is needed; platform rules are validated after account lookup.
format	string	no	Optional publishing format. post, carousel, reel, story, video, or shorts.
workspaceId	string	no	Optional workspace to associate with the post.
pinterestBoardId	string	no	Pinterest Board ID. Required only for platform=pinterest; retrieve it with get_platform_options using option=pinterest_boards.
blueskyThread	array of strings	no	Optional Bluesky replies after the root post. Accepted only for platform=bluesky. Maximum 24 replies; each maximum 300 characters.

Request

{
  "items": [
    {
      "accountId": "account-uuid",
      "platform": "instagram",
      "text": "Live launch post",
      "mediaUrls": [
        {
          "url": "https://cdn.example.com/launch.jpg",
          "kind": "image"
        }
      ]
    }
  ],
  "idempotencyKey": "publish-20260713-01"
}

Success response

{
  "status": "approval_required",
  "actionId": "action-uuid",
  "expiresAt": "2026-07-13T09:15:00.000Z",
  "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid"
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
ACCOUNT_PLATFORM_MISMATCH	The account and requested platform differ.	no
UNSUPPORTED_PLATFORM	The platform is not supported.	no
IDEMPOTENCY_KEY_REUSED	The key is reused with different input.	no
PROVIDER_ERROR	A connected platform returned an upstream failure.	yes
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

reschedule_post

Prepares a new time for an existing scheduled post and requires dashboard approval.

postsposts:update, posts:scheduleapproval required

Input fields

Field	Type	Required	Details
postId	string (UUID)	yes	Scheduled post to move.
scheduledAt	string (ISO 8601 with offset)	yes	New future time.
timezone	string	no	IANA timezone. Default: UTC.
idempotencyKey	string	yes	Required replay key. 8–128 trimmed characters.

Request

{
  "postId": "post-uuid",
  "scheduledAt": "2026-07-15T10:00:00+02:00",
  "timezone": "Europe/Berlin",
  "idempotencyKey": "reschedule-20260715-01"
}

Success response

{
  "status": "approval_required",
  "actionId": "action-uuid",
  "expiresAt": "2026-07-13T09:15:00.000Z",
  "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid"
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
POST_NOT_FOUND	The post is not accessible to the authenticated user.	no
POST_NOT_SCHEDULED	Only scheduled posts can be rescheduled.	no
INVALID_SCHEDULE_TIME	The new time is not in the future.	no
INVALID_TIMEZONE	timezone is not a valid IANA timezone.	no
IDEMPOTENCY_KEY_REUSED	The key is reused with different input.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

update_scheduled_post

Prepares content or media changes for an existing scheduled post and requires dashboard approval.

postsposts:update, posts:scheduleapproval required

Input fields

Field	Type	Required	Details
postId	string (UUID)	yes	Scheduled post to update.
title	string	no	Optional replacement title. Maximum 200 characters.
text	string	no	Optional replacement body. Maximum 20,000 characters.
mediaUrls	array	no	An object with required url and optional kind, thumbnailUrl, and altText. Maximum 35 items; URLs must be valid; remote imports require public HTTPS.
pinterestBoardId	string	no	Optional Pinterest Board ID; supply only for a Pinterest scheduled post.
blueskyThread	array of strings	no	Optional Bluesky replies; supply only for a Bluesky scheduled post. Maximum 24 replies; each maximum 300 characters.
idempotencyKey	string	yes	Required replay key. 8–128 trimmed characters.

Request

{
  "postId": "post-uuid",
  "text": "Updated scheduled copy",
  "idempotencyKey": "scheduled-edit-20260713-01"
}

Success response

{
  "status": "approval_required",
  "actionId": "action-uuid",
  "expiresAt": "2026-07-13T09:15:00.000Z",
  "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid"
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
POST_NOT_FOUND	The post is not accessible to the authenticated user.	no
POST_NOT_SCHEDULED	Only scheduled posts can be updated.	no
INVALID_SCHEDULE_TIME	The existing scheduled time is no longer valid.	no
IDEMPOTENCY_KEY_REUSED	The key is reused with different input.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

delete_post

Prepares deletion of a draft or scheduled post and requires dashboard approval.

postsposts:deleteapproval required

Input fields

Field	Type	Required	Details
postId	string (UUID)	yes	Draft or scheduled post to delete.
idempotencyKey	string	yes	Required replay key. 8–128 trimmed characters.

Request

{
  "postId": "post-uuid",
  "idempotencyKey": "delete-20260713-01"
}

Success response

{
  "status": "approval_required",
  "actionId": "action-uuid",
  "expiresAt": "2026-07-13T09:15:00.000Z",
  "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid"
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
POST_NOT_FOUND	The post is not accessible to the authenticated user.	no
POST_NOT_DELETABLE	Only draft or scheduled posts can be deleted.	no
IDEMPOTENCY_KEY_REUSED	The key is reused with different input.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

list_media

Lists media assets in the authenticated user's media library.

mediamedia:readdirect

Input fields

Field	Type	Required	Details
folder	string	no	Optional folder filter. Maximum 100 characters.
type	string	no	image or video.
limit	integer	no	Maximum number of assets. 1–100. Default: 50.

Request

{
  "folder": "campaigns",
  "type": "image",
  "limit": 20
}

Success response

{
  "status": "ok",
  "count": 1,
  "media": [
    {
      "id": "media-uuid",
      "name": "launch.jpg",
      "url": "https://cdn.example.com/launch.jpg",
      "type": "image",
      "size": 245760,
      "folder": "campaigns",
      "tags": [
        "launch"
      ]
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_social_media_transcript

Extracts a real spoken transcript and provider timestamps from a public social video URL.

mediamedia:readdirect

Input fields

Field	Type	Required	Details
platform	string	yes	Source platform. facebook, instagram, pinterest, threads, tiktok, or youtube.
url	string (URI)	yes	Public HTTPS video URL matching the selected platform. Maximum 2,048 characters; private or login-gated videos are unavailable.
includeTimestamps	boolean	no	Return timestamp segments when available. Default: true.
maxCharacters	integer	no	Maximum transcript characters returned. 1,000–50,000. Default: 24,000.

Request

{
  "platform": "youtube",
  "url": "https://www.youtube.com/watch?v=example",
  "includeTimestamps": true,
  "maxCharacters": 24000
}

Success response

{
  "status": "ok",
  "platform": "youtube",
  "sourceUrl": "https://www.youtube.com/watch?v=example",
  "source": "youtube-bridge",
  "transcript": "First spoken sentence.\nSecond spoken sentence.",
  "language": "en",
  "lineCount": 2,
  "characterCount": 46,
  "returnedCharacters": 46,
  "truncated": false,
  "segments": [
    {
      "text": "First spoken sentence.",
      "startSeconds": 0,
      "durationSeconds": 2.4
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
INVALID_SOCIAL_MEDIA_URL	The URL is not public HTTPS or does not match the selected platform.	no
TRANSCRIPT_UNAVAILABLE	No real spoken transcript can be extracted from the public video.	no
MEDIA_BACKEND_UNAVAILABLE	The extraction backend is unavailable or not configured.	yes
MEDIA_BACKEND_TIMEOUT	The extraction backend does not complete within the MCP timeout.	yes
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_social_video_download

Resolves a public social video into an ephemeral download URL without importing it into the media library.

mediamedia:readdirect

Input fields

Field	Type	Required	Details
platform	string	yes	Source platform. facebook, instagram, linkedin, pinterest, threads, tiktok, twitter, or youtube.
url	string (URI)	yes	Public HTTPS video URL matching the selected platform. Maximum 2,048 characters; the post must contain downloadable video.

Request

{
  "platform": "instagram",
  "url": "https://www.instagram.com/reel/example/"
}

Success response

{
  "status": "ok",
  "platform": "instagram",
  "sourceUrl": "https://www.instagram.com/reel/example/",
  "downloadUrl": "https://tareno.co/api/tools/instagram-download/proxy?url=example",
  "thumbnailUrl": "https://cdn.example.com/thumbnail.jpg",
  "resolvedVia": "bridge-fetch",
  "mediaType": "video",
  "ephemeral": true,
  "note": "Download the file promptly because provider URLs can expire."
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
INVALID_SOCIAL_MEDIA_URL	The URL is not public HTTPS or does not match the selected platform.	no
VIDEO_DOWNLOAD_UNAVAILABLE	The public post has no downloadable video or cannot be accessed.	no
MEDIA_BACKEND_UNAVAILABLE	The extraction backend is unavailable or not configured.	yes
MEDIA_BACKEND_TIMEOUT	The extraction backend does not complete within the MCP timeout.	yes
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

upload_media_from_url

Downloads an allowed public HTTPS image or video into the user's media library.

mediamedia:writedirect

Input fields

Field	Type	Required	Details
url	string (URI)	yes	Public HTTPS source URL. Private IPs, local hosts, unsafe redirects, unsupported MIME types and files over 50 MB are rejected.
fileName	string	no	Optional output filename. Maximum 200 characters.
folder	string	no	Destination folder. Maximum 100 characters. Default: uploads.
tags	array of strings	no	Optional asset tags. Maximum 50 tags; each maximum 100 characters. Default: [].

Request

{
  "url": "https://cdn.example.com/launch.mp4",
  "fileName": "launch.mp4",
  "folder": "campaigns",
  "tags": [
    "launch",
    "video"
  ]
}

Success response

{
  "status": "ok",
  "media": {
    "id": "media-uuid",
    "name": "launch.mp4",
    "url": "https://cdn.tareno.co/launch.mp4",
    "type": "video",
    "size": 5242880,
    "folder": "campaigns"
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
UNSAFE_MEDIA_URL	The URL is non-HTTPS, local, private, or resolves to a private address.	no
MEDIA_REDIRECT_REJECTED	The redirect chain is invalid or exceeds three redirects.	no
UNSUPPORTED_MEDIA_TYPE	The response MIME type is not allowlisted.	no
MEDIA_TOO_LARGE	The download exceeds 50 MB.	no
MEDIA_DOWNLOAD_FAILED	The remote server cannot be downloaded.	yes
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_analytics_overview

Returns the cross-platform analytics overview for a period.

analyticsanalytics:readdirect

Input fields

Field	Type	Required	Details
period	string	no	day, week, month, or quarter. Default: month.

Request

{
  "period": "month"
}

Success response

{
  "status": "ok",
  "analytics": {
    "period": "month",
    "impressions": 12400,
    "engagements": 860,
    "followers": 3200
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_platform_analytics

Returns cached analytics for one platform and optionally one account.

analyticsanalytics:readdirect

Input fields

Field	Type	Required	Details
platform	string	yes	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube.
accountId	string (UUID)	no	Optional account filter.
period	string	no	day, week, month, or quarter. Default: month.

Request

{
  "platform": "instagram",
  "period": "week"
}

Success response

{
  "status": "ok",
  "platform": "instagram",
  "count": 1,
  "analytics": [
    {
      "period": "week",
      "impressions": 4200,
      "engagements": 310,
      "cachedAt": "2026-07-13T09:00:00.000Z"
    }
  ]
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_content_strategy

Returns analytics-backed content recommendations for the user, platform, or account.

analyticsanalytics:readdirect

Input fields

Field	Type	Required	Details
platform	string	no	One of: bluesky, facebook, instagram, linkedin, mastodon, pinterest, threads, tiktok, twitter, youtube.
accountId	string (UUID)	no	Optional account filter.
period	string	no	day, week, month, or quarter. Default: month.

Request

{
  "platform": "tiktok",
  "period": "month"
}

Success response

{
  "status": "ok",
  "strategy": {
    "period": "month",
    "recommendations": [
      "Repurpose the top tutorial into a short video series."
    ],
    "repurposingOpportunities": []
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
ACCOUNT_NOT_FOUND	The account is not accessible to the authenticated user.	no
VALIDATION_ERROR	Input does not match the tool schema.	no
MONTHLY_API_LIMIT_REACHED	The plan's monthly API allowance is exhausted.	yes

get_action_status

Returns approval status and per-item results for an MCP action.

actionsactions:readdirect

Input fields

Field	Type	Required	Details
actionId	string	yes	Action ID returned by an approval-required tool.

Request

{
  "actionId": "action-uuid"
}

Success response

{
  "status": "ok",
  "action": {
    "id": "action-uuid",
    "toolName": "publish_posts",
    "status": "pending",
    "expiresAt": "2026-07-13T09:15:00.000Z",
    "approvalUrl": "https://tareno.co/dashboard/agents/actions/action-uuid",
    "output": null,
    "error": null
  }
}

Tool errors

Code	When	Retryable
INSUFFICIENT_SCOPE	The API key lacks one of the required scopes.	no
ACTION_NOT_FOUND	The action does not belong to the authenticated user or does not exist.	no

Stable error envelope

{
  "isError": true,
  "structuredContent": {
    "status": "error",
    "code": "VALIDATION_ERROR",
    "message": "scheduledAt must be in the future.",
    "retryable": false,
    "fieldErrors": {
      "scheduledAt": [
        "Must be in the future and include an explicit UTC offset."
      ]
    }
  },
  "content": [
    {
      "type": "text",
      "text": "<same JSON as structuredContent>"
    }
  ]
}

Success responses mirror the same object in structuredContent and the JSON text fallback.

Inspector and curl smoke test

export TARENO_API_KEY="tk_live_…"

# Protocol initialize
curl -i https://tareno.co/api/mcp \
  -H "Authorization: Bearer $TARENO_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-check","version":"1.0"}}}'

# List tools
curl -sS https://tareno.co/api/mcp \
  -H "Authorization: Bearer $TARENO_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Get a timestamped transcript
curl -sS https://tareno.co/api/mcp \
  -H "Authorization: Bearer $TARENO_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_social_media_transcript","arguments":{"platform":"youtube","url":"https://www.youtube.com/watch?v=…","includeTimestamps":true}}}'

# Resolve a public video download
curl -sS https://tareno.co/api/mcp \
  -H "Authorization: Bearer $TARENO_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_social_video_download","arguments":{"platform":"instagram","url":"https://www.instagram.com/reel/…"}}}'

# MCP Inspector
npx @modelcontextprotocol/inspector
# Connect with Streamable HTTP URL and Authorization: Bearer $TARENO_API_KEY

Never put the key in the URL, commit it, or paste it into chat. Anonymous requests should return 401; an Origin outside the configured allowlist should return 403.

ChatGPT OAuth is intentionally not part of Phase 1. The production endpoint uses Bearer authentication only.