Agent Discovery and Catalog | XY Developer Platform

Discover agents

Browse the full page or assess and match tasks.

The Discover API returns XY use-case cards and a separate cached directory of public Microsoft and AWS software listings. XY cards contain names, categories, descriptions, capabilities, suggested outcomes, and information URLs. They are broad use cases, not installed workflows.

Browse, assess, and match agents

# Browse the same agent cards shown in XY Discover.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/discovery/agents"


# Describe the work. A display name and labor baseline are optional; no agent ID is needed.
# XY first scores whether each task can become a workflow, then scores agent matches.
# One task may match several agents, and the same agent may match several tasks.
curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/discovery/matches" \
  --data '{
    "tasks": [
      {
        "name": "Application follow-up",
        "description": "Our team checks incoming applications for missing documents and follows up by email",
        "labor_baseline": {
          "human_hours_per_month": 160,
          "fully_loaded_hourly_cost_usd": 62.5,
          "remaining_human_hours_per_month": 24,
          "work_units_per_month": 800
        }
      },
      {"description": "Our finance team compares bank deposits with open invoices and investigates differences"}
    ]
  }'

How to read the response

# Example fields from the response (full card data omitted):
capability_profile_version                         "2026-09-29"  # XY capability rubric
results[0].task_id                                 "task-1"      # XY-generated handle
results[0].agentizability.score                    0.91           # feasibility, not effort saved
results[0].agentizability.label                    "high"
results[0].agentizability.reason                   "Digital inputs and a clear outcome..."
results[0].labor_value.currency                    "USD"
results[0].labor_value.period                      "month"
results[0].labor_value.addressable_labor_value_usd  10000          # current human labor cost
results[0].labor_value.estimated_net_labor_value_usd 8500          # excludes 24 remaining human hours
results[0].labor_value.estimated_human_effort_reduction 0.85      # 85% fewer human hours, caller assumption
results[0].labor_value.estimated_human_effort_reduction_basis "caller_supplied_remaining_hours"
results[0].matches[0].agent.id                     "missing-information-agent"
results[0].matches[0].agent.icon_url               "https://www.xy.ai/icons/discovery/missing-information-agent.svg"
results[0].matches[0].score                        0.89           # 0-1 catalog fit
results[0].matches[0].fit                          "strong"
results[0].matches[0].matched_capabilities[0]      "Completeness validation"

Third-party alternatives are directory recommendations

GET /discovery/agents keeps XY cards indata and provider listings inexternal_listings.POST /discovery/matches returns task-specific suggestions: alongside any XY matches,external_matches may suggest relevant public Microsoft or AWS software. Each suggestion includes a score, reason, andlisting with its name, publisher,provider, and original source_url. Follow that link to the provider; do not put external listing IDs into an XY workflow request's selected_agent_ids. The result's status still describes the XY match:no_current_match can coexist with third-party suggestions. Those suggestions do not establish XY build feasibility and theiroperating_cost_estimate is always null. XY does not purchase, configure, deploy, or support them through discovery. You can also choose the custom XY request path.

Check the directory's coverage and freshness

external_catalogs reports each provider'sstatus, refreshed_at,catalog_version, listing_count, andcoverage. An unavailable feed is not evidence that no suitable product exists. Available snapshots are no older than two days; snapshots older than two but no older than seven days are marked stale. Older snapshots are withheld. The initial coverage is Microsoft's public agent-search results and AWS's AI Agents & Tools category, not every marketplace product. These marketplaces include apps and tools as well as agents. Matching reads cached metadata rather than contacting those providers for every task. XY cards are returned together; third-party browsing is paginated. Use the returned external_pagination to fetch the next page, optionally filtering by external_provider. Provider availability depends on successful imports in your environment; check the live response before promising either feed in your UI.

Theme an XY icon (CSS)

/* Use the returned XY icon_url as a CSS mask, not a background image.
   SVGs loaded through <img> do not inherit your page's color. */
.agent-icon {
  display: inline-block;
  width: 24px;
  height: 24px;
  color: #000000; /* Replace with any theme color. */
  background-color: currentColor;
  -webkit-mask: var(--agent-icon-url) center / contain no-repeat;
  mask: var(--agent-icon-url) center / contain no-repeat;
}


/* Set --agent-icon-url to url("<returned icon_url>") on this element.
   Use an empty decorative span with aria-hidden="true" next to the card title. */

Cost reference first; customer estimate when workload is known

