Runs

Start a single-turn run and read its result. A run executes one job of a single-turn Operation for one Partner and returns an answer and, when the job's agent declares one, structured data.

POST /mcp/v1/runs

Start a run

Runs the job in the foreground and answers with the run, or queues it in the background and answers at once with its runId. A background result is posted to your adapter when the Operation’s callback is on, and can be read with Get a run.

Authentication: your DomainKey in x-api-key. The run belongs to the key’s Domain.

Body parameters

partnerIdstring required

The Partner whose Operation runs.

operationKeystring required

The single-turn Operation to run, for example operation@repair-quote.

inputobject required

jobstring required

The job to run, for example job@repair-quote.

querystring required

The request to answer.

contextstring[] optional

Material you supply for this request. Each string is given to the job’s agent.

runInBackgroundboolean optional

Default false. When true, answers 202 with the runId.

Responses

200The run succeeded; data is the run.

202The run is queued; data is runId.

400invalid_input, job_unknown, job_unfilled, invalid_operation

401Missing or revoked key.

404operation_unknown

502run_failed

503workflow_unavailable

504run_timeout

What to do about each error →

curl https://api.wisa.live/mcp/v1/runs \
  -H "content-type: application/json" \
  -H "x-api-key: $WISA_DOMAIN_KEY" \
  -d '{
    "partnerId": "riverside",
    "operationKey": "operation@repair-quote",
    "input": { "job": "job@repair-quote", "query": "My rear brakes squeal. What does a brake service cost?" }
  }'

const { data: run } = await fetch("https://api.wisa.live/mcp/v1/runs", {
  method: "POST",
  headers: { "content-type": "application/json", "x-api-key": process.env.WISA_DOMAIN_KEY! },
  body: JSON.stringify({
    partnerId: "riverside",
    operationKey: "operation@repair-quote",
    input: { job: "job@repair-quote", query: "My rear brakes squeal. What does a brake service cost?" },
  }),
}).then((r) => r.json());

run = requests.post(
    "https://api.wisa.live/mcp/v1/runs",
    headers={"x-api-key": os.environ["WISA_DOMAIN_KEY"]},
    json={"partnerId": "riverside", "operationKey": "operation@repair-quote",
          "input": {"job": "job@repair-quote", "query": "My rear brakes squeal. What does a brake service cost?"}},
).json()["data"]

{
  "data": {
    "runId": "run_8f2c1a",
    "operationKey": "operation@repair-quote",
    "status": "succeeded",
    "result": {
      "answer": "A brake service usually costs 25 to 40 EUR. The shop confirms the price after a free inspection.",
      "data": { "service": "brake-service", "priceRange": [25, 40], "currency": "EUR" }
    }
  }
}

{ "data": { "runId": "run_8f2c1a" } }

{
  "error": {
    "message": "The Operation has no job named job@repair-quotes.",
    "code": 400,
    "errors": [{ "message": "The Operation has no job named job@repair-quotes.", "code": "job_unknown" }]
  }
}

{
  "error": {
    "message": "The run did not finish in time. Start it with runInBackground to receive the result later.",
    "code": 504,
    "errors": [{ "message": "The run did not finish in time.", "code": "run_timeout" }]
  }
}

GET /mcp/v1/runs/{runId}

Get a run

Reads a run started with a key of your Domain. A run is kept for a limited retention period after it starts.

Authentication: your DomainKey in x-api-key.

Path parameters

runIdstring required

The id returned when the run started.

Responses

200The run, in any status: queued, running, succeeded, failed. A failed run carries error with a code and a message.

404run_expired: unknown, another Domain’s, or past its retention.

curl https://api.wisa.live/mcp/v1/runs/run_8f2c1a \
  -H "x-api-key: $WISA_DOMAIN_KEY"

const { data: run } = await fetch("https://api.wisa.live/mcp/v1/runs/run_8f2c1a", {
  headers: { "x-api-key": process.env.WISA_DOMAIN_KEY! },
}).then((r) => r.json());

run = requests.get(
    "https://api.wisa.live/mcp/v1/runs/run_8f2c1a",
    headers={"x-api-key": os.environ["WISA_DOMAIN_KEY"]},
).json()["data"]

{
  "data": {
    "runId": "run_8f2c1a",
    "operationKey": "operation@repair-quote",
    "status": "running"
  }
}

{
  "error": {
    "message": "No run run_8f2c1a for this Domain.",
    "code": 404,
    "errors": [{ "message": "No run run_8f2c1a for this Domain.", "code": "run_expired" }]
  }
}