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)
• INLINECODE1: Your AIOZ Pin secret key (provided by the platform)
• INLINECODE2: 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:

CODEBLOCK0

Header mapping used by scripts (credentials read from env vars internally):

• - PINNING_API_KEY → pinning-api-key header
• INLINECODE11 → pinning-secret-key header
• INLINECODE13 → 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:

CODEBLOCK1

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: INLINECODE17
• Pin by CID hash: INLINECODE18
• Get pin details: INLINECODE19
• List pins: INLINECODE20
• Unpin file: INLINECODE21

API Key Management (JWT)

• - Generate new API key: INLINECODE22
• List all API keys: INLINECODE23
• Delete API key: INLINECODE24

Usage & Billing

• - Get history usage data: INLINECODE25
• Get top-up data: INLINECODE26
• Get monthly usage data: INLINECODE27

1. Pin Files to IPFS

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

CODEBLOCK2

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:

CODEBLOCK3

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

3. API Key Management (JWT Flow)

Use these scripts to manage AIOZ Pin API keys:

CODEBLOCK4

Actual behavior in scripts:

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

4. Pin Details & Management

To inspect, list, and manage pins:

• - Get Pin Details: INLINECODE37

• - List Pins: INLINECODE39

• - Unpin File: INLINECODE46

5. Usage & Billing Data

To retrieve usage and top-up data:

• - History Usage: INLINECODE48

• - Top-up Data: INLINECODE50

• - Monthly Usage: INLINECODE52

Pagination notes:

• - OFFSET default is INLINECODE55
• INLINECODE56 default is INLINECODE57

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:

CODEBLOCK5

Operational steps:

1. 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

CODEBLOCK6

Response: extract pinId and cid from the response.

Step 2: Check Pin Details

After pinning, verify the pin status:

CODEBLOCK7

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

Step 3: List All Pins

To see all pinned content:

CODEBLOCK8

Response: paginated list of all pins with metadata.

Step 4: Unpin Content

When done, remove the pin:

CODEBLOCK9

Confirms deletion.

Manual cURL Reference

(For reference only; prefer using provided scripts)

Prerequisites: These examples assume environment variables are set:

CODEBLOCK10

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

Pin File by URL

CODEBLOCK11

Generate API Key (JWT)

CODEBLOCK12

List Pins

CODEBLOCK13

Response Handling

1. 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, INLINECODE65
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. 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="..."
   

1. 3. 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)