API Reference

Complete endpoint documentation for the TAGBASE API.

Base URL

https://api.extension.tagbase.io

---

Endpoints

---

GET /claims

Retrieve all claims associated with a specific URL.

Query Parameters:

Parameter	Type	Required	Description
resource_url	string	Yes	URL to query claims for (max 2048 chars)

Example Request:

curl "https://api.extension.tagbase.io/claims?resource_url=https://example.com/product"

Success Response (200):

{
  "claims": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "verification_id": "VRF_abc123def456",
      "resource_url": "https://example.com/product",
      "note": "Authentic product",
      "verified_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z",
      "country": "US",
      "product": {
        "id": "prd_xyz789",
        "name": "Luxury Watch Model X",
        "image_url": "https://...",
        "description": "Premium timepiece"
      },
      "token": {
        "data": { "asset_id": "...", "policy_id": "..." },
        "name": "LuxuryWatch001",
        "symbol": "LW001",
        "blockchain_type": "cardano",
        "contract_address": null,
        "supply": 1
      },
      "ownership": {
        "status": "verified",
        "wallet_address": "addr1q...x7k4",
        "verified_at": "2024-01-16T14:00:00Z"
      }
    }
  ]
}

Error Responses:

Status	Response
400	{ "error": "resource_url is required" }
400	{ "error": "Invalid resource_url format" }

---

GET /verifications/{id}

Retrieve a specific verification by its ID.

Path Parameters:

Parameter	Type	Description
id	string	Verification ID (format: VRF_[a-zA-Z0-9]{6,128})

Example Request:

curl "https://api.extension.tagbase.io/verifications/VRF_abc123def456"

Success Response (200):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_id": "VRF_abc123def456",
  "resource_url": "https://example.com/product",
  "note": "Authentic product",
  "verified_at": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-15T10:30:00Z",
  "country": "US",
  "product": {
    "id": "prd_xyz789",
    "name": "Luxury Watch Model X",
    "image_url": "https://...",
    "description": "Premium timepiece"
  },
  "token": {
    "data": { "asset_id": "...", "policy_id": "..." },
    "name": "LuxuryWatch001",
    "symbol": "LW001",
    "blockchain_type": "cardano",
    "contract_address": null,
    "supply": 1
  },
  "ownership": {
    "status": "verified",
    "wallet_address": "addr1q...x7k4",
    "verified_at": "2024-01-16T14:00:00Z"
  }
}

Error Responses:

Status	Response
400	{ "error": "Invalid verification ID format" }
404	{ "error": "Verification not found" }

---

POST /claims

Create a new claim by linking an existing verification to a URL.

Request Body:

Field	Type	Required	Description
resource_url	string	Yes	URL to link (max 2048 chars)
verification_id	string	Yes	Verification ID (format: VRF_...)
note	string	No	Optional note (max 280 chars)

Example Request:

curl -X POST "https://api.extension.tagbase.io/claims" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_url": "https://example.com/product",
    "verification_id": "VRF_abc123def456",
    "note": "Listed for sale"
  }'

Success Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "verification_id": "VRF_abc123def456"
}

Error Responses:

Status	Response
400	{ "error": "Validation failed", "details": [...] }
400	{ "error": "Verification is not valid", "details": [...] }
404	{ "error": "Verification not found in Tagbase" }

---

POST /verifications/{id}/challenge

Request an ownership verification challenge.

Path Parameters:

Parameter	Type	Description
id	string	UUID or Verification ID

Request Body (optional):

Field	Type	Description
uuid	string	UUID of the verification (optional)
verification_id	string	Text verification ID (optional)

Example Request:

curl -X POST "https://api.extension.tagbase.io/verifications/VRF_abc123def456/challenge" \
  -H "Content-Type: application/json"

Success Response (200):

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Tagbase Ownership Verification\n\nVerification ID: VRF_abc123def456\nNonce: 7a9c3f...\nExpires: 2024-01-15T10:35:00Z",
  "expires_at": "2024-01-15T10:35:00Z",
  "blockchain_type": "cardano",
  "expected_holders": ["addr1q...", "addr1q..."],
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Notes:

• Challenge expires after 5 minutes

• expected_holders is populated for Cardano tokens with on-chain data

---

POST /verifications/{id}/proof

Submit a signed ownership proof.

Path Parameters:

Parameter	Type	Description
id	string	UUID or Verification ID

Request Body (Cardano):

Field	Type	Required	Description
session_id	string	Yes	Session ID from challenge
address	string	Yes	Cardano wallet address (bech32 or hex)
signature	string	Yes	CIP-30 COSE_Sign1 signature (hex)
key	string	Yes	Public key (hex)
blockchain_type	string	Yes	Must be "cardano"

Request Body (Ethereum):

Field	Type	Required	Description
session_id	string	Yes	Session ID from challenge
address	string	Yes	Ethereum address (0x...)
signature	string	Yes	personal_sign signature (0x...)
blockchain_type	string	No	Defaults to "ethereum"

Example Request (Cardano):

curl -X POST "https://api.extension.tagbase.io/verifications/VRF_abc123def456/proof" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "address": "addr1qx...",
    "signature": "84582aa...",
    "key": "a401010327...",
    "blockchain_type": "cardano"
  }'

Success Response (200):

{
  "success": true,
  "request_id": "abc123...",
  "ownership": {
    "status": "verified",
    "wallet_address": "addr1q...x7k4",
    "verified_at": "2024-01-15T10:32:00Z"
  }
}

Error Responses:

Status	Response
400	{ "error": "Invalid or expired challenge" }
400	{ "error": "Signature verification failed" }
400	{ "error": "Address does not hold the required token" }

---

Error Codes

HTTP Status	Meaning
200	Success
201	Created
400	Bad Request — Invalid input
404	Not Found — Resource doesn't exist
500	Server Error — Try again later