Skip to main content
GET
/
api
/
v1
/
sources

​
Overview

Sources are external workflow platforms that Spark connects to for syncing and executing workflows. Supported source types:
  • langflow: LangFlow workflow platform
  • automagik-hive: AutoMagik Hive multi-agent system
  • automagik-agents: AutoMagik Agents framework

​
List Sources

Retrieve all configured workflow sources with pagination support.
​
status
string
Filter by source status: active or inactive
​
limit
integer
default:"50"
Number of items per page (min: 1, max: 100)
​
offset
integer
default:"0"
Number of items to skip for pagination
curl -X GET "http://localhost:8883/api/v1/sources?limit=10&offset=0" \
  -H "X-API-Key: your-api-key"

​
Response

200 Success
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "my-langflow",
      "source_type": "langflow",
      "url": "http://localhost:7860",
      "status": "active",
      "version_info": {
        "version": "1.0.0",
        "name": "LangFlow",
        "status": "ok"
      },
      "created_at": "2025-11-04T12:00:00Z",
      "updated_at": "2025-11-04T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0,
  "has_more": false
}
401 Unauthorized
{
  "detail": "Invalid API key"
}

​
Get Source

Retrieve a specific workflow source by ID.
​
source_id
uuid
required
UUID of the source to retrieve
curl -X GET http://localhost:8883/api/v1/sources/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-api-key"

​
Response

200 Success
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-langflow",
  "source_type": "langflow",
  "url": "http://localhost:7860",
  "status": "active",
  "version_info": {
    "version": "1.0.0",
    "name": "LangFlow",
    "status": "ok"
  },
  "created_at": "2025-11-04T12:00:00Z",
  "updated_at": "2025-11-04T12:00:00Z"
}
404 Not Found
{
  "detail": "Source not found"
}

​
Create Source

Create a new workflow source. Spark will validate the source by checking its health endpoint and fetching version information.
​
name
string
Human-readable name for the source (auto-generated if not provided)
​
source_type
string
required
Source type: langflow, automagik-hive, or automagik-agents
​
url
string
required
Base URL of the workflow source (e.g., http://localhost:7860)
​
api_key
string
API key for authentication (leave empty if source doesn’t require auth)
curl -X POST http://localhost:8883/api/v1/sources \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "name": "my-langflow",
    "source_type": "langflow",
    "url": "http://localhost:7860",
    "api_key": "sk-langflow-key"
  }'

​
Response

201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-langflow",
  "source_type": "langflow",
  "url": "http://localhost:7860",
  "status": "active",
  "version_info": {
    "version": "1.0.18",
    "name": "LangFlow",
    "status": "ok"
  },
  "created_at": "2025-11-04T12:00:00Z",
  "updated_at": "2025-11-04T12:00:00Z"
}
400 Bad Request
{
  "detail": "Source with URL http://localhost:7860 already exists"
}
400 Bad Request (Connection Failed)
{
  "detail": "Failed to validate source: Connection refused"
}
Source Validation: Spark validates the source by connecting to its health endpoint. Ensure the source is running and accessible before creating.Health Endpoints by Type:
  • LangFlow: GET /health
  • Hive: GET /api/v1/health
  • Agents: GET /health

​
Update Source

Update an existing workflow source. You can update the name, URL, API key, or status.
​
source_id
uuid
required
UUID of the source to update
​
name
string
New name for the source
​
source_type
string
New source type (not recommended to change)
​
url
string
New base URL for the source
​
api_key
string
New API key for authentication
​
status
string
New status: active or inactive
curl -X PATCH http://localhost:8883/api/v1/sources/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "name": "updated-langflow",
    "status": "inactive"
  }'

​
Response

200 Success
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "updated-langflow",
  "source_type": "langflow",
  "url": "http://localhost:7860",
  "status": "inactive",
  "version_info": {
    "version": "1.0.18",
    "name": "LangFlow",
    "status": "ok"
  },
  "created_at": "2025-11-04T12:00:00Z",
  "updated_at": "2025-11-04T12:30:00Z"
}
404 Not Found
{
  "detail": "Source not found"
}
400 Bad Request
{
  "detail": "Source with URL http://localhost:7860 already exists"
}
Partial Updates: You only need to include the fields you want to update. Other fields remain unchanged.

​
Delete Source

Delete a workflow source. This will also remove all associated workflows and schedules.
​
source_id
uuid
required
UUID of the source to delete
curl -X DELETE http://localhost:8883/api/v1/sources/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-api-key"

​
Response

200 Success
{
  "message": "Source deleted successfully"
}
404 Not Found
{
  "detail": "Source not found"
}
400 Bad Request
{
  "detail": "Error deleting source: [error details]"
}
Cascade Delete: Deleting a source will remove all workflows and schedules associated with it. This action cannot be undone.

​
Source Types

​
LangFlow

LangFlow is a visual workflow builder for creating AI agents and workflows. Configuration: 
{
  "source_type": "langflow",
  "url": "http://localhost:7860",
  "api_key": "sk-..."
}
Health Check: GET /health (expects {"status": "ok"})

​
AutoMagik Hive

Hive is a multi-agent system supporting agents, teams, and workflows. Configuration: 
{
  "source_type": "automagik-hive",
  "url": "http://localhost:8886",
  "api_key": ""
}
Health Check: GET /api/v1/health (expects {"status": "success"})

​
AutoMagik Agents

AutoMagik Agents is a framework for building AI agents. Configuration: 
{
  "source_type": "automagik-agents",
  "url": "http://localhost:8000",
  "api_key": ""
}
Health Check: GET /health (expects {"status": "healthy"})

​
Error Codes

StatusDetailCause
400Source with URL already existsDuplicate source URL
400Failed to validate sourceCannot connect to source or health check failed
400Error deleting sourceDatabase or cascade delete error
404Source not foundInvalid source ID
401Invalid API keyMissing or incorrect X-API-Key header

​
Next Steps

Workflows API

Sync workflows from sources

Schedules API

Schedule workflows to run automatically

CLI: Sources

Manage sources via command line

Integration: LangFlow

Complete LangFlow integration guide