Actions API

Execute business actions (verbs) with Subject-Verb-Object semantic patterns. Actions represent operations performed by subjects on objects in your business.

Overview

Business actions are semantic operations that:

Follow Subject-Verb-Object (SVO) patterns
Represent real-world business operations
Track who did what to whom
Include context and timestamps
Can trigger workflows and events

import { createBusinessApi } from 'business-as-code'

const api = createBusinessApi({
  apiKey: process.env.APIS_DO_KEY,
})

// Execute an action
const action = await api.actions.execute({
  verb: 'purchase',
  subject: 'cust-123',
  object: 'prod-456',
  timestamp: new Date().toISOString(),
  context: {
    quantity: 2,
    price: 99.99,
  },
})

execute()

Execute a business action.

Signature

execute(
  action: Omit<BusinessAction, 'id'>
): Promise<BusinessAction>

Parameters

Parameter	Type	Required	Description
action	ActionContext	Yes	Action definition without ID

Action Properties

Property	Type	Required	Description
verb	string	Yes	Action verb (e.g., 'purchase', 'create', 'update')
subject	string \| BusinessResource	Yes	Who performs the action
object	string \| BusinessResource	No	What the action is performed on
timestamp	string	No	When the action occurred (ISO 8601)
status	string	No	Action status ('pending', 'in_progress', 'completed', 'failed')
context	object	No	Additional context data

Returns

Promise that resolves to the executed BusinessAction with generated ID.

Example

// Customer purchases product
const action = await api.actions.execute({
  verb: 'purchase',
  subject: { $type: 'Customer', $id: 'cust-123' },
  object: { $type: 'Product', $id: 'prod-456' },
  timestamp: new Date().toISOString(),
  status: 'completed',
  context: {
    quantity: 2,
    price: 99.99,
    total: 199.98,
    paymentMethod: 'credit-card',
  },
})

console.log('Action executed:', action.id)

Common Action Verbs

Commerce Verbs

Execute commerce-related business actions:

// Purchase → https://actions.org.ai/purchase.Product
await api.actions.execute({
  verb: 'purchase',
  subject: 'cust-123',
  object: 'prod-456',
})

// Order → https://actions.org.ai/order.Product
await api.actions.execute({
  verb: 'order',
  subject: 'cust-123',
  object: 'prod-456',
  context: { quantity: 5 },
})

// Pay → https://actions.org.ai/pay.Invoice
await api.actions.execute({
  verb: 'pay',
  subject: 'cust-123',
  object: 'invoice-789',
  context: { amount: 999.0, method: 'credit-card' },
})

// Ship → https://actions.org.ai/ship.Order
await api.actions.execute({
  verb: 'ship',
  subject: 'warehouse-west',
  object: 'order-456',
  context: { carrier: 'FedEx', tracking: 'TRACK-123' },
})

// Return → https://actions.org.ai/return.Order
await api.actions.execute({
  verb: 'return',
  subject: 'cust-123',
  object: 'order-456',
  context: { reason: 'defective', condition: 'unopened' },
})

Semantic Abstractions: purchase.Product · order.Product · pay.Invoice · ship.Order · return.Order

Content Verbs

Execute content management actions:

// Create → https://actions.org.ai/create.Article
await api.actions.execute({
  verb: 'create',
  subject: 'user-789',
  object: 'article-123',
})

// Publish → https://actions.org.ai/publish.Article
await api.actions.execute({
  verb: 'publish',
  subject: 'editor-456',
  object: 'article-123',
  context: { publishDate: '2024-10-27T10:00:00Z' },
})

// Edit → https://actions.org.ai/edit.Article
await api.actions.execute({
  verb: 'edit',
  subject: 'user-789',
  object: 'article-123',
  context: { changes: ['title', 'content'] },
})

// Delete → https://actions.org.ai/delete.Article
await api.actions.execute({
  verb: 'delete',
  subject: 'admin-101',
  object: 'article-123',
  context: { reason: 'outdated' },
})

Semantic Abstractions: create.Article · publish.Article · edit.Article · delete.Article

Relationship Verbs

