README

Minimal PHP client for the PinArkive API v3. Upload files, pin by CID, manage tokens, and check status. See docs.pinarkive.com.

Version: 3.1.2

Installation

composer require pinarkive/pinarkive-sdk-php

Quick Start

<?php

use Pinarkive\PinarkiveClient;
use Pinarkive\PinarkiveException;

// Auth: token, apiKey, baseUrl (default: https://api.pinarkive.com/api/v3)
$client = new PinarkiveClient(null, 'your-api-key-here');

// Upload a file
$response = $client->uploadFile('document.pdf');
$data = json_decode($response->getBody(), true);
echo $data['cid'];

// Or login first
$login = $client->login('user@example.com', 'password');
$data = json_decode($login->getBody(), true);
$client = new PinarkiveClient($data['token'], null);

// List uploads
$response = $client->listUploads(1, 20);
$data = json_decode($response->getBody(), true);
print_r($data['uploads']);

Directory DAG (uploadDirectoryDAG)

The API expects multipart field files (repeated); each part’s filename is the path inside the DAG. The response root CID is cid.

$response = $client->uploadDirectoryDAG(['1.png', '2.png'], 'mydag', 'cl0-global');
$data = json_decode($response->getBody(), true);
echo $data['cid']; // gateway …/ipfs/<cid>/1.png

Authentication

• Constructor: new PinarkiveClient($token = null, $apiKey = null, $baseUrl = '...', $sendRequestSourceWeb = false)
• API Key is sent as X-API-Key header; token as Authorization: Bearer <token>.
• $sendRequestSourceWeb: when true, sends X-Request-Source: web on every Bearer-authenticated request (not when using API Key). Use from web apps so the backend classifies requests as WEB in logs instead of JWT.

API Methods (minimal set)

Optional $clusterId and $timelock (ISO 8601, premium) follow the API docs.

Error handling

On HTTP 4xx/5xx the client throws PinarkiveException with:

• getStatusCode() — HTTP status
• getApiError() — API field error
• getApiMessage() — API field message
• getApiCode() — API field code (e.g. email_not_verified, missing_scope)
• getRequired() — for 403 missing_scope: the required scope
• getRetryAfter() — for 429: seconds until retry (from body or Retry-After header)
• getBody() — full response array

try {
    $client->uploadFile('file.pdf');
} catch (PinarkiveException $e) {
    echo $e->getStatusCode() . ' ' . $e->getApiMessage() . ' ' . $e->getApiCode();
}

Changelog

3.1.2

• Docs: Links updated to https://docs.pinarkive.com.

3.1.0

• Request source: Constructor 4th param $sendRequestSourceWeb = true sends X-Request-Source: web on Bearer requests.
• Scopes & 2FA: generateToken(..., $scopes, $totpCode); revokeToken($name, $totpCode). verify2FALogin($temporaryToken, $code) for login with 2FA.
• Errors: getRequired() (403 missing_scope), getRetryAfter() (429).

3.1.1

• Fix: uploadDirectoryDAG now sends multipart with repeated field name files, with each part’s filename equal to the relative path in the DAG (backend multer upload.array('files')). The previous files[i][path] / files[i][content] format is not accepted by the backend.

See also CHANGELOG.md.

3.0.0

• API v3: Base URL is now https://api.pinarkive.com/api/v3 (was /api/v2). v1/v2 are deprecated (410).
• Errors: On 4xx/5xx the client throws PinarkiveException with getStatusCode(), getApiError(), getApiMessage(), getApiCode(), getBody() (no raw Guzzle response on failure).
• Minimal surface: Only endpoints documented at docs.pinarkive.com: health, plans, peers, login, files (upload, directory, directory-dag, pin, remove), users/me, uploads, tokens (generate with name / label / expiresInDays), status, allocations. Optional $clusterId and $timelock (ISO 8601) on upload/pin.
• Removed: renameFile; token options permissions, ipAllowlist. Use API label and expiresInDays only.
• Constructor: PinarkiveClient($token = null, $apiKey = null, $baseUrl = '...') — third argument is base URL (v2 had only apiKey and baseUrl).
• Pin: pinCid now accepts $originalName, $customName (replacing the old single $filename).

Upgrading from 2.x

1. Change base URL to /api/v3 or use the new default.
2. Add the third constructor argument if you use a custom base URL: new PinarkiveClient(null, $apiKey, 'https://api.pinarkive.com/api/v3').
3. Catch PinarkiveException and use getStatusCode(), getApiMessage(), getApiCode() instead of Guzzle’s RequestException.
4. Use pinCid($cid, $originalName, $customName, $clusterId, $timelock) instead of pinCid($cid, $filename).
5. Use generateToken($name, $label, $expiresInDays); drop permissions and ipAllowlist from options.
6. Require pinarkive/pinarkive-sdk-php: ^3.0 for v3.

Links

• API docs
• Repository