DX API Integration Patterns File (.md) for AI-Assisted Pega Development

AI
,
1

Hey Expert Circle community — I wanted to share something that’s been quietly saving me a lot of time across several projects and might be useful to others doing similar work.

The Problem

I’ve been building custom web front-ends, widgets, and extensions that connect to Pega applications via the DX (Constellation) API. If you’ve done this, you know the experience: the official docs get you to “hello world,” but the moment you try to do something real — ETags, multi-step case flows, embedded pages, file uploads, screen flows — you start accumulating hard-won knowledge that isn’t well documented anywhere. And if you’re using AI-assisted coding tools (like Claude via MCP against a live Pega server), the AI doesn’t have that institutional knowledge baked in either. It will confidently write code that works 80% of the time and silently fails the other 20%.

What I Built

I’ve been maintaining a Markdown file called PEGA_DX_API_PATTERNS.md — a curated, project-tested reference of integration patterns for the Pega DX API. It currently covers:

  • Base URL gotcha — why /prweb/api/application/v2 returns 403 and where to find the right path

  • OAuth2 — client credentials vs. password grant, and the “credentials in header vs. body” quirk that trips up a lot of integrations

  • Case IDs — pzInsKey vs. pyID, and why you must URL-encode the full key before using it in a path

  • Case creation — the AllowedStartingFields data transform requirement, what breaks without it, and how to work around it

  • ETags — the full picture: where to get them, when they go stale (including the POST /cases ETag caveat), how to pass them correctly (quotes included), and what a 412 actually means

  • Assignment actions vs. case-level actions — these endpoints are not interchangeable, and using the wrong one is one of the most common mistakes

  • Advancing cases step-by-step — ?viewType=form vs. ?viewType=none, nextAssignmentInfo parsing, final-step handling

  • Resuming in-progress cases — how to re-acquire the editing lock after a page reload

  • Listing cases — why /cases isn’t what you want, and how to use Data Views instead

  • File uploads — the two attachment patterns (pageInstructions vs. attachments[]), and why you should never manually set Content-Type on a multipart upload

  • Error response shapes — Pega returns errors in at least 4 different structures; the file shows how to parse all of them

  • Screen flows — how they work, navigation step IDs vs. action IDs, and why for headless intake forms you’re often better off skipping them entirely

  • Embedded pages — how to find real property names from viewType=page, and how to write to them via pageInstructions

  • Server-side proxy (BFF) patterns — ETag forwarding, injecting the ETag into the JSON response body, and multipart proxy rules

  • Stage jumping — the PUT /cases/{id}/stages/{stageID} pattern for bypassing broken connectors

  • Multiple assignments after a stage jump — filtering ASSIGN-WORKLIST from ASSIGN-WORKBASKET

  • Save-only PATCH — persisting data without advancing the flow (autosave, partial saves)

  • A minimal fetchDx wrapper and a complete call-sequence quick reference

Many patterns are tagged [Verified] — meaning they’ve been tested end-to-end on a live Pega instance.

How I Use It in AI-Assisted Projects

This file is designed specifically for use with AI coding assistants. I use it as a persistent context document that the agent references before writing any DX API code. Here’s the setup I’ve settled on:

1. Add a directive to your project’s CLAUDE.md (or equivalent master instruction file)

At the start of any project that touches the DX API, I add this to the top-level instruction file:

markdown

## Pega DX API

Any time you hit an issue with the Pega DX API, check `PEGA_DX_API_PATTERNS.md` 
in the project root **first** before debugging or guessing. That file is a 
curated, project-tested reference built from real integration experience.

If the answer isn't there, solve the problem, then **add the solution to 
`PEGA_DX_API_PATTERNS.md`** before moving on — so every project gets smarter 
than the last one.

The second instruction is as important as the first — it makes the file self-improving across projects.

2. Drop the file in the project root

The file lives in your project folder at /PEGA_DX_API_PATTERNS.md alongside your CLAUDE.md. Any agent session that reads the project context will pick it up automatically.

3. Let the agent reference it proactively

With the directive in place, the agent will check the patterns file before generating fetch calls, deciding on ETag handling, or selecting endpoints. This significantly reduces the “confidently wrong” code that wastes debugging time.

Results So Far

I’ve used this across three projects (built on two, tested end-to-end on one) and it has noticeably reduced build time on the DX API integration layer. The ETag section alone has probably made the early interaction setup way more streamlined and eliminated significant confusion with the AI.

Important Caveats

A few things you should know before using this:

  • This is not a Pega-supported document. It’s built from my own experience and testing, not from any official Pega engineering source.

  • It may be incomplete or contain errors. It was developed iteratively across projects and is still a WIP. Patterns marked [Verified] have been tested; others have not all been validated in every Pega version or configuration.

  • It was developed specifically in a VS Code / Claude / Pega Server setup using the MCP integration. Your setup may behave differently.

  • Pega version matters. Some patterns call out version-specific behaviors (like data.caseInfo vs caseInfo response nesting). When in doubt, test against your specific instance.

  • Use it as a starting point, not gospel. Treat it the way you’d treat a colleague’s notes — useful, but verify the things that matter.

Get the File

I’m happy to share the current version of PEGA_DX_API_PATTERNS.md.

If you’re doing similar DX API work and have patterns that should be in here — broken auth flows, Cosmos React integration nuances, Pega Infinity version differences — I’d genuinely welcome contributions. The goal is for this to become a community-maintained resource, not a personal cheat sheet.

Would love to hear if anyone else has been maintaining something similar, or has run into patterns not covered here.

2

That’s incredibly impressive @oglej - now I’m itching to try it out!

3

@oglej Very helpful article and want to implement in our project Thank you very much :clap: :100:

4

Sreeram, thanks for the comment. I would be interested to hear if you are able to access the .md file and if it is helpful to you in your project. Please let me know if you have any questions or run into issues.

5

Hi,

we have something similar here constellation-ui-gallery/.github/skills/pega-dx-component-builder at master · pegasystems/constellation-ui-gallery · GitHub

maybe worth to join efforts? :slight_smile:

6

Kamil, I have seen tremendous help from using the constellation UI content in my projects. I have built a constellation extension and currently am working on a widget and it is super helpful. I would very much welcome the opportunity to collaborate!