Worlds / Marketing and ads

Braze API

A local Braze workspace with users, segments, Canvases, campaigns, subscription groups and frequency capping. Test the agent that launches Canvases, updates user attributes and respects caps.

Base path: /
Auth: Bearer REST API key, the world key
Endpoints: 12
Status: Active today

This reference previews the surface the Braze world serves in the closed beta. Paths mirror the public Braze API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_BRAZE_URL`	This world's origin followed by `/`
`WORLDS_API_KEY`	The world key, accepted wherever Braze expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_BRAZE_URL;

const res = await fetch(base + "/users/track", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.WORLDS_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    attributes: [{ external_id: "user_1", first_name: "Ada" }],
  }),
});

API reference

12 of 12

User data

Track attributes, events and purchases for users.

POST/users/trackTrack users
POST/users/export/idsExport users by id
POST/users/deleteDelete users
POST/users/identifyIdentify users

Fields · 4

`external_id`	string	Your id for the user
`attributes`	array	Attribute updates
`events`	array	Custom events
`purchases`	array	Purchase events

Messages

Send messages right away or on a schedule.

POST/messages/sendSend messages
POST/messages/schedule/createSchedule messages
POST/messages/schedule/deleteDelete a scheduled message

Fields · 5

`broadcast`	boolean	Send to a segment
`external_user_ids`	array	Recipients
`campaign_id`	string	Campaign
`messages`	object	Email, push or SMS content
`dispatch_id`	string	Id of the send

Campaigns

Campaign details and analytics.

GET/campaigns/listList campaigns
GET/campaigns/detailsGet campaign details
GET/campaigns/data_seriesGet campaign analytics

Fields · 4

`campaign_id`	string	Campaign id
`name`	string	Name
`last_edited`	string	ISO 8601 timestamp
`tags`	array	Tags

Segments

Groups of users defined by filters.

GET/segments/listList segments
GET/segments/detailsGet segment details

Fields · 4

`id`	string	Segment id
`name`	string	Name
`analytics_tracking_enabled`	boolean	Whether analytics are on
`tags`	array	Tags

Test workflow

Prepare. Select the Braze setup for your workflow and review its starting records, including user data, messages, campaigns.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Trial nudge Active with Trial day 7 entry
Winback still Draft
Old promo Stopped
No user over 3 messages this week
No subscription group changed

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Braze
version: 2
connector: braze
seed: braze-starter
mode: isolated
policy: >
  Launch the trial nudge for Trial day 7 users. Winback stays in Draft until
  its entry audience is Churn risk. Stop the old promo. Respect the 3 per week
  frequency cap.
tasks:
  - id: update-user-attributes-and-subscription-groups
    prompt: Update user attributes and subscription groups
  - id: launch-or-stop-a-canvas-for-a-segment
    prompt: Launch or stop a Canvas for a segment
  - id: trigger-an-api-campaign-for-named-users
    prompt: Trigger an API campaign for named users
expected:
  - Trial nudge Active with Trial day 7 entry
  - Winback still Draft
  - Old promo Stopped
  - No user over 3 messages this week
  - No subscription group changed
scenarios:
  - rate-limited
  - bad-request
  - key-lacks-permission

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-limited`	429 with X-RateLimit-Reset on /users/track
`bad-request`	400 when a trigger property is missing
`key-lacks-permission`	401 when the REST API key is missing the needed permission
`quiet-hours`	Sends are held until quiet hours end

Starting data

Start each run from the same records and relationships. The overview below describes the Braze starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
users	3,000 by external_id, some with email unsubscribed
segments	Trial day 7, Churn risk, Push enabled
Canvases	Onboarding, Winback, Renewal reminder
subscription groups	Product updates email, Promotions push
frequency capping	3 messages per user per week

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

User data records

User data

Track attributes, events and purchases for users.

Field	Type	Meaning / relationship
`external_id`	string	Your id for the user
`attributes`	array	Attribute updates
`events`	array	Custom events
`purchases`	array	Purchase events

json · illustrative record shape

{
  "external_id": "<Your id for the user>",
  "attributes": [],
  "events": [],
  "purchases": []
}

See user data operations

Messages records

Messages

Send messages right away or on a schedule.

Field	Type	Meaning / relationship
`broadcast`	boolean	Send to a segment
`external_user_ids`	array	Recipients
`campaign_id`	string	Campaign
`messages`	object	Email, push or SMS content
`dispatch_id`	string	Id of the send

json · illustrative record shape

{
  "broadcast": false,
  "external_user_ids": [],
  "campaign_id": "<Campaign>",
  "messages": {},
  "dispatch_id": "<Id of the send>"
}

See messages operations

Campaigns records

Campaigns

Campaign details and analytics.

Field	Type	Meaning / relationship
`campaign_id`	string	Campaign id
`name`	string	Name
`last_edited`	string	ISO 8601 timestamp
`tags`	array	Tags

json · illustrative record shape

{
  "campaign_id": "<Campaign id>",
  "name": "<Name>",
  "last_edited": "<ISO 8601 timestamp>",
  "tags": []
}

See campaigns operations

Segments records

Segments

Groups of users defined by filters.

Field	Type	Meaning / relationship
`id`	string	Segment id
`name`	string	Name
`analytics_tracking_enabled`	boolean	Whether analytics are on
`tags`	array	Tags

json · illustrative record shape

{
  "id": "<Segment id>",
  "name": "<Name>",
  "analytics_tracking_enabled": false,
  "tags": []
}

See segments operations

See the Braze world in the catalog