aioz-pin-toolkit（aioz 引脚工具包）

AIOZ Pin Operations

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:

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:

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]

1. Pin Files to IPFS

Use this script to pin a file by URL to IPFS:

./scripts/pin_files_or_directory.sh "https://example.com/file.zip"

Actual behavior in script:

• Accepts public downloadable URL.
• Downloads file and pins to IPFS via AIOZ Pin service.
• Returns pin ID and CID hash.

2. Pin by CID Hash

To pin existing content by its IPFS CID:

./scripts/pin_by_cid.sh "QmHash..." "optional-name"

• CID_HASH: The IPFS content hash to pin
• METADATA_NAME: Optional name for the pinned content

3. API Key Management (JWT Flow)

Use these scripts to manage AIOZ Pin API keys:

# Generate API key with permissions:
./scripts/generate_api_key.sh "my-key" false true false false true true false false

# List API keys:
./scripts/get_list_api_keys.sh

# Delete API key:
./scripts/delete_api_key.sh "KEY_ID"

Actual behavior in scripts:

• generate_api_key.sh calls POST /api/apikeys/create with permission flags.
• Default permission values are false if not provided.
• get_list_api_keys.sh calls GET /api/apikeys and returns list of keys.
• delete_api_key.sh calls DELETE /api/apikeys/{keyId} and removes the key.

4. Pin Details & Management

To inspect, list, and manage pins:

• Get Pin Details: ./scripts/get_pin_details.sh PIN_ID

- Calls GET /api/pinning/{pinId} - Returns pin status, CID, size, creation date

• List Pins: ./scripts/list_pins.sh [OFFSET] [LIMIT] [PINNED] [SORT_BY] [SORT_ORDER]

- Calls GET /api/pinning/pins?offset=...&limit=... - Defaults: OFFSET=0, LIMIT=10, PINNED=true, SORT_BY=name, SORT_ORDER=ASC

• Unpin File: ./scripts/unpin_file.sh PIN_ID

- Calls DELETE /api/pinning/unpin/{pinId} - Removes pin from AIOZ Pin service

5. Usage & Billing Data

To retrieve usage and top-up data:

• History Usage: ./scripts/get_history_usage_data.sh [OFFSET] [LIMIT]

- Calls GET /api/usage/history?offset=...&limit=... - Returns detailed usage history with timestamps

• Top-up Data: ./scripts/get_top_up.sh [OFFSET] [LIMIT]

- Calls GET /api/usage/topup?offset=...&limit=... - Returns top-up transaction history

• Monthly Usage: ./scripts/get_month_usage_data.sh [OFFSET] [LIMIT]

- Calls GET /api/usage/month?offset=...&limit=... - Returns this month's usage statistics

Pagination notes:

• OFFSET default is 0
• LIMIT default is 10

Full Pinning Flow (Common Operational Path)

For a typical pin lifecycle, use this sequence:

Setup: Ensure credentials are in the environment before executing any scripts:

export PINNING_API_KEY="YOUR_KEY"
export PINNING_SECRET_KEY="YOUR_SECRET"

Operational steps:

1. Pin a file or CID
2. Get pin details to verify status
3. List pins to check all pinned content
4. Unpin when no longer needed

Step 1: Pin File by URL

./scripts/pin_files_or_directory.sh "https://example.com/file.zip"

Response: extract pinId and cid from the response.

Step 2: Check Pin Details

After pinning, verify the pin status:

./scripts/get_pin_details.sh "PIN_ID"

Response includes: status (active/pending), CID, file size, created date.

Step 3: List All Pins

To see all pinned content:

./scripts/list_pins.sh 0 10 true name ASC

Response: paginated list of all pins with metadata.

Step 4: Unpin Content

When done, remove the pin:

./scripts/unpin_file.sh "PIN_ID"

Confirms deletion.

Manual cURL Reference

_(For reference only; prefer using provided scripts)_

Prerequisites: These examples assume environment variables are set:

export PINNING_API_KEY="YOUR_KEY"
export PINNING_SECRET_KEY="YOUR_SECRET"
export AIOZ_JWT_TOKEN="YOUR_JWT"

All credentials are referenced as $VARIABLE_NAME (shell expansion) — never hardcoded.

Pin File by URL

curl -s -X POST "https://api.aiozpin.network/api/files/pin?fileUrl=https://example.com/file.zip" \
  -H "pinning-api-key: $PINNING_API_KEY" \
  -H "pinning-secret-key: $PINNING_SECRET_KEY" \
  -H "Content-Type: application/json"

Generate API Key (JWT)

curl -s -X POST "https://api.aiozpin.network/api/apikeys/create?keyName=my-key&admin=false&pinList=true&nftList=false&unpin=false&pinByHash=true&pinFileToIPFS=true&unpinNFT=false&pinNFTToIPFS=false" \
  -H "Authorization: Bearer $AIOZ_JWT_TOKEN" \
  -H "Content-Type: application/json"

List Pins

curl -s "https://api.aiozpin.network/api/pinning/pins?offset=0&limit=10&pinned=true&sortBy=name&sortOrder=ASC" \
  -H "pinning-api-key: $PINNING_API_KEY" \
  -H "pinning-secret-key: $PINNING_SECRET_KEY"

Response Handling

1. Run the appropriate script from the scripts/ directory.
2. Pin/Search scripts return raw JSON: pin_files_or_directory, pin_by_cid, get_pin_details, list_pins
3. API Key scripts return structured output with key metadata and permissions
4. Usage/Billing scripts return paginated data with timestamps and amounts
5. 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

1. User: "Pin this file to IPFS"
2. 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:

   export PINNING_API_KEY="..."
   export PINNING_SECRET_KEY="..."

_Do not_ pass these as script arguments.

1. Ask for the file URL
2. Execute: ./scripts/pin_files_or_directory.sh "FILE_URL" (credentials come from environment)
3. Extract the returned pin ID and CID
4. Return the pin information to the user
5. Offer optional follow-up: check details (get_pin_details.sh) or list pins (list_pins.sh)