Skip to main content

Image & IPFS Operations

The Intuition GraphQL API provides mutations for uploading images and JSON data to IPFS (InterPlanetary File System). Image uploads return cached image URLs, while JSON uploads return IPFS hashes that can be used in atom creation.

Pinning endpoint and API key

Image and JSON upload mutations use the public gated pinning endpoint, https://pin.intuition.systems/v1/graphql, and require an apikey request header. Keep the API key server-side.

Available Operations​

OperationDescription
uploadImageUpload a base64-encoded image to IPFS
uploadImageFromUrlUpload an image from a URL to IPFS
uploadJsonToIpfsUpload JSON metadata to IPFS

Use Cases​

Atom Creation Workflow​

When creating atoms with images or metadata:

  1. Upload image using uploadImage or uploadImageFromUrl
  2. Upload JSON metadata using uploadJsonToIpfs
  3. Use the returned image URL and metadata IPFS hash in atom creation

Profile Images​

Upload profile images for accounts:

  • Avatar images
  • Banner images
  • Organization logos

Metadata Storage​

Store structured metadata on IPFS:

  • Thing descriptions
  • Organization details
  • Person profiles

Quick Start​

import { GraphQLClient } from 'graphql-request';
import { PIN_API_URL } from '@0xintuition/graphql';

const client = new GraphQLClient(PIN_API_URL, {
  headers: {
    apikey: process.env.INTUITION_PIN_API_KEY!,
  },
});

// Upload an image from URL
const imageResult = await client.request(
  `
  mutation UploadImageFromUrl($image: UploadImageFromUrlInput!) {
    uploadImageFromUrl(image: $image) {
      images {
        url
        safe
      }
    }
  }
`,
  {
    image: { url: 'https://example.com/image.png' },
  },
);

// Upload JSON metadata
const jsonResult = await client.request(
  `
  mutation UploadJsonToIpfs($json: jsonb!) {
    uploadJsonToIpfs(json: $json) {
      hash
      name
      size
    }
  }
`,
  {
    json: {
      name: 'My Atom',
      description: 'Description here',
      image: imageResult.uploadImageFromUrl.images[0].url,
    },
  },
);

console.log('Metadata URI:', `ipfs://${jsonResult.uploadJsonToIpfs.hash}`);
// Use this URI when creating the atom

IPFS Response Format​

Uploaded JSON content is accessible via IPFS:

ipfs://<hash>

The exact response shape depends on the mutation. JSON uploads return the raw hash, which you can convert to an IPFS URI:

{
  "hash": "QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy"
}

File Size Limits​

Upload TypeMaximum Size
Image (base64)5 MB
Image from URL10 MB
JSON1 MB

Supported Image Formats​

  • JPEG / JPG
  • PNG
  • GIF
  • WebP
  • SVG