Skip to main content

​
Overview

The Tags API allows you to manage tags and organize your snapshots. Tags can be used to categorize and filter archived URLs. Base URL: /api/v1/core/tags

​
Tag Schema

A tag object contains: 
{
  "TYPE": "core.models.Tag",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "created_at": "2024-01-15T10:30:00Z",
  "modified_at": "2024-01-15T10:35:00Z",
  "created_by_id": "1",
  "created_by_username": "admin",
  "name": "Important",
  "slug": "important",
  "num_snapshots": 42,
  "snapshots": []
}

​
Field Descriptions

FieldTypeDescription
idUUIDUnique identifier for the tag
created_atdatetimeWhen the tag was created
modified_atdatetimeWhen the tag was last modified
created_by_idstringUser ID who created the tag
created_by_usernamestringUsername who created the tag
namestringDisplay name of the tag
slugstringURL-safe version of the name
num_snapshotsintNumber of snapshots with this tag
snapshotsarrayList of snapshots (if with_snapshots=true)

​
List Tags

Get all tags in the system. 
curl http://127.0.0.1:8000/api/v1/core/tags \
  -H "X-ArchiveBox-API-Key: your-token-here"

​
Response

Returns a paginated list of tags: 
{
  "total_items": 25,
  "total_pages": 1,
  "page": 0,
  "limit": 200,
  "offset": 0,
  "num_items": 25,
  "items": [
    {
      "TYPE": "core.models.Tag",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Important",
      "slug": "important",
      "num_snapshots": 42,
      ...
    }
  ]
}

​
Get Single Tag

Retrieve a specific tag by ID or slug. 
curl http://127.0.0.1:8000/api/v1/core/tag/important \
  -H "X-ArchiveBox-API-Key: your-token-here"

​
Path Parameters

ParameterDescription
tag_idTag UUID (full or prefix) or tag slug

​
Query Parameters

ParameterTypeDefaultDescription
with_snapshotsbooltrueInclude snapshots array

​
Response

Returns a single tag object with optional snapshots array.

​
Tag Management Endpoints

​
Autocomplete Tags

Search for tags by name (useful for autocomplete UI). 
curl "http://127.0.0.1:8000/api/v1/core/tags/autocomplete/?q=imp" \
  -H "X-ArchiveBox-API-Key: your-token-here"
Response: 
{
  "tags": [
    {
      "id": 1,
      "name": "Important",
      "slug": "important"
    },
    {
      "id": 2,
      "name": "Imported",
      "slug": "imported"
    }
  ]
}
Query Parameters:
  • q - Search query (searches tag names)
  • Returns up to 20 matches if query provided
  • Returns up to 50 tags if no query provided

​
Create Tag

Create a new tag or return existing one with the same name. 
curl -X POST http://127.0.0.1:8000/api/v1/core/tags/create/ \
  -H "X-ArchiveBox-API-Key: your-token-here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Tutorial"}'
Request Body: 
{
  "name": "Tutorial"
}
Response: 
{
  "success": true,
  "tag_id": 1,
  "tag_name": "Tutorial",
  "created": true
}
Tag names are case-insensitive. If a tag with the same name (ignoring case) already exists, it will be returned instead of creating a duplicate.

​
Add Tag to Snapshot

Add a tag to a snapshot. Creates the tag if it doesn’t exist. 
curl -X POST http://127.0.0.1:8000/api/v1/core/tags/add-to-snapshot/ \
  -H "X-ArchiveBox-API-Key: your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "01234567",
    "tag_name": "Important"
  }'
Request Body: 
{
  "snapshot_id": "01234567-89ab-cdef-0123-456789abcdef",
  "tag_name": "Important"  // Use tag_name OR tag_id
  // "tag_id": 1            // Alternative to tag_name
}
Response: 
{
  "success": true,
  "tag_id": 1,
  "tag_name": "Important"
}

​
Remove Tag from Snapshot

Remove a tag from a snapshot. 
curl -X POST http://127.0.0.1:8000/api/v1/core/tags/remove-from-snapshot/ \
  -H "X-ArchiveBox-API-Key: your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "01234567",
    "tag_name": "Important"
  }'
Request Body: 
{
  "snapshot_id": "01234567-89ab-cdef-0123-456789abcdef",
  "tag_name": "Important"  // Use tag_name OR tag_id
  // "tag_id": 1            // Alternative to tag_name
}
Response: 
{
  "success": true,
  "tag_id": 1,
  "tag_name": "Important"
}

