Published Agents | XY Developer Platform

Resource model

Agent → installation → execution.

The catalog advertises an agent. Your organization creates an installation. Each request creates a separate 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.

Discover

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

# The 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.

Set up a Knowledge Base agent Build a custom workflow instead Open exact agent schemas