Hermes Tweet

https://github.com/xquik-dev/hermes-tweet
Admin
Native Hermes Agent plugin for Xquik's X/Twitter API: search, read, publish, monitor, and automate X...
Tokens:12,689
Snippets:86
Trust Score:7.8
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Use README.md and docs/CONTEXT7.md for install, configuration, tool usage, security model, and runtime smoke tests.
- Use docs/OBSERVABILITY.md for scripted Hermes runtime checks.
- Use docs.xquik.com/guides/hermes-tweet for end-to-end Hermes setup.
- Use tweet_explore before tweet_read or tweet_action; tweet_action is disabled unless explicitly enabled.
- Use pyproject.toml and the PyPI package hermes-tweet for package metadata and supported Python versions.
- Do not ask users to pass credentials through tool arguments; use environment configuration.

================
CODE SNIPPETS
================
### Install Hermes Tweet via Plugin Manager

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Install the plugin interactively, prompting for XQUIK_API_KEY, or non-interactively by setting the key and enabling the plugin.

```bash
# Interactive install: Hermes will prompt for XQUIK_API_KEY
hermes plugins install Xquik-dev/hermes-tweet --enable

# Non-interactive: set key manually after install
export XQUIK_API_KEY="xq_your_key_here"
hermes plugins enable hermes-tweet
```

--------------------------------

### Install Hermes Tweet from Local Checkout

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/README.md

Install the Hermes Tweet plugin from a local directory path. The --force flag can be used to overwrite an existing installation. Ensure the path is absolute.

```bash
hermes plugins install file:///absolute/path/to/hermes-tweet --force --enable
```

--------------------------------

### Install Hermes Tweet Plugin

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/docs/CONTEXT7.md

Install the Hermes Tweet plugin from GitHub and enable it. This is the first step for using the tool.

```bash
hermes plugins install Xquik-dev/hermes-tweet --enable
```

--------------------------------

### Install Hermes Tweet via PyPI

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/README.md

Install the hermes-tweet Python package into the Hermes Python environment using uv pip. After installation, enable the plugin within Hermes.

```bash
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-tweet
hermes plugins enable hermes-tweet
```

--------------------------------

### Install Hermes Tweet via PyPI

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Install the hermes-tweet package using pip or uv within the Hermes virtual environment, then enable the plugin.

```bash
# Using pip inside Hermes virtualenv
~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-tweet
hermes plugins enable hermes-tweet

# Using uv
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-tweet
hermes plugins enable hermes-tweet
```

--------------------------------

### Install Hermes Tweet Python Package

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/docs/CONTEXT7.md

Install the hermes-tweet Python package into the Hermes Python environment using uv pip and enable the plugin.

```bash
uv pip install --python "~/.hermes/hermes-agent/venv/bin/python" hermes-tweet
hermes plugins enable hermes-tweet
```

--------------------------------

### Install Hermes Tweet using pip (alternative path)

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/README.md

If your Hermes virtual environment includes pip, this alternative path can be used to install the hermes-tweet package. Ensure to enable the plugin afterwards.

```bash
~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-tweet
hermes plugins enable hermes-tweet
```

--------------------------------

### List Hermes Tweet Tools

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/skills/hermes-tweet/SKILL.md

Verify that the hermes-tweet toolset is enabled and available after installation or upgrade. This command also helps confirm tool availability based on environment variables like `XQUIK_API_KEY` and `HERMES_TWEET_ENABLE_ACTIONS`.

```bash
hermes tools list
```

--------------------------------

### Run Hermes Tool Smoke Test

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/docs/OBSERVABILITY.md

Execute a smoke test using `hermes -z` to probe tool functionality and verify specific behaviors, such as access control and endpoint registration. This is useful after installation or updates.

```bash
hermes -z "Use tweet_explore, then read /api/v1/account. Do not call tweet_action." --toolsets hermes-tweet
```

--------------------------------

### Hermes Tweet API Error Handling Examples

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

These examples show the consistent JSON error responses from all Hermes Tweet tools. They cover missing API keys, unknown endpoints, attempts to use action endpoints with `tweet_read`, and general API request failures.

```json
// Missing API key
{ "success": false, "error": "XQUIK_API_KEY is not configured." }
```

```json
// Endpoint not in catalog
{ "success": false, "error": "Endpoint is not in the Hermes Tweet catalog: GET /api/v1/unknown" }
```

```json
// Attempted to call an action endpoint via tweet_read
{ "success": false, "error": "Use tweet_action for private or write-like endpoints." }
```

