API Reference
Complete endpoint documentation for the TAGBASE API.
Base URL
https://api.extension.tagbase.ioEndpoints
GET /claims
Retrieve all claims associated with a specific URL.
Query Parameters:
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:
400
{ "error": "resource_url is required" }
400
{ "error": "Invalid resource_url format" }
GET /verifications/{id}
Retrieve a specific verification by its ID.
Path Parameters:
id
string
Verification ID (format: VRF_[a-zA-Z0-9]{6,128})
Example Request:
Success Response (200):
Error Responses:
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:
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:
Success Response (201):
Error Responses:
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:
id
string
UUID or Verification ID
Request Body (optional):
uuid
string
UUID of the verification (optional)
verification_id
string
Text verification ID (optional)
Example Request:
Success Response (200):
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:
id
string
UUID or Verification ID
Request Body (Cardano):
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):
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):
Success Response (200):
Error Responses:
400
{ "error": "Invalid or expired challenge" }
400
{ "error": "Signature verification failed" }
400
{ "error": "Address does not hold the required token" }
Error Codes
200
Success
201
Created
400
Bad Request — Invalid input
404
Not Found — Resource doesn't exist
500
Server Error — Try again later
Last updated