Simple Page Node API

The SimplePage Node API provides REST endpoints for managing pages and files in the IPFS-based SimplePage system. The API supports uploading pages as CAR files, retrieving page content, and accessing raw IPFS blocks. The easiest way to play around with this api is to run your own node.

Base URL

The API is served at one of the endpoints listed under the dservice text record on the new.simplepage.eth ENS name. This page uses https://your-service.com as an example.

Authentication

Currently, the API uses domain-based authorization. Only domains with active subscriptions can upload pages.

Content Types

  • CAR Files: application/vnd.ipld.car - IPFS Content Addressed Archive format
  • Raw Blocks: application/vnd.ipld.raw - Raw IPFS block data
  • JSON: application/json - Standard JSON responses

Endpoints

Page Operations

GET /page

Retrieve a page by its Content Identifier (CID). This endoint doesn't return the entire DAG under the given CID, but rather the files under the root directory, and all index.html and index.md files in sub-directories.

Parameters:

  • cid (query, required): The CID of the page to retrieve

Response:

  • 200: CAR file containing the page data (application/vnd.ipld.car)
  • 400: Bad request - missing CID parameter (application/json)
  • 404: Page not found (application/json)

Example:

curl -X GET "https://your-service.com/page?cid=bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"

POST /page

Upload a new page as a CAR file. The uploaded content will remain available for 1 hour by default, unless the contenthash for the given domain is updated to cointain the CID of the uploaded content.

Parameters:

  • domain (query, required): The domain for the page
  • file (form-data, required): CAR file (max 500MB)

Response:

  • 200: Successfully uploaded page (application/json)
    {
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
}
  • 400: Bad request - missing parameters (application/json)
  • 401: Unauthorized - domain not subscribed (application/json)
  • 413: File too large - exceeds 500MB limit (application/json)
  • 500: Server error (application/json)

Example:

curl -X POST "https://your-service.com/page?domain=example.com" \
  -F "file=@page.car"

File Operations

GET /file

Retrieve a raw IPFS block by its CID.

Parameters:

  • cid (query, required): The CID of the IPFS block to retrieve

Response:

  • 200: Raw IPFS block data (application/vnd.ipld.raw)
  • 400: Bad request - missing CID parameter (application/json)
  • 404: Block not found (application/json)

Example:

curl -X GET "https://your-service.com/file?cid=bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"

System Operations

GET /info

Get API version information.

Response:

  • 200: Version information (application/json)
    {
  "version": "1.0.0"
}

Example:

curl -X GET "https://your-service.com/info"

Error Responses

All error responses follow this format:

{
  "detail": "Error message description"
}

Common error codes:

  • 400: Bad Request - Invalid parameters or missing required fields
  • 401: Unauthorized - Domain not subscribed or invalid credentials
  • 404: Not Found - Resource (page/file) not found
  • 413: Payload Too Large - File exceeds size limit
  • 500: Internal Server Error - Server-side error

Interactive Documentation

The API includes interactive Swagger UI documentation available at /docs endpoint. This provides:

  • Complete API specification
  • Interactive endpoint testing
  • Request/response examples
  • Schema definitions

Access it at: https://your-service.com/docs

File Size Limits

  • Maximum file upload size: 500MB
  • Supported format: CAR (Content Addressed Archive) files only

< Prev (Protocol)・ Next (Project) >