```json
// API error
{ "success": false, "error": "API request failed.", "status_code": 429, "response": {...} }
```

--------------------------------

### Explore MPP-Eligible Read Endpoints

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Filter the endpoint catalog to find only MPP-eligible read endpoints by setting the 'mpp' parameter to true and specifying the method as GET.

```json
// Filter to MPP-eligible read endpoints only
{
  "mpp": true,
  "method": "GET",
  "limit": 32
}
```

--------------------------------

### Hermes Tweet Smoke Test

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/docs/CONTEXT7.md

Run a smoke test to verify the installation and configuration of Hermes Tweet. This test checks tool listing, endpoint exploration, and read/action capabilities based on API key and action enablement.

```bash
hermes tools list
hermes -z "Use tweet_explore, then read /api/v1/account. Do not call tweet_action." --toolsets hermes-tweet
```

--------------------------------

### Run Development Checks with Ruff, Pytest, Bandit, and more

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/README.md

Execute a series of development checks including code formatting, linting, type checking, testing with coverage, security analysis with Bandit, dependency auditing with pip-audit, package building, and distribution checking.

```bash
uv run --python 3.12 --extra dev ruff format --check .
uv run --python 3.12 --extra dev ruff check .
uv run --python 3.12 --extra dev basedpyright
uv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests --cov-report=term-missing --cov-fail-under=100
uv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts
uv run --python 3.12 --extra dev pip-audit
uv run --python 3.12 --extra dev python -m build
uv run --python 3.12 --extra dev twine check dist/*
```

--------------------------------

### Configure XQUIK API Key

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/docs/CONTEXT7.md

Set the XQUIK_API_KEY environment variable to authenticate with the Xquik dashboard. This is required for most tool functionalities.

```bash
export XQUIK_API_KEY="xq_..."
```

--------------------------------

### Hermes Plugin Entry Point

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

The entry point for the Hermes plugin, automatically called by the Hermes Agent when the plugin is loaded. It registers various tools and commands.

```python
# hermes_tweet/__init__.py — called by Hermes Agent automatically
from hermes_tweet import register

# Hermes calls register(ctx) where ctx is the Hermes plugin context
# register(ctx) calls:
#   ctx.register_tool("tweet_explore", ...)
#   ctx.register_tool("tweet_read", ..., check_fn=check_api_available)
#   ctx.register_tool("tweet_action", ..., check_fn=action_enabled)
#   ctx.register_command("xstatus", handler=xstatus)
#   ctx.register_command("xtrends", handler=xtrends)
#   _register_bundled_skills(ctx)  # loads skills/hermes-tweet/SKILL.md
```

--------------------------------

### explore(args)

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Searches for DM-related endpoints, including action endpoints, or filters endpoints based on criteria like free, MPP, and method.

```APIDOC
## explore(args)

### Description
Searches for DM-related endpoints including action endpoints, or filters endpoints based on criteria like free, MPP, and method.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **query** (string) - Optional - Search query string.
- **include_actions** (boolean) - Optional - Whether to include action endpoints in the search results.
- **limit** (integer) - Optional - The maximum number of results to return.
- **free** (boolean) - Optional - Filter for free endpoints.
- **mpp** (boolean) - Optional - Filter for MPP (Message Per Person) endpoints.
- **method** (string) - Optional - Filter by HTTP method (e.g., "GET").

### Request Example
```python
# Search for DM-related endpoints including action endpoints
result = explore({"query": "dm", "include_actions": True, "limit": 5})

# Filter to free MPP read endpoints
result = explore({"free": True, "mpp": True, "method": "GET"})
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **endpoints** (array) - A list of matching endpoints.

#### Response Example
```json
{
  "success": true,
  "endpoints": [
    ...
  ]
}
```
```

--------------------------------

### request(method, path, query, body)

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

A low-level HTTP client for making requests to the Xquik API. It reads API keys and base URLs from environment variables.

```APIDOC
## request(method, path, query, body)

### Description
A low-level HTTP client for making requests to the Xquik API. It reads API keys and base URLs from environment variables.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Arguments
- **method** (string) - Required - The HTTP method (e.g., "GET", "POST").
- **path** (string) - Required - The API endpoint path (e.g., "/api/v1/account").
- **query** (object) - Optional - Query parameters for the request.
- **body** (object) - Optional - The request payload.

### Request Example
```python
from hermes_tweet.client import request

# Calls Xquik API; reads XQUIK_API_KEY and XQUIK_BASE_URL from environment
result = request("GET", "/api/v1/account")

result = request(
    "POST",
    "/api/v1/x/tweets",
    body={"account": "@myaccount", "text": "Hello!"}
)
# Auth header: "x-api-key: xq_..." for xq_ keys, "Authorization: Bearer ..." for others
```

