Pipe CDN API Documentation

This document provides a comprehensive overview of the Pipe CDN API. All is this is currently based on the Pipe Network CDN Devnet deployment on Solana Devnet.

Base URL

All API endpoints are relative to the base URL

Authentication

Most endpoints require authentication using two parameters:

user_id: The unique identifier for the user
user_app_key: The application key for the user

These parameters are typically included as query parameters for GET requests or in the request body for POST requests.

Account Management APIs

Create User

Creates a new user account.

Endpoint: /createUser
Method: POST
Authentication: None (public endpoint)
Request Body:jsonApply to lib.rs { "username": "string" }
Response:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string", "solana_pubkey": "string" }

Rotate App Key

Rotates (changes) the application key for a user.

Endpoint: /rotateAppKey
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string" }
Response:jsonApply to lib.rs { "user_id": "string", "new_user_app_key": "string" }

File Management APIs

Upload File

Uploads a file to Pipe CDN.

Endpoint: /upload
Method: POST
Authentication: Required
Query Parameters:
user_id: User ID
user_app_key: User application key
file_name: Name to store the file as
epochs (optional): Storage duration in epochs
Body: File content as multipart/form-data
Response: The uploaded filename as a string

Priority Upload

Uploads a file with higher priority.

Endpoint: /priorityUpload
Method: POST
Authentication: Required
Query Parameters:
user_id: User ID
user_app_key: User application key
file_name: Name to store the file as
epochs (optional): Storage duration in epochs
Body: File content as multipart/form-data
Response: The uploaded filename as a string

Download File

Downloads a file from Pipe CDN.

Endpoint: /download
Method: GET
Authentication: Required
Query Parameters:
user_id: User ID
user_app_key: User application key
file_name: Name of the file to download
Response: The file content with appropriate Content-Type and Content-Length headers

Priority Download

Downloads a file with higher priority.

Endpoint: /priorityDownload
Method: GET
Authentication: Required
Query Parameters:
user_id: User ID
user_app_key: User application key
file_name: Name of the file to download
Response: The file content as Base64-encoded string

Delete File

Deletes a file from storage.

Endpoint: /deleteFile
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string", "file_name": "string" }
Response:jsonApply to lib.rs { "message": "string" }

Create Public Link

Creates a public link for a file.

Endpoint: /createPublicLink
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string", "file_name": "string" }
Response:jsonApply to lib.rs { "link_hash": "string" }

Public Download

Downloads a file using a public link.

Endpoint: /publicDownload
Method: GET
Authentication: None (public endpoint)
Query Parameters:
hash: The public link hash
Response: The file content with appropriate headers

Extend Storage

Extends the storage duration for a file.

Endpoint: /extendStorage
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string", "file_name": "string", "additional_months": number }
Response:jsonApply to lib.rs { "message": "string", "new_expires_at": "string" }

Wallet and Payments APIs

Check SOL Balance

Checks the SOL (Solana) balance of the user's wallet.

Endpoint: /checkWallet
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string" }
Response:jsonApply to lib.rs { "user_id": "string", "public_key": "string", "balance_lamports": number, "balance_sol": number }

Check PIPE Token Balance

Checks the PIPE token balance of the user's wallet.

Endpoint: /getCustomTokenBalance
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string" }
Response:jsonApply to lib.rs { "user_id": "string", "public_key": "string", "token_mint": "string", "amount": "string", "ui_amount": number }

Check DC Balance

Checks the DC (Data Credit) balance of the user's wallet.

Endpoint: /getDcBalance
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string" }
Response:jsonApply to lib.rs { "user_id": "string", "dc_balance": number }

Swap SOL for PIPE

Swaps SOL for PIPE tokens.

Endpoint: /swapSolForPipe
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string", "amount_sol": number }
Response:jsonApply to lib.rs { "user_id": "string", "sol_spent": number, "tokens_minted": number }

Swap PIPE for DC

Swaps PIPE tokens for DC (Data Credits).

Endpoint: /swapPipeForDc
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string", "amount_pipe": number }
Response:jsonApply to lib.rs { "user_id": "string", "pipe_spent": number, "dc_minted": number }

Withdraw SOL

Withdraws SOL to an external address.

Endpoint: /withdrawSol
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string", "to_pubkey": "string", "amount_sol": number }
Response:jsonApply to lib.rs { "user_id": "string", "to_pubkey": "string", "amount_sol": number, "signature": "string" }

Withdraw Custom Token

Withdraws PIPE tokens to an external address.

Endpoint: /withdrawToken
Method: POST
Authentication: Required
Request Body:jsonApply to lib.rs { "user_id": "string", "user_app_key": "string", "to_pubkey": "string", "amount": number }
Response:jsonApply to lib.rs { "user_id": "string", "to_pubkey": "string", "amount": number, "signature": "string" }

Utility APIs

Get Priority Fee

Gets the current priority fee for priority uploads.

Endpoint: /getPriorityFee
Method: GET
Authentication: None (public endpoint)
Response:jsonApply to lib.rs { "priority_fee_per_gb": number }

Check Version

Checks if the client is using the latest version.

Endpoint: /versionCheck
Method: POST
Authentication: None (public endpoint)
Request Body:jsonApply to lib.rs { "current_version": "string" }
Response:jsonApply to lib.rs { "is_latest": boolean, "download_link": "string" (optional), "latest_version": "string" (optional), "release_notes": "string" (optional), "minimum_required": "string" (optional) }

Implementation Notes

Error Handling

All API calls should handle HTTP status codes appropriately:

200 OK: Successful request
400 Bad Request: Invalid request parameters
401 Unauthorized: Authentication failed
404 Not Found: Resource not found
500 Internal Server Error: Server-side error

Error responses typically include a text message explaining the error.

File Encryption

The Pipe CLI implements client-side encryption, which is not part of the API. If you want to implement encryption in your application:

Use a strong encryption algorithm (AES-256-GCM is recommended)
Generate and store a random salt and nonce for each encrypted file
Derive an encryption key from the user's password using a strong KDF like Argon2
Encrypt the file before uploading and decrypt after downloading
Store encryption parameters (salt, nonce) securely, but never store the password

Retries and Backoff

For robust applications, implement retry logic with exponential backoff:

Start with an initial delay (e.g., 1000ms)
Increase the delay for each retry (up to a maximum, e.g., 10000ms)
Limit the number of retries (e.g., 3)

Upload Considerations

For large files, use chunked uploads or streaming to avoid memory issues
Consider adding progress tracking for better user experience
For batch operations, limit concurrent requests to avoid overwhelming the server

This documentation provides the foundation for building applications that interact with the Pipe CDN API in any programming language.

PreviousMainnet

Last updated 6 days ago