Dedicated Agent

A per-user, always-on agent with its own gateway, available to accounts with the dedicated_agent flag. Chat with it, inspect its activity, manage its scheduled jobs and autonomous runs, and replay its console history.

Endpoints

Method	Path	Purpose
POST	/microservices/dedicated-agent/chat/stream	Send a message (streamed reply over the socket)
POST	/microservices/dedicated-agent/chat/	Send a message (synchronous)
GET	/microservices/dedicated-agent/messages/	Console history
GET	/microservices/dedicated-agent/activity/	Activity log and spend
POST	/microservices/dedicated-agent/kill/	Pause the agent
GET	/microservices/dedicated-agent/jobs/	Scheduled jobs
GET	/microservices/dedicated-agent/jobs/{job_id}/	One job
DELETE	/microservices/dedicated-agent/jobs/{job_id}/	Delete a job
POST	/microservices/dedicated-agent/jobs/{job_id}/{action}/	Pause, resume or run a job now
POST	/microservices/dedicated-agent/runs/	Start an autonomous run
GET	/microservices/dedicated-agent/runs/{run_id}/	Run status
GET	/microservices/dedicated-agent/runs/{run_id}/events/	Run event stream
POST	/microservices/dedicated-agent/runs/{run_id}/{action}/	Approve a tool call, or stop the run

POST /microservices/dedicated-agent/chat/stream

Send a message (streamed reply over the socket)

Starts a turn on your dedicated agent and returns immediately with 202. The agent's progress and answer arrive on the WebSocket ws/dedicated-agent/{agent_id}/ (same stage:* telemetry envelope as Chat AI — see Streaming & WebSockets) and the answer is also persisted to the chat session, so it survives a closed tab. The agent handles one turn at a time: a second message while it is busy answers 409.

Auth: Session token · In the app: Dedicated Agent console

Request body (application/json)

Field	Type	Required	Description
message	string	yes
chat_session_id	integer	no	A sessions/ row of type dedicated-agent owned by the caller; created for you when omitted.
attached_files	object[]	no	Files from My Data, as in Chat AI.

{
  "message": "Draft a reply to the supplier about the late delivery.",
  "chat_session_id": 9310
}

Response 202 — Turn started; listen on the socket.

Field	Type	Description
status	string ("started")
chat_session_id	integer
session_id	string, nullable	The gateway's conversation id.

{
  "status": "started",
  "chat_session_id": 9310,
  "session_id": "sess_91ab"
}

Response 400 — message missing or bad chat_session_id.

{
  "detail": "Authentication credentials were not provided."
}

Response 403 — The session is not yours.

Response 404 — You have no dedicated agent.

{
  "detail": "no dedicated agent for this user"
}

Response 409 — The agent is paused/stopped, or busy with another turn (busy_chat_session_id names it).

{
  "detail": "agent is busy in another conversation",
  "busy_chat_session_id": 9302
}

Example

curl -X POST "https://api.example.com/microservices/dedicated-agent/chat/stream" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Draft a reply to the supplier about the late delivery.","chat_session_id":9310}'

POST /microservices/dedicated-agent/chat/

Send a message (synchronous)

Waits for the agent's answer (up to 5 minutes) and returns it. Prefer the streaming endpoint from interactive clients.

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
message	string	yes
attached_files	object[]	no

Response 200 — The answer.

Field	Type	Description
answer	string
session_id	string, nullable
generated_files_urls	string[]

Response 404 — No dedicated agent.

Response 409 — Agent not running.

Response 502 — Gateway error.

Example

curl -X POST "https://api.example.com/microservices/dedicated-agent/chat/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/dedicated-agent/messages/

Console history

The stored conversation with the agent (oldest first within the window).

Auth: Session token · In the app: Dedicated Agent console (on open)

Query parameters

Field	Type	Required	Description
limit	integer	no	Default: 100.

Response 200 — Messages.

Field	Type	Description
agent_id	string
messages	object[]
messages[].id	integer
messages[].role	string ("user", "assistant")
messages[].message	string
messages[].created_at	string (date-time)

Example

curl -X GET "https://api.example.com/microservices/dedicated-agent/messages/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/dedicated-agent/activity/

