Service API Reference

Complete API reference for the Service type, including methods, properties, and usage examples

The $.Service type represents a discrete unit of work that can be performed by AI agents, humans, or a combination of both. Services are the core building blocks of the services-as-software marketplace ecosystem.

Type Definition

interface Service extends Thing {
  $type: 'Service'
  $id: string
  name: string
  description: string
  provider: Organization | Person
  workflow: BusinessWorkflow
  pricing: PricingSpecification
  category?: string
  tags?: string[]
  status: ServiceStatus
  version?: string
  capabilities?: string[]
  requirements?: ServiceRequirements
  metadata?: ServiceMetadata
}

type ServiceStatus = 'draft' | 'active' | 'inactive' | 'archived'

interface ServiceRequirements {
  input: string[]
  permissions: string[]
  integrations: string[]
}

interface ServiceMetadata {
  createdAt: string
  updatedAt: string
  createdBy: string
  averageExecutionTime?: number
  successRate?: number
}

Properties

Core Properties

name

Type: string
Required: Yes
Description: Human-readable name of the service
Example: 'AI-Powered SDR Outreach'
Constraints: 3-100 characters

description

Type: string
Required: Yes
Description: Detailed description of what the service does
Example: 'Automated outreach to qualified leads with personalized messaging'
Constraints: 10-1000 characters

provider

Type: Organization | Person
Required: Yes
Description: The organization or individual offering the service
Pattern: $.Service[id].provider -> $.Organization[providerId]
Example: $.Organization.get('acme-corp')

workflow

Type: BusinessWorkflow
Required: Yes
Description: The business-as-code workflow that executes the service
Pattern: $.Service[id].workflow -> $.BusinessWorkflow[workflowId]
Example: See workflow definition examples below

pricing

Type: PricingSpecification
Required: Yes
Description: Pricing information for the service
Properties:
- model: Pricing model type
- amount: Base price amount
- currency: ISO 4217 currency code
- period: Billing period (for subscriptions)

Optional Properties

status

Type: ServiceStatus
Required: Yes
Default: 'draft'
Values: 'draft' | 'active' | 'inactive' | 'archived'
Description: Current availability status of the service

version

Type: string
Required: No
Description: Semantic version identifier for the service
Example: '1.0.0'
Pattern: Follows semver (major.minor.patch)

capabilities

Type: string[]
Required: No
Description: List of capabilities this service provides
Examples: ['email-outreach', 'linkedin-messaging', 'phone-calls']

requirements

Type: ServiceRequirements
Required: No
Description: Requirements or prerequisites for using this service
Properties:
- input: Array of required input parameters
- permissions: Array of required permissions
- integrations: Array of required third-party integrations

metadata

Type: ServiceMetadata
Required: No
Description: Additional metadata about the service
Properties:
- createdAt: ISO 8601 timestamp
- updatedAt: ISO 8601 timestamp
- createdBy: User ID
- averageExecutionTime: number (milliseconds)
- successRate: number (0-1)

Methods

define()

Create a new service definition.

Signature:

$.Service.define(config: ServiceConfig): Promise<Service>

Parameters:

config: Service configuration object

Returns: Promise resolving to the created Service

Example:

const service = await $.Service.define({
  name: 'AI-Powered SDR Outreach',
  description: 'Automated outreach to qualified leads with personalized messaging',
  provider: $.Organization.get('acme-corp'),
  workflow: $.BusinessWorkflow.define({
    steps: [
      $.Step.ai('research-lead', {
        model: 'claude-sonnet-4.5',
        prompt: 'Research this lead and find relevant talking points',
      }),
      $.Step.ai('craft-message', {
        model: 'claude-sonnet-4.5',
        prompt: 'Write a personalized outreach email',
      }),
      $.Step.ai('send-email', {
        integration: 'email',
        action: 'send',
      }),
    ],
  }),
  pricing: {
    model: 'per-lead',
    amount: 5,
    currency: 'USD',
  },
  category: 'sales',
  tags: ['outreach', 'sdr', 'b2b', 'ai'],
  status: 'active',
})

get()

Retrieve a service by ID.

Signature:

$.Service.get(id: string): Promise<Service>

Parameters:

id: Service identifier

Returns: Promise resolving to the Service

Example:

const service = await $.Service.get('service-123')
console.log(service.name)
console.log(service.pricing)

list()

List all services with optional filtering.

Signature:

$.Service.list(filter?: ServiceFilter): Promise<Service[]>

Parameters:

filter: Optional filter criteria

Returns: Promise resolving to array of Services

