Skip to content
looot docs
Esc
↑↓navigate↵open⌘Jpreview

Catalog overview

What the catalog covers: categories, then platforms, then jobs, each with provider, endpoint and runnable counts. No bearer token needed; every caller gets the same answer, rebuilt only when the catalog revision, a platform key or a fee changes.

It counts the rows the live public catalog lists (GET /v1/public-catalog when it serves the live catalog), with the same row rules and public record checks: hidden slugs, prohibited, mock, unpriced, inactive and disabled rows, and records the public schema refuses, are left out. A category is the vocabulary category of the job’s platform, or other when the platform is not in the vocabulary.

Every level (category, platform, job) carries providerCount (distinct providers), endpointCount, runnableCount (runnable without your own key: keyless, or a platform key exists), cheapestPerCall and cheapestPerResult. The two prices are the lowest provider price plus platform fee, null when nothing is priced that way, and never compared with each other.

The default is depth=summary: totals plus one entry per category, a few KB. depth=full is the whole document, about 490 KB. category or platform narrows the answer to one branch (default depth platforms; depth=jobs lists its jobs) and returns filter in place of totals. topic returns the matching jobs, at most 25. Each view has its own ETag; revalidate with If-None-Match.

GET/v1/catalog/overview
Query parameters
depthany

summary (default): totals and per category counts. platforms: adds each category's platforms. jobs: adds each platform's jobs (a tree). full: each category's platforms[] and flat jobs[] with job.platform. Default platforms when category or platform is given; pass jobs to list the branch jobs. Not allowed with topic.

Allowed:summaryplatformsjobsfull
categorystring

A category id: answers only that category. Unknown: 404 unknown_category.

max length 200
platformstring

A platform id: answers the category holding it with only that platform. Unknown (or not in the given category): 404 unknown_platform.

max length 200
topicstring

Words such as email or phone: answers the jobs whose id, title, platform or category match (the job-first search matcher), best first, at most 25, with truncated. Combines with category and platform.

max length 200
Header parameters
If-None-Matchstring
Responses
200

Catalog overview view: a depth view, or a topic view when topic is given

One of:
CatalogOverview
revisionstringrequired
builtAtstring<date-time>required
depthanyrequired
Allowed:summaryplatformsjobsfull
filterobject

Present only on a narrowed view (category or platform given); such a view has no totals

Show properties
categorystring
platformstring
totalsobject

Whole catalog; only on a view that is not narrowed

Show properties
categoriesintegerrequired
platformsintegerrequired
jobsintegerrequired
providersintegerrequired
endpointsintegerrequired
runnableEndpointsintegerrequired
categoriesobject[]required
Show properties
Array of object
idstringrequired
titlestringrequired
platformCountintegerrequired
jobCountintegerrequired
providerCountintegerrequired

Distinct providers with at least one listed endpoint at this level

endpointCountintegerrequired
runnableCountintegerrequired

Endpoints runnable without your own key (keyless, or a platform key exists)

cheapestPerCallnumber | nullrequired

Lowest per-call price in dollars at this level (provider price plus platform fee); null when nothing is priced per call

cheapestPerResultnumber | nullrequired

Lowest per-result price in dollars at this level (provider price plus platform fee); null when nothing is priced per result

platformsobject[]

Depth platforms, jobs and full, and any view narrowed by platform

Show properties
Array of object
idstringrequired
titlestringrequired
jobCountintegerrequired
providerCountintegerrequired

Distinct providers with at least one listed endpoint at this level

endpointCountintegerrequired
runnableCountintegerrequired

Endpoints runnable without your own key (keyless, or a platform key exists)

cheapestPerCallnumber | nullrequired

Lowest per-call price in dollars at this level (provider price plus platform fee); null when nothing is priced per call

cheapestPerResultnumber | nullrequired

Lowest per-result price in dollars at this level (provider price plus platform fee); null when nothing is priced per result

jobsobject[]

Depth jobs only: this platform's jobs

Show properties
Array of object
idstringrequired
titlestringrequired
providerCountintegerrequired

