Open Dashboard

This feature is only available in the Enterprise version

AI integrations

Control agent job

Pause, resume, approve, reject, or schedule an agent job.

POST/agents/jobs/{job_id}/control

Use this endpoint to pause or resume a running job, approve or reject a waiting checkpoint, or promote a finished plan into a one-time or recurring schedule.

Pause, resume, approve, and reject return a job status object. Schedule actions return a smaller payload with the new child job or recurring template.

Enterprise authentication

Send these requests to https://api.cloud.blnkfinance.com on Blnk Cloud. On a self-hosted Enterprise deployment, send them to ENTERPRISE_PUBLIC_URL.

Pass an Enterprise API key, or an OAuth access token, in the X-blnk-key header. Create the key in Enterprise API keys, or issue a token with Enterprise OAuth.

This credential comes from the Cloud or Enterprise workspace. A Core API key belongs to the Core instance.

X-blnk-keystringrequiredheader

Enterprise API key, or an OAuth access token.

Path

job_idstringrequiredpath

Job to control (job_...). Use the job_id returned by Create agent job.

Body

actionstringrequiredbody

What to do with the job:

  • pause: Soft pause. The current step finishes, then the job and its plan run stop before the next step. Status becomes paused.
  • resume: Start the job again. If scheduled_run_at is still in the future, status returns to scheduled. Otherwise Cloud runs it now.
  • approve: Continue a job in waiting_approval. The job must already have a plan_run_id.
  • reject: Fail the waiting step and move the job to failed. The job must already have a plan_run_id.
  • schedule: Create a one-time child job or a recurring template from this job’s plan. The job must already have a reusable plan.
approver_idstringbody

Who approved or rejected the waiting step. Required in practice for an audit trail. If you omit it, Cloud stores job-control. Used only with approve and reject.

reasonstringbody

Why you approved or rejected the step. Stored with the decision. Used only with approve and reject.

schedule.modestringbody

Required when action is schedule.

  • once: creates a child job that runs at run_at.
  • recurring: creates a template that keeps using this job’s plan.
schedule.run_atstringbody

When the child job should start. Required for mode: "once". Send an RFC3339 timestamp such as 2026-09-17T09:00:00Z.

schedule.cron_exprstringbody

How often the recurring template should run. Required for mode: "recurring", e.g. 0 * * * * for every hour.

schedule.timezonestringbody

Timezone for the cron expression. Defaults to UTC. Use an IANA name such as Africa/Lagos.

schedule.namestringbody

Label for the recurring template. If you omit it, Cloud uses a truncated copy of the original job message.

Response

Pause, resume, approve, and reject return the job after the action. Schedule returns a smaller payload for the new child job or template.

job_idstring

Job you sent in the path (job_...). On schedule actions this is the parent job, not the new child or template.

statusstring

After pause: paused. After resume or approve: usually running. After reject: failed. After schedule once: scheduled (the child job). After schedule recurring: active (the template).

status_messagestring

Short sentence that matches status. Present on pause, resume, approve, and reject. Not on schedule responses.

plan_run_idstring

Plan attached to the job (pr_...). Present on pause, resume, approve, and reject.

last_errorstring

Why the job failed. Present after reject, or when a step already failed.

sub_tasksarray

Plan steps on the job. Present on pause, resume, approve, and reject. This is the raw step list, not the compact status view.

created_attimestamp

When Cloud accepted the job. Present on pause, resume, approve, and reject.

updated_attimestamp

When the control action landed. Present on pause, resume, approve, and reject.

scheduled_job_idstring

New child job created by schedule + once (job_...). Poll this ID with Get job status.

scheduled_run_attimestamp

When that child job will start, in UTC ISO 8601. Only on schedule + once.

recurring_template_idstring

Template created by schedule + recurring (rt_...).

next_run_attimestamp

When that template will fire next, in UTC ISO 8601. Only on schedule + recurring.