Activity log and spend

Every platform tool the agent called (newest first) and its LLM spend against the budget.

Auth: Session token · In the app: Dedicated Agent → Activity

Query parameters

Field	Type	Required	Description
limit	integer	no	Default: 50.

Response 200 — Activity.

Field	Type	Description
agent_id	string
status	string ("running", "paused", "stopped", "provisioning")
activity	object[]
activity[].tool_name	string
activity[].success	boolean
activity[].duration_ms	integer
activity[].ts	string (date-time)
spend	object, nullable
spend.spend	number
spend.soft_budget	number, nullable

{
  "agent_id": "agt_42",
  "status": "running",
  "activity": [
    {
      "tool_name": "send_email",
      "success": true,
      "duration_ms": 812,
      "ts": "2026-09-22T08:03:10Z"
    }
  ],
  "spend": {
    "spend": 12.4,
    "soft_budget": 50
  }
}

Response 404 — No dedicated agent.

Example

curl -X GET "https://api.example.com/microservices/dedicated-agent/activity/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/dedicated-agent/kill/

Pause the agent

Soft pause — the console stops routing to the agent and the gateway is asked to stop. Resuming is done by an operator.

Auth: Session token · In the app: Dedicated Agent → Pause

Response 200 — Paused.

Field	Type	Description
success	boolean
status	string
note	string

Response 404 — No dedicated agent.

Example

curl -X POST "https://api.example.com/microservices/dedicated-agent/kill/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/dedicated-agent/jobs/

Scheduled jobs

Auth: Session token · In the app: Dedicated Agent → Jobs

Query parameters

Field	Type	Required	Description
include_disabled	boolean	no

Response 200 — Jobs (gateway response).

Field	Type	Description
jobs	object[]
jobs[].id	string
jobs[].name	string
jobs[].prompt	string	What the agent does when the job fires.
jobs[].schedule	object	Machine schedule (kind: interval, cron or once, …).
jobs[].schedule_display	string	Human-readable, e.g. every day 9am.
jobs[].enabled	boolean
jobs[].state	string ("scheduled", "paused", "completed", "error")
jobs[].next_run_at	string (date-time), nullable
jobs[].last_run_at	string (date-time), nullable
jobs[].last_status	string, nullable
jobs[].last_error	string, nullable
jobs[].repeat	object
jobs[].repeat.times	integer, nullable	null = forever.
jobs[].repeat.completed	integer
jobs[].latest_execution	object, nullable	The most recent run (status, timestamps).

Response 502 — Agent unreachable.

Example

curl -X GET "https://api.example.com/microservices/dedicated-agent/jobs/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/dedicated-agent/jobs/{job_id}/

One job

Auth: Session token

Path parameters

Field	Type	Required	Description
job_id	string	yes

Response 200 — The job.

Field	Type	Description
id	string
name	string
prompt	string	What the agent does when the job fires.
schedule	object	Machine schedule (kind: interval, cron or once, …).
schedule_display	string	Human-readable, e.g. every day 9am.
enabled	boolean
state	string ("scheduled", "paused", "completed", "error")
next_run_at	string (date-time), nullable
last_run_at	string (date-time), nullable
last_status	string, nullable
last_error	string, nullable
repeat	object
repeat.times	integer, nullable	null = forever.
repeat.completed	integer
latest_execution	object, nullable	The most recent run (status, timestamps).

{
  "id": "job_7a1",
  "name": "Morning briefing",
  "prompt": "Summarise overnight emails and today's calendar.",
  "schedule": {
    "kind": "cron",
    "expr": "0 9 * * 1-5"
  },
  "schedule_display": "every weekday 9am",
  "enabled": true,
  "state": "scheduled",
  "next_run_at": "2026-09-23T09:00:00+03:00",
  "last_run_at": "2026-09-22T09:00:00+03:00",
  "last_status": "completed",
  "last_error": null,
  "repeat": {
    "times": null,
    "completed": 14
  },
  "latest_execution": {
    "status": "completed"
  }
}

Example

curl -X GET "https://api.example.com/microservices/dedicated-agent/jobs/<job_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /microservices/dedicated-agent/jobs/{job_id}/

