v1.0.5 to v1.1.0

85 added, 67 removed. Audit A to A.

---

name: aisa-twitter-api

- description: 'Twitter/X research, monitoring, watchlists, and OAuth-approved posting through AIsa. Use when: the user needs one flagship Twitter skill for trend tracking, competitor monitoring, timeline analysis, or approved posting without sharing passwords. Supports search, watchlists, relay-based reads, and OAuth-gated text or media posting.'

+ description: Search and inspect Twitter/X posts, profiles, timelines, communities, and trends through AIsa, or publish user-authorized posts with OAuth. Use for recent X research, account comparisons, conversation review, and approved text or media posting.

license: Apache-2.0

- compatibility: Designed for Agent Skills compatible clients such as OpenClaw, Claude Code, Hermes, and GitHub-backed skill catalogs. Requires system binaries python3, environment variables AISA_API_KEY and internet access to api.aisa.one.

+ compatibility: Requires Python 3.11+, a POSIX system, AISA_API_KEY, and access to api.aisa.one. Executed requests require an authorized estimate budget; publishing also requires the linked X account and user authorization.

metadata:

- version: "1.0.5"

+ version: "1.1.0"

aisa:

emoji: 🐦

requires:

bins:

- python3

env:

- AISA_API_KEY

primaryEnv: AISA_API_KEY

- version: 1.0.5

+ version: "1.1.0"

---

- # AIsa Twitter API Command Center

- Flagship Twitter/X skill for research, monitoring, watchlists, and OAuth-approved posting through the AIsa relay.

+ # AIsa Twitter API

- ## When to use

+ Use the read client for one-page research and the OAuth client for approved

+ posting. Both preserve provider data, report failures with nonzero exit status,

+ and account for requests through a durable cost ledger. This skill does not

+ create schedules or maintain a persistent watchlist by itself.

- - When the user wants one primary Twitter/X skill for research, monitoring, trend discovery, timeline review, or content discovery.

- - When the user needs to inspect profiles, timelines, mentions, trends, replies, quotes, lists, communities, or Spaces.

- - When the user wants to draft or publish posts after explicit OAuth approval without sharing passwords or browser cookies.

- - When the workflow should use `AISA_API_KEY` and relay-based access to `https://api.aisa.one` instead of local credential extraction.

+ ## Setup

- ## When NOT to use

+ Resolve commands relative to this installed skill directory, or use absolute

+ script paths. Python 3.11+ and a POSIX system are required; there are no third-party

+ runtime packages.

- - Do NOT use this for password-based login, cookie extraction, or browser credential scraping.

- - Do NOT use this when the workflow must avoid relay-based requests to `https://api.aisa.one`.

- - Do NOT use this as the primary skill for like, follow, reply, or growth-action workflows better handled by `aisa-twitter-engagement-suite`.

+ `AISA_API_KEY` resolves from the environment, then `~/.aisa/credentials`, then the

+ active Hermes profile configuration. Do not print the key or put it in command

+ arguments. OAuth binds the X account to that AIsa key; account authorization does

+ not itself authorize publishing content.

- ## Quick Reference

+ ## Research

- - Required environment variable: `AISA_API_KEY`

- - Required binary: `python3`

- - Read client: `scripts/twitter_client.py`

- - OAuth and posting client: `scripts/twitter_oauth_client.py`

- - Posting guide: `references/post_twitter.md`

- - Relay target: `https://api.aisa.one`

- - External writes: posting happens only after explicit OAuth approval

- - Upload behavior: image and video posting sends user-selected media through the relay

+ ```bash

+ # Inspect an authenticated free quote; this does not retrieve posts.

+ python3 scripts/twitter_client.py search --query "AI agents" --type Latest --quote

- ## Setup

+ # Execute within the user's approved estimate budget.

+ python3 scripts/twitter_client.py search --query "AI agents" --type Latest \

+ --budget-usd "$APPROVED_BUDGET_USD" --cost-ledger research-costs.json

- ```bash

- export AISA_API_KEY="your-key"

+ # Reuse the same task budget for another page or operation.

+ python3 scripts/twitter_client.py community-search --query "AI agents" --type Top \

+ --cost-ledger research-costs.json

```

- Requirements:

- - `python3`

- - `AISA_API_KEY`

- - Internet access to `https://api.aisa.one`

- - Explicit OAuth approval before posting

- - User-provided media files when posting images or videos

+ Read [cost controls and recovery](references/cost-control.md) before execution.

+ When a quote reports `may_exceed_estimate`, use `--allow-variable-cost` only if the

+ user accepted that possibility. Admission estimates are not final-charge caps.

- ## Capabilities

+ Use `--help` for profiles, timelines, followers, searches, tweet detail/replies,

+ lists, and communities. Results contain original provider objects plus `_aisa`

+ HTTP and billing metadata. Native IDs, URLs, timestamps, metrics, and cursors are

+ not rewritten. Report missing data as missing; a quote is not retrieved evidence.

