Airtop Agents Skill

You can list, run, monitor, and cancel Airtop agents using their REST API.

Authentication

The Airtop API key is required for all operations. Resolve it in this order:

$AIRTOP_API_KEY environment variable
A .env file in this skill's directory containing AIRTOP_API_KEY=...
If neither is found, ask the user to provide their API key (available at https://portal.airtop.ai/api-keys) and offer to save it to the skill's .env file.

Store the resolved key in a shell variable for the session:

API_KEY="${AIRTOP_API_KEY}"

If loading from .env:

API_KEY=$(grep AIRTOP_API_KEY "$(dirname "$SKILL_PATH")/.env" | cut -d= -f2-)

Base URL

All authenticated API endpoints use: https://api.airtop.ai/api

Webhook endpoints (run agent, poll result) use the public path: https://api.airtop.ai/api/hooks/

Argument Parsing

Parse $ARGUMENTS as follows:

list [--name <filter>]              List agents
run <agent-name-or-id> [--vars {}]  Run an agent with optional config variables
status <agentId> <invocationId>     Check invocation status
cancel <agentId> <invocationId>     Cancel a running invocation
history <agentId>                   View recent invocations

If $ARGUMENTS is empty or unrecognized, show the usage summary above and ask the user what they'd like to do.

Commands

1. List Agents

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents?limit=25&sortBy=lastRun&sortOrder=desc&createdByMe=true"

Always include createdByMe=true to show only agents owned by the current user (not the entire organization).

Optional query parameters to append:

&name=<filter> — case-insensitive partial match (use when --name is provided)
&enabled=true — filter to enabled agents only
&published=true — filter to published agents only

Display: Format the response as a markdown table with columns: Name, ID, Enabled, Last Run. Show the pagination.total count in a header line.

Example output:

Found 3 agents:
| Name              | ID                                   | Enabled | Last Run    |
|-------------------|--------------------------------------|---------|-------------|
| Price Tracker     | 550e8400-e29b-41d4-a716-446655440000 | Yes     | 2 hours ago |
| Lead Enricher     | 6ba7b810-9dad-11d1-80b4-00c04fd430c8 | Yes     | Yesterday   |
| Competitor Monitor| 6ba7b811-9dad-11d1-80b4-00c04fd430c8 | No      | Never       |

2. Run Agent

This is a multi-step process:

Step 1 — Resolve agent by name or ID.

If the argument looks like a UUID, use it directly as the agent ID. Otherwise, search by name:

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents?name=$(printf '%s' '<agent-name>' | jq -sRr @uri)&createdByMe=true"

If exactly one agent matches, use it (but still validate it in Step 2).
If multiple agents match, prefer enabled and published agents over disabled or draft-only ones. If there is still ambiguity, display them in a table (with Enabled and Published status columns) and ask the user to pick one.
If no agents match, tell the user no agent was found and suggest running list.

Step 2 — Validate the agent is runnable.

Fetch the full agent details (already available from step 1 if resolved by name, or fetch now):

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>"

Check the following before proceeding:

Disabled agent (enabled is false): Tell the user the agent is disabled and cannot be run. Suggest they enable it in the Airtop portal.
Draft-only agent (hasDraft is true AND publishedVersion is absent): Tell the user the agent has only a draft version and has never been published. It must be published in the Airtop portal before it can be invoked via webhook.
Published agent with draft (hasDraft is true AND publishedVersion is present): The agent is runnable. Note to the user that the agent has unpublished draft changes, and the published version will be used. Use the publishedVersion value for the version parameter.
Published agent (publishedVersion is present, hasDraft is false): The agent is runnable. Use the publishedVersion value for the version parameter.

Step 3 — Check required configVars.

The agent details response includes a versionData.configVarsSchema field. Inspect it for required properties. If the user has not provided values for required configVars via --vars, prompt them for the missing values before invoking.

Display the required and optional parameters with their descriptions and defaults so the user knows what to provide.

Step 4 — Get the agent's webhook.

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>/webhooks?limit=10"

Use the first webhook from the webhooks array. If no webhooks exist, tell the user the agent needs a webhook configured in the Airtop portal (https://portal.airtop.ai).

Step 5 — Invoke the webhook.

curl -s -X POST "https://api.airtop.ai/api/hooks/agents/<agentId>/webhooks/<webhookId>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "configVars": { <user-provided key-value pairs from --vars, or empty object {}> },
    "version": <publishedVersion from agent details>
  }'

Always use the publishedVersion value from the agent details as the version parameter — never hardcode it.

The response contains { "invocationId": "<uuid>" }. Save this for polling.

Step 6 — Poll for the result.

curl -s "https://api.airtop.ai/api/hooks/agents/<agentId>/invocations/<invocationId>/result" \
  -H "Authorization: Bearer $API_KEY"

Polling rules:

Poll every 5 seconds
Print a status update to the user after each poll (e.g., "Status: Running...")
Terminal statuses: Completed, Failed, Cancelled
Timeout after 5 minutes (60 polls). If not complete, tell the user the invocation is still running and provide the invocation ID so they can check later with the status command.

Step 7 — Display the result.

On Completed: Show the output field. If it's JSON, format it nicely. If it's a string, display it directly.
On Failed: Show the error field and the full status.
On Cancelled: Inform the user the invocation was cancelled.

3. Check Status

Poll a specific invocation's result:

curl -s "https://api.airtop.ai/api/hooks/agents/<agentId>/invocations/<invocationId>/result" \
  -H "Authorization: Bearer $API_KEY"

Display the status field. If terminal, also display output or error.

Note: This requires both the agent ID and invocation ID. If the user only provides one, ask for the other.

4. Cancel Invocation

curl -s -X DELETE -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>/invocations/<invocationId>?reason=user_requested"

Confirm to the user that the cancellation was requested.

5. View History

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.airtop.ai/api/v2/agents/<agentId>/invocations?limit=10"

Display results as a table with columns: Invocation ID, Status, Trigger, Started At.

Error Handling

401 Unauthorized: Tell the user their API key is invalid or expired. Direct them to https://portal.airtop.ai/api-keys.
404 Not Found: The agent or invocation doesn't exist. Suggest checking the ID or running list.
429 Rate Limited: Tell the user they've hit the rate limit and should wait before retrying.
No webhook configured: Explain that the agent needs a webhook set up in the Airtop portal before it can be invoked from the CLI.
Multiple name matches: List all matches and ask the user to pick one or use the agent ID directly.
Empty API key: Guide the user to set AIRTOP_API_KEY or provide it interactively.

Important Notes

Always use curl -s (silent mode) to avoid progress bars in output.
Parse all JSON responses with jq or inline JSON parsing in bash.
The webhook invoke and poll endpoints are under /api/hooks/ (public path), NOT /api/v2/.
The list, webhooks, history, and cancel endpoints are under /api/v2/ (authenticated path).
When displaying times, convert ISO timestamps to human-readable relative times (e.g., "2 hours ago").

airtop-agents