HTTP API

/api/v1/{integration}/{operation}

# Simple invocation
curl http://localhost:8080/api/v1/httpbin/get_headers
 
# GET with connection and instance selectors
curl 'http://localhost:8080/api/v1/slack/chat.postMessage?_connection=mcp&_instance=workspace-123&channel=C123&text=hello'
 
# POST with connection selector and parameters
curl -X POST http://localhost:8080/api/v1/slack/chat.postMessage \
  -H 'Content-Type: application/json' \
  -d '{"_connection": "mcp", "channel": "C123", "text": "hello"}'
 
# Create a workflow schedule
curl -X POST http://localhost:8080/api/v1/workflow/schedules \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "cron": "0 */6 * * *",
    "timezone": "America/New_York",
    "target": {
      "plugin": {
        "name": "github",
        "operation": "issues.list",
        "input": {
          "owner": "valon-technologies",
          "repo": "gestalt"
        }
      }
    }
  }'
 
# Create a workflow trigger
curl -X POST http://localhost:8080/api/v1/workflow/event-triggers \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "match": {
      "type": "roadmap.item.updated",
      "source": "roadmap",
      "subject": "item"
    },
    "target": {
      "plugin": {
        "name": "slack",
        "operation": "chat.postMessage",
        "input": {
          "channel": "C123",
          "text": "Roadmap item updated"
        }
      }
    }
  }'
 
# Publish a workflow event
curl -X POST http://localhost:8080/api/v1/workflow/events \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "roadmap.item.updated",
    "source": "roadmap",
    "subject": "item",
    "dataContentType": "application/json",
    "data": {
      "id": "item-1"
    },
    "extensions": {
      "traceId": "trace-1"
    }
  }'
 
# List failed workflow runs for one plugin
curl 'http://localhost:8080/api/v1/workflow/runs?plugin=github&status=failed' \
  -H 'Authorization: Bearer gst_api_...'
 
# Create an agent session
curl -X POST http://localhost:8080/api/v1/agent/sessions \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: agent-session-1' \
  -d '{
    "provider": "managed",
    "model": "gpt-5.4",
    "clientRef": "roadmap-risk",
    "metadata": {
      "ticket": "RD-42"
    }
  }'
 
# Create a turn in that session
curl -X POST http://localhost:8080/api/v1/agent/sessions/session-123/turns \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: agent-turn-1' \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "system",
        "text": "Be concise.",
        "parts": [
          {"type": "text", "text": "Be concise."}
        ]
      },
      {
        "role": "user",
        "text": "Summarize the roadmap risk.",
        "parts": [
          {"type": "text", "text": "Summarize the roadmap risk."},
          {
            "type": "json",
            "json": {
              "ticket": "RD-42"
            }
          }
        ],
        "metadata": {
          "ticket": "RD-42"
        }
      }
    ],
    "toolRefs": [
      {"pluginName": "roadmap", "operation": "sync"}
    ],
    "responseSchema": {
      "type": "object",
      "properties": {
        "summary": {"type": "string"}
      },
      "required": ["summary"]
    },
    "metadata": {
      "ticket": "RD-42"
    }
  }'
 
# List active sessions for one provider
curl -H 'Authorization: Bearer gst_api_...' \
  'http://localhost:8080/api/v1/agent/sessions?provider=managed&state=active'
 
# Inspect a session
curl -H 'Authorization: Bearer gst_api_...' \
  http://localhost:8080/api/v1/agent/sessions/session-123
 
# Inspect a turn
curl -H 'Authorization: Bearer gst_api_...' \
  http://localhost:8080/api/v1/agent/turns/turn-123
 
# List session turns
curl -H 'Authorization: Bearer gst_api_...' \
  'http://localhost:8080/api/v1/agent/sessions/session-123/turns?status=running'
 
# List turn events after sequence 0
curl -H 'Authorization: Bearer gst_api_...' \
  'http://localhost:8080/api/v1/agent/turns/turn-123/events?after=0&limit=100'
 
# Stream turn events until the turn reaches a terminal state
curl -N -H 'Authorization: Bearer gst_api_...' \
  'http://localhost:8080/api/v1/agent/turns/turn-123/events/stream?after=0'
 
# Stream turn events until the turn is terminal or waiting on an interaction
curl -N -H 'Authorization: Bearer gst_api_...' \
  'http://localhost:8080/api/v1/agent/turns/turn-123/events/stream?after=0&until=blocked_or_terminal'
 
# List pending turn interactions
curl -H 'Authorization: Bearer gst_api_...' \
  'http://localhost:8080/api/v1/agent/turns/turn-123/interactions'
 
# Resolve a pending interaction
curl -X POST http://localhost:8080/api/v1/agent/turns/turn-123/interactions/interaction-123/resolve \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "resolution": {
      "approved": true
    }
  }'
 
# Cancel an agent turn
curl -X POST http://localhost:8080/api/v1/agent/turns/turn-123/cancel \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"operator requested"}'
 
# Typical session create response
# {
#   "id": "session-123",
#   "provider": "managed",
#   "model": "gpt-5.4",
#   "state": "active",
#   "clientRef": "roadmap-risk",
#   "createdAt": "2026-04-22T00:00:00Z",
#   "updatedAt": "2026-04-22T00:00:00Z"
# }
 
# Typical turn create response
# {
#   "id": "turn-123",
#   "sessionId": "session-123",
#   "provider": "managed",
#   "model": "gpt-5.4",
#   "status": "running",
#   "messages": [
#     {"role":"system","text":"Be concise.","parts":[{"type":"text","text":"Be concise."}]},
#     {"role":"user","text":"Summarize the roadmap risk.","parts":[{"type":"text","text":"Summarize the roadmap risk."}],"metadata":{"ticket":"RD-42"}}
#   ],
#   "createdAt": "2026-04-22T00:00:00Z",
#   "startedAt": "2026-04-22T00:00:00Z",
#   "executionRef": "turn-123"
# }
 
# Typical interaction list response
# [
#   {
#     "id": "interaction-123",
#     "turnId": "turn-123",
#     "type": "approval",
#     "state": "pending",
#     "title": "Approve external call",
#     "prompt": "Allow this turn to continue?",
#     "request": {"host":"api.openai.com"}
#   }
# ]
 
# Add a dynamic plugin member from the management/admin surface by email alias
curl -X PUT http://localhost:9090/admin/api/v1/authorization/plugins/sample_plugin/members \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","role":"viewer"}'