Example:

// List all services
const allServices = await $.Service.list()

// List active services
const activeServices = await $.Service.list({ status: 'active' })

// List by provider
const providerServices = await $.Service.list({
  provider: 'provider-id',
})

find()

Find services matching specific criteria.

Signature:

$.Service.find(query: ServiceQuery): Promise<Service[]>

Parameters:

query: Query object with filter criteria

Returns: Promise resolving to matching Services

Example:

// Find by category
const salesServices = await $.Service.find({ category: 'sales' })

// Find by tag
const aiServices = await $.Service.find({
  tags: { $contains: 'ai' },
})

// Complex query
const results = await $.Service.find({
  status: 'active',
  category: 'sales',
  'pricing.model': 'per-lead',
})

search()

Full-text search across services.

Signature:

$.Service.search(query: string, options?: SearchOptions): Promise<Service[]>

Parameters:

query: Search query string
options: Optional search configuration

Returns: Promise resolving to matching Services

Example:

// Simple search
const results = await $.Service.search('SDR outreach')

// Search with options
const results = await $.Service.search('content generation', {
  category: 'marketing',
  limit: 10,
  sort: 'relevance',
})

update()

Update service properties.

Signature:

$.Service[id].update(changes: Partial<ServiceConfig>): Promise<Service>

Parameters:

changes: Object containing properties to update

Returns: Promise resolving to updated Service

Example:

// Update description and pricing
await $.Service[serviceId].update({
  description: 'Updated description',
  pricing: {
    model: 'per-lead',
    amount: 4.5,
    currency: 'USD',
  },
})

// Update status
await $.Service[serviceId].update({ status: 'inactive' })

// Update tags
await $.Service[serviceId].update({
  tags: ['outreach', 'sdr', 'b2b', 'ai', 'updated'],
})

delete()

Delete a service (soft delete by default).

Signature:

$.Service[id].delete(options?: DeleteOptions): Promise<void>

Parameters:

options: Optional deletion configuration

Returns: Promise resolving when complete

Example:

// Soft delete (archives the service)
await $.Service[serviceId].delete()

// Hard delete (permanent removal)
await $.Service[serviceId].delete({ hard: true })

execute()

Execute a service (creates order and execution).

Signature:

$.Service[id].execute(params: ServiceParams): Promise<ExecutionResult>

Parameters:

params: Service execution parameters

Returns: Promise resolving to execution result

Example:

const result = await $.Service[serviceId].execute({
  leads: [
    { name: 'John Doe', email: '[email protected]', company: 'Acme Inc' },
    { name: 'Jane Smith', email: '[email protected]', company: 'Beta Corp' },
  ],
  company_info: {
    name: 'Your Company',
    value_proposition: 'We help companies automate their sales process',
  },
})

console.log(result.orderId)
console.log(result.executionId)
console.log(result.status)

Property Access

Services support semantic property access:

// Get service name
const name = await $.Service[serviceId].name

// Get service provider
const provider = await $.Service[serviceId].provider

// Get service workflow
const workflow = await $.Service[serviceId].workflow

// Get service pricing
const pricing = await $.Service[serviceId].pricing

// Get service status
const status = await $.Service[serviceId].status

// Get service metadata
const metadata = await $.Service[serviceId].metadata

Relations

provider

Access the organization or person providing the service.

Pattern: $.Service[id].provider -> $.Organization[providerId]

Example:

const service = await $.Service.get('service-123')
const provider = await service.provider
console.log(provider.name)

offerings

Access marketplace listings for this service.

Pattern: $.Service[id].offerings -> $.ServiceOffering[]

Example:

const offerings = await $.Service[serviceId].offerings
offerings.forEach((offering) => {
  console.log(offering.title, offering.pricing)
})

orders

Access orders placed for this service.

Pattern: $.Service[id].orders -> $.ServiceOrder[]

Example:

const orders = await $.Service[serviceId].orders
console.log(`Total orders: ${orders.length}`)

executions

Access execution history for this service.

Pattern: $.Service[id].executions -> $.ServiceExecution[]

Example:

const executions = await $.Service[serviceId].executions
const successful = executions.filter((e) => e.status === 'completed')
console.log(`Success rate: ${successful.length / executions.length}`)

workflow

Access the workflow that executes this service.

Pattern: $.Service[id].workflow -> $.BusinessWorkflow[workflowId]

Example:

const workflow = await $.Service[serviceId].workflow
console.log(`Steps: ${workflow.steps.length}`)

Usage Examples

Example 1: Create SDR Outreach Service

