Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

API Documentation

Each service in the Pinner ecosystem provides self-hosted OpenAPI (Swagger) documentation.

Service Endpoints

ServiceDomainDescription
IPFSipfs.pinner.xyzFile upload, pinning, TUS protocol
Accountaccount.pinner.xyzUser account, API keys, limits

Accessing Swagger Docs

Every service exposes three documentation endpoints:

EndpointFormatDescription
/swaggerHTMLInteractive Swagger UI
/swagger.yamlYAMLOpenAPI specification file
/swagger.jsonJSONOpenAPI specification file

Examples

IPFS Service: Account Service:

Using Swagger UI

The interactive Swagger UI allows you to:

  • Browse all available endpoints
  • View request/response schemas
  • Execute API calls directly from the browser
  • Generate client code in multiple languages

Programmatic Access

Download the OpenAPI spec for use in code generation tools:

# Download IPFS service spec
curl -o ipfs-swagger.json https://ipfs.pinner.xyz/swagger.json
 
# Download Account service spec
curl -o account-swagger.json https://account.pinner.xyz/swagger.json

Generate TypeScript Clients with Orval

Orval generates type-safe TypeScript clients from OpenAPI specifications with support for multiple frameworks including React Query, SWR, Angular, and plain fetch.

Installation

npm install orval --save-dev

Configuration

Create an orval.config.ts file in your project:

import { defineConfig } from "orval";
 
export default defineConfig({
  pinner: {
    input: "./pinner-api.yaml",
    output: {
      mode: "tags",
      client: "react-query",
      target: "src/api",
      schemas: "src/api/model",
    },
  },
});

Generate API Client

# Download the OpenAPI spec
curl -o pinner-api.yaml https://ipfs.pinner.xyz/swagger.yaml
 
# Generate TypeScript client
npx orval

Framework-Specific Examples

React Query (default): 
import { useQuery, useMutation } from "@tanstack/react-query";
import { getPins, uploadFile } from "./src/api/pinner";
 
function PinsComponent() {
  const { data, isLoading } = useQuery({
    queryKey: ["pins"],
    queryFn: getPins,
  });
  // ...
}
SWR: 
import useSWR from "swr";
import { getPins } from "./src/api/pinner";
 
function PinsComponent() {
  const { data } = useSWR("/pins", getPins);
  // ...
}
Plain Fetch: 
import { getPins } from "./src/api/pinner";
 
async function fetchPins() {
  const response = await getPins();
  return response.data;
}

Using with Portal SDK

The portal-sdk demonstrates Orval integration with the Account API:

# From the portal-sdk directory
cd libs/portal-sdk
pnpm orval

This generates type-safe clients at src/account/generated/ with fetch-based HTTP calls.

See Also