Platform Guide | XY Developer Platform

Choose a surface

There are three ways to deliver the automation.

These paths share an organization-scoped API key, but their resources and ownership boundaries are different. Choose the delivery contract first; then use its supporting tools.

1. Install a published agent

A reviewed, productized agent already matches the job.

Discover → install/configure → execute → poll result or review queue.

2. Build a workflow self-service

You need an organization-specific multi-step pipeline.

Describe → test every step → accept → promote → schedule.

3. Ask XY to build an agent

The job needs a component not exposed for self-service, or you want XY to own delivery.

Submit a complete specification → answer clarification → XY publishes and entitles it.

Resource model

Definition, installation, and run are different objects.

Keeping these identities separate prevents the most common integration mistakes. IDs are opaque and organization-scoped.

Object	What it means	What comes next
Agent	A published, versioned business capability.	Create an installation with its setup schema.
Installation	One exact agent version plus sources, configuration, and required connection state.	Wait for ready/degraded, then create executions.
Execution	One asynchronous run of an installation.	Poll status/result and handle any review items.
Planner build	A durable authoring conversation with tested steps and explicit decisions.	Promote the accepted build to a production definition.
Workflow definition	The promoted, reusable production workflow.	Create and operate a recurring schedule.
Workflow run	One execution of a promoted workflow definition.	Read safe phase projections and governed analytics.

Authentication

Create a key for a job, not for everything.

A Marketplace API key is bound to one XY organization and one environment. XY derives tenant identity from the key; never send an organization ID as authority.

Verify a production key

export XY_API_BASE='https://marketplace.prod.xyai.beer/api/v1'
export XY_API_KEY='xy_prod_…'

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

Organization settings → API Keys

An authorized organization user creates, tests, edits, rotates, or revokes a key. The complete value is shown only to the user who created or rotated it and only until the page is left or reloaded. Other administrators see metadata and the public prefix—not each other's plaintext keys. Access to this settings tab is granted by XY for the organization and user.

Job	Typical minimum scopes	Add only when needed
Run a published agent	`agents:read`, `installations:`, `executions:`	`review_items:*`, `metrics:read`
Build a workflow	`planner:read`, `planner:write`	`planner:view`, `planner:control`, `planner:promote`
Author a browser step	`browser:read`, `browser:write`, `planner:write`	`browser:control`, `browser:debug`
Operate production	`schedules:read`, `executions:read`	`schedules:write`, `dashboards:read`, `usage:read`

An asterisk above means the separate read and write scopes. The API-key editor shows the exact current catalog. Analytics access returns aggregate metrics and approved tile data that a partner can render in its own UI. Creating or editing XY dashboard definitions is not part of the partner API.

Build or request

Self-service workflows and XY-built agents are different outputs.

A Planner build creates an organization-owned workflow definition. A custom-agent request starts a separate XY delivery lifecycle. It does not publish the Planner definition into the catalog.

Build it self-service when

Planner can compose browser steps, pure transforms, OCR, control flow, and available integrations.
The required portal credential can be referenced through the credential API.
Your team can review tests, accept each step, and own the promoted definition.

Request XY to build it when

A new connector, webhook, inbox, typed client, or specialized persistence service is required.
The flow needs bespoke operational hardening, reconciliation, monitoring, or human-review behavior.
You want XY to review, publish, version, and support the result as an entitled agent.

1. Submit a custom-agent specification

curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Idempotency-Key: daily-portal-reconciliation-v1" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/agent-requests" \
  --data '{
    "name": "Daily portal reconciliation",
    "systems": ["Source portal", "Destination system"],
    "trigger": "Weekdays at 09:00 America/Los_Angeles",
    "specification": "Read open records, validate required fields, write accepted records, and return a per-record result.",
    "expected_output": {
      "type": "object",
      "required": ["processed", "failed", "results"]
    },
    "completion_criteria": "No record is marked successful until the destination confirms its identifier.",
    "sample_inputs": [{"external_batch_id": "example-001"}]
  }'

2. Poll and answer clarification

# POST returns 202 Accepted, Location, and Retry-After: 5.
curl --fail-with-body \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/agent-requests/${REQUEST_ID}"

# When state is needs_information, answer the XY message.
curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Idempotency-Key: ${REQUEST_ID}-clarification-1" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/agent-requests/${REQUEST_ID}/messages" \
  --data '{"message":"The portal account is customer-owned and uses TOTP."}'

Request state	What the partner does
`submitted / in_progress`	Poll the request URL; XY is triaging, building, or reviewing.
`needs_information`	Read the XY message and reply through the messages route; the reply returns the request to in_progress.
`ready_for_review`	Delivery is built, but publication and organization entitlement are still separate XY review actions.
`available`	Read agent.id and agent.version, then use the normal catalog, installation, and execution APIs.
`rejected / failed`	Read decision and messages. These states are terminal.

Build a custom workflow Open the exact REST schemas Connect an MCP client