Postagent

Postagent

Overview

Use Postagent as an agent-friendly API client. The normal flow is: search for the action you want, inspect the manual for the target site/group/action, authenticate the site if needed, then send the request with curl-style flags.

Installation

npm install -g postagent

Quick Start

Start with natural language search:

postagent search "create a document on notion"
postagent search "create github issue"

Drill into the manual progressively:

postagent manual notion
postagent manual notion pages
postagent manual notion pages create_page
postagent manual notion pages create_page --format json

Authenticate the site before sending requests that need credentials:

postagent auth notion

Send the request with curl-style options:

postagent send -X POST https://api.notion.com/v1/pages \
  -H 'Authorization: Bearer $POSTAGENT.NOTION.API_KEY' \
  -H 'Notion-Version: 2022-06-28' \
  -H 'Content-Type: application/json' \
  -d '{"parent":{"page_id":"YOUR_PAGE_ID"},"properties":{"title":[{"text":{"content":"My Page"}}]}}'

Core Commands

Use postagent search <query> to map a user goal to likely site/group/action combinations. Prefer this when you know the intent but not the exact API shape.

Use postagent manual <site> [group] [action] to browse progressively:

• Site only: list groups and top actions.
• Site + group: list actions in that group.
• Site + group + action: get full endpoint details, parameters, request body, and response info.

Use --format json on search or manual when another tool or agent needs structured output instead of markdown text.

Use postagent auth <site> to save a credential locally for one site. Postagent will prompt for the secret without echoing it in a normal TTY.

Use postagent send <url> [curl-like options] to execute the real HTTP request. It accepts -X/--method, repeated -H/--header, and -d/--data.

Recommended Workflow

Search first unless you already know the exact site, group, and action.

Read the manual before sending a request so you can confirm the method, path, auth header, version header, and request schema.

Authenticate only the site you need. Saved credentials are referenced later with placeholders instead of being pasted into commands.

Use placeholder substitution in the URL, headers, or body:

$POSTAGENT.<SITE>.API_KEY

Example:

-H "Authorization: Bearer $POSTAGENT.GITHUB.API_KEY"

Prefer placeholders over raw secrets so credentials stay in local storage rather than the model context.

Send Behavior

If -X/--method is omitted and -d/--data is present, Postagent sends POST.

If both method and body are omitted, Postagent sends GET.

Headers can be provided as repeated Key: Value strings or as a JSON object string.

Postagent prints the raw response body on success. On HTTP error responses it prints the status and body, then exits non-zero.

Practical Examples

Create a Notion page:

postagent search "create a notion page"
postagent manual notion pages create_page
postagent auth notion
postagent send -X POST https://api.notion.com/v1/pages \
  -H 'Authorization: Bearer $POSTAGENT.NOTION.API_KEY' \
  -H 'Notion-Version: 2022-06-28' \
  -H 'Content-Type: application/json' \
  -d '{"parent":{"page_id":"YOUR_PAGE_ID"},"properties":{"title":[{"text":{"content":"My Page"}}]}}'

Inspect GitHub issue creation before making the call:

postagent search "create github issue"
postagent manual github issues create