Execute relationship and collaboration actions:

// Follow → https://actions.org.ai/follow.User
await api.actions.execute({
  verb: 'follow',
  subject: 'user-123',
  object: 'user-456',
})

// Subscribe → https://actions.org.ai/subscribe.Newsletter
await api.actions.execute({
  verb: 'subscribe',
  subject: 'user-123',
  object: 'newsletter-marketing',
  context: { frequency: 'weekly' },
})

// Assign → https://actions.org.ai/assign.Task
await api.actions.execute({
  verb: 'assign',
  subject: 'manager-789',
  object: 'task-456',
  context: { assignee: 'emp-101', dueDate: '2024-10-30' },
})

// Invite → https://actions.org.ai/invite.Organization
await api.actions.execute({
  verb: 'invite',
  subject: 'user-123',
  object: 'org-456',
  context: { role: 'member', expiresIn: 7 },
})

Semantic Abstractions: follow.User · subscribe.Newsletter · assign.Task · invite.Organization

Communication Verbs

Execute communication and sharing actions:

// Send → https://actions.org.ai/send.Email
await api.actions.execute({
  verb: 'send',
  subject: 'user-123',
  object: 'email-456',
  context: { to: '[email protected]', subject: 'Hello' },
})

// Reply → https://actions.org.ai/reply.Email
await api.actions.execute({
  verb: 'reply',
  subject: 'user-456',
  object: 'email-456',
  context: { body: 'Thanks for reaching out!' },
})

// Share → https://actions.org.ai/share.Document
await api.actions.execute({
  verb: 'share',
  subject: 'user-123',
  object: 'document-789',
  context: { with: 'user-456', permissions: 'view' },
})

Semantic Abstractions: send.Email · reply.Email · share.Document

list()

List all actions, optionally filtered.

Signature

list(): Promise<BusinessAction[]>

Returns

Promise that resolves to an array of BusinessAction objects.

Example

const actions = await api.actions.list()

console.log(`Found ${actions.length} actions`)

// Filter by verb
const purchases = actions.filter((a) => a.verb === 'purchase')

// Filter by subject
const userActions = actions.filter((a) => a.subject === 'user-123')

// Filter by date
const recentActions = actions.filter((a) => {
  const actionDate = new Date(a.timestamp)
  const oneDayAgo = new Date(Date.now() - 86400000)
  return actionDate > oneDayAgo
})

get()

Retrieve a specific action by ID.

Signature

get(id: string): Promise<BusinessAction>

Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique identifier of the action

Returns

Promise that resolves to a BusinessAction object.

Example

const action = await api.actions.get('action-abc123')

console.log('Action:', action.verb)
console.log('Subject:', action.subject)
console.log('Object:', action.object)
console.log('Status:', action.status)
console.log('Context:', action.context)

Subject-Verb-Object Patterns

Basic SVO

// Subject: Customer
// Verb: purchases
// Object: Product
await api.actions.execute({
  verb: 'purchase',
  subject: { $type: 'Customer', $id: 'cust-123' },
  object: { $type: 'Product', $id: 'prod-456' },
})

SV Pattern (No Object)

// Subject: User
// Verb: login
await api.actions.execute({
  verb: 'login',
  subject: { $type: 'User', $id: 'user-123' },
  context: { ipAddress: '192.168.1.1', userAgent: 'Mozilla/5.0...' },
})

Complex Patterns

// Employee assigns Task to another Employee
await api.actions.execute({
  verb: 'assign',
  subject: { $type: 'Employee', $id: 'emp-manager' },
  object: { $type: 'Task', $id: 'task-123' },
  context: {
    assignee: { $type: 'Employee', $id: 'emp-developer' },
    dueDate: '2024-10-30',
    priority: 'high',
  },
})

// Organization hires Person
await api.actions.execute({
  verb: 'hire',
  subject: { $type: 'Organization', $id: 'org-acme' },
  object: { $type: 'Person', $id: 'person-jane' },
  context: {
    position: 'Senior Developer',
    startDate: '2024-11-01',
    salary: 150000,
    department: 'Engineering',
  },
})

