Run integration execution

POST
/workspaces
/:workspace
/integrations
/:hash_id
/execs

Run a one-shot execution on the integration. type is required and selects the payload: MCP runs the mcp operation on the MCP server of the integration and returns the response in the execution log as JSON.

Request

REQUIRED SCOPES

INTEGRATION_USE

URL PARAMETERS

workspacerequiredstring

The human-readable ID of the workspace

Example: "my-company"

hash_idrequiredstring

The hash ID of the integration

Example: "abc123def456"

BODY PARAMETERS

typerequiredstring enum

The type of the execution; it selects the payload. MCP runs the mcp operation on the MCP server of the integration

Allowed enum:

COMMAND,

MCP

mcpMcpExecRequest

The MCP operation to run on the integration's MCP server. Required with type MCP

Response

RESPONSE BODY

typestring enum

The type of the execution: COMMAND (a command in the target's language) or MCP (an operation on the integration's MCP server)

Allowed enum:

COMMAND,

MCP

urlread-onlystring

API endpoint to GET this object

html_urlread-onlystring

Web URL to view this object in Buddy.works

execution_idstring

The ID of the execution

target_idstring

The ID of the target

target_typestring enum

The type of the target

Allowed enum:

FTP,

SSH,

MATCH,

MATCH_ID,

VULTR,

DIGITAL_OCEAN,

UPCLOUD,

GIT,

ARTIFACT_VERSION,

GKE,

EKS,

AKS,

DOKS,

K8S_CLUSTER,

EC2,

AGENT,

SANDBOX,

MYSQL,

PROJECT_REPO,

POSTGRESQL,

MONGO,

MSSQL,

RDS_MSSQL,

CLICKHOUSE,

RDS_MYSQL,

RDS_POSTGRESQL

integrationstring

The hash ID of the integration the execution ran on (MCP executions)

invokerMemberView

User/member reference

cancelled_byMemberView

User/member reference

proxy_target_idstring

The ID of the proxy target used to tunnel the connection

commandstring

The executed command; for an MCP execution the operation as canonical JSON

started_atstring

The date and time when the execution started

finished_atstring

The date and time when the execution finished

statusstring

The status of the execution. One of: INPROGRESS, SUCCESSFUL, FAILED, CANCELLED

failure_reasonstring

Platform-level reason a FAILED execution failed (absent for an ordinary non-zero exit): TIMEOUT (hard time cap reached), SPAWN_FAILED (execution could not be started), BASTION_FAILED (SSH bastion tunnel failed)

exit_codeinteger

The exit code of the executed command

bytes_outinteger

The size of the execution output in bytes

truncatedboolean

Indicates if the execution output was truncated

error_messagestring

The error message if the execution failed

log_urlstring

The URL to fetch the execution log

Last modified on Oct 20, 2026

List integration executions Get integration execution

Examples

MCP list tools request MCP tool call request

Example: MCP list tools request


curl -X POST "https://api.buddy.works/workspaces/:workspace/integrations/:hash_id/execs" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "MCP",
  "mcp": {
    "operation": "LIST_TOOLS"
  }
}'

Example: MCP tool call request


curl -X POST "https://api.buddy.works/workspaces/:workspace/integrations/:hash_id/execs" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "MCP",
  "mcp": {
    "operation": "CALL_TOOL",
    "tool": "search_issues",
    "arguments": {
      "query": "is:open label:bug"
    }
  }
}'

EXAMPLE RESPONSE
{
  "url": "https://api.buddy.works/workspaces/my-workspace/integrations/eXaMpLeHaSh/execs/0f7c2d51-4a8e-4f0b-9d7e-3c1b2a6e5f90",
  "log_url": "https://api.buddy.works/workspaces/my-workspace/integrations/eXaMpLeHaSh/execs/0f7c2d51-4a8e-4f0b-9d7e-3c1b2a6e5f90/log",
  "execution_id": "0f7c2d51-4a8e-4f0b-9d7e-3c1b2a6e5f90",
  "integration": "eXaMpLeHaSh",
  "type": "MCP",
  "invoker": {
    "url": "https://api.buddy.works/workspaces/my-workspace/members/1",
    "id": 1,
    "name": "John Doe"
  },
  "command": "{\"operation\":\"LIST_TOOLS\"}",
  "started_at": "2026-05-28T08:00:09.820Z",
  "status": "INPROGRESS"
}

STATUS
200 Execution accepted and started; row carries `status: RUNNING` until poll endpoints flip to terminal