Capduck Iran-Briefing API v2.1

Authentication

Authorization: Bearer YOUR_API_KEY

1 · Overview

AI multi-perspective situation briefing, updated hourly. 4 perspectives + watch items.

2 · Events

Structured event timeline with impact scores, categories, and source attribution.

Parameters

Response Fields

source_details[] Fields

3 · Posts

Unified Twitter + Telegram social feed. Author classification, engagement metrics.

Parameters

Response Fields

source_type Dictionary

Example Response

{
  "success": true,
  "data": [{
    "id": "683514831161",
    "author_name": "Commentary: Trump Truth Social Posts On X",
    "author_handle": "@TrumpTruthOnX",
    "author_avatar": "https://iran-monitor.okfrontier.com/img?url=...",
    "source_type": "gov_military",
    "content": "Trump to address the nation on #Iran tomorrow\n\n'Important Update' — WH\n\n#IranWar",
    "content_zh": "特朗普将于明天就#伊朗问题发表全国讲话\n\n“重要进展”——白宫\n\n#伊朗战争",
    "source_url": "https://x.com/TrumpTruthOnX/status/2039129683514831161",
    "platform": "twitter",
    "retweets": 5,
    "likes": 35,
    "translated": true,
    "published_at": "2026-03-31T23:56:16+00:00",
    "fetched_at": "2026-04-01T07:06:59.454Z"
  }],
  "meta": { "topic": "iran", "total": 285, "returned": 50, "limit": 50, "since": "2026-03-30T07:06:59Z" }
}

4 · News

18 major outlets: Reuters, AP, CNN, NYT, WaPo, Fox, Bloomberg, Guardian, BBC, Al Jazeera, and more.

Parameters

Response Fields

media_region Dictionary

Example Response

{
  "success": true,
  "data": [{
    "id": "a7c3e1f29b04",
    "title": "U.S. deploys additional carrier strike group to Middle East amid Iran tensions",
    "title_zh": "美国在伊朗紧张局势加剧之际向中东增派航母打击群",
    "url": "https://www.reuters.com/world/middle-east/us-deploys-additional-carrier-2026-03-31/",
    "author_name": "Reuters",
    "author_avatar": "https://iran-monitor.okfrontier.com/img?url=...",
    "media_region": "intl",
    "sentiment": "NEGATIVE",
    "language": "en",
    "translated": true,
    "published_at": "2026-03-31T18:42:00+00:00",
    "fetched_at": "2026-04-01T07:06:59.454Z"
  }],
  "meta": { "topic": "iran", "total": 143, "returned": 50, "limit": 50, "since": "2026-03-30T07:06:59Z" }
}

5 · Polymarket

Prediction market data with current probabilities and price history series.

Response Fields

6 · Trump Truth Social

Full Trump Truth Social feed — all posts, no topic filtering. No auth required. Response schema identical to Posts with additional tags field.

Parameters

Response Fields

Example

# All Trump posts (latest 20, no auth needed)
curl "https://api.capduck.com/trump?limit=20"

# Iran-related posts only
curl "https://api.capduck.com/trump?tags=iran-war&limit=50"

# Paginate with cursor
curl "https://api.capduck.com/trump?limit=10&cursor=2026-04-06T04:57:00+00:00"

Example Response

{
  "success": true,
  "data": [{
    "id": "93607e27-683f-44d0-8390-ec74ef74c611",
    "author_name": "Donald J. Trump",
    "author_handle": "@realDonaldTrump",
    "author_avatar": "https://r2.okfrontier.com/files/8cf2a24f...jpg",
    "source_type": "gov_military",
    "entity_slug": "donald-trump",
    "content": "Tuesday will be Power Plant Day, and Bridge Day...",
    "content_zh": "周二在伊朗将是发电厂之日和桥梁之日...",
    "source_url": "https://truthsocial.com/@realDonaldTrump/statuses/...",
    "platform": "truth-social",
    "tags": ["iran-war"],
    "translated": true,
    "published_at": "2026-04-05T12:30:45+00:00",
    "fetched_at": "2026-04-05T12:30:45+00:00"
  }],
  "meta": {
    "topic": "trump",
    "total": 10,
    "returned": 10,
    "offset": 0,
    "limit": 50,
    "has_more": true,
    "next_cursor": "2026-04-04T19:22:00+00:00"
  }
}

