platform-agentsetup-categories-fetch

platform-agentsetup-categories-fetch

Fetch prompt categories from the Agentic Setup Categories Connect API on a connected Salesforce org.

Scope

In scope:

• Calling GET /services/data/{apiVersion}/agenticsetup/categories via SF CLI
• Passing the fetchPrompts query parameter to include nested prompts
• Parsing and presenting the JSON response (categories, labels, prompts)
• Handling errors (403 when feature is disabled, auth failures)

Out of scope — delegate elsewhere:

• Creating or modifying prompt categories → not supported via this API (read-only)
• Org authentication setup → use sf org login separately
• Permission set assignment → assigning-permission-set

---

Required Inputs

The agent needs:

• A connected org (already authenticated via sf org login)
• Optionally: whether to include nested prompts (fetchPrompts=true)
• Optionally: target API version (default: v67.0). Replace v67.0 in the URL with the user-specified version if provided.

---

Workflow

1. Verify org connectivity

sf org display --json

Confirm the org is authenticated and extract the instance URL. If no default org is set, ask the user which org to target with --target-org.

2. Call the Categories API

Basic call (categories only):

sf api request rest /services/data/v67.0/agenticsetup/categories --method GET

With nested prompts:

sf api request rest "/services/data/v67.0/agenticsetup/categories?fetchPrompts=true" --method GET

3. Parse and present the response

The API returns a JSON object with a categories array. Each category has name, label, and prompts fields. See references/api-response-schema.md for the full response structure and examples for both fetchPrompts=true and fetchPrompts=false.

Present the results clearly:

• List categories with their name and label
• If fetchPrompts=true was used, show nested prompts under each category
• Note any categories with empty prompts arrays (means no prompts exist for that category)

4. Handle errors

| Error | Meaning | Action |

|-------|---------|--------|

| Success (exit 0) | 200 OK | Parse and display results |

| FUNCTIONALITY_NOT_ENABLED | Feature not enabled for this org/user | Tell user the Agentic Setup Categories feature needs to be enabled — check Setup > Einstein/Agentforce |

| INVALID_SESSION_ID | Session expired | Re-authenticate with sf org login |

| NOT_FOUND | Endpoint not found | API version too old or feature not deployed to this org |

---

Rules / Constraints

| Rule | Rationale |

|------|-----------|

| Always use sf api request rest — never curl or raw HTTP | curl bypasses ~/.sfdx session tokens and requires manual Authorization headers, making it brittle |

| NEVER use SOQL queries | Categories are NOT in standard objects — only available via this Connect REST API |

| NEVER generate files (LWC, Apex, XML) | This is a data-fetching task, not a code generation task |

| Default to v67.0 unless user specifies | This is the min-version where the endpoint was introduced |

| Don't pass fetchPrompts unless asked | Reduces payload size; prompts can be large |

| Categories are sorted by label | The API returns them alphabetically — don't re-sort |

| Prompts are sorted by text | Within each category, prompts come alphabetically |

---

Output Expectations

When finishing, present:

1. Number of categories returned
2. Category list — name and label for each
3. Prompts (if requested) — nested under their category
4. Any errors encountered with suggested fixes

---

Reference File Index

| File | When to read |

|------|--------------|

| references/api-response-schema.md | When you need to understand the full response structure and field descriptions |