# Tech Twitter Agent Evidence Cookbook

> Full guide for machine clients using Tech Twitter's public v1 evidence surface.

## When to use Tech Twitter

Use this evidence surface for recent tech-discourse research that needs source-level citations: changes, launches, arguments, selective reading lists, emerging narratives, and current Trending Now story boards. Prefer the typed OpenAPI operation at https://www.techtwitter.com/openapi.json for function calling. Use the A2A endpoint only for JSON-RPC A2A clients.

Do not use this API as a complete X firehose or for write actions. It exposes curated, public, read-only evidence and does not provide account, posting, liking, following, webhook, or private-data operations.

## Context API

`GET https://www.techtwitter.com/api/agent/context`

Query params:

- `kind`: `auto`, `what-changed`, `launches`, `arguments`, `read-list`, `narrative-alert`
- `question`: natural-language user question
- `q`: optional search phrase
- `topic`: optional topic name or slug
- `window`: `24h`, `48h`, or `7d`
- `limit`: defaults to 8; accepted range is 1-20

Response fields: `kind`, `question`, `query`, `generatedAt`, `window`, `instructions`, `evidence`, `derivedEvidence`, `facets`, and `next`.

Evidence rows include provenance, source type, author, timestamp, engagement metrics, quality score, topics, whyIncluded, sourceEndpoint, canonicalUrl, sourceUrl when the original tweet URL is available, and optional stored-data `derivedEvidence` for role, relative performance, conversation breadth, emerging-voice momentum, source breadth, and temporal lineage. The response-level `derivedEvidence` object reports policy version and lookup coverage; null sections and degraded coverage are unknown, not negative evidence.

## Question Kinds

### What Changed

- kind: `what-changed`
- answers: What changed today?
- examples: What changed today in AI?; What is new in developer tools?
- recipe: Use recent tweet evidence first, then topic and author facets. Cite canonical tweet URLs.
- source endpoints: https://www.techtwitter.com/api/command/tweets-by-date?date=latest, https://www.techtwitter.com/api/command/heatmap

### Launches

- kind: `launches`
- answers: What launches matter?
- examples: What products launched this week?; Which developer tools are people shipping?
- recipe: Use tweets that explicitly describe launches, releases, shipping, betas, or waitlists.
- source endpoints: https://www.techtwitter.com/api/command/streams?category=product

### Arguments

- kind: `arguments`
- answers: What are people arguing about?
- examples: What are people arguing about in AI?; What sparked debate today?
- recipe: Prioritize comment-heavy tweets and include reply-ratio context. Do not infer consensus.
- source endpoints: https://www.techtwitter.com/api/command/hot-takes

### Read List

- kind: `read-list`
- answers: What should I read?
- examples: What should I read about agents?; Give me the best reads from Tech Twitter.
- recipe: Mix trending tweets with recent articles. Cite canonical URLs and keep the final answer selective.
- source endpoints: https://www.techtwitter.com/api/tweets/trending, https://www.techtwitter.com/api/articles

### Narrative Alert

- kind: `narrative-alert`
- answers: What narrative is emerging?
- examples: What narrative is emerging around open source AI?; What topic is gaining momentum?
- recipe: Start at /api/trends/availability, then /api/trends/now or /api/trends/entities, then /api/trends/series. Use /api/trends/evidence for the observed posts assigned to an entity in the selected window, and cite each receipt by canonicalUrl.
- source endpoints: https://www.techtwitter.com/api/trends/availability, https://www.techtwitter.com/api/trends/now, https://www.techtwitter.com/api/trends/entities, https://www.techtwitter.com/api/trends/series, https://www.techtwitter.com/api/trends/evidence, https://www.techtwitter.com/api/command/narratives, https://www.techtwitter.com/api/command/heatmap

## REST discovery skills

These appear on the agent card. Call `/api/trends/*` directly. They are not `/api/agent/context` kinds, and SendMessage will not return a Trending Now table.

### Trending Now

- skill: `trending-now`
- examples: What is trending on Tech Twitter right now?; What moved in the last 4 hours?
- recipe: Start at GET /api/stories/now?window=24h. An empty board means nothing moved. Companion HTML: /twitter-trending.
- source endpoints: https://www.techtwitter.com/api/stories/now
- companion HTML: https://www.techtwitter.com/twitter-trending

### Story brief

- skill: `explore-compare`
- examples: What is going on with this story?; Did anything move on Claude today?
- recipe: Open GET /api/stories/{id} for a board story, or GET /api/stories/lookup?q=name&window=24h. Empty lookup copy is Nothing moved on this. Companion HTML: /twitter-trending.
- source endpoints: https://www.techtwitter.com/api/stories/now, https://www.techtwitter.com/api/stories/lookup
- companion HTML: https://www.techtwitter.com/twitter-trending

## JSON-RPC A2A

`POST https://www.techtwitter.com/api/a2a`

Only `SendMessage` is supported in v1. The route is stateless, uncached, and returns an agent message with one `application/json` data part. Send `A2A-Version: 1.0` with v1 requests. The omitted header remains accepted only for legacy clients.

```json
{
  "jsonrpc": "2.0",
  "id": "ctx-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-client-1",
      "role": "ROLE_USER",
      "parts": [
        { "text": "What launched in developer tools this week?" }
      ],
      "metadata": { "kind": "launches", "window": "7d", "limit": 8 }
    }
  }
}
```