const sdrService = await $.Service.define({
  name: 'AI-Powered SDR Outreach',
  description: 'Automated outreach to qualified leads with personalized messaging',
  provider: $.Organization.get('sales-automation-co'),
  workflow: $.BusinessWorkflow.define({
    steps: [
      $.Step.ai('research-lead', {
        model: 'claude-sonnet-4.5',
        prompt: 'Research the lead and company, find 3-5 relevant talking points',
      }),
      $.Step.ai('craft-message', {
        model: 'claude-sonnet-4.5',
        prompt: 'Write a personalized outreach email using the research',
      }),
      $.Step.ai('send-email', {
        integration: 'email',
        action: 'send',
      }),
      $.Step.human('review-responses', {
        role: 'sdr',
        task: 'Review and respond to any replies',
      }),
    ],
  }),
  pricing: {
    model: 'per-lead',
    amount: 5,
    currency: 'USD',
  },
  category: 'sales',
  tags: ['outreach', 'sdr', 'b2b', 'ai'],
  status: 'active',
  version: '1.0.0',
  capabilities: ['email-outreach', 'lead-research', 'personalization'],
  requirements: {
    input: ['leads', 'company_info'],
    permissions: ['email:send'],
    integrations: ['email-provider'],
  },
})

Example 2: Create Content Writing Service

const contentService = await $.Service.define({
  name: 'AI Blog Post Writer',
  description: 'Generate high-quality blog posts on any topic with human review',
  provider: $.Organization.get('content-ai-co'),
  workflow: $.BusinessWorkflow.define({
    steps: [
      $.Step.ai('research-topic', {
        model: 'claude-sonnet-4.5',
        prompt: 'Research the topic and gather key points, statistics, and examples',
      }),
      $.Step.ai('create-outline', {
        model: 'claude-sonnet-4.5',
        prompt: 'Create a detailed outline with H2 and H3 headings',
      }),
      $.Step.ai('write-content', {
        model: 'claude-sonnet-4.5',
        prompt: 'Write the full blog post following the outline',
      }),
      $.Step.human('review-edit', {
        role: 'editor',
        task: 'Review and polish the content for quality and accuracy',
      }),
    ],
  }),
  pricing: {
    model: 'per-unit',
    amount: 50,
    currency: 'USD',
  },
  category: 'content',
  tags: ['content', 'blog', 'writing', 'ai'],
  status: 'active',
  version: '1.0.0',
  capabilities: ['content-generation', 'research', 'seo-optimization'],
  requirements: {
    input: ['topic', 'keywords', 'target_audience'],
    permissions: [],
    integrations: [],
  },
})

Example 3: Create Data Analysis Service

const analysisService = await $.Service.define({
  name: 'Business Intelligence Dashboard',
  description: 'Analyze your data and create interactive dashboards with insights',
  provider: $.Organization.get('data-insights-co'),
  workflow: $.BusinessWorkflow.define({
    steps: [
      $.Step.ai('analyze-data', {
        model: 'claude-sonnet-4.5',
        prompt: 'Analyze the dataset and identify key insights, trends, and anomalies',
      }),
      $.Step.ai('create-visualizations', {
        integration: 'charting',
        action: 'generate',
        config: {
          chartTypes: ['line', 'bar', 'pie', 'scatter'],
        },
      }),
      $.Step.ai('generate-report', {
        model: 'claude-sonnet-4.5',
        prompt: 'Write executive summary and actionable recommendations',
      }),
      $.Step.human('review-insights', {
        role: 'analyst',
        task: 'Validate insights and recommendations',
      }),
    ],
  }),
  pricing: {
    model: 'subscription',
    amount: 299,
    currency: 'USD',
    period: 'monthly',
  },
  category: 'analytics',
  tags: ['analytics', 'bi', 'dashboard', 'data'],
  status: 'active',
  version: '2.1.0',
  capabilities: ['data-analysis', 'visualization', 'reporting'],
  requirements: {
    input: ['dataset', 'metrics', 'dimensions'],
    permissions: ['data:read'],
    integrations: ['database', 'charting-library'],
  },
})

Example 4: Query Services by Category

// Get all sales services
const salesServices = await $.Service.find({ category: 'sales' })

salesServices.forEach((service) => {
  console.log(`${service.name}: ${service.pricing.amount} ${service.pricing.currency}`)
})

Example 5: Search Services

// Search for AI-powered services
const aiServices = await $.Service.search('ai powered automation', {
  limit: 10,
  sort: 'relevance',
})

console.log(`Found ${aiServices.length} AI services`)

