SDKs & Code Examples

Quick start examples for integrating with the TAGVU API in your preferred language.

Official SDKs (Coming Soon)

Official TypeScript/JavaScript and Python SDKs are in development. Until then, use the REST API directly with any HTTP client. The OpenAPI 3.1 spec can be used to auto-generate typed clients with tools like openapi-generator or orval.

Quick Start

Get an API key from your dashboard at app.tag.vu/dashboard/settings/api
Set the Authorization header to Bearer tvk_live_your_key
Send requests to https://api.tag.vu/v1/...
Handle responses using the standard envelope format: { data, meta, error }

Examples

List Your Tags

Retrieve a paginated list of tags for the authenticated user or company.

cURL

curl -X GET "https://api.tag.vu/v1/tags?limit=10" \
  -H "Authorization: Bearer tvk_live_your_api_key" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('https://api.tag.vu/v1/tags?limit=10', {
  headers: {
    'Authorization': 'Bearer tvk_live_your_api_key',
    'Content-Type': 'application/json',
  },
});

const { data, meta } = await response.json();
console.log(`Found ${meta.count} tags`);
data.forEach(tag => console.log(tag.name, tag.status));

Python

import requests

response = requests.get(
    "https://api.tag.vu/v1/tags",
    params={"limit": 10},
    headers={
        "Authorization": "Bearer tvk_live_your_api_key",
        "Content-Type": "application/json",
    },
)

result = response.json()
for tag in result["data"]:
    print(f"{tag['name']}: {tag['status']}")

Create a Tag

Provision a new tag associated with a solution.

cURL

curl -X POST "https://api.tag.vu/v1/tags" \
  -H "Authorization: Bearer tvk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "solutionId": "your-solution-uuid",
    "name": "Office Laptop #42"
  }'

JavaScript

const response = await fetch('https://api.tag.vu/v1/tags', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tvk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    solutionId: 'your-solution-uuid',
    name: 'Office Laptop #42',
  }),
});

const { data: tag } = await response.json();
console.log(`Created tag: ${tag.tag_code}`);

Python

import requests

response = requests.post(
    "https://api.tag.vu/v1/tags",
    headers={
        "Authorization": "Bearer tvk_live_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "solutionId": "your-solution-uuid",
        "name": "Office Laptop #42",
    },
)

tag = response.json()["data"]
print(f"Created tag: {tag['tag_code']}")

Toggle Lost Mode

Enable or disable lost mode on a tag. When enabled, finders see a lost notification and can submit a scan.

cURL

curl -X POST "https://api.tag.vu/v1/tags/{tagId}/lost-mode" \
  -H "Authorization: Bearer tvk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "reason": "Lost at Brussels airport"
  }'

JavaScript

const response = await fetch(`https://api.tag.vu/v1/tags/${tagId}/lost-mode`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tvk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    enabled: true,
    reason: 'Lost at Brussels airport',
  }),
});

const { data } = await response.json();
console.log(`Lost mode: ${data.lost_mode_enabled}`);

Python

import requests

response = requests.post(
    f"https://api.tag.vu/v1/tags/{tag_id}/lost-mode",
    headers={
        "Authorization": "Bearer tvk_live_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "enabled": True,
        "reason": "Lost at Brussels airport",
    },
)

data = response.json()["data"]
print(f"Lost mode: {data['lost_mode_enabled']}")

Resolve a Tag

Look up a tag by its public code. Returns public-facing profile data. No authentication required.

cURL

curl -X GET "https://api.tag.vu/v1/tags/resolve/A1B2-C3D4-EF" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch(
  'https://api.tag.vu/v1/tags/resolve/A1B2-C3D4-EF'
);

const { data: tag } = await response.json();
console.log(tag.name);           // "Max's Collar"
console.log(tag.status);         // "lost"
console.log(tag.has_medical_info); // true

Python

import requests

response = requests.get(
    "https://api.tag.vu/v1/tags/resolve/A1B2-C3D4-EF"
)

tag = response.json()["data"]
print(f"{tag['name']} - Status: {tag['status']}")

Create a Batch

Provision a batch of tags for production. Batches go through the production pipeline (provisioned, programming, QC, shipping).

cURL

curl -X POST "https://api.tag.vu/v1/batches" \
  -H "Authorization: Bearer tvk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tagTypeId": "tag-type-uuid",
    "solutionId": "solution-uuid",
    "quantity": 500,
    "manufacturingModel": "in_house",
    "priority": "normal"
  }'

JavaScript

const response = await fetch('https://api.tag.vu/v1/batches', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tvk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tagTypeId: 'tag-type-uuid',
    solutionId: 'solution-uuid',
    quantity: 500,
    manufacturingModel: 'in_house',
    priority: 'normal',
  }),
});

const { data: batch } = await response.json();
console.log(`Batch ${batch.id}: ${batch.quantity} tags`);

Python

import requests

response = requests.post(
    "https://api.tag.vu/v1/batches",
    headers={
        "Authorization": "Bearer tvk_live_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "tagTypeId": "tag-type-uuid",
        "solutionId": "solution-uuid",
        "quantity": 500,
        "manufacturingModel": "in_house",
        "priority": "normal",
    },
)

batch = response.json()["data"]
print(f"Batch {batch['id']}: {batch['quantity']} tags")

Submit a Scan (Finder)

Submit a scan event as a finder. Used by the public finder form when someone scans a tag.

cURL

curl -X POST "https://api.tag.vu/v1/scans/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_id": "tag-uuid",
    "tag_code": "A1B2-C3D4-EF",
    "location_text": "Found at Brussels Central Station",
    "location_lat": 50.8453,
    "location_lng": 4.3570,
    "message": "I found your bag near platform 5",
    "finder_name": "Jan"
  }'

JavaScript

const response = await fetch('https://api.tag.vu/v1/scans/submit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tag_id: 'tag-uuid',
    tag_code: 'A1B2-C3D4-EF',
    location_text: 'Found at Brussels Central Station',
    location_lat: 50.8453,
    location_lng: 4.3570,
    message: 'I found your bag near platform 5',
    finder_name: 'Jan',
  }),
});

const { data } = await response.json();
console.log(`Scan recorded: ${data.id}`);

Python

import requests

response = requests.post(
    "https://api.tag.vu/v1/scans/submit",
    json={
        "tag_id": "tag-uuid",
        "tag_code": "A1B2-C3D4-EF",
        "location_text": "Found at Brussels Central Station",
        "location_lat": 50.8453,
        "location_lng": 4.3570,
        "message": "I found your bag near platform 5",
        "finder_name": "Jan",
    },
)

data = response.json()["data"]
print(f"Scan recorded: {data['id']}")

Generate a Typed Client

Use the OpenAPI spec to generate a fully typed API client in any language.

# Download the OpenAPI spec
curl -o tagvu-openapi.json https://api.tag.vu/v1/openapi.json

# Generate a TypeScript client with openapi-generator
npx @openapitools/openapi-generator-cli generate \
  -i tagvu-openapi.json \
  -g typescript-fetch \
  -o ./tagvu-client

# Or use orval for a more opinionated React Query integration
npx orval --input tagvu-openapi.json --output ./src/api