Distinct providers with at least one listed endpoint at this level

endpointCountintegerrequired
runnableCountintegerrequired

Endpoints runnable without your own key (keyless, or a platform key exists)

cheapestPerCallnumber | nullrequired

Lowest per-call price in dollars at this level (provider price plus platform fee); null when nothing is priced per call

cheapestPerResultnumber | nullrequired

Lowest per-result price in dollars at this level (provider price plus platform fee); null when nothing is priced per result

jobsobject[]

Depth full only: the category's jobs, each naming its platform

Show properties
Array of object
idstringrequired
titlestringrequired
platformstringrequired
providerCountintegerrequired

Distinct providers with at least one listed endpoint at this level

endpointCountintegerrequired
runnableCountintegerrequired

Endpoints runnable without your own key (keyless, or a platform key exists)

cheapestPerCallnumber | nullrequired

Lowest per-call price in dollars at this level (provider price plus platform fee); null when nothing is priced per call

cheapestPerResultnumber | nullrequired

Lowest per-result price in dollars at this level (provider price plus platform fee); null when nothing is priced per result

CatalogOverviewTopic
revisionstringrequired
builtAtstring<date-time>required
topicstringrequired

The topic as matched: lowercased, punctuation folded to spaces

filterobject

Present only on a narrowed view (category or platform given); such a view has no totals

Show properties
categorystring
platformstring
matchCountintegerrequired

Jobs that match before the cap

truncatedbooleanrequired

True when matchCount is over the 25 jobs answered

jobsobject[]required
max items 25
Show properties
Array of object
idstringrequired
titlestringrequired
providerCountintegerrequired

Distinct providers with at least one listed endpoint at this level

endpointCountintegerrequired
runnableCountintegerrequired

Endpoints runnable without your own key (keyless, or a platform key exists)

cheapestPerCallnumber | nullrequired

Lowest per-call price in dollars at this level (provider price plus platform fee); null when nothing is priced per call

cheapestPerResultnumber | nullrequired

Lowest per-result price in dollars at this level (provider price plus platform fee); null when nothing is priced per result

categorystringrequired
platformstringrequired
304

View unchanged since If-None-Match

400

validation_error: error.field names the argument (depth, category, platform or topic) and error.message says what to send

404

unknown_category (error.categories lists the ids) or unknown_platform; error.field names the argument

503

catalog_loading: no catalog snapshot is loaded yet; retry after retry-after seconds. production_runtime_unavailable: this deployment serves no v2 catalog

Try it
Server
Parameters
Request
curl -X GET "https://api.looot.ai/v1/catalog/overview"
Response
{
  "revision": "string",
  "builtAt": "2019-08-24T14:15:22Z",
  "depth": "summary",
  "filter": {
    "category": "string",
    "platform": "string"
  },
  "totals": {
    "categories": 0,
    "platforms": 0,
    "jobs": 0,
    "providers": 0,
    "endpoints": 0,
    "runnableEndpoints": 0
  },
  "categories": [
    {
      "id": "string",
      "title": "string",
      "platformCount": 0,
      "jobCount": 0,
      "providerCount": 0,
      "endpointCount": 0,
      "runnableCount": 0,
      "cheapestPerCall": 0,
      "cheapestPerResult": 0,
      "platforms": [
        {
          "id": "string",
          "title": "string",
          "jobCount": 0,
          "providerCount": 0,
          "endpointCount": 0,
          "runnableCount": 0,
          "cheapestPerCall": 0,
          "cheapestPerResult": 0,
          "jobs": [
            {
              "id": "string",
              "title": "string",
              "providerCount": 0,
              "endpointCount": 0,
              "runnableCount": 0,
              "cheapestPerCall": 0,
              "cheapestPerResult": 0
            }
          ]
        }
      ],
      "jobs": [
        {
          "id": "string",
          "title": "string",
          "platform": "string",
          "providerCount": 0,
          "endpointCount": 0,
          "runnableCount": 0,
          "cheapestPerCall": 0,
          "cheapestPerResult": 0
        }
      ]
    }
  ]
}