User-Facing External API

Tareno API for drafts, scheduling, media uploads, usage, and analytics

This reference covers the public endpoints real users can call with an API key. Internal or admin-only endpoints such as blog admin routes are intentionally excluded.

Base URL

https://tareno.co/api/external

Best used with

Claude, ChatGPT, Cursor, Gemini, Perplexity, Zapier-style automations, scripts, internal tools, render pipelines, and custom apps.

Open API key guide n8n guide Make guide

AI Integration

Control Tareno from Claude, ChatGPT, or Cursor

Use our MCP server to manage social media through natural language. Schedule posts, check analytics, upload media — all from the chat. No dashboard needed.

MCP Setup Guide n8n Guide Make Guide

Claude

ChatGPT

Cursor

Gemini

Perplexity

Authentication

API key headers and scopes

You can authenticate with either a Bearer token or the X-Tareno-API-Key header. Read-only endpoints such as accounts, usage, boards, and analytics require read scope. Uploading media and creating posts require publish scope.

Headers

Authorization: Bearer tk_live_your_key
X-Tareno-API-Key: tk_live_your_key

API keys are managed in Dashboard → Settings → API Keys.

JavaScript example

const response = await fetch(
  "https://tareno.co/api/external/analytics/overview?period=month",
  { headers: { Authorization: "Bearer tk_live_your_key" } }
)
const data = await response.json()

Quick Start

Typical automation flow

Most workflows follow the same four steps: resolve accounts, upload or reference media, create drafts or schedules, then inspect analytics or usage.

GET/accounts

1. Resolve account IDs

Fetch the connected accounts first so your workflow always targets the correct channel or page.

Request

curl -X GET "https://tareno.co/api/external/accounts" \
  -H "Authorization: Bearer tk_live_your_key"

POST/media

2. Upload or import media

Upload rendered files into the Media Library so the same asset can be reused across drafts, scheduled posts, and future campaigns.

Request

curl -X POST "https://tareno.co/api/external/media" \
  -H "Authorization: Bearer tk_live_your_key" \
  -F "file=@video.mp4"

POST/publish

3. Save draft or schedule post

Use draft mode when you want a safe inbox flow, or schedule mode when you already know the account and time.

Request

curl -X POST "https://tareno.co/api/external/publish" \
  -H "Authorization: Bearer tk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"mode":"draft","platform":"instagram","text":"Caption"}'

GET/analytics/overview

4. Pull analytics back into your workflow

Fetch overview or platform-specific analytics to report performance, fill dashboards, or trigger follow-up actions.

Request

curl -X GET "https://tareno.co/api/external/analytics/overview?period=month" \
  -H "Authorization: Bearer tk_live_your_key"

Endpoints

User-facing endpoint reference

These are the public endpoints currently available to users through the External API. Everything listed here is API-key compatible and safe to document publicly.

GET/accounts

Connected accounts

Lists the connected social accounts that belong to the API key owner. Use these account IDs for scheduled posts, direct posts, Pinterest board lookup, and account-specific analytics.

Requires read scope

Request

curl -X GET "https://tareno.co/api/external/accounts" \
  -H "Authorization: Bearer tk_live_your_key"

Response

{
  "accounts": [{
    "id": "acc_123",
    "platform": "instagram",
    "username": "yourhandle",
    "displayName": "Your Brand",
    "profilePicture": "https://..."
  }],
  "count": 1
}

POST/publish

Create drafts, schedules, or immediate posts

The main content endpoint for user-facing posting. Use mode=draft for safe preparation, mode=schedule for scheduled publishing, or mode=publish for immediate posting.

Requires publish scopeSupports text, image, video, carouselTikTok Photo Mode can return processing before final publication

Request

curl -X POST "https://tareno.co/api/external/publish" \
  -H "Authorization: Bearer tk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "schedule",
    "accountId": "acc_instagram_123",
    "title": "Spring promo",
    "text": "Caption from your automation",
    "mediaUrls": ["https://pub.example.com/video.mp4"],
    "scheduledAt": "2026-04-20T09:00:00",
    "timezone": "Europe/Berlin"
  }'

Response

{
  "success": true,
  "postId": "post_123",
  "status": "scheduled",
  "scheduledAt": "2026-04-20T07:00:00.000Z"
}

// Immediate TikTok Photo Mode may return:
{
  "success": true,
  "postId": "post_123",
  "publishId": "v_pub_123",
  "status": "processing"
}

POST/media

