# Tech Twitter Developer Portal

> Public, read-only, citation-ready evidence for agents researching high-signal tech discourse.

## Authentication

No API key is required, and API keys are not issued. Never send Supabase service-role credentials, cron secrets, or internal job secrets to public endpoints.

## Quickstart

```bash
curl --get 'https://www.techtwitter.com/api/agent/context' \
  --data-urlencode 'kind=launches' \
  --data-urlencode 'question=What launched in developer tools?' \
  --data-urlencode 'window=7d' \
  --data-urlencode 'limit=8'
```

The context endpoint accepts `kind`, `question`, `q`, `topic`, `window`, and `limit`. Evidence rows include provenance, metrics, a reason for inclusion, the original source URL when available, and a canonical Tech Twitter URL for citation.

## A2A v1

Send the negotiated protocol version and an A2A v1 `Message`. The no-header request shape remains readable for legacy clients, but new integrations should always identify v1.

```bash
curl 'https://www.techtwitter.com/api/a2a' \
  --header 'Content-Type: application/json' \
  --header 'A2A-Version: 1.0' \
  --data '{"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}}}}'
```

## Rate limits

- Context API: 120 requests per minute per client.
- A2A JSON-RPC: 60 requests per minute per client.
- A 429 response includes a `Retry-After` header. Wait that many seconds before retrying.

## Errors

REST errors return `{"error":{"code":"...","message":"...","hint":"..."}}`. Unknown API paths use the same JSON envelope. A2A keeps standard JSON-RPC error objects.

## Resources

- [OpenAPI 3.1 specification](https://www.techtwitter.com/openapi.json): Typed operations and schemas for function calling.
- [llms.txt instructions](https://www.techtwitter.com/llms.txt): When-to-use guidance and evidence recipes.
- [A2A agent card](https://www.techtwitter.com/.well-known/agent-card.json): Agent discovery and skills.
- [Full agent cookbook](https://www.techtwitter.com/llms-full.txt): Request examples and response guidance.
- [HTML developer portal](https://www.techtwitter.com/developers): Live read-only GET sandbox.

## External agent integration

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 workflows such as `since`, `momentum`, and `narrative`. Follow the linked skill's current setup instructions before invoking `techtwitter-pp-cli`. It is separate from the public API and A2A contract.

## Boundaries

Tech Twitter is a curated evidence source, not a complete X firehose. It does not expose posting, liking, following, webhooks, user accounts, private data, or operator endpoints.