HTTP API

{
  "name": "github",
  "status": "ready",
  "credentialState": "connected",
  "connections": [
    {
      "name": "default",
      "status": "ready",
      "authTypes": ["oauth"],
      "instances": [{"id": "acme", "name": "Acme"}],
      "connectionParams": {},
      "credentialFields": []
    }
  ]
}

{
  "target": {
    "steps": [
      {
        "id": "sync",
        "app": {
          "name": "roadmap",
          "operation": "sync_items",
          "input": {
            "literal": { "mode": "incremental" }
          }
        }
      }
    ]
  }
}

/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": {
	      "steps": [{
	        "id": "list-issues",
	        "app": {
	          "name": "github",
	          "operation": "issues.list",
	          "input": {
	            "literal": {
	              "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": {
	      "steps": [{
	        "id": "notify",
	        "app": {
	          "name": "slack",
	          "operation": "chat.postMessage",
	          "input": {
	            "literal": {
	              "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 app
curl 'http://localhost:8080/api/v1/workflow/runs?app=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",
    "workspace": {
      "checkouts": [
        {
          "url": "https://github.com/valon-technologies/roadmap.git",
          "ref": "main",
          "path": "roadmap"
        }
      ],
      "cwd": "roadmap"
    },
    "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": [
      {"appName": "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 app member from the management/admin surface by email alias
curl -X PUT http://localhost:9090/admin/api/v1/authorization/apps/sample_app/members \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","role":"viewer"}'
 
# Create a managed subject and grant it viewer access to a app
curl -X POST http://localhost:8080/api/v1/authorization/subjects \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -d '{"id":"release-bot","displayName":"Release Bot"}'
 
curl -X PUT http://localhost:8080/api/v1/authorization/subjects/service_account:release-bot/grants/github \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -d '{"role":"viewer"}'
 
curl -X POST http://localhost:8080/api/v1/authorization/subjects/service_account:release-bot/auth/connect-manual \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -d '{"integration":"github","credential":"ghp_..."}'
 
curl http://localhost:8080/api/v1/authorization/subjects/service_account:release-bot/integrations \
  -H 'Authorization: Bearer gst_api_...'
 
curl -X POST http://localhost:8080/api/v1/authorization/subjects/service_account:release-bot/tokens \
  -H 'Authorization: Bearer gst_api_...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"release-bot","permissions":[{"app":"github","operations":["issues.list"]}]}'