When comparable XY cost history exists, a match can includematches[].operating_cost_estimate. Without workload volume, itsreference_daily_operating_cost_usd is a daily reference based on existing deployments' observed workloads, not what your customer will pay. If you know roughly how many workflow runs or business items the customer expects each month, sendexpected_runs_per_month or expected_items_per_month. With compatible history, the response instead includesestimated_monthly_operating_cost_usd for that supplied volume. Read its basis and coverage before displaying dollars. A missing estimate is null, never a claim that the work is free. Neither figure is an XY price or guaranteed savings; shared services, implementation, support, and customer-specific configuration are not fully included.

Add current human labor value

Optionally include labor_baseline with the task's current monthly human hours and fully loaded hourly labor cost in USD. XY returns their product aslabor_value.addressable_labor_value_usd. If you also estimate the total human hours that would remain after automation, XY calculates the labor value of the hours that could be reallocated. Monthly work-unit volume optionally gives a value per unit. With the example above, the current labor value is $10,000 per month; after 24 remaining human hours, it is $8,500. These calculations do not affect the matching scores. They describe customer labor value, not an XY price or guaranteed savings. Without a baseline,labor_value is null. A baseline can still be calculated forno_current_match; delivery pricing requires the configuration and scoping step below. Check your environment's live API schema for these optional fields before using them.

Effort reduction uses your estimated hours, not the matching scores

If you supply remaining_human_hours_per_month, XY returnslabor_value.estimated_human_effort_reduction as current human hours minus remaining human hours, divided by current human hours. For 70 hours today and 14 expected to remain each month, the result is 0.8: an estimated 80% reduction in human effort, not 56 hours of agent runtime. The example above returns0.85 from 160 current hours and 24 remaining hours. The basis is caller_supplied_remaining_hours, not measured savings. Discovery calculates from the supplied hours without independently predicting or verifying them. Compare the same workload and quality standard, including all remaining unautomated work, review, exceptions, corrections, and oversight. Remaining hours must be between zero and current hours; zero explicitly assumes no human effort remains. If remaining hours are unknown, omit them: reduction and its basis arenull. This does not block operating-cost estimates. Neither agentizability nor catalog fit supplies a numerical split. Validate your assumption against actual human time and output quality after deployment before treating it as a measured result. If an earlier baseline included only review and escalation, include the other remaining human work before using this fraction.

Configure the match

Continue into the structured request.

A match is a recommendation, not permission to execute another customer's workflow. XY still needs the systems, access, steps, inputs, outputs, and constraints for your organization.

Create a request from a selected match

# Copy task_id and the chosen matches[].agent.id from the match response.
# task_id is generated by XY unless you supplied an optional correlation ID.
# Set REQUEST_IDEMPOTENCY_KEY once per new request; reuse it only for retries.
curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Idempotency-Key: ${REQUEST_IDEMPOTENCY_KEY}" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/agent-requests" \
  --data '{
    "name": "Application document follow-up",
    "discovery_selections": [{
      "id": "task-1",
      "name": "Application follow-up",
      "description": "Our team checks incoming applications for missing documents and follows up by email",
      "selected_agent_ids": ["missing-information-agent"]
    }]
  }'


# If a task returns no_current_match, create the same request without
# discovery_selections and put its description in specification instead.

Customer workflow walkthrough

From a task description to a running workflow.

Capture your customer's requirements using the XY form, your own UI, or MCP. This path delivers a customer-specific XY workflow, not a catalog installation.

Discover and open a request. Describe the task, choose a relevant XY suggestion, and create its request using the calls above. No current match? You can still ask XY to build a custom workflow. Keep the request ID and returned form link; approved bulk submission creates one of each per task.
Complete the form your way. Use the XY form, your own form built from OpenAPI, or MCP. Read GET /agent-requests/{request_id}for workflow_spec and unanswered open_fields. Save answers with PATCH on that request, then share them withPOST /agent-requests/{request_id}/publish. Use the current quoted version in If-Matchand an Idempotency-Key for each change. MCP offerscustom_agent_request_get,custom_agent_request_update, andcustom_agent_request_publish for the same steps. Credential fields take authorized vault references, not passwords or API keys.
Follow delivery using the same request ID. XY reviews the requirements and builds the workflow. If more information is needed, read XY's messages and update and publish the same form. Subscribe to request status events or poll the request. custom_request.deployed and the request's/deployments response identify the delivered workflow. Publication is not execution: agree its run or schedule separately using theworkflow operations.
Receive run and review notifications. Add the delivered workflow to your receiver using the webhook configuration. Choose workflow.run.completed andworkflow.run.failed for outcomes,workflow.daily_results for daily summaries, andworkflow.human_review_required for items entering your selected review states. These states come from the workflow's configured queue. A completed run can still leave items awaiting review; an error alone is not a review alert.
Read recorded usage. Use the original request's/usage route or custom_agent_request_usagefor run counts and recorded token totals. Subscribe tocustom_request.usage_updated for completed UTC-day snapshots. Build and test usage is excluded. These totals are not a bill or a measure of business success.