- - Read user data, timelines, mentions, followers, followings, and related profile information.

- - Search tweets and users, inspect replies, quotes, retweeters, thread context, trends, lists, communities, and Spaces.

- - Run watchlist-style research and monitoring workflows from one Twitter/X command surface.

- - Publish text, image, and video posts after explicit OAuth approval.

+ Requests fetch one page. Use a returned cursor only on an operation that supports

+ it, and reuse the ledger for additional pages. `mentions`, `user-search`, and

+ `quotes` reject nonempty cursors because the current parameter contracts do not

+ declare them despite pagination prose. `space-detail` is blocked before network

+ access because its contract does not declare the required cost controls.

- ## High-Intent Workflows

+ For a time-bounded research question, include the appropriate X search operators

+ (e.g. `since:YYYY-MM-DD until:YYYY-MM-DD`) and inspect result dates before drawing

+ conclusions. Link supporting posts and describe the coverage actually retrieved.

+ Do not turn a one-off research request into scheduled monitoring.

- - Research a creator, competitor, brand, or narrative before writing.

- - Monitor a keyword, launch, or watchlist and pull representative tweets quickly.

- - Review timelines, mentions, replies, and trend movement from one command surface.

- - Draft and publish a post only after the user explicitly approves OAuth.

+ ## Approved posting

- ## Common Commands

+ Read [posting and media](references/post_twitter.md) for account linking, exact

+ payloads, thread behavior, and recovery. Use the user's authorized text, target,

+ attachments, and number of posts. OAuth approval only links an account.

```bash

- python3 scripts/twitter_client.py search --query "AI agents" --type Latest

- python3 scripts/twitter_oauth_client.py authorize

- python3 scripts/twitter_oauth_client.py post --text "Hello from AIsa"

+ # Preview locally without credentials, spending, uploads, or publishing.

+ python3 scripts/twitter_oauth_client.py post --text "$APPROVED_TEXT" --dry-run

+ # Link an account when needed; --media also requests media.write for uploads.

+ python3 scripts/twitter_oauth_client.py authorize --media \

+ --budget-usd "$APPROVED_BUDGET_USD" --cost-ledger posting-costs.json

+ # Publish the authorized content using the existing task budget.

+ python3 scripts/twitter_oauth_client.py post --text "$APPROVED_TEXT" \

+ --cost-ledger posting-costs.json

```

- ## Guardrails

+ Local files use the dedicated binary upload endpoint, followed by a post using

+ returned media IDs. Each request is separately quoted and recorded. Existing

+ media IDs can be attached directly. Oversized content requires explicit

+ `--thread`; inspect `--dry-run` output before publishing the expanded thread.

- - Do not ask for Twitter/X passwords or browser cookies.

- - Do not invent captions, tweet URLs, or attachment files.

- - Do not claim external posting succeeded until the API confirms success.

- - Do not imply OAuth is optional for posting.

+ No external write is retried automatically. If an upload/post result is ambiguous,

+ inspect the account and request-specific billing evidence before continuing.

+ Preserve confirmed IDs and partial results. Do not republish an entire thread to

+ recover a failed later chunk. `status` shows local configuration, not live OAuth

+ account validity. Do not request X passwords or browser cookies.

- ## Example Requests

+ ## API contracts

- - Research what builders on X are saying about AI agents this week.

- - Track reactions to our product launch and pull representative tweets.

- - Build a small watchlist of competitor accounts and summarize what changed today.

- - Authorize and publish a short Twitter post with an attached image.

+ The clients use [AIsa's Twitter API](https://aisa.one/docs/api-reference) with

+ Bearer authentication. The operation/parameter snapshot used by tests is in

+ `tests/fixtures/provider_contracts.json`; live contracts remain authoritative.

- ## Security Notes

+ - [Advanced search](https://aisa.one/docs/api-reference/twitter/get_twitter-tweet-advanced-search)

+ - [Community search](https://aisa.one/docs/api-reference/twitter/get_twitter-community-get-tweets-from-all-community)

+ - [OAuth authorization](https://aisa.one/docs/api-reference/twitter/post_twitter-auth-twitter)

+ - [Media upload](https://aisa.one/docs/api-reference/twitter/post_twitter-upload-media)

+ - [Post creation](https://aisa.one/docs/api-reference/twitter/post_twitter-post-twitter)

+ - [Billing and quote semantics](https://aisa.one/docs/guides/pricing)

- - This is a relay-based workflow that sends Twitter/X API requests to `https://api.aisa.one`.

- - Posting requires explicit OAuth approval through the relay before external writes occur.

- - Approved image and video posting sends user-selected media through the relay for upload.

- - Required secret: `AISA_API_KEY`.

- - This workflow does not require passwords or browser cookie extraction.

+ ## Validation

+ ```bash

+ python3 -m unittest discover -s tests -v

+ ```

+ Tests use fixtures and mocked transport; they do not authorize accounts, upload

+ media, publish posts, or execute paid retrieval.