---
title: "Trigger Agent Job with Message"
method: POST
path: "/job/{runchat_job_id}"
tags: ["Jobs"]
---

# Trigger Agent Job with Message

`POST /job/{runchat_job_id}`

## Request

- Base URL: `https://runchat.com/api/v1`
- URL: `https://runchat.com/api/v1/job/{runchat_job_id}`
- Auth: HTTP bearer

Triggers an agent job and appends an additional user message to the saved chat template before running the agent loop. Use this to wire webhooks into scheduled agents.

This endpoint only supports agent jobs (jobs with a backing chat). Flow-backed jobs return `400` — use `GET /job/{runchat_job_id}` for those.

If `message` is provided, it is appended verbatim. Otherwise the entire request body is JSON-stringified and appended as the user message — useful for raw webhook payloads where the caller doesn't control the body shape. An empty body runs the saved template as-is.

The history row written to `runchat_job_history` is identical in shape to scheduled (GET) runs.

## Request body

- AgentJobRequest: Optional payload for triggering an agent job. If `message` is set it is appended as a user message after the saved chat template. If `message` is absent, the entire body is JSON-stringified and appended as the user message.
  - `message` string: User message to append to the saved chat template before running the agent loop.

## Response `200`

Successful agent execution.

- AgentJobResponse: Response shape for agent-backed job runs.
  - `metadata` string, json: Stringified JSON containing the agent run metadata (token counts, credits, etc.).
  - `messages` object[]: Final transcript including the saved template, any appended user message, and the agent's responses.
  - `job_id` string: The job identifier.
  - `runchat_id` string: The underlying Runchat identifier.
  - `status` 'success' | 'error': Outcome of the agent run.
  - `error` string: Error message, present only when `status` is `error`.

## Other responses

- `400`: Bad Request — body could not be parsed, or the job is a flow job (use GET).
- `403`: Access denied — user does not have permission to the underlying Runchat.
- `404`: Job or Runchat not found.
- `500`: Internal Server Error - An unexpected error occurred on the server.

---

[API](https://skmtc.dev/runchat/apis/runchat-api.md) - [All operations](https://skmtc.dev/runchat/apis/runchat-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runchat/apis/runchat-api/revisions/4fa3fd81ab51?raw)