# API Reference

#### 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:**

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

**Success Response (200):**

```json
{
  "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:**

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

**Success Response (200):**

```json
{
  "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:**

```bash
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):**

```json
{
  "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:**

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

**Success Response (200):**

```json
{
  "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):**

```bash
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):**

```json
{
  "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     |