Incremental Polling

# 1. Initial fetch
GET /v2/event/iran/events?limit=100

# 2. Record latest published_at
last = response.data[0].published_at

# 3. Next fetch — Unix timestamp or ISO 8601
GET /v2/event/iran/events?since=1743321600           # Unix seconds
GET /v2/event/iran/events?since=1743321600000        # Unix milliseconds
GET /v2/event/iran/events?since=2026-03-30T00:00:00Z # ISO 8601

# 4. Dedup by id (edge overlap)

Errors

{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing API key" }
}

SDK Examples

cURL

# Overview briefing
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.capduck.com/v2/event/iran"

# High-impact events (translated only)
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.capduck.com/v2/event/iran/events?impact=8&lang=translated"

# Political figure posts (e.g. Trump Truth Social)
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.capduck.com/v2/event/iran/posts?source_type=gov_military&limit=20"

# Filter by specific author (entity_slug or handle)
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.capduck.com/v2/event/iran/posts?author=donald-trump&since=0&limit=50"

# US media news
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.capduck.com/v2/event/iran/news?region=us&limit=50"

# Posts linked to a specific event
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.capduck.com/v2/event/iran/posts?event=77a29138-954f-4767-9246-493f7bcc34aa"

TypeScript

const BASE = 'https://api.capduck.com/v2/event/iran';
const headers = { Authorization: 'Bearer YOUR_KEY' };

interface ApiResponse<T> {
  success: boolean;
  data: T;
  meta: { topic: string; total: number; returned: number; limit: number; since?: string };
}

interface Post {
  id: string;
  author_name: string;
  author_handle?: string;
  author_avatar: string;
  source_type: 'news_agency' | 'state_media' | 'osint' | 'gov_military' | 'journalist' | 'think_tank' | 'other';
  content: string;
  content_zh?: string;
  source_url: string;
  platform: 'twitter' | 'telegram';
  retweets?: number;
  likes?: number;
  translated: boolean;
  published_at: string;
  fetched_at: string;
}

async function fetchPosts(params?: Record<string, string>): Promise<ApiResponse<Post[]>> {
  const qs = params ? '?' + new URLSearchParams(params).toString() : '';
  const res = await fetch(`${BASE}/posts${qs}`, { headers });
  return res.json();
}

// Usage
const { data: posts } = await fetchPosts({ source_type: 'gov_military', limit: '20' });
posts.forEach(p => console.log(`[${p.source_type}] ${p.author_name}: ${p.content.slice(0, 80)}`));

Python

import requests

BASE = "https://api.capduck.com/v2/event/iran"
H = {"Authorization": "Bearer YOUR_KEY"}

briefing = requests.get(BASE, headers=H).json()
events   = requests.get(f"{BASE}/events", headers=H, params={"impact": 8}).json()
posts    = requests.get(f"{BASE}/posts", headers=H, params={"source_type": "gov_military"}).json()
news     = requests.get(f"{BASE}/news", headers=H, params={"region": "us", "limit": 50}).json()

JavaScript

const BASE = 'https://api.capduck.com/v2/event/iran';
const h = { 'Authorization': 'Bearer YOUR_KEY' };

const briefing = await fetch(BASE, {headers: h}).then(r => r.json());
const events   = await fetch(`${BASE}/events?impact=8`, {headers: h}).then(r => r.json());
const posts    = await fetch(`${BASE}/posts?platform=telegram`, {headers: h}).then(r => r.json());
const news     = await fetch(`${BASE}/news?region=us&limit=50`, {headers: h}).then(r => r.json());