### Response
#### Success Response (200)
- **(type)** - Parsed JSON dictionary of the response or an error dictionary.

#### Response Example
```json
{
  "data": { ... }
}
```

```json
{
  "error": "..."
}
```
```

--------------------------------

### Show Account and Usage Status with /xstatus

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

The `/xstatus` slash command displays account information, plan details, and credit usage. It internally calls `tweet_read` with `path: "/api/v1/account"` and accepts no arguments.

```bash
# In an active Hermes interactive CLI or gateway session
/xstatus
```

--------------------------------

### Explore Endpoints Including Actions

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Include write-like and private endpoints in the search results by setting 'include_actions' to true, useful for finding posting functionalities.

```json
// Show action (write) endpoints too
{
  "query": "post tweet",
  "include_actions": true
}
```

--------------------------------

### Generate Bundled Catalog

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/README.md

Generate the bundled catalog from the Xquik OpenAPI specification. This script is used during development to update the tool catalog.

```bash
python scripts/build_catalog.py ../xquik/openapi.yaml
```

--------------------------------

### Development Scripts

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Scripts for development tasks, including generating the API catalog from an OpenAPI spec and running a full quality gate with various checks like formatting, linting, type checking, and security analysis.

```bash
# Generate catalog from Xquik OpenAPI spec
python scripts/build_catalog.py ../xquik/openapi.yaml

# Run full quality gate
uv run --python 3.12 --extra dev ruff format --check . && \
uv run --python 3.12 --extra dev ruff check . && \
uv run --python 3.12 --extra dev basedpyright && \
uv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests \
  --cov-report=term-missing --cov-fail-under=100 && \