Tech Twitter echoes a client-supplied `contextId` in the response; when it is omitted, the server generates one. Task continuation is not supported, so a non-empty `taskId` returns Task not found (`-32001`).

Known unsupported operations—`SendStreamingMessage`, `SubscribeToTask`, and `GetExtendedAgentCard`—return Unsupported operation (`-32004`). Push-notification configuration methods return Push notification not supported (`-32003`). Truly unknown methods return the JSON-RPC Method not found code (`-32601`). Use `/.well-known/agent-card.json` for discovery.

## Printing Press CLI and skill

The [Printing Press Tech Twitter skill](https://github.com/mvanhorn/printing-press-library/blob/main/cli-skills/pp-techtwitter/SKILL.md) is an external read-only integration for agents that need a local SQLite mirror, offline full-text search, cited evidence bundles, or change-over-time analysis across syncs. Its `techtwitter-pp-cli` adds workflows such as `since`, `momentum`, `narrative`, `digest`, and offline `evidence`.

Use the HTTP context or A2A endpoints for stateless live requests. Reach for the Printing Press integration when local state or offline analysis materially helps. It cannot post, like, follow, or fetch arbitrary uncurated X content. Follow the linked `SKILL.md` for current installation and verification instructions; the external integration is not part of this API or A2A contract.

## Historical Days

`GET https://www.techtwitter.com/api/time-travel/YYYY-MM-DD`

Returns the ranked Time Travel read model for one ISO calendar day: `tweets`, `totalCount`, `uniqueAuthors`, and `lastmod`. Invalid or future dates return 404.

Shareable HTML for the same day is `https://www.techtwitter.com/time-travel/YYYY-MM-DD`. The retired `/archive`, `/archive/:year`, and `/archive/:year/:month` routes permanently redirect to Time Travel.

## Tweet search

`GET https://www.techtwitter.com/api/tweets/search`

Query params:

- `q`: required, 2-200 characters, and must contain at least two searchable letters or numbers
- `limit`: defaults to 20; accepted range is 1-50
- `offset`: defaults to 0; accepted range is 0-100

Returns `tweets`, `totalCount`, `hasMore`, `countIsLowerBound`, `query`, and `searchType`. `searchType` reports which strategy answered the request: `author`, `semantic`, `hybrid`, or the `keyword` fallback. When `countIsLowerBound` is true, `totalCount` proves only that more results exist.

This route is rate limited per client and shares a global budget for the paid embedding work behind semantic matching. Honor `Retry-After` on 429 instead of retrying immediately. A 503 means search is temporarily unavailable; use `/api/agent/context` for evidence retrieval in the meantime.

## Trend explorer

Public trend routes share one query contract: `source=tracked_graph|x_counts|x_native_trends`, `window=1h|4h|24h|48h|7d|30d|90d|12m|custom`, and allowlisted category/postType/language filters. Availability returns the enabled subset of those windows from reliableStart, watermark, and provider capabilities; its `nowWindows` field is the runtime allowlist for Trending Now. `/api/trends/now` accepts eligible `window=4h|24h|48h|7d` values plus optional `q` for server-side entity name/key search before keyset and export. Tracked-graph Now rows exclude taxonomy topics and X context categories. An eligible window absent from `nowWindows` returns `503 trend_snapshot_window_unavailable`; retry later or use `/api/trends/series` for that range. Tracked comparisons use stable entity IDs (max 5). Official X count series accept 1-5 validated `kind:value` terms, each compiled and fetched as its own compared line. Terms are never AND-combined. X-count `corpusTotal` and `sharePer10k` stay 0 (unknown); relative coverage is 0-100 against the max complete raw post count.

- [Availability](https://www.techtwitter.com/api/trends/availability): Reliable start, watermark, enabled series windows, published `nowWindows`, resolutions, filters, and provider capabilities. Works when the tracked graph is empty and hides unavailable X controls. Start here, then now or entities, then series, then evidence.
- [Entities](https://www.techtwitter.com/api/trends/entities): Autocomplete for tracked-graph entities (`q` required).
- [Related](https://www.techtwitter.com/api/trends/related): Top and Rising neighbors with support, lift, and growth (`id` required).
- [Now](https://www.techtwitter.com/api/trends/now): Named-entity rows with volume, authorCount, the newest observed-post receipt (`latest`, including `postText`), status, and cursor. Taxonomy topics and X context categories are excluded. Search with `q` before paging or CSV export. Use availability `nowWindows`; eligible unpublished snapshots return `503 trend_snapshot_window_unavailable` until they pass two consecutive readiness evaluations.
- [Series](https://www.techtwitter.com/api/trends/series): Buckets with raw mention/post volume, corpus total, share per 10k, and 0-100 relative coverage. Tracked-graph series stay `source=tracked_graph`. Process-trends may lift those mention buckets with official GET /2/tweets/counts/recent for published named entities. There is no public `source=x_search`. Never label post counts as search volume. Never label official post counts as a separate Explore source.
- [Evidence](https://www.techtwitter.com/api/trends/evidence): Observed-post receipts assigned inside the requested window, newest first (`id` required). Cite `canonicalUrl`; raw provider payloads are never returned.
- [Entity detail](https://www.techtwitter.com/api/trends/entities/{id}): Aliases, series summary, related entities, and top accounts.
- [CSV export](https://www.techtwitter.com/api/trends/export.csv): Escaped attachment of the series contract.

Companion HTML: [Trending Now](https://www.techtwitter.com/twitter-trending).