Executar Workflow

Executar um workflow com deploy ativo de forma síncrona, de forma assíncrona ou como Server-Sent Events. Workflows públicos permitem execução anônima síncrona e por streaming; a execução assíncrona exige uma API key. Uma execução síncrona que ultrapassa seu timeout de execução retorna HTTP 200 com status: "failed" e error.code: "TIMEOUT" em vez de um erro HTTP, portanto ramifique pelo status. Cada opção indica os modos que exige e os modos que a rejeitam; uma combinação violada é um 400.

POST/api/v2/workflows/{workflowId}/execute

Authorization

X-API-Key<token>

Sua API key do Studio, pessoal ou com escopo de workspace. Gere uma em Settings e depois API Keys. As operações que rejeitam API keys de workspace dizem isso na própria descrição.

Em: header

Parâmetros de path

workflowId*string

Identificador único do workflow.

Tamanho1 <= length

Parâmetros de header

x-run-id?string

Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns 409 with RUN_ID_CONFLICT, without replaying results. Check Get Workflow Run, but 404 can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.

Corresponde a^[A-Za-z0-9._:-]+$

Tamanho1 <= length <= 128

x-studio-via?string

Identificadores de workflow, separados por vírgula, que nomeiam a cadeia de chamadas de workflow para workflow que levou a esta requisição. Cada salto acrescenta o próprio id de workflow, e o Studio define isso automaticamente; informe você mesmo apenas ao repassar uma cadeia existente. Uma cadeia na profundidade máxima é rejeitada com 409 e error.details.code: "CALL_CHAIN_DEPTH_EXCEEDED".

Corpo da requisição

application/json

Input, workflow-state selection, and execution-mode options. Input descriptions specify compatible modes; invalid combinations return 400.

Definições TypeScript

Use o tipo request body no TypeScript.

input?

Workflow input keyed by the selected trigger input-field name.

run?|

Workflow state and entry point to execute. Omit for the active deployment. Manual execution requires OAuth or personal-key write access and supports synchronous or streamed runs only.

async?boolean

Queue the run and return a 202 receipt when true. Requires an OAuth access token or API key, cannot be combined with stream, and rejects all streaming and output-shaping options (selectedOutputs, includeThinking, includeToolCalls, includeFileBase64, base64MaxBytes).

Padrãofalse

executionTimeoutSeconds?integer

Maximum duration of an asynchronous run, in seconds, capped by the plan's execution timeout. Requires async: true; otherwise returns 400.

Intervalo1 <= value <= 604800

stream?boolean

Retornar Server-Sent Events em vez de JSON quando true. Não pode ser combinado com async.

Padrãofalse

selectedOutputs?array<>

Output references for streaming: <blockName>.<outputPath> or <childWorkflowId>.<blockName>.<outputPath>, using normalized block names. Child references apply to every invocation. Requires stream: true and rejects synchronous or async requests. Use selectedOutputs with Get Workflow Run to narrow an existing run.

Itensitems <= 100

includeThinking?boolean

Incluir eventos de raciocínio do modelo em um stream de eventos do agente. Exige stream: true e o header de requisição X-Studio-Stream-Protocol: agent-events-v1, e é rejeitado quando async é true.

Padrãofalse

includeToolCalls?boolean

Incluir eventos de chamada de ferramenta em um stream de eventos do agente. Exige stream: true e o header de requisição X-Studio-Stream-Protocol: agent-events-v1, e é rejeitado quando async é true.

Padrãofalse

includeFileBase64?boolean

Embutir os files de saída elegíveis como conteúdo base64. Rejeitado quando async é true.

base64MaxBytes?integer

Maximum total bytes of file content to inline as base64, lowering but never raising the server limit of 16 MiB. Rejected when async is true.

Intervalo0 < value <= 16777216

Corpo da resposta

`application/json`

curl -X POST "https://agent-studio.seeyu.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute" \  -H "X-API-Key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "ticketId": "ticket_123"    }  }'

{
  "data": {
    "runId": "run_8f14e45f-ceea-467f-a",
    "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
    "status": "completed",
    "output": {
      "result": "Ticket routed to Support"
    },
    "error": null,
    "startedAt": "2026-08-09T18:04:10.000Z",
    "endedAt": "2026-08-09T18:04:11.000Z",
    "durationMs": 1000
  }
}

{
  "data": {
    "runId": "run_8f14e45f-ceea-467f-a",
    "statusUrl": "https://agent-studio.seeyu.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Usage limit exceeded. Please upgrade your plan to continue."
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "Run ID has already been used",
    "details": {
      "code": "RUN_ID_CONFLICT",
      "runId": "0f7c1a2e-9b3d-4c58-8a21-6d4e5f7a9b01"
    }
  }
}

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}

{
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Request body must be sent as application/json"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}

{
  "error": {
    "code": "CLIENT_CLOSED_REQUEST",
    "message": "Client cancelled request",
    "details": {
      "runId": "0f7c1a2e-9b3d-4c58-8a21-6d4e5f7a9b01"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}

Executar Workflow

Authorization

Parâmetros de path

Parâmetros de header

Corpo da requisição

Corpo da resposta

200application/json

202application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

413application/json

415application/json

429application/json

499application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`