Workflow API

The Workflow API enables you to programmatically create, manage, and execute workflows in meinGPT. This is useful for integrating workflows into your applications or automating workflow management.

API Overview

Base URL: https://api.meingpt.com/v1

Authentication: Bearer token in Authorization header

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://api.meingpt.com/v1/workflows

Endpoints

List Workflows

GET /workflows

Retrieve all workflows in your organization.

curl -X GET https://api.meingpt.com/v1/workflows \
     -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "workflows": [
    {
      "id": "wf_123456",
      "name": "Customer Support Automation",
      "description": "Handles customer inquiries",
      "status": "active",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-20T15:30:00Z",
      "execution_count": 245
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20
}

Get Workflow Details

GET /workflows/{workflow_id}

Retrieve detailed information about a specific workflow.

curl -X GET https://api.meingpt.com/v1/workflows/wf_123456 \
     -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "id": "wf_123456",
  "name": "Customer Support Automation",
  "description": "Handles customer inquiries",
  "status": "active",
  "trigger": {
    "type": "webhook",
    "config": {
      "url": "https://api.meingpt.com/v1/webhooks/wh_789012"
    }
  },
  "steps": [
    {
      "id": "step_1",
      "type": "ai_completion",
      "name": "Analyze Inquiry",
      "config": {
        "model": "gpt-4",
        "prompt": "Analyze the customer inquiry: {{input.message}}"
      }
    },
    {
      "id": "step_2",
      "type": "condition",
      "name": "Route by Urgency",
      "config": {
        "condition": "{{step_1.output.urgency}} == 'high'",
        "true_branch": "step_3",
        "false_branch": "step_4"
      }
    }
  ],
  "variables": {
    "support_email": "support@company.com",
    "max_response_time": 300
  }
}

Create Workflow

POST /workflows

Create a new workflow.

curl -X POST https://api.meingpt.com/v1/workflows \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "New Customer Onboarding",
       "description": "Automates the onboarding process",
       "trigger": {
         "type": "webhook"
       },
       "steps": [
         {
           "id": "welcome",
           "type": "ai_completion",
           "name": "Generate Welcome Message",
           "config": {
             "model": "gpt-3.5-turbo",
             "prompt": "Generate a personalized welcome message for {{input.customer_name}}"
           }
         },
         {
           "id": "send_email",
           "type": "email",
           "name": "Send Welcome Email",
           "config": {
             "to": "{{input.customer_email}}",
             "subject": "Welcome to Our Service!",
             "body": "{{welcome.output}}"
           }
         }
       ]
     }'

Update Workflow

PUT /workflows/{workflow_id}

Update an existing workflow.

curl -X PUT https://api.meingpt.com/v1/workflows/wf_123456 \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Updated Workflow Name",
       "status": "active",
       "steps": [
         // Updated steps configuration
       ]
     }'

Delete Workflow

DELETE /workflows/{workflow_id}

Delete a workflow.

curl -X DELETE https://api.meingpt.com/v1/workflows/wf_123456 \
     -H "Authorization: Bearer YOUR_API_TOKEN"

Execute Workflow

POST /workflows/{workflow_id}/execute

Manually trigger a workflow execution.

curl -X POST https://api.meingpt.com/v1/workflows/wf_123456/execute \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "input": {
         "customer_name": "John Doe",
         "customer_email": "john@example.com",
         "inquiry": "I need help with my order"
       }
     }'

Response:

{
  "execution_id": "exec_456789",
  "status": "running",
  "started_at": "2024-01-20T16:00:00Z",
  "workflow_id": "wf_123456"
}

Get Execution Status

GET /workflows/{workflow_id}/executions/{execution_id}

Check the status of a workflow execution.

curl -X GET https://api.meingpt.com/v1/workflows/wf_123456/executions/exec_456789 \
     -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "execution_id": "exec_456789",
  "workflow_id": "wf_123456",
  "status": "completed",
  "started_at": "2024-01-20T16:00:00Z",
  "completed_at": "2024-01-20T16:00:45Z",
  "duration_ms": 45000,
  "steps": [
    {
      "step_id": "step_1",
      "status": "completed",
      "started_at": "2024-01-20T16:00:00Z",
      "completed_at": "2024-01-20T16:00:10Z",
      "output": {
        "urgency": "high",
        "category": "order_issue"
      }
    }
  ],
  "output": {
    "ticket_id": "TICKET-12345",
    "response_sent": true
  }
}

Workflow Components

Triggers

Webhook Trigger:

{
  "type": "webhook",
  "config": {
    "method": "POST",
    "headers": {
      "X-API-Key": "{{secrets.webhook_key}}"
    }
  }
}

Schedule Trigger:

{
  "type": "schedule",
  "config": {
    "cron": "0 9 * * MON-FRI",
    "timezone": "Europe/Berlin"
  }
}

Email Trigger:

{
  "type": "email",
  "config": {
    "address": "workflow-trigger@company.com",
    "subject_filter": "Support Request"
  }
}

Step Types

AI Completion:

{
  "id": "ai_step",
  "type": "ai_completion",
  "name": "Process with AI",
  "config": {
    "model": "gpt-4",
    "prompt": "Your prompt here",
    "temperature": 0.7,
    "max_tokens": 500
  }
}

HTTP Request:

{
  "id": "api_call",
  "type": "http",
  "name": "Call External API",
  "config": {
    "method": "POST",
    "url": "https://api.example.com/endpoint",
    "headers": {
      "Authorization": "Bearer {{secrets.api_key}}"
    },
    "body": {
      "data": "{{previous_step.output}}"
    }
  }
}

Condition:

{
  "id": "decision",
  "type": "condition",
  "name": "Check Condition",
  "config": {
    "condition": "{{ai_step.output.score}} > 0.8",
    "true_branch": "high_priority_step",
    "false_branch": "normal_priority_step"
  }
}

Loop:

{
  "id": "process_items",
  "type": "loop",
  "name": "Process Each Item",
  "config": {
    "items": "{{input.items}}",
    "steps": [
      {
        "id": "process_item",
        "type": "ai_completion",
        "config": {
          "prompt": "Process item: {{item}}"
        }
      }
    ]
  }
}

Variables and Expressions

Variable References

{{input.field_name}} - Access input data
{{step_id.output}} - Access step output
{{variables.var_name}} - Access workflow variables
{{secrets.secret_name}} - Access secrets
{{env.VARIABLE}} - Access environment variables

Expressions

// Arithmetic
{{step1.output.count + step2.output.count}}

// String operations
{{input.first_name + " " + input.last_name}}

// Conditionals
{{input.priority == "high" ? "urgent" : "normal"}}

// Array operations
{{input.items.length}}
{{input.items[0].name}}

// Object access
{{response.data.user.email}}

Error Handling

Error Response Format

{
  "error": {
    "code": "WORKFLOW_NOT_FOUND",
    "message": "The requested workflow does not exist",
    "details": {
      "workflow_id": "wf_invalid"
    }
  }
}

Common Error Codes

UNAUTHORIZED - Invalid or missing API token
WORKFLOW_NOT_FOUND - Workflow ID doesn't exist
INVALID_INPUT - Request body validation failed
EXECUTION_FAILED - Workflow execution error
RATE_LIMIT_EXCEEDED - Too many requests
INSUFFICIENT_CREDITS - Not enough credits

Webhooks

Webhook URL Format

https://api.meingpt.com/v1/webhooks/{webhook_id}

Webhook Security

Signature Verification:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your webhook handler
signature = request.headers.get('X-Webhook-Signature')
if not verify_webhook(request.body, signature, webhook_secret):
    return 401

Rate Limits

API Calls: 1000 requests per hour
Workflow Executions: 100 per minute
Webhook Calls: 500 per minute

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642684800

SDKs and Examples

Python SDK

from meingpt import WorkflowClient

client = WorkflowClient(api_key="YOUR_API_KEY")

# Create workflow
workflow = client.workflows.create(
    name="My Workflow",
    trigger={"type": "webhook"},
    steps=[
        {
            "id": "step1",
            "type": "ai_completion",
            "config": {
                "model": "gpt-4",
                "prompt": "Process: {{input.data}}"
            }
        }
    ]
)

# Execute workflow
execution = client.workflows.execute(
    workflow_id=workflow.id,
    input={"data": "Hello World"}
)

# Check status
status = client.executions.get(execution.id)
print(f"Status: {status.status}")

JavaScript SDK

import { WorkflowClient } from '@meingpt/workflows';

const client = new WorkflowClient({
  apiKey: process.env.MEINGPT_API_KEY
});

// Create workflow
const workflow = await client.workflows.create({
  name: 'My Workflow',
  trigger: { type: 'webhook' },
  steps: [
    {
      id: 'step1',
      type: 'ai_completion',
      config: {
        model: 'gpt-4',
        prompt: 'Process: {{input.data}}'
      }
    }
  ]
});

// Execute workflow
const execution = await client.workflows.execute(workflow.id, {
  input: { data: 'Hello World' }
});

// Check status
const status = await client.executions.get(execution.id);
console.log(`Status: ${status.status}`);

Best Practices

Use Secrets for sensitive data
Implement Error Handling in your workflows
Set Timeouts for external API calls
Use Conditions to handle edge cases
Monitor Executions for failures
Version Control your workflow definitions
Test Thoroughly before production
Use Webhooks for real-time triggers