Example 6: Get Service Statistics

const service = await $.Service.get('service-123')

// Get execution statistics
const executions = await service.executions
const completed = executions.filter((e) => e.status === 'completed')
const failed = executions.filter((e) => e.status === 'failed')

const successRate = completed.length / executions.length
const avgDuration = completed.reduce((sum, e) => sum + e.metrics.duration, 0) / completed.length

console.log(`Success Rate: ${(successRate * 100).toFixed(1)}%`)
console.log(`Average Duration: ${(avgDuration / 1000).toFixed(1)}s`)
console.log(`Total Orders: ${(await service.orders).length}`)

Example 7: Update Service Workflow

// Update the workflow to add a new step
const currentWorkflow = await $.Service[serviceId].workflow

await $.Service[serviceId].update({
  workflow: $.BusinessWorkflow.define({
    steps: [
      ...currentWorkflow.steps,
      $.Step.ai('follow-up', {
        model: 'claude-sonnet-4.5',
        prompt: 'Send follow-up message after 3 days',
      }),
    ],
  }),
  version: '1.1.0',
})

Example 8: Activate/Deactivate Service

// Deactivate a service
await $.Service[serviceId].update({ status: 'inactive' })

// Reactivate later
await $.Service[serviceId].update({ status: 'active' })

// Archive permanently
await $.Service[serviceId].update({ status: 'archived' })

Example 9: Clone Service with Modifications

const originalService = await $.Service.get('original-service-id')

const clonedService = await $.Service.define({
  ...originalService,
  name: `${originalService.name} - Enterprise`,
  pricing: {
    ...originalService.pricing,
    amount: originalService.pricing.amount * 2,
  },
  version: '1.0.0',
})

Example 10: Batch Service Operations

// Get all draft services and publish them
const draftServices = await $.Service.find({ status: 'draft' })

await Promise.all(draftServices.map((service) => $.Service[service.$id].update({ status: 'active' })))

console.log(`Published ${draftServices.length} services`)

Example 11: Service with Custom Requirements

const enterpriseService = await $.Service.define({
  name: 'Enterprise Data Pipeline',
  description: 'Custom data pipeline with enterprise-grade security and compliance',
  provider: $.Organization.get('data-platform-co'),
  workflow: $.BusinessWorkflow.define({
    steps: [
      /* workflow steps */
    ],
  }),
  pricing: {
    model: 'custom',
    amount: 0,
    currency: 'USD',
  },
  category: 'data',
  status: 'active',
  requirements: {
    input: ['data_sources', 'transformations', 'destinations'],
    permissions: ['data:read:all', 'data:write:all', 'admin:manage'],
    integrations: ['aws-s3', 'snowflake', 'databricks', 'looker'],
  },
})

Example 12: Multi-Step Service Execution

// Execute service and monitor progress
const result = await $.Service[serviceId].execute({
  leads: [{ name: 'John Doe', email: '[email protected]' }],
})

// Monitor execution
const execution = await $.ServiceExecution.get(result.executionId)

const watcher = execution.watch()
watcher.on('progress', (progress) => {
  console.log(`Progress: ${progress}%`)
})

watcher.on('completed', (result) => {
  console.log('Service completed:', result)
  watcher.stop()
})

Events

Services emit the following events:

service.created - Service was created
service.updated - Service was updated
service.deleted - Service was deleted
service.executed - Service was executed
service.status_changed - Service status changed

Example:

import { on } from 'sdk.do'

on.Service.created(async (service) => {
  console.log(`New service created: ${service.name}`)
})

on.Service.executed(async ({ service, execution }) => {
  console.log(`Service ${service.name} executed: ${execution.status}`)
})

API Endpoints

When deployed, services are accessible via REST API:

GET /api/services - List all services
GET /api/services/:id - Get service details
POST /api/services - Create a new service
PUT /api/services/:id - Update a service
DELETE /api/services/:id - Delete a service
POST /api/services/:id/execute - Execute a service
GET /api/services/:id/orders - Get service orders
GET /api/services/:id/executions - Get service executions

Security

Services support the following security features:

Authentication: Required for execution
Authorization: Role-based access control
Rate Limiting: Configurable per service
API Keys: For programmatic access
Webhooks: For event notifications

Schema.org Mapping

Services extend Schema.org types:

schema.org/Service: A service provided by an organization
schema.org/Product: A product or service being offered

Property Mappings:

serviceType -> category
provider -> provider
offers -> pricing
aggregateRating -> metadata.rating
termsOfService -> requirements

Service API Reference

On this page