GraphQL API

Use GraphQL to query exactly the data you need with a single request.

GraphQL Endpoint

All GraphQL queries and mutations are sent to a single endpoint:

https://api.tagit.network/graphql

Send all requests as POST with the query in the request body:

curl -X POST https://api.tagit.network/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "{ product(id: \"123\") { name } }"}'

Authentication

Include your API key in the Authorization header for all requests:

const headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer tagit_live_abc123xyz789'
};

Schema Overview

The TAG IT GraphQL schema includes the following main types:

type Product {
  id: ID!
  tagId: String!
  name: String!
  brand: String
  serialNumber: String
  metadata: ProductMetadata
  currentOwner: Owner
  transfers: [Transfer!]!
  verified: Boolean!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Owner {
  address: String!
  displayName: String
  verifiedAt: DateTime
}

type Transfer {
  id: ID!
  from: Owner!
  to: Owner!
  timestamp: DateTime!
  txHash: String!
  status: TransferStatus!
}

type ProductMetadata {
  description: String
  imageUrl: String
  manufactureDate: Date
  origin: String
  customFields: JSON
}

enum TransferStatus {
  PENDING
  CONFIRMED
  FAILED
}

Available Queries

Query TAG IT data with these available operations:

product(id: ID!)

Fetch a single product by its unique ID:

query GetProduct($productId: ID!) {
  product(id: $productId) {
    id
    tagId
    name
    brand
    serialNumber
    verified
    currentOwner {
      address
      displayName
    }
    metadata {
      description
      imageUrl
      origin
      manufactureDate
    }
    transfers {
      from { address }
      to { address }
      timestamp
      txHash
      status
    }
  }
}

Example response:

{
  "data": {
    "product": {
      "id": "prod_abc123",
      "tagId": "NFC-TAG-001-ABC",
      "name": "Luxury Watch Model X",
      "brand": "Premium Timepieces",
      "serialNumber": "SN-2024-001234",
      "verified": true,
      "currentOwner": {
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f5c9E8",
        "displayName": "John Doe"
      },
      "metadata": {
        "description": "Swiss-made automatic watch",
        "imageUrl": "https://cdn.tagit.network/images/watch-x.jpg",
        "origin": "Switzerland",
        "manufactureDate": "2024-01-15"
      },
      "transfers": [
        {
          "from": { "address": "0x0000000000000000000000000000000000000000" },
          "to": { "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f5c9E8" },
          "timestamp": "2024-01-15T10:30:00Z",
          "txHash": "0xabc123...",
          "status": "CONFIRMED"
        }
      ]
    }
  }
}

products(filter: ProductFilter)

Query multiple products with optional filtering and pagination:

query GetProducts($filter: ProductFilter, $first: Int, $after: String) {
  products(filter: $filter, first: $first, after: $after) {
    edges {
      node {
        id
        tagId
        name
        brand
        verified
        currentOwner {
          address
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

# Variables
{
  "filter": {
    "brand": "Premium Timepieces",
    "verified": true
  },
  "first": 10,
  "after": null
}

transfers(productId: ID)

Query transfer history for a specific product or across all products:

query GetTransfers($productId: ID, $status: TransferStatus, $first: Int) {
  transfers(productId: $productId, status: $status, first: $first) {
    edges {
      node {
        id
        product {
          id
          name
        }
        from {
          address
          displayName
        }
        to {
          address
          displayName
        }
        timestamp
        txHash
        status
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Mutations

Modify data using these mutation operations:

registerProduct

Register a new product on the TAG IT Network:

mutation RegisterProduct($input: RegisterProductInput!) {
  registerProduct(input: $input) {
    product {
      id
      tagId
      name
      verified
      currentOwner {
        address
      }
    }
    txHash
    success
    errors {
      field
      message
    }
  }
}

# Variables
{
  "input": {
    "tagId": "NFC-TAG-002-XYZ",
    "name": "Designer Handbag",
    "brand": "Luxury Fashion House",
    "serialNumber": "BAG-2024-5678",
    "metadata": {
      "description": "Limited edition leather handbag",
      "origin": "Italy",
      "manufactureDate": "2024-03-01"
    }
  }
}

initiateTransfer

Initiate an ownership transfer for a product:

mutation InitiateTransfer($input: TransferInput!) {
  initiateTransfer(input: $input) {
    transfer {
      id
      from { address }
      to { address }
      status
      txHash
    }
    success
    errors {
      field
      message
    }
  }
}

# Variables
{
  "input": {
    "productId": "prod_abc123",
    "toAddress": "0x8901234567890abcdef1234567890abcdef12345",
    "message": "Transferring to new owner"
  }
}

Subscriptions

Subscribe to real-time updates using GraphQL subscriptions over WebSocket:

subscription OnProductTransfer($productId: ID!) {
  productTransferred(productId: $productId) {
    transfer {
      id
      from { address }
      to { address }
      timestamp
      status
    }
    product {
      id
      name
      currentOwner { address }
    }
  }
}

subscription OnProductVerification {
  productVerified {
    product {
      id
      tagId
      name
      verified
    }
    verifiedAt
    verifiedBy { address }
  }
}

Connect to the WebSocket endpoint for subscriptions:

import { createClient } from 'graphql-ws';

const client = createClient({
  url: 'wss://api.tagit.network/graphql',
  connectionParams: {
    authorization: 'Bearer tagit_live_abc123xyz789'
  }
});

// Subscribe to product transfers
const unsubscribe = client.subscribe(
  {
    query: `subscription OnProductTransfer($productId: ID!) {
      productTransferred(productId: $productId) {
        transfer { id status }
        product { name currentOwner { address } }
      }
    }`,
    variables: { productId: 'prod_abc123' }
  },
  {
    next: (data) => console.log('Transfer update:', data),
    error: (err) => console.error('Subscription error:', err),
    complete: () => console.log('Subscription completed')
  }
);

GraphQL Playground

Explore and test the API interactively using our GraphQL Playground:

The playground provides:

• Auto-complete for queries and mutations
• Schema documentation browser
• Query history and saved queries
• Variable editor for parameterized queries
• Real-time subscription testing