​
Common Workflows

​
Organize Snapshots with Tags

import requests

api_key = "your-token-here"
base_url = "http://127.0.0.1:8000/api/v1"
headers = {
    "X-ArchiveBox-API-Key": api_key,
    "Content-Type": "application/json"
}

# Create a tag
response = requests.post(
    f"{base_url}/core/tags/create/",
    headers=headers,
    json={"name": "Research"}
)
tag = response.json()
print(f"Created tag: {tag['tag_name']}")

# Add tag to multiple snapshots
snapshot_ids = ["01234567", "89abcdef", "fedcba98"]
for snapshot_id in snapshot_ids:
    requests.post(
        f"{base_url}/core/tags/add-to-snapshot/",
        headers=headers,
        json={
            "snapshot_id": snapshot_id,
            "tag_id": tag["tag_id"]
        }
    )
    print(f"Tagged snapshot {snapshot_id}")

​
View All Snapshots with a Tag

# Method 1: Get tag with snapshots
curl "http://127.0.0.1:8000/api/v1/core/tag/important?with_snapshots=true" \
  -H "X-ArchiveBox-API-Key: your-token-here"

# Method 2: Filter snapshots by tag
curl "http://127.0.0.1:8000/api/v1/core/snapshots?tag=important" \
  -H "X-ArchiveBox-API-Key: your-token-here"

​
Build a Tag Cloud

import requests

response = requests.get(
    "http://127.0.0.1:8000/api/v1/core/tags",
    headers={"X-ArchiveBox-API-Key": "your-token-here"}
)

tags = response.json()["items"]
tag_cloud = sorted(tags, key=lambda t: t["num_snapshots"], reverse=True)

for tag in tag_cloud[:10]:
    print(f"{tag['name']}: {tag['num_snapshots']} snapshots")

​
Bulk Tag Removal

import requests

api_key = "your-token-here"
base_url = "http://127.0.0.1:8000/api/v1"
headers = {
    "X-ArchiveBox-API-Key": api_key,
    "Content-Type": "application/json"
}

# Get all snapshots with a tag
response = requests.get(
    f"{base_url}/core/tag/temporary?with_snapshots=true",
    headers={"X-ArchiveBox-API-Key": api_key}
)
tag = response.json()

# Remove tag from all snapshots
for snapshot in tag["snapshots"]:
    requests.post(
        f"{base_url}/core/tags/remove-from-snapshot/",
        headers=headers,
        json={
            "snapshot_id": snapshot["id"],
            "tag_id": tag["id"]
        }
    )

​
Tag Autocomplete UI

// JavaScript example for autocomplete UI
const searchTags = async (query) => {
  const response = await fetch(
    `http://127.0.0.1:8000/api/v1/core/tags/autocomplete/?q=${query}`,
    {
      headers: {
        'X-ArchiveBox-API-Key': 'your-token-here'
      }
    }
  );
  const data = await response.json();
  return data.tags;
};

// Use in autocomplete input
const input = document.getElementById('tag-input');
input.addEventListener('input', async (e) => {
  const suggestions = await searchTags(e.target.value);
  // Display suggestions to user
  console.log(suggestions);
});

​
Error Responses

​
404 Not Found - Tag

{
  "succeeded": false,
  "message": "ObjectDoesNotExist: Tag matching query does not exist."
}

​
404 Not Found - Snapshot

{
  "succeeded": false,
  "message": "ObjectDoesNotExist: Snapshot not found"
}

​
400 Bad Request - Missing Name

{
  "succeeded": false,
  "message": "Tag name is required"
}

​
400 Bad Request - Missing Parameters

{
  "succeeded": false,
  "message": "Either tag_name or tag_id is required"
}

​
Tag Naming Guidelines

Best Practices:
  • Use clear, descriptive names
  • Keep names concise (1-2 words)
  • Use title case (e.g., “Important”, “Work Project”)
  • Avoid special characters (slugs are auto-generated)
  • Tag names are case-insensitive but preserve display case
Examples:
  • Good: “Research”, “Important”, “Work”, “Personal”
  • Avoid: “IMPORTANT!!!”, “todo-2024-jan”, “misc”

Snapshots API

Filter snapshots by tags

Crawls API

Crawls can apply tags to all snapshots

Build docs developers (and LLMs) love

Get started for freeTalk to us