# AGENTS.md — Anypoint Platform API Portal

> Machine-readable API reference for MuleSoft's Anypoint Platform.
> This file is the entry point for AI agents. It explains the site structure,
> discovery mechanisms, and how to resolve references found in skills and specs.

## Quick Start

1. Fetch `https://dev-portal.mulesoft.com/registry.json` to discover all documents
2. Filter by `kind` to find APIs (`oas`), skills (`agent-skill`), or schemas (`json-schema` / `schema-doc`)
3. Use the `href` field to fetch raw source files (OpenAPI YAML, SKILL.md, JSON Schema)
4. Use the `docs` field for rendered HTML documentation

## Site Structure

```
https://dev-portal.mulesoft.com/
├── AGENTS.md              # This file — agent entry point
├── llms.txt               # LLM discovery file (llmstxt.org convention)
├── registry.json          # Document registry (all APIs, skills, schemas)
├── index.html             # Human-readable homepage
├── apis/
│   ├── {slug}.html        # API documentation page
│   └── {slug}/
│       └── api.yaml       # Raw OpenAPI 3.0 spec
├── skills/
│   ├── {slug}.html        # Skill documentation page
│   └── {slug}/
│       └── SKILL.md       # Raw skill definition
└── schemas/
    ├── x-origin.schema.json   # JSON Schema for x-origin extension
    ├── x-origin-schema.md     # x-origin documentation
    ├── jtbd-schema.md         # JTBD skill format documentation
    └── jtbd-template.md       # Template for creating new skills
```

## Registry Format

`registry.json` is a flat JSON array. Each entry has:

| Field | Type | Description |
|---|---|---|
| `$id` | string | Unique URN identifier |
| `kind` | string | `oas`, `agent-skill`, `json-schema`, or `schema-doc` |
| `slug` | string | URL-safe short name |
| `name` | string | Human-readable name |
| `description` | string | Brief description |
| `href` | string | Relative path to raw source file |
| `docs` | string | Relative path to rendered HTML |
| `version` | string | Semantic version (APIs only) |
| `category` | string | Grouping category (APIs only) |
| `apis` | string[] | Referenced API slugs (skills only) |

All `href` and `docs` paths are relative to `https://dev-portal.mulesoft.com/`.

## URN Scheme

Documents are identified by URNs:

- **APIs:** `urn:api:{slug}` — e.g., `urn:api:api-manager`
- **Skills:** `urn:skill:{slug}` — e.g., `urn:skill:deploy-api-with-rate-limiting`
- **Schemas:** `urn:schema:{name}` — e.g., `urn:schema:x-origin`

### Resolving URNs to URLs

| URN Pattern | URL Template |
|---|---|
| `urn:api:{slug}` | `https://dev-portal.mulesoft.com/apis/{slug}/api.yaml` |
| `urn:skill:{slug}` | `https://dev-portal.mulesoft.com/skills/{slug}/SKILL.md` |
| `urn:schema:x-origin` | `https://dev-portal.mulesoft.com/schemas/x-origin.schema.json` |
| `urn:schema:jtbd` | `https://dev-portal.mulesoft.com/schemas/jtbd-schema.md` |

## API Specs (OpenAPI 3.0)

Each API is an OpenAPI 3.0 specification. Key conventions:

