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:

1. Use a strong encryption algorithm (AES-256-GCM is recommended)

2. Generate and store a random salt and nonce for each encrypted file

3. Derive an encryption key from the user's password using a strong KDF like Argon2

4. Encrypt the file before uploading and decrypt after downloading

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