What You Can Do
Discovery
List content types, describe a single content type and its field shapes, list entries by content type with publish-detail metadata.
Read and search
Read a single entry with linked-entry resolution. Re-inspect stored workspace snapshots without re-querying Contentstack.
Authoring
Create entries (JSON RTE, master locale, custom asset fields, taxonomy). Update entries across locales. Preserve formatting and field-level rules so edits don’t collapse rich content.
Assets
Upload assets and reference the returned asset UIDs in entry payloads.
Publishing
Publish and unpublish entries on explicit request. The skill defaults to draft — entries are not published automatically.
Live-page migration
Capture a source URL, assemble a source brief, discover the target content model, upload assets, create linked entries, and QA via the configured preview URL — end to end in one workflow.
Prerequisites
- Admin access to your Contentstack stack to generate a Management Token
- Your stack’s regional CMA host and Stack API Key
- A Gradial organization Administrator role to complete setup
How to Connect
Get your authentication details from Contentstack
- Sign in to Contentstack and open the target stack.
- Go to Settings → Stack and copy the Stack API Key.
- Go to Settings → Tokens → Management Tokens and create a token dedicated to Gradial.
- Scope the token to the operations you want available:
- Read and write on entries, assets, content types, global fields, and taxonomies
- Publish/unpublish if the agent should be able to push live
- Branch- and environment-scoped if you want to limit Gradial’s blast radius
- Do not grant audit log, roles, stack admin, or token admin scopes — Gradial deliberately excludes those endpoints.
- Copy the Management Token.
- Confirm which regional CMA host your stack is on:
| Region | Host |
|---|---|
| North America (default) | api.contentstack.io |
| Europe | eu-api.contentstack.com |
| Australia | au-api.contentstack.com |
| Azure NA | azure-na-api.contentstack.com |
| Azure EU | azure-eu-api.contentstack.com |
| GCP NA | gcp-na-api.contentstack.com |
| GCP EU | gcp-eu-api.contentstack.com |
Add the integration in Gradial
- In Gradial, go to Settings → Integrations.
- Find Contentstack and click + Add.
- Fill in the connection details:
| Field | Value |
|---|---|
| Integration Name | A display name (e.g., Dell Marketing Stack) |
| Management API URL | Your regional CMA host |
| Stack API Key | From step 2 |
| Management Token | From step 2 |
- Click Connect to validate. Gradial probes the CMA and discovers the stack’s branches and environments.
- Fill in the stack-specific config:
| Field | Value |
|---|---|
| Branch | Default branch for CMA calls (typically main) |
| Environment | Default publishing environment (e.g., production) |
| Page Content Type IDs | Comma-separated UIDs for page-like content types (e.g., page, article, landing_page) |
| Preview Base URL (optional) | Host serving rendered preview pages |
| Preview URL Patterns (optional) | Per-content-type URL templates — supports {entry.uid}, {entry.locale}, {entry.<fieldName>} |
- Click Save. Gradial validates the regional host, credentials, and any preview URL patterns at save time.
How It Fits Into Broader Workflows
| Use case | How to use it |
|---|---|
| Content authoring | Author Contentstack pages and components from the same Gradial thread that produced the brief, copy, or designs |
| Live-page migrations | Capture a public source URL, assemble a source brief, discover the target content model, upload assets, and assemble the page as linked entries preserving copy, hierarchy, and links 1:1 |
| Rendered-page QA | Use Gradial preview (via the configured preview URL pattern) to QA the actual rendered page, not just JSON |
| Multi-region stacks | Operate safely across NA, EU, AU, Azure, and GCP stacks by configuring the matching CMA host |
- Run
capture_webpageagainst the source URL to capture cleaned markdown, content chunks, and images. - Discover the target model by listing content types and reading a nearby existing page as the shape reference.
- Upload source images, capturing the returned asset UIDs.
- Create referenced block entries first, then the root page entry, preserving section order and asset references.
- Re-read the root page and verify against the source brief: sections present, copy 1:1, links mapped, images linked.
- Open the Contentstack artifact and confirm the preview URL renders correctly before handing back to the requester.
Operational Notes — Rate Limits
Contentstack’s CMA enforces a notably low rate limit compared to other CMS APIs. Gradial does not currently implement client-side throttling or retry-with-backoff for Contentstack — a 429 from Contentstack surfaces directly as an error.- Bias toward narrow, targeted operations: read a single entry by UID rather than listing entire content types when possible.
- Bulk migrations are quota-fragile: multi-locale writes, mass updates, or migration runs touching many linked blocks can saturate the quota in a single thread. Stage payloads carefully and expect to space work across multiple turns.
- Asset uploads compound the cost: each upload is its own request. Plan uploads alongside entry creation, not as a separate sweep.
- Triage 429s manually: if the agent reports a Contentstack 429, pause the workflow rather than retrying immediately.
- Customer-side quota bumps help: higher Contentstack plans come with higher CMA quotas. Confirm the plan tier supports expected request volume before kicking off bulk migrations.
Security Boundary
Gradial deliberately blocks privileged Contentstack admin operations from the agent surface. The following are not callable through the integration:- Audit log, Roles, Stacks, and Token admin endpoints
/management_tokens,/delivery_tokens,/roles,/stacks/share,/stacks/transfer_ownership