SaaSFlow
DevelopersAPIReferenceagent_runs

Create agent run

Start an agent run. `definitionId` comes from the agent-definitions endpoint and `input` carries that agent's parameters. Returns a `runId` immediately; the agent works in the background, so poll the run or its messages. To continue a finished session rather than start fresh, pass `resumeFromRunId` and put the follow-up instruction in `input.prompt`; the earlier transcript is restored. Because agents send company data to an AI provider, a company that has not consented gets 403 with `code: "aiConsentRequired"` and the `providerKey` to request. The caller also needs every permission the agent uses, not just `transactions:read`. One run at a time per company (409), with a per-company rate limit (429, carrying `retryAt`).

Authentication

You're not signed in. Either sign in at app.saasflow.com and reload (then pick sessionCookie), or paste a SaaSFlow sf_… API key in the bearerAuth field below.
POST
/companies/{companyId}/agent_runs

Authorization

Authorization<token>

A SaaSFlow API key (format sf_…) or an OAuth bearer token. Paste only the key — the proxy adds the Bearer prefix. Create an API key in Settings → Company settings → API keys — see API keys.

In: header

Path Parameters

companyId*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/companies/string/agent_runs" \  -H "Content-Type: application/json" \  -d '{    "definitionId": "string"  }'
{  "runId": "string"}

List agent runs

List this company's agent runs, past and in progress, with their status and which definition they came from. Use it to find a run id, or to check whether an agent is already working before starting another one.

Retrieve agent run

Retrieve one agent run: its status, the input it was started with, and its result once finished. Poll this after starting a run. Returns 404 if the run does not exist or belongs to another company.