Skip to main content
POST
Agent Jobs API is currently in beta.
The Agent Jobs API turns an operator or developer request into a workflow that Cloud can plan, execute, approve, pause, resume, and schedule. You send a message such as “Review pending high-value transactions from the last 24 hours” or “Create a customer identity and a NGN balance.” The agent plans the work, applies the right tools and ledger scope, then runs the steps. The Jobs API is asynchronous. You create a job once, persist the job_id, then poll status, read the result, and control the job when you need to pause, approve, or schedule it.
Use this API when your app, worker, or internal tool submits work and tracks the lifecycle. For an AI assistant chatting against your ledger through tools, use the MCP server.

​
How it works

1

Create the job

Call POST /agents/jobs?instance_id=... with a message (or query) and optional tools, filters, and callbacks.
2

Persist the job ID

Store the returned job_id. You need it for status, result, and control.
3

Poll status, then read the result

Poll Get job status for progress, subtasks, and approval state. When the job completes or fails, read Get job result.
4

Control the job when needed

Use Control agent job to pause, resume, approve, reject, or schedule a follow-up run.

​
Authorization

Blnk Cloud APIs support any one of the following authentication methods. All of them work with your CLOUD_API_KEY or OAUTH_ACCESS_TOKEN.
Pass Authorization: Bearer CLOUD_API_KEY or Authorization: Bearer OAUTH_ACCESS_TOKEN.
​
string
required
Cloud API key or OAuth access token. Create credentials in API keys or OAuth.

​
Query

​
string
required
Core instance to run the job against (instance_...). Do not put instance_id inside filters.

​
Body

​
string
Natural-language request for the planner. Required unless you send query.
​
string
Alias for message. Both map to the same planner input. Send one of them.
​
boolean
When true, the job auto-approves steps that would otherwise pause. When false or omitted, a step that needs approval moves the job to waiting_approval. Poll Get job status for the approval state, then Control agent job with approve or reject.
​
array
Capabilities this job is allowed to use, such as filter.transactions or transactions.create.Do not send planner step names like backoffice.filter_collection. If a planned step needs a capability that is not in this list, the job fails before it runs. Omit the field to allow every capability. See Tool allowlist for the ful list.
​
string
Standing instructions for how the planner should behave on this job, for example “You are an operations analyst.” The original message stays the same.
​
string
Extra guidance for this request only, for example “Stay concise and list next steps.” Use this for one-off constraints. It does not replace message.
​
string
HTTPS URL Cloud POSTs when the job completes. Cloud sends this only on the terminal completed state. The body is the same payload as Get job result.
​
string
HTTPS URL Cloud POSTs when the job fails. Cloud sends this only on the terminal failed state. The body is the same payload as Get job result.
​
string
Shared secret so you can verify the webhook. When set, Cloud adds X-Blnk-Timestamp and X-Blnk-Signature. The signature is an HMAC-SHA256 hex digest of {timestamp}.{raw_json_body}.
​
array
Ledgers this job is allowed to read or write (ldg_...). Cloud narrows collection queries to these IDs, checks every step input against them, and fails the job before a step runs if it uses a ledger outside the list. This is a hard limit, not a hint to the planner.
​
array
Balances this job is allowed to read or write (bln_...). Cloud narrows collection queries to these IDs and fails any step that uses a balance outside the list.
​
array
Identities this job is allowed to read or write (idt_...). Cloud narrows collection queries to these IDs and fails any step that uses an identity outside the list.
​
array
Transactions this job is allowed to read or write (txn_...). Cloud narrows collection queries to these IDs and fails any step that uses a transaction outside the list.

​
Response

The create endpoint returns 202 Accepted with the new job ID, an initial status snapshot, and links for the next calls. Cloud claims the job immediately, so the first snapshot is usually running. It then moves to planning while the agent builds the plan.
​
string
ID of the new job (job_ plus a timestamp, for example job_1779300000000000000). Store this. You pass it to Get job status, Get job result, and Control agent job.
​
string
Where the job is right now. Create usually returns running because Cloud claims the job immediately. It then moves to planning, then back to running while steps execute. Later values: queued, scheduled, paused, waiting_approval, completed, failed. See Job lifecycle.
​
string
Short sentence that matches status, for example Workflow executing. or Planning workflow. Use this for logs or UI copy. Do not parse it.
​
string
ID of the plan Cloud built from your message (pr_...). Empty on create. It fills in after planning finishes. You need it only if you inspect the plan; status, result, and control use job_id.
​
timestamp
When Cloud accepted the job, in UTC ISO 8601.
​
timestamp
When the job last changed, in UTC ISO 8601. On create this matches created_at.
​
object
Relative paths for the next calls on this job: status, result, and control. Prefix them with https://api.cloud.blnkfinance.com.
​
object
Full compact status snapshot at create time. Same fields as Get job status, including progress, sub_tasks, and links. On create, steps are still empty. Poll status to watch them fill in.

​
Job lifecycle

A job moves through these states:

​
Tool allowlist

Each approved_tools entry is a tool permission token, not a step task_type. A single step may require more than one token.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.