Delete a job

Auth: Session token

Path parameters

Field	Type	Required	Description
job_id	string	yes

Response 200 — Deleted.

Example

curl -X DELETE "https://api.example.com/microservices/dedicated-agent/jobs/<job_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/dedicated-agent/jobs/{job_id}/{action}/

Pause, resume or run a job now

Auth: Session token

Path parameters

Field	Type	Required	Description
job_id	string	yes
action	string ("pause", "resume", "run")	yes

Response 200 — Done (gateway response).

Response 400 — Unknown action, or the gateway refused (e.g. resuming a one-shot whose time has passed — error explains).

Example

curl -X POST "https://api.example.com/microservices/dedicated-agent/jobs/<job_id>/run/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/dedicated-agent/runs/

Start an autonomous run

Hands the agent a task to complete on its own. Follow it with GET …/runs/{run_id}/ or the event stream; approve tool use when it pauses in waiting_for_approval.

Auth: Session token · In the app: Dedicated Agent → Runs → New

Request body (application/json)

Field	Type	Required	Description
input	string	yes	The task.
instructions	string	no	Extra guidance.
model	string	no

{
  "input": "Audit last month's invoices for duplicates and prepare a report."
}

Response 200 — The run (gateway response; the id is run_id or id).

Field	Type	Description
id	string	Also returned as run_id.
status	string ("started", "queued", "running", "waiting_for_approval", "stopping", "completed", "failed", "cancelled")
input	string
instructions	string
model	string
output	string, nullable	Final answer when completed.
created_at	string (date-time)
updated_at	string (date-time)

{
  "id": "run_3f2e",
  "status": "running",
  "input": "Audit last month's invoices for duplicates and prepare a report.",
  "model": "default",
  "output": null,
  "created_at": "2026-09-22T08:00:00Z",
  "updated_at": "2026-09-22T08:03:10Z"
}

Response 502 — Agent unreachable.

Example

curl -X POST "https://api.example.com/microservices/dedicated-agent/runs/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"Audit last month's invoices for duplicates and prepare a report."}'

GET /microservices/dedicated-agent/runs/{run_id}/

Run status

Auth: Session token

Path parameters

Field	Type	Required	Description
run_id	string	yes

Response 200 — The run.

Field	Type	Description
id	string	Also returned as run_id.
status	string ("started", "queued", "running", "waiting_for_approval", "stopping", "completed", "failed", "cancelled")
input	string
instructions	string
model	string
output	string, nullable	Final answer when completed.
created_at	string (date-time)
updated_at	string (date-time)

{
  "id": "run_3f2e",
  "status": "running",
  "input": "Audit last month's invoices for duplicates and prepare a report.",
  "model": "default",
  "output": null,
  "created_at": "2026-09-22T08:00:00Z",
  "updated_at": "2026-09-22T08:03:10Z"
}

Response 404 — Unknown run.

Example

curl -X GET "https://api.example.com/microservices/dedicated-agent/runs/<run_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/dedicated-agent/runs/{run_id}/events/

Run event stream

Server-Sent Events from the gateway for one run (tool calls, approvals, output). Open with EventSource or any SSE client.

Auth: Session token

Path parameters

Field	Type	Required	Description
run_id	string	yes

Response 200 — SSE stream.

Content type: text/event-stream

Example

curl -X GET "https://api.example.com/microservices/dedicated-agent/runs/<run_id>/events/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/dedicated-agent/runs/{run_id}/{action}/

Approve a tool call, or stop the run

approval answers a pending approval with choice (once, session, always or deny; add all: true to apply to every pending request). stop cancels the run.

Auth: Session token

Path parameters

Field	Type	Required	Description
run_id	string	yes
action	string ("approval", "stop")	yes

Request body (application/json, optional)

Field	Type	Required	Description
choice	string ("once", "session", "always", "deny")	no
all	boolean	no

{
  "choice": "once"
}

Response 200 — Done (gateway response).

Response 400 — Unknown action.

Example

curl -X POST "https://api.example.com/microservices/dedicated-agent/runs/<run_id>/<action>/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"choice":"once"}'