Agents

Create Agent Work Item

Start a unit of autonomous work. THE AGENT BEGINS PLANNING IMMEDIATELY.

agent_id selects the planner template. A known id gets its own template; anything else falls back to full, which is why it is an open string rather than an enum - an enum would reject the ad-hoc case the planner explicitly supports.

visibility defaults to private: work started through a key is not visible org-wide unless asked for.

user_email defaults to the identity the key was minted under, so the item belongs to a real person rather than to nobody.

post/agent/work-items

Request

  • Base URL: https://be.graph8.com/api/v1
  • URL: https://be.graph8.com/api/v1/agent/work-items
  • Auth: HTTP bearer

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

agent_idstring required

Which agent owns it. A known id the planner has a template for - onboarding, dialer_setup, sequencer_setup, campaign_run, voice_setup, marketplace, dev_setup - or a free-form value, for which the planner falls back to its full template. Left as an open string for that reason: an enum here would reject the ad-hoc case the planner explicitly supports.

titlestring required
goalstring required

What the agent should achieve.

visibility'shared' | 'private'

private (default) or shared org-wide. The default is the safe one: work started through an API key is not visible to the whole org unless asked for.

entry_pointstring nullable

Per-session override. Unset, the planner reads the org's own signup entry point as the long-term truth - so omitting this is usually right.

subject_account_idstring nullable

Bind the session to a company.

subject_campaign_idstring nullable

Bind the session to a campaign.

session_titlestring nullable

Sidebar title. Defaults to title.

seed_messagestring nullable

First user message, so the session opens on the real request.

skill_modestring nullable

web_search, deep_thinking or research. Biases the planner prompt and model tier. Unknown values are IGNORED by the planner rather than rejected, which is why this is not an enum.

pagestring nullable
source'canvas' | 'bridge' nullable
platform'whatsapp' | 'slack' | 'roam' | 'imessage' nullable
user_emailstring nullable

Whose work item this is. Defaults to the identity the key was minted under.

Response

Successful Response

Changes

No recorded changes to this operation across all 2 revisions of this API.