Complete Examples

E-commerce Purchase Flow

// 1. Customer adds product to cart
await api.actions.execute({
  verb: 'add',
  subject: { $type: 'Customer', $id: 'cust-123' },
  object: { $type: 'Product', $id: 'prod-laptop' },
  context: {
    container: { $type: 'ShoppingCart', $id: 'cart-abc' },
    quantity: 1,
  },
})

// 2. Customer proceeds to checkout
await api.actions.execute({
  verb: 'checkout',
  subject: { $type: 'Customer', $id: 'cust-123' },
  object: { $type: 'ShoppingCart', $id: 'cart-abc' },
})

// 3. Customer pays for order
await api.actions.execute({
  verb: 'pay',
  subject: { $type: 'Customer', $id: 'cust-123' },
  object: { $type: 'Order', $id: 'order-789' },
  context: {
    amount: 1299.0,
    currency: 'USD',
    method: 'credit-card',
    transactionId: 'txn-xyz',
  },
})

// 4. Warehouse ships order
await api.actions.execute({
  verb: 'ship',
  subject: { $type: 'Organization', $id: 'warehouse-west' },
  object: { $type: 'Order', $id: 'order-789' },
  context: {
    carrier: 'FedEx',
    trackingNumber: 'TRACK-123456',
    estimatedDelivery: '2024-10-30',
  },
})

// 5. Customer receives order
await api.actions.execute({
  verb: 'receive',
  subject: { $type: 'Customer', $id: 'cust-123' },
  object: { $type: 'Order', $id: 'order-789' },
  context: {
    deliveryDate: '2024-10-29',
    condition: 'good',
  },
})

// 6. Customer reviews product
await api.actions.execute({
  verb: 'review',
  subject: { $type: 'Customer', $id: 'cust-123' },
  object: { $type: 'Product', $id: 'prod-laptop' },
  context: {
    rating: 5,
    title: 'Excellent laptop!',
    body: 'Great performance and build quality.',
    verified: true,
  },
})

Content Publishing Workflow

// 1. Author creates article
await api.actions.execute({
  verb: 'create',
  subject: { $type: 'Person', $id: 'author-123' },
  object: { $type: 'Article', $id: 'article-456' },
  context: {
    title: 'Getting Started with Business-as-Code',
    draft: true,
  },
})

// 2. Author edits article
await api.actions.execute({
  verb: 'edit',
  subject: { $type: 'Person', $id: 'author-123' },
  object: { $type: 'Article', $id: 'article-456' },
  context: {
    changes: ['content', 'images'],
    revision: 3,
  },
})

// 3. Author submits for review
await api.actions.execute({
  verb: 'submit',
  subject: { $type: 'Person', $id: 'author-123' },
  object: { $type: 'Article', $id: 'article-456' },
  context: {
    to: { $type: 'Person', $id: 'editor-789' },
    message: 'Ready for review',
  },
})

// 4. Editor reviews article
await api.actions.execute({
  verb: 'review',
  subject: { $type: 'Person', $id: 'editor-789' },
  object: { $type: 'Article', $id: 'article-456' },
  context: {
    approved: true,
    feedback: 'Looks great! Minor edits needed.',
  },
})

// 5. Author addresses feedback
await api.actions.execute({
  verb: 'edit',
  subject: { $type: 'Person', $id: 'author-123' },
  object: { $type: 'Article', $id: 'article-456' },
  context: {
    changes: ['grammar', 'formatting'],
    addressesFeedback: true,
  },
})

// 6. Editor publishes article
await api.actions.execute({
  verb: 'publish',
  subject: { $type: 'Person', $id: 'editor-789' },
  object: { $type: 'Article', $id: 'article-456' },
  context: {
    publishDate: '2024-10-27T10:00:00Z',
    channels: ['website', 'newsletter', 'social'],
  },
})

// 7. User reads article
await api.actions.execute({
  verb: 'read',
  subject: { $type: 'Person', $id: 'reader-999' },
  object: { $type: 'Article', $id: 'article-456' },
  context: {
    duration: 360, // seconds
    completionRate: 0.95,
  },
})

