GraphQL Mutations

Our GraphQL API provides convenient mutations to help structure and publish Atom metadata following common schemas and best practices. While the protocol supports any URI scheme, these mutations offer an opinionated approach to creating well-structured, interoperable data.

Current Schema Support

Currently, our default schema is the Thing schema. This provides essential properties for describing any entity:

mutation UploadThing(
  $name: String!
  $description: String!
  $image: String!
  $url: String!
) {
  uploadThing(
    arg1: { name: $name, description: $description, image: $image, url: $url }
  ) {
    cid
  }
}

Example Usage

{
  "name": "My First Thing",
  "description": "This is an example description",
  "image": "ipfs://Qm...", // IPFS URI for image
  "url": "<https://example.com>" // Reference URL
}

The mutation returns an IPFS CID that can be used when creating an Atom:

const { cid } = await uploadThing(thingData)
const atomId = await createAtom(cid)

Upcoming Schema Support

We are actively expanding our mutation support to include schemas from schema.org. Additionally, we'll be adding support for CAIP-10 addresses to enable cross-chain identity resolution.

Best Practices

1. Complete Metadata: Provide as much relevant metadata as possible to improve the Atom's utility across different contexts.
2. Persistent Storage: All metadata is stored on IPFS, ensuring data availability and immutability.
3. URI Standards: Use standard URI formats:
   • IPFS: ipfs://Qm...
   • HTTP(S): https://...
   • CAIP-10 (coming soon): eip155:1:0x...

Example Workflows

Basic Thing Creation

// 1. Upload metadata
const thingData = {
  name: 'Example Thing',
  description: 'Description...',
  image: 'ipfs://Qm...',
  url: 'https://...',
}

const { cid } = await uploadThing(thingData)

// 2. Create Atom with returned CID
const atomId = await createAtom(cid)

TypeScript Integration

We maintain a package, graphql within our intuition-ts monorepo that auto-generates TypeScript types and React hooks to make integrations easier. This includes type-safe mutations, queries, and React hooks for all supported schemas. We are actively finalizing patterns to properly externalize this package, which will be released shortly. This guide will be updated to provide example implementations once the package is released.

Future Schema Support

We are also actively expanding our mutation support to include schemas from schema.org as well as CAIP-10 addresses to enable cross-chain identity resolution.