Upload media into the Media Library

Uploads a file directly or imports a file from a URL. The uploaded asset can then be reused across drafts, schedules, and direct publish flows.

Requires publish scopeMultipart upload or JSON import

Request

curl -X POST "https://tareno.co/api/external/media" \
  -H "Authorization: Bearer tk_live_your_key" \
  -F "file=@promo-video.mp4"

Response

{
  "success": true,
  "mediaId": "asset_123",
  "url": "https://pub.example.com/promo-video.mp4"
}

GET/media

List uploaded media

Returns media items from the user's Media Library. Useful when your workflow wants to reuse existing assets instead of uploading a new file every time.

Requires read scope

Request

curl -X GET "https://tareno.co/api/external/media" \
  -H "X-Tareno-API-Key: tk_live_your_key"

Response

{
  "media": [{
    "id": "asset_123",
    "name": "promo-video.mp4",
    "url": "https://pub.example.com/promo-video.mp4"
  }]
}

POST/media/sign

Get a presigned upload URL

Creates a direct upload URL for R2 and supports deduplication via contentHash. This is the recommended flow for large media pipelines and external renderers.

Requires publish scopeSupports content hash deduplication

Request

curl -X POST "https://tareno.co/api/external/media/sign" \
  -H "Authorization: Bearer tk_live_your_key" \
  -d '{"fileName":"promo-video.mp4","contentType":"video/mp4"}'

Response

{
  "success": true,
  "signedUrl": "https://...",
  "expiresIn": 3600
}

POST/media/register-hash

Register an uploaded content hash

Finalizes the deduplication flow after a successful presigned upload. Call this once the file is stored so future uploads with the same hash can be reused.

Requires publish scope

Request

curl -X POST "https://tareno.co/api/external/media/register-hash" \
  -H "Authorization: Bearer tk_live_your_key" \
  -d '{"contentHash":"sha256-abc123","publicUrl":"https://..."}'

Response

{
  "success": true,
  "registered": true
}

GET/pinterest/boards?accountId=acc_pinterest_123

Fetch Pinterest boards

Returns available Pinterest boards for a connected Pinterest account so your automation can set the correct board ID before scheduling or publishing.

Requires read scopePinterest only

Request

curl -X GET "https://tareno.co/api/external/pinterest/boards?accountId=acc_pinterest_123" \
  -H "Authorization: Bearer tk_live_your_key"

Response

{
  "boards": [{
    "name": "Marketing ideas",
    "value": "987654321"
  }]
}

GET/usage?period=month

Inspect API usage

Returns current API consumption, per-endpoint breakdown, recent activity, and the reset date for the current billing window.

Requires read scope

Request

curl -X GET "https://tareno.co/api/external/usage?period=month" \
  -H "Authorization: Bearer tk_live_your_key"

Response

{
  "usage": {
    "current": 187,
    "limit": 2000,
    "remaining": 1813,
    "percentUsed": 9
  }
}

Analytics API

Read analytics over the API

Analytics endpoints are now available through the same External API. They mirror the dashboard data shape as closely as possible, so you can use them in reports, automations, and custom dashboards.

Analytics endpoints require a Starter plan or higher and an API key with read scope. Without paid analytics access, the API returns ANALYTICS_PLAN_REQUIRED.

InstagramFacebookTikTokYouTubeThreadsPinterestX / TwitterLinkedIn

GET/analytics/overview?period=month

Cross-platform analytics overview

Aggregates audience, impressions, engagement, post volume, platform breakdown, and top posts across all connected social accounts with cached dashboard-compatible data.

Requires read scopeStarter plan or higher

Request

curl -X GET "https://tareno.co/api/external/analytics/overview?period=month" \
  -H "Authorization: Bearer tk_live_your_key"

Response

{
  "totalMetrics": {
    "audience": { "value": "12.4K", "change": "+5.2%" },
    "impressions": { "value": "84.1K", "change": "+12%" }
  }
}

GET/analytics/audience?period=month

Audience growth and follower mix

Returns total audience, new followers, growth data, engagement, platform follower split, and freshness metadata based on snapshots and cached analytics history.

Requires read scopeStarter plan or higher

Request

curl -X GET "https://tareno.co/api/external/analytics/audience?period=month" \
  -H "Authorization: Bearer tk_live_your_key"

Response

{
  "totalAudience": { "value": "12.4K", "change": "+5.2%" },
  "newFollowers": { "value": "613", "change": "+5.2%" }
}

