Tilt API

https://api.heytilt.com

Authorization: Bearer YOUR_API_KEY

curl -X POST https://api.heytilt.com/api/v1/plans \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "domain": "kohls.com",
    "task": "black t-shirts in medium size sorted by price low to high"
  }'

curl -X POST https://api.heytilt.com/api/v1/plans \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "domain": "kohls.com",
    "task": "black t-shirts in medium size",
    "plan_types": ["deep_links"]
  }'

const response = await fetch("https://api.heytilt.com/api/v1/plans", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    domain: "kohls.com",
    task: "black t-shirts in medium size sorted by price low to high",
  }),
});

const plan = await response.json();
console.log(plan.url);

import requests

response = requests.post(
    "https://api.heytilt.com/api/v1/plans",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    },
    json={
        "domain": "kohls.com",
        "task": "black t-shirts in medium size sorted by price low to high",
    },
)

plan = response.json()
print(plan["url"])

{
  "url": "https://www.kohls.com/catalog/mens-t-shirts.jsp?CN=...",
  "description": "Search for 't-shirts' filtered by Color: Black, Size: Medium",
  "plan_types": ["deep_links", "guidance"],
  "alternatives": [
    {
      "url": "https://www.kohls.com/catalog/...",
      "description": "Without size filter"
    }
  ],
  "guidance": {
    "site": "Kohls uses faceted navigation.",
    "filter_visual_confirmation": "Selected filters appear as chips above the grid",
    "sort_visual_confirmation": "Current sort is highlighted in the dropdown"
  }
}

{
  "url": "https://www.example.com/mortgage-calculator",
  "description": "Navigate to mortgage calculator and follow guidance",
  "url_linking_supported": false,
  "plan_types": ["deep_links"],
  "guidance": {
    "navigation": "1. Enter loan amount...\n2. Set interest rate...",
    "site": "Calculator inputs are client-side only"
  }
}

curl -X GET "https://api.heytilt.com/api/v1/domains?domain=kohls.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "domain": "kohls.com",
  "status": "indexed",
  "site_name": "Kohl's",
  "search_engines": [
    { "id": 1, "name": "Product Search", "status": "complete" },
    { "id": 2, "name": "Store Locator", "status": "error" }
  ]
}

curl -X POST https://api.heytilt.com/api/v1/domains \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"domain": "kohls.com"}'

type PlanType = "deep_links" | "guidance" | "refinements";

interface PlanRequest {
  domain: string;
  task: string;
  plan_types?: PlanType[];
  debug_level?: "verbose";
}

interface PlanResponse {
  url: string;
  description: string;
  url_linking_supported?: boolean;
  plan_types: PlanType[];
  alternatives?: Array<{ url: string; description: string }>;
  supplemental_strategies?: Array<{
    url?: string;
    description: string;
    results?: Array<{ url: string; title: string; description: string; commentary?: string }>;
  }>;
  guidance?: {
    site?: string;
    selection?: string;
    search_engine?: string;
    navigation?: string;
    task_specific?: string;
    filter_visual_confirmation?: string;
    sort_visual_confirmation?: string;
  };
  refinements?: {
    status: "coming_soon";
    description: string;
  };
  debug_log?: Array<{ step: string; timestamp: string; details?: any; error?: string }>;
}

type IndexingStatus = "indexed" | "error" | "indexing" | "queued" | "none";

interface DomainStatusResponse {
  domain: string;
  status: IndexingStatus;
  site_name?: string | null;
  search_engines?: Array<{ id: number; name: string | null; status: string | null }>;
}

interface DomainQueueRequest {
  domain?: string; url?: string; force?: boolean;
}

interface DomainQueueResponse {
  domain: string; status: IndexingStatus; message: string;
}

interface ApiError {
  error: string; details?: string;
}