Interact with AIOZ Pin API quickly with API key authentication. A suite of integrated bash scripts is provided to automatically call REST APIs for pinning files, managing API keys, and tracking usage.
When to use this skill
User wants to pin files to IPFS or pin by CID hash
User mentions "pin file", "pin to IPFS", "unpin", or "IPFS pinning"
User wants to generate, list, or delete AIOZ Pin API keys
User wants to retrieve pin details or list all pinned content
User wants to check usage data, top-ups, or billing information
User wants to manage AIOZ Pin resources
Authentication
This skill uses API key authentication via environment variables:
PINNING_API_KEY: Your AIOZ Pin API key (provided by the platform)
PINNING_SECRET_KEY: Your AIOZ Pin secret key (provided by the platform)
AIOZ_JWT_TOKEN: Your AIOZ Pin JWT token (for API key management operations)
Credential-safe policy:
Prefer credentials from secure environment injection.
If missing, ask the user for credentials and set them as temporary environment variables.
Never hardcode keys in command examples, logs, or responses.
Avoid inline one-off commands that contain raw secrets.
⚠️ Critical Security Notice:
Never pass credentials as CLI arguments. Credentials passed as positional arguments become visible in ps listings, shell history (.bash_history, .zsh_history), and process environment dumps.
All scripts must read credentials from environment variables only. Do not manually pass PINNING_API_KEY, PINNING_SECRET_KEY, or AIOZ_JWT_TOKEN as script arguments.
If a script prompts for credentials or accepts them as arguments, that is a violation of this policy.
If credentials are not present in the shell session, set them once before running any scripts:
bash
export PINNING_API_KEY="YOUR_PINNING_API_KEY"
export PINNING_SECRET_KEY="YOUR_PINNING_SECRET_KEY"
export AIOZ_JWT_TOKEN="YOUR_JWT_TOKEN" # if needed for API key management
Header mapping used by scripts (credentials read from env vars internally):
PINNING_API_KEY → pinning-api-key header
PINNING_SECRET_KEY → pinning-secret-key header
AIOZ_JWT_TOKEN → Authorization: Bearer header
This keeps credentials out of repeated command history and avoids accidental exposure.
Usage Options (Available Scripts)
When the user asks for a feature, use one of the bash scripts located in the scripts/ directory.
Prerequisite: All scripts read credentials from environment variables. Ensure these are set before executing any script:
bash
export PINNING_API_KEY="YOUR_KEY"
export PINNING_SECRET_KEY="YOUR_SECRET"
export AIOZ_JWT_TOKEN="YOUR_JWT" # for API key management only
Script Routing Map (for Clawbot)
All scripts below assume credentials are available in the environment (set via export). Do not pass credentials as CLI arguments.
Pinning Operations
Pin file by URL: ./scripts/pin_files_or_directory.sh FILE_URL
Pin by CID hash: ./scripts/pin_by_cid.sh CID_HASH [METADATA_NAME]
Get pin details: ./scripts/get_pin_details.sh PIN_ID
List pins: ./scripts/list_pins.sh [OFFSET] [LIMIT] [PINNED] [SORT_BY] [SORT_ORDER]
Unpin file: ./scripts/unpin_file.sh PIN_ID
API Key Management (JWT)
Generate new API key: ./scripts/generate_api_key.sh KEY_NAME [admin] [pinList] [nftList] [unpin] [pinByHash] [pinFileToIPFS] [unpinNFT] [pinNFTToIPFS]
List all API keys: ./scripts/get_list_api_keys.sh
Delete API key: ./scripts/delete_api_key.sh KEY_ID
Usage & Billing
Get history usage data: ./scripts/get_history_usage_data.sh [OFFSET] [LIMIT]
Get top-up data: ./scripts/get_top_up.sh [OFFSET] [LIMIT]
Get monthly usage data: ./scripts/get_month_usage_data.sh [OFFSET] [LIMIT]
Run the appropriate script from the scripts/ directory.
Pin/Search scripts return raw JSON: pin_files_or_directory, pin_by_cid, get_pin_details, list_pins
API Key scripts return structured output with key metadata and permissions
Usage/Billing scripts return paginated data with timestamps and amounts
Extract and return useful fields explicitly: pin IDs, CID hashes, status, URLs, balances. If pin status is pending, inform the user to check again later.
Error Handling
401 Unauthorized: Invalid API keys. Verify that PINNING_API_KEY and PINNING_SECRET_KEY are correctly set in the environment (e.g., echo $PINNING_API_KEY).
Missing Parameters: Scripts validate arguments; pass exactly what they require.
Credential exposure warnings: If you accidentally pass credentials as CLI arguments, immediately revoke those keys from your AIOZ Pin account and generate new ones. Credentials in commands are visible via ps, shell history files, and process environment listings.
404: Resource not found (invalid pin ID or key ID).
500: Server error; suggest retrying.
Connection timeout/refused: API endpoint may be unavailable; retry and verify https://api.aiozpin.network/api/ accessibility.
Example Interaction Flow
User: "Pin this file to IPFS"
Verify environment setup: Confirm that PINNING_API_KEY and PINNING_SECRET_KEY are already set in the shell environment. If missing, ask the user for their credentials and set them via:
bash