- **Operations** have unique `operationId` values in camelCase
- **Parameters** with dynamic enum values use the `x-origin` extension (see schema below)
- **Server URLs** use `{region}` variable for multi-region support
- **Authentication** is via Bearer token or OAuth2 client credentials (see [Authentication](#authentication) below)

### Authentication

All APIs require a Bearer token. There are two ways to obtain one, both via the **Access Management API** (`urn:api:access-management`).

#### Option 1: Username & Password (User Token)

```
POST https://anypoint.mulesoft.com/accounts/api/login
Content-Type: application/json

{"username": "<username>", "password": "<password>"}
```

- **operationId:** `createLogin`
- **Response:** `{"access_token": "...", "token_type": "bearer"}`
- Use the `access_token` as `Authorization: Bearer <access_token>` on all subsequent requests.

#### Option 2: Client Credentials (Connected App Token)

```
POST https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token
Content-Type: application/json

{"client_id": "<client_id>", "client_secret": "<client_secret>", "grant_type": "client_credentials"}
```

- **operationId:** `createV2Oauth2Token`
- **Response:** `{"access_token": "...", "token_type": "bearer", "expires_in": 3600}`
- Use the `access_token` as `Authorization: Bearer <access_token>` on all subsequent requests.

#### After Authentication

Once you have a token, retrieve your organization ID by calling:

```
GET https://anypoint.mulesoft.com/accounts/api/me
Authorization: Bearer <access_token>
```

- **operationId:** `listMe`
- The organization ID is at `$.user.organization.id` in the response.
- Most API operations require `organizationId` as a path parameter.

#### Multi-Region Support

Replace the base URL depending on the region:
- **US:** `https://anypoint.mulesoft.com/accounts/api`
- **EU:** `https://eu1.anypoint.mulesoft.com/accounts/api`
- **Regional:** `https://{region}.platform.mulesoft.com/accounts/api`

### x-origin Extension

Parameters whose valid values come from another API's response carry an `x-origin` annotation:

```yaml
x-origin:
  - api: urn:api:access-management
    operation: listEnvironments
    values: "$.data[*].id"
    labels: "$.data[*].name"
```

Full schema: `https://dev-portal.mulesoft.com/schemas/x-origin.schema.json`
Documentation: `https://dev-portal.mulesoft.com/schemas/x-origin-schema.md`

## Skills (JTBD Format)

Skills are multi-step API workflows in markdown. Each `SKILL.md` has:

1. **YAML frontmatter** with `name` (kebab-case) and `description` (includes trigger terms for agent matching)
2. **Numbered steps** (`## Step N: Title`) each containing a YAML code block:
   ```yaml
   api: urn:api:{slug}
   operationId: someOperation
   inputs:
     paramName:
       from:
         step: Previous Step Title
         output: outputName
       description: What this parameter is
   outputs:
     - name: resultName
       path: $.jsonpath.expression
       description: What this output represents
   ```
3. **Prose sections**: Overview, Prerequisites, Completion Checklist, Tips, Troubleshooting

### Input Types

| Type | Key | Description |
|---|---|---|
| From previous step | `from.variable` | Variable from an earlier workflow step |
| From API | `from.api` + `from.operation` + `from.field` | Value fetched from an API call |
| User-provided | `userProvided: true` | Must be supplied by the user/agent |
| Literal | `value: "..."` | Static constant |

Full schema: `https://dev-portal.mulesoft.com/schemas/jtbd-schema.md`
Template: `https://dev-portal.mulesoft.com/schemas/jtbd-template.md`

## Common Agent Workflows

### Discover all APIs

```
GET https://dev-portal.mulesoft.com/registry.json
Filter: entries where kind == "oas"
```

### Find skills for a specific API

```
GET https://dev-portal.mulesoft.com/registry.json
Filter: entries where kind == "agent-skill" AND apis contains "{api-slug}"
```

### Execute a skill

1. Fetch the skill: `GET https://dev-portal.mulesoft.com/skills/{slug}/SKILL.md`
2. Parse YAML frontmatter and step blocks
3. For each step, resolve the API spec: `GET https://dev-portal.mulesoft.com/apis/{slug}/api.yaml`
4. Find the operation by `operationId`, build the request from inputs
5. Chain variables between steps — outputs and resolved inputs become available to subsequent steps

### Resolve x-origin dynamic values

1. Read the parameter's `x-origin` array
2. For each source, fetch the referenced API spec via `urn:api:{slug}`
3. Call the referenced `operation` with required parameters
4. Apply JSONPath `values` (and `labels` if present) to extract options

## Current Inventory

**35 APIs** across 15 categories, **13 skills**, 1459 total endpoints.
- [`Access Management API`](apis/access-management/api.yaml) (1.0.0) — Manage access control, identity, and authorization for the Anypoint Platform. Create and configur...- [`Agent Scanner Configuration Service API`](apis/agent-scanner-configuration-service/api.yaml) (0.0.1) — REST API for Agent Scanner Configuration Service- [`AMC Application Manager API`](apis/amc-application-manager/api.yaml) (2.1.3) — Manage alerts, deployments, diagnostics, logs, and schedulers for Runtime Fabric and CloudHub 2.0...- [`Analytics Events Export API`](apis/analytics-event-export/api.yaml) (1.0.0) — Export raw analytics events captured by MuleSoft API gateways. Filter by date range, API, and ver...- [`API Governance Experience API`](apis/anypoint-api-governance/api.yaml) (1.0.0) — API Governance specification crate update modify profiles, and query governance status- [`Anypoint Monitoring Archive API`](apis/anypoint-monitoring-archive/api.yaml) (1.0.0) — List and retrieve archived Anypoint Monitoring metrics and logs organized by organization, enviro...- [`Anypoint MQ Admin API`](apis/anypoint-mq-admin/api.yaml) (1.0.0) — Manage Anypoint MQ destinations, exchanges, bindings, and client authorizations across environments.- [`Courier Messaging API`](apis/anypoint-mq-broker/api.yaml) (1.0.0) — Publish, consume, and acknowledge messages on Anypoint MQ destinations. Manage message locks and ...- [`Anypoint MQ Statistics API`](apis/anypoint-mq-stats/api.yaml) (1.0.0) — Retrieve usage statistics for Anypoint MQ queues, exchanges, and environments.- [`Anypoint Security Policies API`](apis/anypoint-security-policies/api.yaml) (2.0.0) — Manage edge security policies, TLS contexts, virtual servers, and deployments for Anypoint Security.- [`API Designer Experience API`](apis/api-designer-experience/api.yaml) (1.0.0) — Design and manage API specifications and fragments in Design Center. Create projects, manage bran...- [`API Experience Hub Consumer API`](apis/api-experience-hub-consumer/api.yaml) (1.0.0) — Discover APIs and request access from a published API Experience Hub portal.

Use this API to act...- [`API Experience Hub Management API`](apis/api-experience-hub-management/api.yaml) (1.0.0) — Administer API Experience Hub portals, members and the assets they expose.

Use this API as a por...- [`API Manager API`](apis/api-manager/api.yaml) (1.0.0) — Manage APIs, policies, contracts, and SLA tiers within Anypoint Platform. Create, configure, depl...- [`API Platform API`](apis/api-platform/api.yaml) (2.0.0) — Manage APIs, applications, alerts, and classifications in the Anypoint API Platform repository.- [`ARM Monitoring Query API`](apis/arm-monitoring-query/api.yaml) (1.0.0) — Query application metrics and performance data for Mule applications managed through Anypoint Run...- [`ARM REST Services API`](apis/arm-rest-services/api.yaml) (1.23.0) — Manage applications, clusters, server groups, alerts, and deployment actions in Anypoint Runtime Manager.- [`Anypoint Platform Audit Log API`](apis/audit-log-query/api.yaml) (2.0.0) — Query audit log events, actions, and object types for organizations on the Anypoint Platform. Con...- [`Citizen Platform Experience API`](apis/citizen-platform-experience/api.yaml) (0.1.0) — Manage flows, connections, connectors, and metadata for Anypoint Composer.- [`CloudHub API`](apis/cloudhub/api.yaml) (1.0.0) — Manage CloudHub applications, domains, deployments, alerts, and autoscale policies. Monitor dashb...- [`CH2 Management API`](apis/cloudhub-20/api.yaml) (1.0.0) — Manage Private Spaces, connections, egress and ingress configurations, IAM roles, and logs for Cl...- [`Exchange Experience API`](apis/exchange-experience/api.yaml) (2.0.1) — Manage assets, reviews, ratings, and portal customizations in Anypoint Exchange. Search, publish,...- [`Flex Gateway Manager API`](apis/flex-gateway-manager/api.yaml) (0.1.0) — Register, manage, and monitor Flex Gateway instances. Configure runtime settings and track gatewa...- [`Metrics API`](apis/metrics/api.yaml) (1.0.0) — Search and describe metric types for the Anypoint Observability platform.- [`ARM Mule Agent Plugin API`](apis/mule-agent-plugin/api.yaml) (1.0.0) — Manage and monitor a locally running Mule runtime instance through the Mule Agent REST API.- [`Object Store v2 API`](apis/object-store-v2/api.yaml) (1.0.0) — Manage object stores, partitions, and key-value entries across environments and regions in Object...- [`Object Store v2 Statistics API`](apis/object-store-v2-stats/api.yaml) (1.0.0) — Retrieve usage statistics for Object Store v2 stores, environments, and regions.- [`Partner Manager Partners API`](apis/partner-manager-v2-partners/api.yaml) (1.0.1) — Manage partner profiles, certificates, EDI document types, document flows, and deployment configu...- [`Partner Manager v2 Tracking API`](apis/partner-manager-v2-tracking/api.yaml) (1.0.0) — Track and replay B2B message activity, review transmission status, and query message contents in ...- [`Proxies API`](apis/proxies-xapi/api.yaml) (1.0.0) — Manage API proxy deployments and deployment targets for CloudHub, CloudHub 2.0, and Runtime Fabric.- [`Runtime Fabric Management API`](apis/runtime-fabric/api.yaml) (1.0.0) — Manage Runtime Fabric clusters, agents, associations, ingress configurations, and deployment targets.- [`Secrets Manager API`](apis/secrets-manager/api.yaml) (1.0.0) — Manage keystores, truststores, certificates, TLS contexts, and shared secrets across environments...- [`Tokenization Management API`](apis/tokenization-creation-and-mgmt/api.yaml) (1.0.0) — Manage tokenization services, formats, and deployments for data tokenization within Anypoint Security.- [`Tokenization Runtime Service API`](apis/tokenization-runtime-service/api.yaml) (1.0.0) — Tokenize and detokenize sensitive data using configured tokenization services.- [`Usage API`](apis/usage/api.yaml) (1.0.0) — Query and search platform usage meters and consumption metrics for the Anypoint Platform.
### Skills
- [`apply-policy-to-api-instance`](skills/apply-policy-to-api-instance.html) — Apply a policy to an existing API Manager instance. Use when the user wants to
add a policy, enfo...- [`protect-agent-with-policies`](skills/protect-agent-with-policies.html) — Protect an agent by applying a policy from the catalog. Handles multiple
starting points: from an...- [`protect-api-with-policies`](skills/protect-api-with-policies.html) — Protect an API by applying a policy from the catalog. Handles multiple starting
points: from an e...- [`protect-mcp-server-with-policies`](skills/protect-mcp-server-with-policies.html) — Protect an MCP server by applying a policy from the catalog. Handles multiple
starting points: fr...- [`run-agent-scan-and-view-results`](skills/run-agent-scan-and-view-results.html) — Executes an agent scanner and views the discovered AI agents. Use when running an agent scan, che...- [`setup-agent-scanner`](skills/setup-agent-scanner.html) — Creates a scanner configuration to discover AI agents from external platforms like AWS Bedrock, M...- [`discover-portal-apis`](skills/discover-portal-apis.html) — Discover APIs published in an API Experience Hub portal as a portal
consumer. Use when an end use...- [`manage-portal-applications`](skills/manage-portal-applications.html) — Manage the applications that hold API credentials inside an API Experience
Hub portal. Use when a...- [`request-api-access`](skills/request-api-access.html) — Request access to a published API in an API Experience Hub portal by
creating a contract between ...- [`curate-portal-assets`](skills/curate-portal-assets.html) — Curate API assets in an API Experience Hub portal. Use when an admin needs to
publish Exchange as...- [`manage-portal-members-and-prospects`](skills/manage-portal-members-and-prospects.html) — Manage the lifecycle of API Experience Hub portal members and prospects.
Use when an admin needs ...- [`manage-portal-user-groups`](skills/manage-portal-user-groups.html) — Manage the user groups that gate access to APIs and content inside an API
Experience Hub portal. ...- [`anypoint-platform-operations`](skills/anypoint-platform-operations.html) — Discover and navigate the Anypoint Platform API developer portal to find APIs,
agent skills, and ...
### Internal APIs

These APIs are not listed in the public catalog but are referenced by skills and available for agent use. Specs are accessible via their URN (e.g., `https://dev-portal.mulesoft.com/apis/{slug}/api.yaml`).
- [`API Portal Experience API`](apis/api-portal-xapi/api.yaml) (1.0.0) — Retrieve policy templates from Exchange and manage gateway targets across organizations and envir...