# ARD Catalog Resolver (`vincesoft/ard-catalog-resolver`) Actor

Resolve and normalize the Agentic Resource Discovery catalog for a domain, including validation, nested catalogs, provenance, and machine-readable errors.

- **URL**: https://apify.com/vincesoft/ard-catalog-resolver.md
- **Developed by:** [VinceSoft](https://apify.com/vincesoft) (community)
- **Categories:** Agents, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.02 / catalog resolution

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What does ARD Catalog Resolver do?

**ARD Catalog Resolver finds and normalizes a domain’s Agentic Resource Discovery catalog.** Give it a hostname or URL and it checks the canonical `/.well-known/ai-catalog.json` location, validates the pinned catalog schema, and returns advertised machine resources with hashes, redirects, provenance, warnings, and stable errors. It is designed for agents asking “What agent resources does this domain advertise?” and can be called through the Apify API, schedules, integrations, or hosted MCP tooling.

The deterministic implementation uses no LLM, browser, proxy, or paid data supplier. Missing and invalid catalogs are useful structured determinations rather than unexplained run crashes.

### Why use ARD Catalog Resolver?

Use it to find a domain’s ARD catalog, resolve `ai-catalog.json`, discover MCP or A2A resources advertised through ARD, or turn nested catalogs into one predictable routing contract. The Actor handles HTTPS normalization, DNS/IP safety, redirect validation, response limits, ARD draft/catalog version separation, strict or permissive validation, nested cycles, duplicates, and deterministic ordering—work a calling agent would otherwise repeatedly implement and debug.

### How to use ARD Catalog Resolver

1. Open the Actor’s Input tab.
2. Enter a public domain such as `example.com`.
3. Leave nested resolution off for the cheapest single-catalog determination, or enable it with a bounded depth.
4. Run the Actor and consume the one dataset item through the Output tab, API, or MCP.

### Input

```json
{
  "domain": "example.com",
  "resolveNested": false,
  "maxNestedDepth": 1,
  "validationMode": "strict"
}
```

`domain` is required. Input paths, queries, and fragments are discarded. `maxNestedDepth` is capped at 3. Strict mode returns no resources from an invalid catalog; permissive mode keeps independently valid entries and preserves their unknown fields under `extensions`.

### Output

```json
{
  "contractVersion": "1.0",
  "ok": true,
  "found": false,
  "request": { "normalizedDomain": "example.com" },
  "catalog": { "httpStatus": 404, "ardSpecVersion": "0.9" },
  "resources": [],
  "warnings": []
}
```

You can download the dataset in formats such as JSON, HTML, CSV, or Excel, though JSON preserves the full nested contract best.

### Data table

| Field | Meaning |
|---|---|
| `ok` | A trustworthy determination completed. |
| `found` | The canonical catalog exists. |
| `catalog` | HTTP, version, hash, schema revision, and redirect facts. |
| `validation` | Stable errors and warnings. |
| `resources` | Deduplicated resources with `url` or embedded `data` delivery. |
| `catalogGraph` | Root-first nested catalog graph. |

### Pricing / Cost estimation

The price is **$0.02 for one `catalog-resolution` event**. A completed found, absent, malformed, or invalid determination is billable. Input rejection and accepted-input network, resource-limit, cancellation, or internal failures are free. Confirm the live Actor details before purchase because platform pricing can change.

### Tips and limits

Keep `resolveNested` disabled unless downstream work needs nested resources. Traversal is limited to depth 3, 20 catalogs, 25 requests, and 5 MiB decoded content. Each response is limited to 1 MiB; redirects and DNS answers are revalidated against public-network policy.

### FAQ, disclaimers, and support

The supported baseline is ARD draft 0.9 with catalog manifest 1.0 at pinned schema revision `5fa2f5aef790b478319f6a3b43adf4661b0ed0e0`. Absence does not mean a domain has no agent capability—only that the canonical ARD catalog was not found. This Actor fetches public machine metadata; users remain responsible for lawful use and applicable site terms. Use the Actor’s Issues tab for reproducible failures or protocol-version requests.

# Actor input Schema

## `domain` (type: `string`):

Public hostname or HTTP(S) URL. Paths, query parameters, and fragments are discarded for discovery.

## `resolveNested` (type: `boolean`):

Traverse entries with type application/ai-catalog+json.

## `maxNestedDepth` (type: `integer`):

Maximum nested catalog depth when traversal is enabled; hard-capped at 3.

## `validationMode` (type: `string`):

Strict rejects unknown fields; permissive reports them as warnings and keeps them under extensions.

## Actor input object example

```json
{
  "domain": "example.com",
  "resolveNested": false,
  "maxNestedDepth": 1,
  "validationMode": "strict"
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset containing the single ARD catalog resolution envelope.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "domain": "example.com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("vincesoft/ard-catalog-resolver").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "domain": "example.com" }

# Run the Actor and wait for it to finish
run = client.actor("vincesoft/ard-catalog-resolver").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "domain": "example.com"
}' |
apify call vincesoft/ard-catalog-resolver --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vincesoft/ard-catalog-resolver"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/XytseNEWWHT3LEe0U/builds/fkCzdDs1et25UfjGW/openapi.json