API & Automation
Use the Orchestrator REST API to manage workflows programmatically, export code, and generate workflows with AI.
What you'll be able to do after this module
- Use the REST API to list, create, update, and delete workflows
- Query execution status and step logs programmatically
- Generate a full workflow from a natural language description using AI
- Export a workflow as TypeScript code and a downloadable ZIP project
The Orchestrator REST API
All APIs are served from https://orchestrator.skytells.ai. Management APIs use session-based authentication (cookie). The webhook endpoint uses API key auth (covered in Module 4).
Workflow Management
| Method | Endpoint | Description |
|---|---|---|
GET | /api/workflows | List all your workflows |
POST | /api/workflows/create | Create a new workflow |
GET | /api/workflows/{id} | Get a specific workflow |
PATCH | /api/workflows/{id} | Update name, description, nodes, edges, visibility |
DELETE | /api/workflows/{id} | Delete a workflow |
POST | /api/workflows/{id}/duplicate | Duplicate with new IDs (integrations stripped) |
Execution Monitoring
| Method | Endpoint | Description |
|---|---|---|
GET | /api/workflows/{id}/executions | List 50 most recent executions |
GET | /api/workflows/executions/{execId}/status | Get execution status + per-node status |
GET | /api/workflows/executions/{execId}/logs | Get per-step logs (auto-redacted) |
DELETE | /api/workflows/{id}/executions | Delete all execution records |
Integration Management
| Method | Endpoint | Description |
|---|---|---|
GET | /api/integrations | List integrations (config excluded) |
POST | /api/integrations | Create integration (encrypted before storage) |
GET | /api/integrations/{id} | Get with decrypted config (owner only) |
PUT | /api/integrations/{id} | Update |
DELETE | /api/integrations/{id} | Delete |
POST | /api/integrations/{id}/test | Test credentials |
API Keys
| Method | Endpoint | Description |
|---|---|---|
GET | /api/api-keys | List keys (prefix only, never full key) |
POST | /api/api-keys | Create key (full key returned once) |
Monitoring Executions
After triggering a workflow (via webhook or manually), you can poll for results:
Execution Status Model
Workflow-level statuses:
| Status | Meaning |
|---|---|
pending | Created, not yet started |
running | Actively executing steps |
success | All steps completed successfully |
error | One or more steps failed |
cancelled | Execution was cancelled |
Per-step statuses:
| Status | Meaning |
|---|---|
pending | Step not yet reached |
running | Step currently executing |
success | Step completed |
error | Step failed |
Step Log Entry
Each step produces a log entry:
{
"nodeId": "node1",
"nodeName": "Generate Text",
"nodeType": "action",
"status": "success",
"input": { "prompt": "..." },
"output": { "text": "..." },
"error": null,
"startedAt": "2025-01-15T10:00:00Z",
"completedAt": "2025-01-15T10:00:02Z",
"duration": "2000"
}Inputs and outputs are automatically redacted. API keys, auth headers, and sensitive data are stripped from execution logs before storage.
AI Workflow Generation
Orchestrator can build entire workflows from a natural language description.
How to use it
Open AI Generate
Click the sparkles icon (AI Generate) in the toolbar.
Describe your workflow
Write a clear, specific description of what the workflow should do. Mention:
- Which integrations to use (be specific: "use Perplexity" not "search the web")
- What data flows between steps
- Any branching logic
- The trigger type
Example prompt:
When a webhook receives a customer support ticket, use AI Gateway to classify the priority as high or normal. If high, send a Slack message to #support-urgent. Otherwise, create a Linear ticket in the backlog.
Review the result
The AI streams operations to the canvas in real-time — you'll see nodes appear and connect.
The AI knows about:
- All 45+ actions across all 15 plugins
- All 3 system actions
- Template variable syntax
- Condition branching
- Node positioning on the canvas
Finalize
After generation:
- Attach integrations — the AI creates the correct action types but can't assign credentials
- Review prompts and config — fine-tune values
- Test with Manual run before switching to production trigger
Tips for Better AI Generation
| Tip | Why |
|---|---|
| Name integrations explicitly | "use Perplexity to search" > "search the web" |
| Mention branching conditions | The AI needs explicit branching instructions |
| Specify trigger type | "When a webhook receives..." > "When something happens..." |
| Describe data flow | "take the text output and send it to Slack" |
Code Export
Export any workflow as production-ready TypeScript code.
View Generated Code
Click Export → View Code in the toolbar. Orchestrator generates TypeScript using two special directives:
export async function myWorkflow() {
"use workflow"; // marks the workflow entry point
async function generateText() {
"use step"; // marks each step for observability
const response = await skytells.predictions.create({
model: "truefusion-pro",
input: { prompt: "..." },
});
return { success: true, data: response };
}
async function sendSlackMessage() {
"use step";
const textOutput = await generateText();
await slack.chat.postMessage({
channel: "#results",
text: textOutput.data.text,
});
}
await sendSlackMessage();
}Key features:
"use workflow"— marks the function as a workflow entry point"use step"— marks each step for logging and observability- Template variables are translated to JavaScript references
- Dependencies are auto-calculated from the actions used
Download as ZIP
Click Export → Download to get a complete Next.js project:
my-workflow/
├── workflows/
│ └── my-workflow.ts # Generated workflow code
├── app/
│ ├── page.tsx # Landing page
│ └── api/
│ └── workflows/
│ └── my-workflow/
│ └── route.ts # API route to trigger
├── package.json # Auto-calculated dependencies
└── tsconfig.jsonDependencies are auto-resolved based on the actions in your workflow:
| Actions used | Packages included |
|---|---|
| AI Gateway Generate Text | ai, openai, @google/genai, zod |
| Slack Send Message | @slack/web-api |
| Stripe operations | stripe |
| GitHub operations | @octokit/rest |
| Resend Send Email | resend |
To run the exported project:
unzip my-workflow.zip -d my-workflow
cd my-workflow
npm install
# Set environment variables for API keys
npm run dev
# API route available at http://localhost:3000/api/workflows/my-workflowExported code is a snapshot — it doesn't sync with changes made in the editor after export. Credentials are not included; set them up as environment variables.
What you now understand
| Concept | What it means |
|---|---|
| REST API | Full programmatic access to workflows, executions, integrations, and keys |
| Execution polling | Check status and logs after triggering a workflow |
| Log redaction | Sensitive data automatically stripped from stored logs |
| AI generation | Natural language → full workflow on canvas |
| Code export | TypeScript SDK code with "use workflow" / "use step" directives |
| ZIP download | Complete Next.js project with auto-resolved dependencies |
Up next: Production Best Practices — secure your workflows, debug failures, and operate at scale.