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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tagbase.io/extension/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.