Respond to user requests for AIOZ Pin API. Use provided scripts to manage API keys, pin files to IPFS, track usage, and more.
---
name: aioz-pin-toolkit
description: Respond to user requests for AIOZ Pin API. Use provided scripts to manage API keys, pin files to IPFS, track usage, and more.
metadata:
openclaw:
emoji: "📌"
requires:
envVars:
- name: PINNING_API_KEY
description: AIOZ Pin API key for pinning and billing operations
required: true
primaryCredential: true
- name: PINNING_SECRET_KEY
description: AIOZ Pin secret key for pinning and billing operations
required: true
- name: AIOZ_JWT_TOKEN
description: JWT token for API key management operations (generate, list, delete)
required: false
bins:
- curl
- jq
---
# 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:
```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]`
### 1. Pin Files to IPFS
Use this script to pin a file by URL to IPFS:
```bash
./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:
```bash
./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:
```bash
# 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:
```bash
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
```bash
./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:
```bash
./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:
```bash
./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:
```bash
./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:
```bash
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
```bash
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)
```bash
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
```bash
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:
```bash
export PINNING_API_KEY="..."
export PINNING_SECRET_KEY="..."
```
_Do not_ pass these as script arguments.
3. Ask for the file URL
4. Execute: `./scripts/pin_files_or_directory.sh "FILE_URL"` (credentials come from environment)
5. Extract the returned pin ID and CID
6. Return the pin information to the user
7. Offer optional follow-up: check details (`get_pin_details.sh`) or list pins (`list_pins.sh`)
don't have the plugin yet? install it then click "run inline in claude" again.
restructured into six explicit implexa components, separated credential setup from procedure steps, formalized decision tree for auth failures and pin status checks, added output contract with json field specs and error formats, clarified outcome signals with concrete success markers and credential exposure detection.
---
name: aioz-pin-toolkit
description: Respond to user requests for AIOZ Pin API. Use provided scripts to manage API keys, pin files to IPFS, track usage, and more.
---
## intent
use this skill when a user asks to pin files to IPFS, manage pinning API keys, retrieve pin details, unpin content, or check usage and billing data. the skill provides a suite of bash scripts that wrap AIOZ Pin REST APIs, handling authentication via environment variables and abstracting away direct curl commands. deploy it for any IPFS pinning workflow, API key lifecycle management, or account usage queries.
## inputs
**environment variables (required):**
- `PINNING_API_KEY`: AIOZ Pin API key for pinning and billing operations. set via `export PINNING_API_KEY="your_key"` before running scripts.
- `PINNING_SECRET_KEY`: AIOZ Pin secret key for pinning and billing operations. set via `export PINNING_SECRET_KEY="your_secret"` before running scripts.
- `AIOZ_JWT_TOKEN`: JWT token for API key management operations (generate, list, delete). optional; required only if user needs to create or delete API keys. set via `export AIOZ_JWT_TOKEN="your_jwt"`.
**external dependencies:**
- AIOZ Pin API endpoint: `https://api.aiozpin.network/api/`
- bash runtime and standard tools: `curl`, `jq` (for JSON parsing)
- internet connectivity to reach the AIOZ Pin service
**script location:**
- all operational scripts are in the `scripts/` directory relative to the working directory.
**user inputs (context-dependent):**
- file URL (for pinning by URL)
- IPFS CID hash (for pinning by existing content hash)
- pin ID (for retrieving details, unpinning)
- API key name and permission flags (for generating keys)
- offset and limit values (for pagination in usage/billing queries)
## procedure
**prerequisite: set credentials in environment**
before running any script, ensure credentials are exported to the shell session. never pass credentials as CLI arguments.
```bash
export PINNING_API_KEY="your_key"
export PINNING_SECRET_KEY="your_secret"
export AIOZ_JWT_TOKEN="your_jwt" # only if managing API keys
ask the user for credentials if they are not already set in their session. verify credentials via echo $PINNING_API_KEY (should return non-empty string).
1. pin file by URL
input: file URL (must be publicly accessible)
command: ./scripts/pin_files_or_directory.sh "https://example.com/file.zip"
output: JSON response containing pinId, cid, size, created timestamp
2. pin content by IPFS CID
input: IPFS CID hash, optional metadata name
command: ./scripts/pin_by_cid.sh "QmHash123..." "optional-name"
output: JSON response with pin confirmation, CID, status
3. get pin details
input: pin ID (obtained from pinning operation or list)
command: ./scripts/get_pin_details.sh "PIN_ID_HERE"
output: JSON response with pin status (active/pending/failed), CID, size, creation date, last accessed
4. list all pins
input: optional pagination (offset, limit, pinned status, sort field, sort order)
command: ./scripts/list_pins.sh 0 10 true name ASC
output: JSON array of pin objects, total count, pagination metadata
default values: offset=0, limit=10, pinned=true, sortBy=name, sortOrder=ASC
5. unpin file
input: pin ID to remove
command: ./scripts/unpin_file.sh "PIN_ID_HERE"
output: JSON confirmation with deleted pin ID
6. generate API key
input: key name, optional permission flags (admin, pinList, nftList, unpin, pinByHash, pinFileToIPFS, unpinNFT, pinNFTToIPFS)
command: ./scripts/generate_api_key.sh "my-key" false true false false true true false false
output: JSON response with new API key ID, secret key, permissions, created timestamp
permission flags default to false if not provided.
7. list all API keys
input: none (uses AIOZ_JWT_TOKEN from environment)
command: ./scripts/get_list_api_keys.sh
output: JSON array of API key objects with ID, name, permissions, created date
8. delete API key
input: key ID to revoke
command: ./scripts/delete_api_key.sh "KEY_ID_HERE"
output: JSON confirmation with deleted key ID
9. get usage history
input: optional pagination (offset, limit)
command: ./scripts/get_history_usage_data.sh 0 10
output: JSON array of usage records with timestamps, data used (bytes), cost
10. get top-up history
input: optional pagination (offset, limit)
command: ./scripts/get_top_up.sh 0 10
output: JSON array of top-up transactions with amount, timestamp, balance change
11. get monthly usage
input: optional pagination (offset, limit)
command: ./scripts/get_month_usage_data.sh 0 10
output: JSON with this month's total data pinned, requests, cost
if user needs to pin a file:
if user checks pin status:
if user manages API keys:
if user checks credentials:
if API returns 401 Unauthorized:
echo $PINNING_API_KEYif API returns 404 Not Found:
if API returns 500 Server Error or connection timeout:
if pagination is needed:
pin operations:
pinId (string), cid (string), size (number, bytes), status (string: "active", "pending", "failed"), created (ISO 8601 timestamp)API key operations:
keyId, secret, keyName, permissions (object with boolean flags), created (ISO 8601 timestamp)keyIdusage/billing operations:
data (array of records), total (number), offset (number), limit (number)timestamp (ISO 8601), amount (number), type (string: "pin", "storage", "topup")list pins response:
pins (array), total (number), offset, limitpinId, cid, size, status, created, metadataerror response format:
error (string), message (string), statusCode (number)all responses are returned as raw JSON unless post-processing is explicitly requested.
user knows the skill worked when:
pin created: user receives a pin ID and CID from the pin_files_or_directory or pin_by_cid script. pin status is "active" or "pending" (not "failed").
pin details verified: user executes get_pin_details and receives status "active" along with size and creation date, confirming the pin exists and is queryable.
pins listed: user runs list_pins and receives a non-empty array with at least one pin object, showing all pinned content in their account.
pin removed: user runs unpin_file and receives confirmation message with the deleted pin ID. subsequent list_pins calls do not include that pin.
API key created: user gets generate_api_key response with a new keyId and secret. user can then use that key for future pinning operations (by setting PINNING_API_KEY to the new secret).
API key listed: user runs get_list_api_keys and receives an array of key objects. count matches expected number of keys.
API key deleted: user runs delete_api_key and receives confirmation. subsequent get_list_api_keys does not include that key ID.
usage data retrieved: user runs get_history_usage_data (or similar) and receives records with timestamps and amounts. data aligns with pinning activity.
credentials validated: user runs a script without 401 error, indicating environment variables are correctly set.
no credential exposure in logs: user checks shell history and process listings (via ps or env dump) and sees no raw API keys or secrets in command output.
explicit success markers: pin ID returned, HTTP 200 response, JSON output with expected fields, zero 401/403 errors, confirmation messages with resource IDs.
credits: original skill by clawhub. rewritten to Implexa standards. ```