REST API Reference

The TAG IT REST API provides programmatic access to product registration, verification, and ownership management.

Base URL

All API requests should be made to the following base URL:

https://api.tagit.network/v1

For testing and development, use the sandbox environment:

https://sandbox.api.tagit.network/v1

Authentication

The TAG IT API uses API keys and Bearer tokens for authentication. Include your credentials in every request.

API Key Header

Pass your API key in the X-API-Key header:

curl -X GET "https://api.tagit.network/v1/products/123" \
  -H "X-API-Key: tagit_live_abc123xyz789"

Bearer Token

For user-specific actions, use Bearer token authentication:

curl -X POST "https://api.tagit.network/v1/transfers" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Products Endpoints

Endpoints for managing product registration, retrieval, and verification.

POST /products - Register a Product

Register a new product on the TAG IT Network blockchain.

Request

curl -X POST "https://api.tagit.network/v1/products" \
  -H "X-API-Key: tagit_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "tagId": "NFC-TAG-002-XYZ",
    "productName": "Designer Handbag Limited Edition",
    "brand": "Luxury Fashion House",
    "serialNumber": "SN-2024-005678",
    "category": "fashion",
    "metadata": {
      "material": "Italian Leather",
      "color": "Black",
      "manufactureDate": "2024-03-15",
      "origin": "Italy"
    }
  }'

Response

{
  "success": true,
  "data": {
    "productId": "prod_a1b2c3d4e5f6",
    "tagId": "NFC-TAG-002-XYZ",
    "productName": "Designer Handbag Limited Edition",
    "brand": "Luxury Fashion House",
    "serialNumber": "SN-2024-005678",
    "category": "fashion",
    "metadata": {
      "material": "Italian Leather",
      "color": "Black",
      "manufactureDate": "2024-03-15",
      "origin": "Italy"
    },
    "blockchain": {
      "network": "polygon",
      "contractAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "tokenId": "56789",
      "txHash": "0xabc123def456789..."
    },
    "registeredAt": "2024-03-15T14:30:00Z",
    "owner": "0x742d35Cc6634C0532925a3b844Bc9e7595f5c9E8"
  }
}

GET /products/{id} - Get Product Details

Retrieve detailed information about a registered product.

Request

curl -X GET "https://api.tagit.network/v1/products/prod_a1b2c3d4e5f6" \
  -H "X-API-Key: tagit_live_abc123xyz789"

Response

{
  "success": true,
  "data": {
    "productId": "prod_a1b2c3d4e5f6",
    "tagId": "NFC-TAG-002-XYZ",
    "productName": "Designer Handbag Limited Edition",
    "brand": "Luxury Fashion House",
    "serialNumber": "SN-2024-005678",
    "category": "fashion",
    "status": "active",
    "metadata": {
      "material": "Italian Leather",
      "color": "Black",
      "manufactureDate": "2024-03-15",
      "origin": "Italy"
    },
    "currentOwner": "0x742d35Cc6634C0532925a3b844Bc9e7595f5c9E8",
    "transferCount": 0,
    "verificationCount": 12,
    "lastVerifiedAt": "2024-03-20T09:15:00Z",
    "registeredAt": "2024-03-15T14:30:00Z"
  }
}

POST /products/verify - Verify Authenticity

Verify a product's authenticity using its NFC tag ID or product ID.

Request

curl -X POST "https://api.tagit.network/v1/products/verify" \
  -H "X-API-Key: tagit_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "tagId": "NFC-TAG-002-XYZ",
    "signature": "0x1234567890abcdef...",
    "timestamp": 1710936000
  }'

Response

{
  "success": true,
  "data": {
    "verified": true,
    "authenticity": "confirmed",
    "product": {
      "productId": "prod_a1b2c3d4e5f6",
      "tagId": "NFC-TAG-002-XYZ",
      "productName": "Designer Handbag Limited Edition",
      "brand": "Luxury Fashion House"
    },
    "currentOwner": "0x742d35Cc6634C0532925a3b844Bc9e7595f5c9E8",
    "blockchain": {
      "network": "polygon",
      "tokenId": "56789",
      "verified": true
    },
    "verifiedAt": "2024-03-20T10:00:00Z"
  }
}

Transfers Endpoints

Endpoints for managing product ownership transfers.

POST /transfers - Initiate Ownership Transfer

Start a product ownership transfer to a new owner.

Request

curl -X POST "https://api.tagit.network/v1/transfers" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_a1b2c3d4e5f6",
    "toAddress": "0x9876543210fedcba9876543210fedcba98765432",
    "message": "Gift for birthday"
  }'

Response

{
  "success": true,
  "data": {
    "transferId": "txfr_x1y2z3a4b5c6",
    "productId": "prod_a1b2c3d4e5f6",
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f5c9E8",
    "toAddress": "0x9876543210fedcba9876543210fedcba98765432",
    "status": "pending",
    "message": "Gift for birthday",
    "expiresAt": "2024-03-27T10:00:00Z",
    "createdAt": "2024-03-20T10:00:00Z"
  }
}

POST /transfers/{id}/confirm - Confirm Transfer

Confirm and complete a pending ownership transfer.

Request

curl -X POST "https://api.tagit.network/v1/transfers/txfr_x1y2z3a4b5c6/confirm" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "signature": "0xabcdef1234567890..."
  }'

Response

{
  "success": true,
  "data": {
    "transferId": "txfr_x1y2z3a4b5c6",
    "productId": "prod_a1b2c3d4e5f6",
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f5c9E8",
    "toAddress": "0x9876543210fedcba9876543210fedcba98765432",
    "status": "completed",
    "blockchain": {
      "txHash": "0xdef456789abc123...",
      "blockNumber": 54321098,
      "gasUsed": "85000"
    },
    "completedAt": "2024-03-20T10:05:00Z"
  }
}

Error Codes

The API uses standard HTTP status codes and returns detailed error information in the response body.

Error Response Format

{
  "success": false,
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "No product found with the specified ID",
    "details": {
      "productId": "prod_invalid123"
    }
  },
  "requestId": "req_abc123xyz"
}

Rate Limiting

API requests are rate limited based on your subscription plan. Limits are applied per API key.

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1710936060