HTTP API

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

{
  "integration": "github",
  "connection": "default",
  "instance": "automation",
  "serviceAccountId": "nightly-sync",
  "scopes": ["repo"],
  "connectionParams": {}
}

{
  "integration": "model-api",
  "connection": "default",
  "instance": "automation",
  "serviceAccountId": "service_account:nightly-sync",
  "credential": "api-token",
  "credentials": {
    "client_id": "id-123",
    "client_secret": "secret-456"
  },
  "connectionParams": {}
}

{
  "id": "run_123",
  "definitionId": "cfg_roadmap_sync",
  "definitionGeneration": "gen_20260603",
  "status": "RUNNING",
  "currentStepId": "sync",
  "input": { "itemId": "item-1" },
  "steps": [
    {
      "id": "sync",
      "status": "RUNNING",
      "attempts": []
    }
  ]
}

/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"}'
 
# Deliver a workflow event. source is the trusted app name; explicitly scoped
# API tokens must include that app.
curl -X POST http://localhost:8080/api/v1/workflow/events \
  -H 'Authorization: Bearer <api-grant>' \
  -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 <api-grant>'
 
# Create an agent session
curl -X POST http://localhost:8080/api/v1/agent/sessions \
  -H 'Authorization: Bearer <api-grant>' \
  -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 <api-grant>' \
  -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": [
      {"app": "roadmap", "operation": "sync"}
    ],
    "output": {
      "structured": {
        "schema": {
          "type": "object",
          "properties": {
            "summary": {"type": "string"}
          },
          "required": ["summary"]
        }
      }
    },
    "metadata": {
      "ticket": "RD-42"
    }
  }'
 
# List active sessions for one provider
curl -H 'Authorization: Bearer <api-grant>' \
  'http://localhost:8080/api/v1/agent/sessions?provider=managed&state=active'
 
# Inspect a session
curl -H 'Authorization: Bearer <api-grant>' \
  http://localhost:8080/api/v1/agent/sessions/session-123
 
# Inspect a turn
curl -H 'Authorization: Bearer <api-grant>' \
  http://localhost:8080/api/v1/agent/turns/turn-123
 
# List session turns
curl -H 'Authorization: Bearer <api-grant>' \
  'http://localhost:8080/api/v1/agent/sessions/session-123/turns?status=running'
 
# List turn events after sequence 0
curl -H 'Authorization: Bearer <api-grant>' \
  '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 <api-grant>' \
  '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 <api-grant>' \
  '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 <api-grant>' \
  '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 <api-grant>' \
  -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 <api-grant>' \
  -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"}
#   }
# ]