uv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts && \
uv run --python 3.12 --extra dev pip-audit && \
uv run --python 3.12 --extra dev python -m build && \
uv run --python 3.12 --extra dev twine check dist/*
```

--------------------------------

### Set Xquik API Key Persistently

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/after-install.md

Add the XQUIK_API_KEY to the ~/.hermes/.env file for persistent sessions. After editing, reload the CLI or restart gateway/cron sessions for changes to take effect.

```bash
XQUIK_API_KEY=xq_...
```

--------------------------------

### Configure Optional Hermes Tweet Settings

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/docs/CONTEXT7.md

Set optional environment variables for XQUIK_BASE_URL and HERMES_TWEET_ENABLE_ACTIONS. Disabling actions enhances safety for unattended sessions.

```bash
export XQUIK_BASE_URL="https://xquik.com"
export HERMES_TWEET_ENABLE_ACTIONS="false"
```

--------------------------------

### Configure Hermes Tweet Environment Variables

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Set required and optional environment variables for Xquik API key, base URL, and action endpoint enablement. For persistent settings, add them to ~/.hermes/.env.

```bash
# Required: Xquik API key (create at https://dashboard.xquik.com)
export XQUIK_API_KEY="xq_..."

# Optional: override API base URL (default: https://xquik.com)
export XQUIK_BASE_URL="https://xquik.com"

# Optional: enable write/action endpoints (disabled by default)
export HERMES_TWEET_ENABLE_ACTIONS="false"
```

```bash
XQUIK_API_KEY=xq_...
HERMES_TWEET_ENABLE_ACTIONS=false
```

--------------------------------

### Low-Level HTTP Request Client

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

A low-level HTTP client for making requests to the Xquik API. Reads API key and base URL from environment variables. Handles authentication headers automatically.

```python
from hermes_tweet.client import request

# Calls Xquik API; reads XQUIK_API_KEY and XQUIK_BASE_URL from environment
result = request("GET", "/api/v1/account")
# Returns parsed JSON dict or error dict

result = request(
    "POST",
    "/api/v1/x/tweets",
    body={"account": "@myaccount", "text": "Hello!"}
)
# Auth header: "x-api-key: xq_..." for xq_ keys, "Authorization: Bearer ..." for others
```

--------------------------------

### Single Local Quality Gate

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/README.md

Run all development checks in a single command to ensure code quality and compliance before committing. This combines formatting, linting, type checking, testing, security analysis, dependency auditing, building, and distribution checks.

```bash
uv run --python 3.12 --extra dev ruff format --check . && \
uv run --python 3.12 --extra dev ruff check . && \
uv run --python 3.12 --extra dev basedpyright && \
uv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests --cov-report=term-missing --cov-fail-under=100 && \
uv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts && \
uv run --python 3.12 --extra dev pip-audit && \
uv run --python 3.12 --extra dev python -m build && \
uv run --python 3.12 --extra dev twine check dist/*
```

--------------------------------

### call_action(args)

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Calls an action endpoint on the Xquik API. Used for performing operations like posting tweets. Requires API key and action enablement.

```APIDOC
## call_action(args)

### Description
Calls an action endpoint on the Xquik API. Used for performing operations like posting tweets. Requires API key and action enablement.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **method** (string) - Required - The HTTP method (e.g., "POST").
- **path** (string) - Required - The API endpoint path (e.g., "/api/v1/x/tweets").
- **body** (object) - Required - The request payload (e.g., `{"account": "@myaccount", "text": "Posted via Hermes Tweet API"}`).
- **reason** (string) - Optional - A reason for the action, used for auditing or confirmation.

### Request Example
```python
import os
os.environ["XQUIK_API_KEY"] = "xq_..."
os.environ["HERMES_TWEET_ENABLE_ACTIONS"] = "true"

result = call_action({
    "method": "POST",
    "path": "/api/v1/x/tweets",
    "body": {"account": "@myaccount", "text": "Posted via Hermes Tweet API"},
    "reason": "Test post"
})
```

### Response
#### Success Response (200)
- **(type)** - JSON string representing the result of the action (e.g., created tweet details) or an error object.

#### Response Example
```json
{
  "id": "...",
  "text": "...",
  ...
}
```

```json
{
  "error": "..."
}
```
```

--------------------------------

### tweet_explore Tool

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Searches the bundled Xquik endpoint catalog locally to discover available endpoints, their paths, parameters, and response shapes. This tool is useful for understanding the capabilities of `tweet_read` and `tweet_action` before invoking them.

```APIDOC
## tweet_explore

### Description
Searches the bundled Xquik endpoint catalog locally (no network call). Use this before calling `tweet_read` or `tweet_action` to discover available endpoints, their paths, parameters, and response shapes.

### Method
GET

### Endpoint
`/api/v1/tools/tweet_explore`

### Parameters
#### Query Parameters
- **query** (string) - Optional - Keyword search across paths, summaries, parameters, response shapes
- **category** (string) - Optional - Filter by endpoint category
- **method** (enum) - Optional - HTTP method filter: GET, POST, PATCH, PUT, DELETE
- **path** (string) - Optional - Exact or partial `/api/v1/...` path filter
- **free** (boolean) - Optional - Filter to free or paid endpoints
- **mpp** (boolean) - Optional - Filter to MPP-eligible endpoints
- **include_actions** (boolean) - Optional - Default: `false` - Include write-like and private endpoints
- **limit** (integer) - Optional - Default: `25` - Max results returned (1–100)

### Request Example
```json
{
  "query": "tweet search",
  "method": "GET",
  "limit": 10
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the search was successful.
- **endpoints** (array) - A list of discovered endpoints matching the criteria.
  - **category** (string) - The category of the endpoint.
  - **method** (string) - The HTTP method of the endpoint.
  - **path** (string) - The API path for the endpoint.
  - **summary** (string) - A brief summary of the endpoint's function.
  - **free** (boolean) - Indicates if the endpoint is free to use.
  - **action** (boolean) - Indicates if the endpoint is an action (write) endpoint.
  - **responseShape** (string) - Describes the shape of the response.

#### Response Example
```json
{
  "success": true,
  "endpoints": [
    {
      "category": "x",
      "method": "GET",
      "path": "/api/v1/x/tweets/search",
      "summary": "Search tweets",
      "free": true,
      "action": false,
      "responseShape": "Tweet list"
    }
  ]
}
```
```

--------------------------------

### Hermes Smoke Test Commands

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Bash commands for verifying the Hermes plugin's functionality, including loading, exploring, reading, and checking registered tools and commands.

```bash
# Verify plugin loads, explore works without API key, read works with key
hermes -z "Use tweet_explore, then read /api/v1/account. Do not call tweet_action."
  --toolsets hermes-tweet

# Check registered tools
hermes tools list

# Verify slash commands in an interactive session or gateway (not -z)
# /xstatus
# /xtrends technology
```

--------------------------------

### Runtime Smoke Test with Hermes

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/README.md

Execute a smoke test using the hermes CLI to verify tool discovery and read-only endpoint access. This command ensures that tweet_explore works and that /api/v1/account can be read without enabling actions.

```bash
hermes -z "Use tweet_explore, then read /api/v1/account. Do not call tweet_action." --toolsets hermes-tweet
```

--------------------------------

### Enable and Use Write-Like Endpoints with tweet_action

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Use `tweet_action` for catalog-listed action endpoints (writes, private reads). This requires `HERMES_TWEET_ENABLE_ACTIONS=true`. Always show the endpoint and payload to the user before calling.

```bash
# Enable actions first
export HERMES_TWEET_ENABLE_ACTIONS=true
```

```json
// Post a tweet
{
  "path": "/api/v1/x/tweets",
  "method": "POST",
  "body": {
    "account": "@myaccount",
    "text": "Hello from Hermes Tweet! #automation"
  },
  "reason": "Post the user-approved tweet."
}
```

```json
// Reply to a tweet
{
  "path": "/api/v1/x/tweets",
  "method": "POST",
  "body": {
    "account": "@myaccount",
    "text": "Great point! 👍",
    "reply_to": "1234567890123456789"
  },
  "reason": "Post reply as approved by user."
}
```

```json
// Follow a user
{
  "path": "/api/v1/x/follows",
  "method": "POST",
  "body": { "account": "@myaccount", "target": "@targetuser" },
  "reason": "Follow the user as requested."
}
```

```json
// Send a DM
{
  "path": "/api/v1/x/dms",
  "method": "POST",
  "body": {
    "account": "@myaccount",
    "recipient": "@recipient",
    "text": "Hi! Thanks for connecting."
  },
  "reason": "Send welcome DM to new follower."
}
```

```json
// Run a giveaway draw
{
  "path": "/api/v1/draws",
  "method": "POST",
  "body": {
    "tweet_url": "https://x.com/user/status/1234567890",
    "winner_count": 3,
    "require_retweet": true,
    "require_follow": true
  },
  "reason": "Run giveaway draw for contest tweet."
}
```

```json
// Start an extraction job
{
  "path": "/api/v1/extractions",
  "method": "POST",
  "body": {
    "tool_type": "tweet_likers",
    "target": "1234567890123456789"
  },
  "reason": "Extract likers list for analytics."
}
```

```json
// Save a tweet draft
{
  "path": "/api/v1/drafts",
  "method": "POST",
  "body": {
    "text": "Draft tweet text for review later.",
    "topic": "product launch"
  },
  "reason": "Save draft for later review."
}
```

```json
// Compose and score a tweet
{
  "path": "/api/v1/compose",
  "method": "POST",
  "body": {
    "workflow": "score",
    "text": "Excited to announce our new feature!",
    "goal": "engagement"
  },
  "reason": "Score draft tweet quality."
}
```

--------------------------------

### call_read(args)

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Calls a read-only endpoint on the Xquik API. Used for retrieving data such as account information or search results.

```APIDOC
## call_read(args)

### Description
Calls a read-only endpoint on the Xquik API. Used for retrieving data such as account information or search results.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **path** (string) - Required - The API endpoint path (e.g., "/api/v1/account").
- **query** (object) - Optional - Query parameters for the request (e.g., `{"q": "hermes agent", "limit": 10}`).

### Request Example
```python
# Get account info
result = call_read({"path": "/api/v1/account"})

# Search tweets
result = call_read({
    "path": "/api/v1/x/tweets/search",
    "query": {"q": "hermes agent", "limit": 10}
})
```

### Response
#### Success Response (200)
- **(type)** - JSON string of account data or search results, or an error object.

#### Response Example
```json
{
  "account_data": { ... }
}
```

```json
{
  "error": "..."
}
```
```

--------------------------------

### Set Xquik API Key for Current Session

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/after-install.md

Set the XQUIK_API_KEY environment variable for the current terminal session before using read tools. This is required for authenticated access to Xquik services.

```bash
export XQUIK_API_KEY="xq_..."
```

--------------------------------

### Explore Catalog Search

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Searches the catalog for DM-related endpoints, optionally including action endpoints or filtering by specific criteria like free or MPP read endpoints.

```python
from hermes_tweet.tools import explore

# Search for DM-related endpoints including action endpoints
result = explore({"query": "dm", "include_actions": True, "limit": 5})
# Returns JSON string: '{"success":true,"endpoints":[...]}"'

# Filter to free MPP read endpoints
result = explore({"free": True, "mpp": True, "method": "GET"})
```

--------------------------------

### Initiate Tweet Posting

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/hermes_tweet/skills/hermes-tweet/SKILL.md

Use this JSON to indicate the intent to post a tweet. This is a precursor to calling `tweet_action` with the actual tweet content.

```json
{"query":"post tweet","include_actions":true}
```

--------------------------------

### Post a Tweet with `tweet_action`

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/hermes_tweet/skills/hermes-tweet/SKILL.md

Execute a tweet post action. Requires the account, text content, and a reason for the action. Ensure actions are enabled via `HERMES_TWEET_ENABLE_ACTIONS=true`.

```json
{"path":"/api/v1/x/tweets","method":"POST","body":{"account":"@example","text":"Hello from Hermes Tweet"},"reason":"Post the user-approved tweet."}
```

--------------------------------

### Call Action Endpoint

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Calls an action endpoint in the catalog, used for performing operations like posting tweets. Requires API key and action enablement environment variables.

```python
import os
os.environ["XQUIK_API_KEY"] = "xq_..."
os.environ["HERMES_TWEET_ENABLE_ACTIONS"] = "true"

from hermes_tweet.tools import call_action

result = call_action({
    "method": "POST",
    "path": "/api/v1/x/tweets",
    "body": {"account": "@myaccount", "text": "Posted via Hermes Tweet API"},
    "reason": "Test post"
})
# Returns JSON string: '{"id":"...","text":"...",...}' or error
```

--------------------------------

### Explore Endpoints by Category

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Filter the endpoint catalog by category to find specific types of functionalities, such as 'draws'.

```json
// Filter by category
{
  "category": "draws",
  "limit": 25
}
```

--------------------------------

### Enable Hermes Tweet Plugin

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/skills/hermes-tweet/SKILL.md

Enable the hermes-tweet plugin within the Hermes Agent environment. This is a prerequisite for using the toolset.

```bash
hermes plugins enable hermes-tweet
```

--------------------------------

### /xstatus

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Shows account and usage status by internally calling `tweet_read` with `path: "/api/v1/account"`.

```APIDOC
## /xstatus

### Description
Shows account and usage status, including account info, plan, credits used/remaining, and subscription status.

### Method
GET (internally)

### Endpoint
`/xstatus` (Slash command)

### Parameters
This command accepts no arguments.

### Request Example
```bash
/xstatus
```

### Response
#### Success Response (200)
- **Output**: Account info, plan, credits used/remaining, subscription status.

#### Response Example
```
Account: pro
Credits Used: 142 / 5000
Subscription: Active
```

### Note
Internally calls `tweet_read` with `path: "/api/v1/account"`.
```

--------------------------------

### Post a Tweet with Hermes Tweet

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/skills/hermes-tweet/SKILL.md

Initiate a tweet post request using `tweet_explore` with `include_actions: true`. Then, call `tweet_action` with the full payload, including the account, text, and a reason for the action. Actions require `HERMES_TWEET_ENABLE_ACTIONS=true`.

```json
{"query":"post tweet","include_actions":true}
```

```json
{"path":"/api/v1/x/tweets","method":"POST","body":{"account":"@example","text":"Hello from Hermes Tweet"},"reason":"Post the user-approved tweet."}
```

--------------------------------

### Call Read Endpoint

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Calls a read endpoint in the catalog, used for retrieving data such as account information or searching for tweets.

```python
from hermes_tweet.tools import call_read

# Get account info
result = call_read({"path": "/api/v1/account"})
# Returns JSON string of account data or error

# Search tweets
result = call_read({
    "path": "/api/v1/x/tweets/search",
    "query": {"q": "hermes agent", "limit": 10}
})
```

--------------------------------

### Find Endpoint in Catalog

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Looks up an endpoint in the catalog by HTTP method and path. Provides details about the endpoint such as its category, summary, and whether it's an action or free endpoint.

```python
from hermes_tweet.catalog import find_endpoint

ep = find_endpoint("GET", "/api/v1/x/tweets/search")
if ep:
    print(ep.category)       # "x"
    print(ep.summary)        # "Search tweets"
    print(ep.action)         # False
    print(ep.free)           # True
    print(ep.mpp)            # {"credits": "2", ...} or None
    print(ep.response_shape) # "Tweet list"

# Parameterized paths resolve correctly
ep = find_endpoint("GET", "/api/v1/extractions/550e8400-e29b-41d4-a716-446655440000")
# Matches template: /api/v1/extractions/{id}
```

--------------------------------

### find_endpoint(method, path)

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Looks up an endpoint in the catalog based on its HTTP method and path. Provides details about the endpoint's category, summary, action status, MPP details, and response shape.

```APIDOC
## find_endpoint(method, path)

### Description
Looks up an endpoint in the catalog based on its HTTP method and path. Provides details about the endpoint's category, summary, action status, MPP details, and response shape.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Arguments
- **method** (string) - Required - The HTTP method of the endpoint (e.g., "GET").
- **path** (string) - Required - The path of the endpoint (e.g., "/api/v1/x/tweets/search").

### Request Example
```python
from hermes_tweet.catalog import find_endpoint

ep = find_endpoint("GET", "/api/v1/x/tweets/search")
if ep:
    print(ep.category)       # "x"
    print(ep.summary)        # "Search tweets"
    print(ep.action)         # False
    print(ep.free)           # True
    print(ep.mpp)            # {"credits": "2", ...} or None
    print(ep.response_shape) # "Tweet list"

# Parameterized paths resolve correctly
ep = find_endpoint("GET", "/api/v1/extractions/550e8400-e29b-41d4-a716-446655440000")
# Matches template: /api/v1/extractions/{id}
```

### Response
#### Success Response (200)
- **ep** (object) - An endpoint object with attributes like `category`, `summary`, `action`, `free`, `mpp`, and `response_shape`, or `None` if not found.

#### Response Example
```python
# Example of an endpoint object
# ep.category = "x"
# ep.summary = "Search tweets"
# ep.action = False
# ep.free = True
# ep.mpp = {"credits": "2", ...}
# ep.response_shape = "Tweet list"
```
```

--------------------------------

### Call Read-Only Xquik Endpoints with tweet_read

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Use `tweet_read` to invoke catalog-listed read-only endpoints. Requires `XQUIK_API_KEY`. Rejects endpoints marked as `action: true`.

```json
// Read account info
{
  "path": "/api/v1/account"
}
```

```json
// Search tweets with query parameters
{
  "path": "/api/v1/x/tweets/search",
  "query": {
    "q": "AI agents",
    "limit": 25
  }
}
```

```json
// Look up a user profile
{
  "path": "/api/v1/x/users/elonmusk"
}
```

```json
// Get X trends
{
  "path": "/api/v1/x/trends",
  "query": { "category": "technology" }
}
```

```json
// List extraction jobs filtered by status
{
  "path": "/api/v1/extractions",
  "query": { "status": "completed" }
}
```

```json
// Get a specific extraction result
{
  "path": "/api/v1/extractions/550e8400-e29b-41d4-a716-446655440000",
  "query": { "limit": 100 }
}
```

```json
// List tweet drafts
{
  "path": "/api/v1/drafts"
}
```

```json
// Check credits balance
{
  "path": "/api/v1/credits"
}
```

--------------------------------

### Show Current X Trends with /xtrends

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

The `/xtrends` slash command shows current X trends. It can display all trends or filter them by category. Internally, it calls `tweet_read` with `path: "/api/v1/x/trends"` and an optional `category` query parameter.

```bash
# All trends
/xtrends
```

```bash
# Filter by category
/xtrends technology
```

--------------------------------

### Explore Tweet Endpoint

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/hermes_tweet/skills/hermes-tweet/SKILL.md

Use this JSON to discover available X/Twitter API endpoints. It helps in finding the correct path and query parameters for subsequent operations.

```json
{"query":"tweet search","method":"GET"}
```

--------------------------------

### tweet_read

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Invokes a single catalog-listed read-only endpoint against the Xquik API. Requires `XQUIK_API_KEY`. Rejects any endpoint marked as `action: true`.

```APIDOC
## tweet_read

### Description
Invokes a single catalog-listed read-only endpoint against the Xquik API. Requires `XQUIK_API_KEY`. Rejects any endpoint marked as `action: true`.

### Method
POST (implicitly, as it's a tool invocation)

### Endpoint
`/tweet_read` (Tool invocation endpoint)

### Parameters
#### Request Body
- **path** (string) - Required - Concrete `/api/v1/...` endpoint path
- **query** (object) - Optional - Query parameters (string, number, or boolean values)

### Request Example
```json
{
  "path": "/api/v1/account"
}
```

### Response
#### Success Response (200)
- **Response body**: Varies based on the invoked Xquik endpoint. Example: `{"plan": "pro", "credits_used": 142, "credits_total": 5000, ...}`

#### Response Example
```json
{
  "plan": "pro",
  "credits_used": 142,
  "credits_total": 5000
}
```

### Error Handling Examples
```json
// Missing API key
{
  "success": false,
  "error": "XQUIK_API_KEY is not configured."
}

// Endpoint not in catalog
{
  "success": false,
  "error": "Endpoint is not in the Hermes Tweet catalog: GET /api/v1/unknown"
}

// Attempted to call an action endpoint via tweet_read
{
  "success": false,
  "error": "Use tweet_action for private or write-like endpoints."
}

// API error
{
  "success": false,
  "error": "API request failed.",
  "status_code": 429,
  "response": {...}
}
```
```

--------------------------------

### List Hermes Tools

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/docs/OBSERVABILITY.md

Use `hermes tools list` to check if the hermes-tweet toolset is available in non-interactive terminals. Bare `hermes tools` opens an interactive UI.

```bash
hermes tools list
```

--------------------------------

### Search Tweets with Parameters

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/hermes_tweet/skills/hermes-tweet/SKILL.md

Call this after `tweet_explore` to perform a tweet search. Specify the query and limit for the search results.

```json
{"path":"/api/v1/x/tweets/search","query":{"q":"AI agents","limit":25}}
```

--------------------------------

### Explore Tweet Search Endpoints

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Use the tweet_explore tool to search the local endpoint catalog for tweet search functionalities. Filter by query, method, and limit.

```json
// Search for tweet search endpoints
{
  "query": "tweet search",
  "method": "GET",
  "limit": 10
}
```

--------------------------------

### /xtrends

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Shows current X trends, optionally filtered by category, by internally calling `tweet_read`.

```APIDOC
## /xtrends

### Description
Shows current X trends. Can display all trends or filter by a specific category.

### Method
GET (internally)

### Endpoint
`/xtrends` (Slash command)

### Parameters
#### Path Parameters
- **category** (string) - Optional - Filters trends by the specified category (e.g., 'technology').

### Request Example
```bash
# Show all trends
/xtrends

# Show technology trends
/xtrends technology
```

### Response
#### Success Response (200)
- **Response body**: A list of current X trends, potentially filtered by category.

#### Response Example
```json
[
  {"name": "#AI", "volume": 15000},
  {"name": "#MachineLearning", "volume": 12000}
]
```

### Note
Internally calls `tweet_read` with `path: "/api/v1/x/trends"` and an optional `category` query parameter.
```

--------------------------------

### tweet_action

Source: https://context7.com/xquik-dev/hermes-tweet/llms.txt

Invokes catalog-listed action endpoints (writes, private reads). Disabled unless `HERMES_TWEET_ENABLE_ACTIONS=true`. Always show the endpoint and payload to the user before calling.

```APIDOC
## tweet_action

### Description
Invokes catalog-listed action endpoints (writes, private reads). Disabled unless `HERMES_TWEET_ENABLE_ACTIONS=true`. Always show the endpoint and payload to the user before calling.

### Method
POST (implicitly, as it's a tool invocation)

### Endpoint
`/tweet_action` (Tool invocation endpoint)

### Parameters
#### Request Body
- **path** (string) - Required - Concrete `/api/v1/...` endpoint path
- **method** (enum) - Required - HTTP method: GET, POST, PATCH, PUT, DELETE
- **reason** (string) - Required - Brief user-visible reason for the action
- **query** (object) - Optional - Query parameters (string, number, or boolean values)
- **body** (any) - Optional - JSON request body

### Request Example
```json
{
  "path": "/api/v1/x/tweets",
  "method": "POST",
  "body": {
    "account": "@myaccount",
    "text": "Hello from Hermes Tweet! #automation"
  },
  "reason": "Post the user-approved tweet."
}
```

### Response
#### Success Response (200)
- **Response body**: Varies based on the invoked Xquik endpoint. Typically a success confirmation or the result of the action.

#### Response Example
```json
{
  "success": true,
  "message": "Tweet posted successfully."
}
```

### Usage Note
Enable actions first by setting the environment variable: `export HERMES_TWEET_ENABLE_ACTIONS=true`
```

--------------------------------

### Disable Account-Changing Actions

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/after-install.md

Set the HERMES_TWEET_ENABLE_ACTIONS environment variable to false to disable account-changing operations. Keep actions disabled unless intentionally allowing them.

```bash
export HERMES_TWEET_ENABLE_ACTIONS=false
```

--------------------------------

### Search Tweets with Hermes Tweet

Source: https://github.com/xquik-dev/hermes-tweet/blob/master/skills/hermes-tweet/SKILL.md

Use this JSON payload with `tweet_explore` to discover the tweet search endpoint. Ensure `XQUIK_API_KEY` is configured for read operations.

```json
{"query":"tweet search","method":"GET"}
```

```json
{"path":"/api/v1/x/tweets/search","query":{"q":"AI agents","limit":25}}
```
Tokens:
Raw