GET/analytics/{platform}?accountId=acc_instagram_123&period=month

Platform-specific analytics detail

Returns the same platform-native analytics structure used by the dashboard. You can pass accountId to target one connected account, otherwise the first matching account is used.

Supported: instagram, facebook, tiktok, youtube, pinterest, threads, twitter, linkedin

Request

curl -X GET "https://tareno.co/api/external/analytics/instagram?accountId=acc_instagram_123&period=month" \
  -H "Authorization: Bearer tk_live_your_key"

Response

{
  "account": {
    "id": "acc_instagram_123",
    "username": "yourhandle",
    "followersCount": 5420
  },
  "metrics": {
    "followers": 5420,
    "periodImpressions": 38210
  }
}

GET/analytics/strategy?period=month&provider=youtube

AI content strategy from owned data

Builds a strategy profile from your own posts, media library, AI clip transcripts, analytics snapshots, cached platform metrics, niche signals, and recommendation rules.

Requires read scopeStarter plan or higherOptional: provider, accountId

Request

curl -X GET "https://tareno.co/api/external/analytics/strategy?period=month&provider=youtube" \
  -H "Authorization: Bearer tk_live_your_key"

Response

{
  "videoStrategy": {
    "bestDurationBucket": "21-35s",
    "topHookType": "question"
  },
  "recommendations": [
    "Test sharper problem-based openings for 5-8 consecutive Shorts."
  ]
}

Render Workflows

Example batch flows

These examples are handy for render pipelines and automation servers that want to push many assets into drafts or schedules.

Batch push renders into drafts

TARENO_API_KEY=tk_live_your_key \
npm run remotion:push-tareno-api -- --mode=draft VAR-061

Batch schedule with explicit account mapping

TARENO_API_KEY=tk_live_your_key \
TARENO_ACCOUNT_MAP='{"instagram":"acc_instagram_123"}' \
npm run remotion:push-tareno-api -- \
  --mode=schedule \
  --scheduled-at=2026-04-20T09:00:00

Errors

Common response pattern

Errors are returned as JSON and may include an additional message, details, or platform hint depending on the endpoint.

{
  "error": "Error message here",
  "message": "Optional extra details",
  "details": "Platform-specific context"
}

Code	Meaning
400	Invalid parameters or missing required values
401	Missing, invalid, expired, or revoked API key
403	Missing scope or analytics not available on current plan
404	Account, board, provider, or resource not found
429	Rate-limited by platform or upstream provider
500	Unexpected server error

Limits

Monthly API call quotas

Usage limits apply per plan and can be inspected programmatically via the /usage endpoint.

Plan	Monthly API Calls
Free	Not included
Starter	Not included
Pro	2,000
Business	Unlimited

Tareno API for drafts, scheduling, media uploads, usage, and analytics

This reference covers the public endpoints real users can call with an API key. Internal or admin-only endpoints such as blog admin routes are intentionally excluded.

Base URL

https://tareno.co/api/external

Best used with

Claude, ChatGPT, Cursor, Gemini, Perplexity, Zapier-style automations, scripts, internal tools, render pipelines, and custom apps.

curl -X POST "https://tareno.co/api/external/publish" \ -H "Authorization: Bearer tk_live_your_key" \ -H "Content-Type: application/json" \ -d '{"mode":"draft","platform":"instagram","text":"Caption"}'

curl -X POST "https://tareno.co/api/external/publish" \ -H "Authorization: Bearer tk_live_your_key" \ -H "Content-Type: application/json" \ -d '{ "mode": "schedule", "accountId": "acc_instagram_123", "title": "Spring promo", "text": "Caption from your automation", "mediaUrls": ["https://pub.example.com/video.mp4"], "scheduledAt": "2026-04-20T09:00:00", "timezone": "Europe/Berlin" }'

{ "success": true, "postId": "post_123", "status": "scheduled", "scheduledAt": "2026-04-20T07:00:00.000Z" } // Immediate TikTok Photo Mode may return: { "success": true, "postId": "post_123", "publishId": "v_pub_123", "status": "processing" }

Code

Meaning

400

Invalid parameters or missing required values

401

Missing, invalid, expired, or revoked API key

403

Missing scope or analytics not available on current plan

404

Account, board, provider, or resource not found

429

Rate-limited by platform or upstream provider

500

Unexpected server error

Plan

Monthly API Calls

Free

Not included

Starter

Not included

Pro

2,000

Business

Unlimited