Content Workflow API¶
Structured content workflow engine designed for both REST consumption and MCP server integration. Manage AI capabilities, track executions, and organize content through a kanban board.
Base URL: https://api.vell.ai/api/v1
Authentication: Bearer token
Prefix: /content-workflow
Capabilities¶
List Capabilities¶
| Parameter | Type | Required | Description |
|---|---|---|---|
category |
string | No | Filter: generation, publishing, analysis, workflow |
include_beta |
boolean | No | Include beta capabilities (default: false) |
Response:
{
"data": [
{
"type": "capability",
"id": 1,
"attributes": {
"slug": "generate-blog-post",
"name": "Blog Post Generator",
"description": "Generate SEO-optimized blog posts",
"category": "generation",
"category_label": "Content Generation",
"requires_credits": true,
"estimated_credits": 5,
"is_beta": false
}
}
],
"meta": {
"total": 12,
"categories": ["generation", "publishing", "analysis", "workflow"]
}
}
Get Capability Details¶
Returns full capability details including required_settings, default_settings, and required_extensions.
Execute Capability¶
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id |
integer | No | Specific agent to use (auto-selects if omitted) |
settings |
object | No | Capability-specific settings |
context |
object | No | Additional context for the agent |
priority |
string | No | low, normal, high, urgent (default: normal) |
notify_on_complete |
boolean | No | Send notification when done (default: false) |
Response (201):
{
"data": {
"type": "execution",
"id": 789,
"attributes": {
"status": "pending",
"priority": "normal",
"progress_percentage": 0,
"credits_used": 0,
"created_at": "2026-02-26T10:00:00Z"
},
"relationships": {
"agent": { "id": 5, "name": "Content Writer", "type": "internal" }
}
},
"meta": { "message": "Capability execution started" }
}
Executions¶
List Executions¶
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
status |
string | No | — | pending, planning, executing, completed, failed, cancelled, archived |
agent_id |
integer | No | — | Filter by agent |
priority |
string | No | — | low, normal, high, urgent |
from |
date | No | — | Start date filter |
to |
date | No | — | End date filter |
page |
integer | No | 1 |
Page number |
per_page |
integer | No | 20 |
Items per page (max: 100) |
Get Execution Details¶
Returns full execution details including execution_plan, step_results, error_message, generated_assets, and guardrails_triggered.
Get Execution Assets¶
Response:
{
"data": {
"execution_id": 789,
"status": "completed",
"content_items": [
{
"type": "content_item",
"id": 101,
"attributes": {
"title": "Cloud Cost Optimization Guide",
"content_type": "blog_post",
"kanban_status": "generated",
"preview": "Cloud cost optimization is one of...",
"word_count": 1200
}
}
]
},
"meta": { "content_count": 1 }
}
Kanban Board¶
Get Board State¶
| Parameter | Type | Required | Description |
|---|---|---|---|
execution_id |
integer | No | Filter by execution |
content_type |
string | No | text_content, blog_post, email_draft, social_post, product_description |
from |
date | No | Start date filter |
to |
date | No | End date filter |
Response:
{
"data": {
"columns": {
"generated": { "label": "Generated", "items": [], "count": 5 },
"review": { "label": "In Review", "items": [], "count": 3 },
"ready": { "label": "Ready", "items": [], "count": 8 },
"published": { "label": "Published", "items": [], "count": 12 }
},
"valid_statuses": ["generated", "review", "ready", "published"]
}
}
Move Content¶
| Parameter | Type | Required | Description |
|---|---|---|---|
status |
string | Yes | generated, review, ready, published |
Bulk Move¶
| Parameter | Type | Required | Description |
|---|---|---|---|
content_ids |
array | Yes | Content IDs to move (max: 100) |
status |
string | Yes | Target status |
Brand Voices & Agents¶
List Brand Voices¶
Get Brand Voice¶
List Agents¶
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
type |
string | No | — | Filter by agent type |
active_only |
boolean | No | true |
Only active agents |
Get Agent¶
Workflow Templates¶
List Templates¶
List Templates (Grouped)¶
Returns templates organized by category.
Get Template¶
Suggest Templates¶
AI-powered template suggestion based on your use case.
Execute Template¶
Validate Template Input¶
Workflow Triggers¶
List Triggers¶
Create Trigger¶
Toggle Trigger¶
Delete Trigger¶
MCP Schema Discovery¶
Returns the full MCP tool schema for all capabilities, enabling MCP server adapters to auto-discover available tools.
Response:
{
"mcp_version": "2025-11-25",
"server_name": "vellocity-content-workflow",
"server_version": "1.0.0",
"tools": [
{
"name": "list_capabilities",
"title": "List Capabilities",
"description": "List available AI content capabilities",
"inputSchema": { "type": "object", "properties": {} },
"annotations": { "readOnlyHint": true }
}
]
}
Use Cases¶
Automated Content Pipeline¶
- List capabilities:
GET /content-workflow/capabilities?category=generation - Execute a blog post generation:
POST /content-workflow/capabilities/generate-blog-post/execute - Poll execution status:
GET /content-workflow/executions/{id} - When complete, retrieve assets:
GET /content-workflow/executions/{id}/assets - Move through kanban:
POST /content-workflow/kanban/{id}/status(review -> ready -> published)
Event-Driven Workflows¶
- Create a trigger:
POST /content-workflow/workflow-triggers - Configure it to fire on listing updates or schedule-based events
- The trigger executes a workflow template automatically
- Monitor executions via
GET /content-workflow/executions
MCP Integration¶
Use the MCP schema endpoint to register Vellocity capabilities as tools in any MCP-compatible AI client. See MCP Server API for direct JSON-RPC integration.