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

n8n, Make, Zapier-style automations, scripts, internal tools, render pipelines, and custom apps.

Open API key guide n8n guide Make guide

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","mediaUrls":["https://pub.example.com/video.mp4"]}'

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, carousel

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",
    "metadata": {
      "format": "reel"
    }
  }'

Response

{
  "success": true,
  "postId": "post_123",
  "status": "scheduled",
  "scheduledAt": "2026-04-20T09:00:00.000Z",
  "timezone": "Europe/Berlin",
  "platform": "instagram"
}

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" \
  -F "folder=social-media-renders/channel-tareno" \
  -F 'tags=["campaign-spring","reel"]'

Response

{
  "success": true,
  "mediaId": "asset_123",
  "url": "https://pub.example.com/promo-video.mp4",
  "name": "promo-video.mp4",
  "folder": "social-media-renders/channel-tareno",
  "tags": ["campaign-spring", "reel"],
  "dashboardUrl": "https://tareno.co/dashboard/media"
}

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",
      "type": "video/mp4",
      "size": 1250000,
      "createdAt": "2026-04-15T17:42:00.000Z"
    }
  ]
}

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" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "promo-video.mp4",
    "contentType": "video/mp4",
    "folder": "api-imports",
    "contentHash": "sha256-abc123",
    "fileSize": 58219310
  }'

Response

{
  "success": true,
  "deduplicated": false,
  "signedUrl": "https://...",
  "path": "user-id/public/api-imports/1713280000000_promo-video.mp4",
  "publicUrl": "https://pub.example.com/...",
  "expiresIn": 3600,
  "shouldRegisterHash": true,
  "contentHash": "sha256-abc123"
}

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" \
  -H "Content-Type: application/json" \
  -d '{
    "contentHash": "sha256-abc123",
    "storagePath": "user-id/public/api-imports/1713280000000_promo-video.mp4",
    "publicUrl": "https://pub.example.com/...",
    "fileName": "promo-video.mp4",
    "contentType": "video/mp4",
    "fileSize": 58219310
  }'

Response

{
  "success": true,
  "registered": true,
  "contentHash": "sha256-abc123",
  "publicUrl": "https://pub.example.com/..."
}

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",
      "description": "Content inspiration board"
    }
  ]
}

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": 500,
    "remaining": 313,
    "percentUsed": 37,
    "resetDate": "2026-05-01T00:00:00.000Z"
  },
  "stats": {
    "period": "month",
    "total": 187,
    "successful": 181,
    "failed": 6,
    "successRate": 97
  },
  "plan": "starter"
}

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. On Free plans the API returnsANALYTICS_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", "rawValue": 12412, "change": "+0%", "trend": "neutral" },
    "impressions": { "value": "84.1K", "rawValue": 84102, "change": "+0%", "trend": "neutral" },
    "engagement": { "value": "4.8K", "rawValue": 4820, "change": "+0%", "trend": "neutral" },
    "posts": { "value": "96", "rawValue": 96, "change": "+0%", "trend": "neutral" }
  },
  "platformData": [],
  "platformBreakdown": [],
  "timeSeries": [],
  "topPosts": [],
  "connectedPlatforms": ["instagram", "tiktok", "youtube"],
  "cacheStatus": "valid",
  "needsWarmup": false
}

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", "rawValue": 12412, "change": "+5.2%" },
  "newFollowers": { "value": "613", "rawValue": 613, "change": "+5.2%" },
  "engagement": { "value": "4.8K", "rawValue": 4820, "change": "+0%" },
  "activeUsers": { "value": "4.8K", "rawValue": 4820, "change": "+0%" },
  "growthData": [
    { "date": "Mar 17", "value": 11820 },
    { "date": "Apr 16", "value": 12412 }
  ],
  "platformBreakdown": [],
  "accountCount": 4,
  "demographics": null,
  "dataSource": "snapshots",
  "lastUpdated": "2026-04-16T08:20:00.000Z"
}

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",
    "name": "Your Brand",
    "followersCount": 5420,
    "mediaCount": 86
  },
  "metrics": {
    "followers": 5420,
    "periodImpressions": 38210,
    "periodReach": 29114,
    "periodAccountsEngaged": 1880,
    "totalLikes": 1421,
    "totalComments": 203
  },
  "timeSeries": [],
  "topMedia": [],
  "availableAccounts": [],
  "currentAccountId": "acc_instagram_123"
}

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

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. Optional provider and accountId filters let you isolate one platform or one connected account.

Requires read scopeStarter plan or higherOptional: provider, accountId

Request

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

Response

{
  "version": "own-content-strategy-v2",
  "period": "month",
  "scope": {
    "provider": "youtube",
    "accountId": "acc_youtube_123",
    "filtered": true,
    "accountCount": 1
  },
  "dataCoverage": {
    "postsAnalyzed": 24,
    "mediaAssetsAnalyzed": 18,
    "transcriptsAnalyzed": 6,
    "accountsWithAnalytics": 4
  },
  "videoStrategy": {
    "accounts": [
      {
        "platform": "youtube",
        "videosAnalyzed": 15,
        "videosAbove1000Views": 0,
        "bestDurationBucket": "21-35s",
        "topHookType": "question",
        "recommendations": [
          "Pause generic feature-list packaging for the next batch and test sharper problem or question-based openings for 5-8 consecutive Shorts."
        ]
      }
    ],
    "crossPlatformTakeaways": [
      "YouTube has not found a repeatable breakout package yet, which usually means the topic is still too generic or the first second is not specific enough."
    ]
  },
  "niche": {
    "label": "Social media automation and content operations",
    "confidence": 0.78,
    "keywords": [{ "term": "automation", "score": 18 }]
  },
  "recommendations": [
    {
      "priority": "high",
      "title": "Transcribe your own video assets",
      "action": "Run AI Clip Studio or transcript extraction for your best recent videos."
    }
  ]
}

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

TARENO_API_KEY=tk_live_your_key \
npm run remotion:push-tareno-api -- --mode=draft --platforms=instagram,tiktok VAR-061 VAR-062

Batch schedule with explicit account mapping

TARENO_API_KEY=tk_live_your_key \
TARENO_ACCOUNT_MAP='{"instagram":"acc_instagram_123","tiktok":"acc_tiktok_456"}' \
TARENO_PLATFORM_METADATA='{"pinterest":{"pinterestBoard":"board_123"}}' \
npm run remotion:push-tareno-api -- \
  --mode=schedule \
  --scheduled-at=2026-04-20T09:00:00 \
  --timezone=Europe/Berlin \
  VAR-061 VAR-062

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	50
Starter	500
Pro	2,000
Business	10,000