Team Collaboration

// Manager creates project
await api.actions.execute({
  verb: 'create',
  subject: { $type: 'Employee', $id: 'emp-manager' },
  object: { $type: 'Project', $id: 'proj-123' },
  context: {
    name: 'Q4 Product Launch',
    deadline: '2024-12-31',
  },
})

// Manager assigns tasks
await api.actions.execute({
  verb: 'assign',
  subject: { $type: 'Employee', $id: 'emp-manager' },
  object: { $type: 'Task', $id: 'task-design' },
  context: {
    assignee: { $type: 'Employee', $id: 'emp-designer' },
    project: { $type: 'Project', $id: 'proj-123' },
  },
})

await api.actions.execute({
  verb: 'assign',
  subject: { $type: 'Employee', $id: 'emp-manager' },
  object: { $type: 'Task', $id: 'task-dev' },
  context: {
    assignee: { $type: 'Employee', $id: 'emp-developer' },
    project: { $type: 'Project', $id: 'proj-123' },
  },
})

// Team members complete tasks
await api.actions.execute({
  verb: 'complete',
  subject: { $type: 'Employee', $id: 'emp-designer' },
  object: { $type: 'Task', $id: 'task-design' },
  context: {
    deliverables: ['mockups.fig', 'assets.zip'],
  },
})

await api.actions.execute({
  verb: 'complete',
  subject: { $type: 'Employee', $id: 'emp-developer' },
  object: { $type: 'Task', $id: 'task-dev' },
  context: {
    pullRequest: 'PR-456',
    testsPass: true,
  },
})

// Manager approves project
await api.actions.execute({
  verb: 'approve',
  subject: { $type: 'Employee', $id: 'emp-manager' },
  object: { $type: 'Project', $id: 'proj-123' },
  context: {
    completionDate: '2024-10-27',
  },
})

Action Status Tracking

Track action lifecycle:

// Start action (pending)
const action = await api.actions.execute({
  verb: 'process',
  subject: 'system',
  object: 'order-123',
  status: 'pending',
})

// Update to in_progress
action.status = 'in_progress'
await api.resources.update(action)

// Update to completed
action.status = 'completed'
action.context = {
  ...action.context,
  completedAt: new Date().toISOString(),
  result: 'success',
}
await api.resources.update(action)

Action Triggers

Actions can trigger workflows:

// Create workflow triggered by action
await api.workflows.create({
  name: 'Order Fulfillment',
  steps: [...],
  triggers: [
    {
      type: 'event',
      config: {
        eventType: 'action.executed',
        filter: {
          verb: 'purchase',
          status: 'completed'
        }
      }
    }
  ]
})

// Execute action (triggers workflow)
await api.actions.execute({
  verb: 'purchase',
  subject: 'cust-123',
  object: 'prod-456',
  status: 'completed'
})

Best Practices

1. Use Standard Verbs

// ✅ Good - standard verbs
await api.actions.execute({ verb: 'create', ... })
await api.actions.execute({ verb: 'update', ... })
await api.actions.execute({ verb: 'delete', ... })

// ❌ Avoid - non-standard verbs
await api.actions.execute({ verb: 'make', ... })
await api.actions.execute({ verb: 'do-something', ... })

2. Include Context

// ✅ Good - rich context
await api.actions.execute({
  verb: 'purchase',
  subject: 'cust-123',
  object: 'prod-456',
  context: {
    quantity: 2,
    price: 99.99,
    total: 199.98,
    discount: 0,
    paymentMethod: 'credit-card',
    shippingAddress: {...}
  }
})

// ❌ Avoid - missing context
await api.actions.execute({
  verb: 'purchase',
  subject: 'cust-123',
  object: 'prod-456'
})

3. Track Status

// ✅ Good - status tracking
await api.actions.execute({
  verb: 'process',
  subject: 'system',
  object: 'order-123',
  status: 'in_progress',
  timestamp: new Date().toISOString(),
})

Next Steps

Events API - Publish events for actions
Workflows API - Trigger workflows from actions
Resources API - Manage resources involved in actions

Actions API

On this page