Page Type: Item

Items are structured data entries for building directory sites — tool listings, resource collections, product catalogs, or marketplace pages. Each item has a title, description, and custom attributes like badges, pricing, ratings, and external URLs.

Content Structure

Items use config for structured data instead of markdown:

curl -X POST "https://api.pagegun.com/pages" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_name": "Notion",
    "slug": "notion",
    "subroute": "tools",
    "type": "item",
    "project_id": "proj_abc123",
    "description": "All-in-one workspace for notes, docs, and project management.",
    "og_image_url": "https://example.com/notion-logo.png",
    "config": {
      "badges": [
        { "text": "Freemium", "color": "green" },
        { "text": "Productivity", "color": "blue" }
      ],
      "url": "https://notion.so",
      "attributes": {
        "Category": "Productivity",
        "Pricing": "Free / $8+ per user/mo",
        "Platform": "Web, Mac, Windows, iOS, Android",
        "Rating": "4.8/5"
      }
    }
  }'

Config Fields

Field	Type	Required	Description
`badges`	array	No	Colored badge tags
`badges[].text`	string	Yes	Badge label text
`badges[].color`	string	No	Badge color: `"blue"`, `"green"`, `"red"`, `"yellow"`, `"purple"`, `"gray"`
`url`	string	No	External link URL
`attributes`	object	No	Key-value pairs for custom metadata

Metadata Fields

Field	Type	Required	Description
`page_name`	string	Yes	Item title
`slug`	string	Yes	URL slug
`subroute`	string	Yes	URL path prefix (e.g., `"tools"`)
`type`	string	Yes	Always `"item"`
`description`	string	No	Short description (shown on card and SEO)
`og_image_url`	string	No	Item logo/image URL

How Items Are Displayed

Items appear in two places:

Item detail page at yourdomain.com/{subroute}/{slug} — full item view with all attributes
Items Grid section — card view on a directory page (shows title, description, image, badges)

URL Structure

yourdomain.com/{subroute}/{slug}

Example: An item with subroute: "tools" and slug: "notion" appears at yourdomain.com/tools/notion.

Building a Directory

1. Create a Landing Page with Items Grid

curl -X POST "https://api.pagegun.com/pages" \
  -H "Authorization: Bearer $PAGEGUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_name": "AI Tools Directory",
    "slug": "tools",
    "subroute": "pages",
    "type": "page",
    "project_id": "proj_abc123",
    "config": {
      "sections": [
        {
          "type": "directory-hero",
          "title": "AI Tools Directory",
          "description": "Discover the best AI tools for every use case.",
          "searchPlaceholder": "Search by name or category..."
        },
        { "type": "items-grid", "columns": 3 }
      ]
    }
  }'

2. Add Items

# Add multiple items
for tool in "ChatGPT" "Cursor" "Midjourney"; do
  curl -X POST "https://api.pagegun.com/pages" \
    -H "Authorization: Bearer $PAGEGUN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"page_name\": \"$tool\",
      \"slug\": \"$(echo $tool | tr '[:upper:]' '[:lower:]')\",
      \"subroute\": \"tools\",
      \"type\": \"item\",
      \"project_id\": \"proj_abc123\",
      \"config\": { \"badges\": [{ \"text\": \"AI\", \"color\": \"blue\" }] }
    }"
done

3. Publish Everything

Publish the directory page and all items.

Use Cases

SaaS directories — Tool collections, alternatives pages, comparison sites
Resource libraries — Curated links, learning materials, templates
Marketplaces — Product listings with pricing and ratings
Job boards — Listings with location, salary, and category badges

Tips

Write unique descriptions for each item — duplicate descriptions hurt SEO
Use consistent badge colors across items in the same category
Include og_image_url for visual cards — directories with images convert better
Custom attributes are flexible — use them for any key-value data relevant to your directory

Items Grid Section — Display items in a grid
Directory Hero Section — Search UI for directories
Page Types Overview — Compare all page types