Resource model

Agent → installation → execution.

The published-agent catalog below is separate from Discover. It advertises an executable productized agent; your organization creates an installation, and each run creates an execution.

Agent

A stable public ID with a semantic version and reviewed JSON schemas.

Installation

One exact version plus organization configuration, sources, and connection state.

Execution

One idempotently created asynchronous run with its own public status and result.

Published catalog

Let the catalog tell your client what is supported.

Do not copy setup or execution fields from an example. Read the current agent detail and validate your payload against the returned schema.

List and inspect agents

# This separate catalog contains only published versions entitled to your organization.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/agents"


# Agent detail is the contract for setup, input, output, errors, sources,
# required connections, triggers, and supported metrics.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/agents/${AGENT_ID}"

Install and connect

Follow state instead of guessing the next call.

Installation setup is agent-specific. Creation may immediately provision, start source indexing, or return action_required with an exact next action.

Create and poll an installation

curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Idempotency-Key: ${AGENT_ID}-installation-v1" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/agents/${AGENT_ID}/installations" \
  --data @installation-setup.json


# Always follow the returned state and next_action instead of assuming readiness.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/installations/${INSTALLATION_ID}"

Complete a required connection

# Only when the installation returns an authorization next_action.
curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/installations/${INSTALLATION_ID}/authorization-actions" \
  --data '{"connection":"gmail"}'


# Send/open the returned short-lived hosted connection URL for an administrator.
# Then poll the installation or list its authorization actions.

Knowledge Base installations use source actions rather than OAuth. See the dedicated guide for URL crawling, signed file uploads, readiness, and querying.

Execute

Create once, then poll the public execution.

Execution input must match the installed version's live input schema. Use your own stable partner_reference for reconciliation and a unique idempotency key for safe retries.

Start and read one execution

curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Idempotency-Key: partner-job-1842" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/installations/${INSTALLATION_ID}/executions" \
  --data '{
    "input": {},
    "metadata": {"partner_reference": "job-1842"}
  }'


curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/executions/${EXECUTION_ID}"

Human review

Decisions have real downstream effects.

Some agent results create work that a person or partner system must decide. Review items are the same operational queue XY users act on, not a recommendation-only copy.

List and decide review items

# Read open work produced by entitled agent executions.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/review-items?installation_id=${INSTALLATION_ID}"


# Decisions are per item; partial success is a normal batch result.
curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/review-items/decisions" \
  --data '{
    "item_ids": ["item_REPLACE"],
    "decision": "approve",
    "note": "Validated against the source record."
  }'

Observe

Read results, phases, and approved metrics.

Use the execution and installation identities you already have. Public observability returns a stable, safe phase projection without exposing workflow inputs, outputs, or internal capabilities.

Metrics for your own reporting UI

# Stable aggregate facts. FROM and TO are timezone-aware ISO-8601 timestamps.
# FROM must be earlier than TO and the interval must fit the server's maximum window.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/installations/${INSTALLATION_ID}/metrics?from=${FROM}&to=${TO}"


# Discover XY's approved metric views for this installation.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/installations/${INSTALLATION_ID}/metrics/dashboards"


# Receive visualization metadata plus aliased data rows. Render it in your UI.
# Metric-view FROM_DATE and TO_DATE are YYYY-MM-DD calendar dates. Supply both,
# keep FROM_DATE on or before TO_DATE, and stay within the maximum window.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/installations/${INSTALLATION_ID}/metrics/dashboards/operations?from=${FROM_DATE}&to=${TO_DATE}"

Execution phases

Read safe progress for one public execution without mutating its run.

Installation metrics

Measure the installed agent's approved organization-scoped outcomes.

Agent metrics

Aggregate across entitled installations using the advertised metrics profile.

Configure your own Knowledge Base agent Build a custom workflow instead Open exact agent schemas