Actions API

Actions represent unit-of-work operations in Pathbound — emails, LinkedIn messages, internal notes, lifecycle changes, CRM syncs, Slack pings. Actions can be scheduled, executed immediately, or queued for human approval. Most actions are created by agents, but you can also create them directly.

All endpoints require actions:write, except listing/reading which require actions:read.

Action types

The type field is an extensible string. The built-in core types are:

Type	Purpose
email_message	Send an email through a connected identity.
linkedin_connection	Send a LinkedIn connection request with a note.
create_note	Add an internal note on a contact or company.
create_task	Create an internal task.
update_contact	Update properties on a contact.
update_company	Update properties on a company.
update_lifecycle_stage	Audited lifecycle stage transition.
escalate_to_human	Pause for human review with a reason.
sync_to_crm	Push contact/company state to a connected CRM.
send_slack_message	Send a Slack message via the connected workspace.
resend_send_email	Send a transactional email via Resend.
resend_create_contact	Create a contact in your Resend audience.
resend_create_broadcast	Create a Resend broadcast.
mcp_tool_call	Invoke a configured external MCP tool.

New integrations register additional string types via the executor registry, so the list above is not exhaustive.

Action statuses

scheduled, pending_approval, approved, auto_approved, rejected, running, completed, failed, cancelled.

---

Create an Action

POST /v1/actions

Required scope: actions:write

Request Body

Field	Type	Required	Description
type	string	yes	Action type (see above).
params	object	yes	Type-specific parameters (see Action params).
identity_id	string	yes	Identity to perform the action as.
direct	boolean	no	Execute immediately without scheduling.
scheduled_time	string	no	ISO 8601 timestamp for scheduled execution.
description	string	no	Human-readable description.
require_approval	boolean	no	If true, the action queues as pending_approval.
list_id	string	no	Associated list ID.
item_id	string	no	Associated list item ID.

Example — send an email

curl -X POST https://api.pathbound.ai/v1/actions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email_message",
    "params": {
      "email": "[email protected]",
      "subject": "Following up",
      "message": "Hi — circling back on yesterday's demo.",
      "contact_id": "ct_abc"
    },
    "identity_id": "id_123",
    "require_approval": true
  }'

Response — 200 OK

{
  "status": "success",
  "action_id": "act_abc123",
  "action_summary": "Email to [email protected] queued for approval"
}

Action params

The shape of params depends on type:

• email_message — { email, subject, message, html?, cc?, bcc?, contact_id?, follow_up?, thread_id?, in_reply_to_message_id?, references? }. When contact_id is set, email and subject are auto-resolved. For follow-ups, set follow_up: true (auto-targets the most recent thread) or pass an explicit thread_id from GET /v1/contacts/:contact_id/email-threads.
• linkedin_connection — { linkedin_url, message?, contact_id? }.
• create_note — { content, contact_id }.
• create_task — { title, description?, due_date?, contact_id? }.
• update_contact — { contact_id, properties }.
• update_company — { company_id, properties }.
• update_lifecycle_stage — { contact_id, lifecycle_stage }.
• escalate_to_human — { reason, contact_id? }.
• send_slack_message — { channel, message }.

---

List Actions

GET /v1/actions

Required scope: actions:read

Query Parameters

Parameter	Type	Default	Description
status	string	—	Filter by status.
type	string	—	Filter by action type.
list_id	string	—	Filter by list.
item_id	string	—	Filter by list item.
identity_id	string	—	Filter by identity.
contact_id	string	—	Filter by contact.
company_id	string	—	Filter by company.
agent_id	string	—	Filter by agent that proposed the action.
limit	number	20	Results per page (1–100).
skip	number	0	Number of results to skip.
sort_by	string	—	Field to sort by.
sort_dir	string	desc	Sort direction.

Response — 200 OK

{
  "status": "success",
  "actions": [ /* action objects */ ],
  "pagination": { "total_items": 42, "limit": 20, "skip": 0 }
}

---

Get an Action

GET /v1/actions/:action_id

Required scope: actions:read

Returns the full action object including its current status, logs, and result.

---

Update an Action

PATCH /v1/actions/:action_id

Required scope: actions:write

Only params, scheduled_time, identity_id, description, and require_approval can be changed. Actions that are running, completed, failed, rejected, or cancelled are immutable.

---

Execute an Action

POST /v1/actions/:action_id/execute

Required scope: actions:write

Runs a scheduled or pending action immediately, bypassing its scheduled time.

---

Cancel an Action

POST /v1/actions/:action_id/cancel

Required scope: actions:write

Cancels a scheduled action that has not yet executed.

---

Approve or Reject an Action

POST /v1/actions/:action_id/approve

Required scope: actions:write

Request Body

Field	Type	Required	Description
action	string	yes	One of approve, reject, edit.
comment	string	no	Optional reviewer comment.

POST /v1/actions/:action_id/reject

Equivalent to POST /actions/:action_id/approve with action: "reject".

---

Bulk Approve / Reject

POST /v1/actions/approve/bulk

Required scope: actions:write

Request Body

Field	Type	Required	Description
action	string	yes	One of approve, reject, edit.
action_ids	string[]	yes	Array of action IDs to process.
comment	string	no	Optional reviewer comment.

Response — 200 OK

{
  "status": "success",
  "processed": 12,
  "failed": [],
  "results": [ /* one entry per action_id */ ]
}

---

Bulk Create

POST /v1/actions/bulk

Required scope: actions:write

Create multiple actions in a single request.

Field	Type	Required	Description
actions	object[]	yes	Array of action create payloads.

---

Process Pending Actions

POST /v1/actions/process

Required scope: actions:write

Triggers the worker to drain pending scheduled actions whose scheduled_time has passed.

Query Param	Type	Default	Description
limit	number	20	Max actions to process (1–100).

Useful in CI/test environments where the cron worker isn’t running. In production, the worker drains the queue automatically.

---

Approve / Reject from an Agent Run

Actions proposed by an agent run are addressed by (run_id, contact_id, action_index) rather than a top-level action ID. See the agent run approval endpoints in the Agents API.