AIOZ Pin for Developers: API, SDK, and CLI Explained

AIOZ Pin for developers breaks down into three layers: a REST API with 8 distinct sections, an official Node.js SDK that wraps the most common calls into 14 methods, and a standalone CLI tool for scripting from the terminal. All three authenticate the same way, through a scoped API key you generate from your account. This guide covers how the pieces fit together, so you can pick the right layer for what you're building instead of guessing.

TL;DR:

• AIOZ Pin's API covers 8 sections: Users, ApiKeys, Pinning, Nft, Gateways, Pinning Services API, Billing, Image Optimization
• The Node.js SDK (@aioznetwork/aioz-pin-sdk) wraps common operations into methods like pinFilesToIPFS() and pinNft()
• API keys carry granular scopes, so you can issue a key that can only pin, not delete or manage billing

AIOZ Pin's API Surface, Section by Section

The REST API is organized into 8 sections, each covering a distinct area:

Every request authenticates with Authorization: Bearer <access_token>. If you're building a script that only needs to pin files and never touch billing or user settings, you don't need the full picture, just the Pinning and ApiKeys sections.

Scoped API Keys, Not One Master Secret

Generating a key is a POST to /apiKeys with a scopes object, and the scopes are genuinely granular: admin (boolean, full access), data (with pin_list and nft_list read permissions), pinning (with unpin, pin_by_hash, and pin_file_to_ipfs permissions), and pin_nft (with unpin_nft and pin_nft_to_ipfs permissions). AIOZ Pin's docs specify that when setting permissions, you need to include all properties, admin keys are the one exception where sub-properties can be omitted.

In practice, this means a key handed to a CI pipeline that only uploads build artifacts can be scoped to pinning alone, with no ability to unpin existing content or touch NFT operations, meaningfully different from generating one admin key and using it everywhere.

The Node.js SDK: 14 Methods Over the Same API

The official SDK, @aioznetwork/aioz-pin-sdk (currently v1.0.1), wraps the REST API into a client object:

import AiozPinClient from '@aioznetwork/aioz-pin-sdk'
const client = new AiozPinClient('api-key', 'secret-key')

From there, the SDK covers pinning (pinFilesToIPFS(), pinFolderToIPFS(), pinByHash(), unpin()), NFTs (pinNft(), pinNftByStreamMetadata(), pinNftByHash(), pinNftByHashAndMetadataStream(), unpinNft()), and retrieval (getPinList(), getPinByID(), getPinByCID(), optimizeImage()), plus testAuthentication() to verify your keys work before you build anything on top of them. One naming note worth flagging: AIOZ's own quick-start guide writes the file-pinning method as the singular pinFileToIPFS, but the actual published package ships the plural pinFilesToIPFS(), which takes an array of file paths. Use the plural form, it's what the real package exports.

The CLI: Scripting Without Node.js

A separate command-line tool lives on the AIOZNetwork GitHub org for pinning from a shell script or CI pipeline without pulling in the Node.js SDK:

pinning login --key "your_key" --secret "your_secret"
pinning pin --file afile.txt
pinning list-pins
pinning unpin --id=00000000-0000-0000-0000-000000000000

This is the right layer if you're pinning from a build step, a cron job, or any environment where adding a Node.js dependency is more overhead than it's worth.

Choosing a Layer

All three ultimately call the same underlying REST endpoints, so this isn't a choice between different capabilities, it's a choice about which layer fits the runtime environment a given integration already lives in. A project that starts with direct REST calls in a Python data pipeline and later adds a Node.js dashboard doesn't need to reconcile two different pinning implementations, both are talking to the identical API underneath.

Testing Before You Build On Top

Whichever layer an integration uses, the same first step applies before writing any real pinning logic: confirm the credentials actually work. The SDK and CLI both expose this directly, testAuthentication() in the SDK, and the CLI's login command itself fails immediately on bad credentials rather than deferring the error to the first real pin attempt. Calling this before building anything further catches a copy-pasted key with a typo, or a key scoped incorrectly for the operation about to be attempted, at the cheapest possible point, before it's buried under application logic that makes the actual auth failure harder to spot.

Frequently Asked Questions

What are the 8 sections of AIOZ Pin's API? Users, ApiKeys, Pinning, Nft, Gateways, Pinning Services API, Billing, and Image Optimization, each covering a distinct area of functionality.

What is the correct Node.js SDK package name? @aioznetwork/aioz-pin-sdk. The unscoped name aioz-pin-sdk shown in some AIOZ documentation does not exist as a real package.

Are AIOZ Pin API keys scoped, or is it all-or-nothing access? Scoped. You can generate a key limited to specific permissions, like pinning without unpin or billing access, rather than one master key with full access to everything.

Should I use the SDK or call the REST API directly? Use the SDK if you're in Node.js and want higher-level methods. Call the REST API directly for other languages, or for endpoints like the Pinning Services API standard that are meant to be called directly by IPFS tooling.

Does AIOZ Pin have a command-line tool? Yes, a separate CLI on the AIOZNetwork GitHub org, useful for pinning from shell scripts or CI pipelines without adding a Node.js dependency.

What's the exact method name for pinning multiple files in the SDK? pinFilesToIPFS({filePaths, options}). AIOZ's own quick-start guide shows this as the singular pinFileToIPFS, but the real published package uses the plural form.

Related Reading

• How AIOZ Pin Works: Pinning, Gateways, and NFT Tools - the product-level explanation of what these API sections actually do
• IPFS Pinning Service API: What It Is, Why It Matters - full detail on the standard-compliant endpoint mentioned above
• AIOZ Pin vs Pinata: IPFS Pinning Service Compared 2026 - how AIOZ Pin's developer experience compares to the market leader's
• Getting Started with the AIOZ Pin Node.js SDK: A Guide - the SDK section of this API surface, in hands-on detail
• AIOZ Pin CLI Tutorial: Login, Pin, List, and Unpin Files - the CLI section of this API surface, in hands-on detail
• AIOZ Pin AI Agent Setup: MCP Server and llms.txt Guide - the same API surface for super intelligence assistants: llms.txt to read it, an MCP server to call it

References

• AIOZ Pin API Keys Documentation
• AIOZ Pin SDK Package (npm registry)
• AIOZ Pin Users API Documentation