> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runchat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Agent Job with Message

> Trigger an agent job and append a user message to the saved chat template before running the agent loop. Use this to wire webhooks into agent tasks.



## OpenAPI

````yaml POST /job/{runchat_job_id}
openapi: 3.1.0
info:
  title: Runchat API
  description: API for executing Runchat flows and retrieving schema information.
  version: 1.0.0
servers:
  - url: https://runchat.com/api/v1
    description: Relative path for the API endpoints
security:
  - bearerAuth: []
tags:
  - name: Execution
    description: Endpoints related to running Runchat flows.
  - name: Schema
    description: Endpoints for retrieving Runchat flow structure and definitions.
  - name: Canvas
    description: >-
      Endpoints for programmatic canvas manipulation — reading, creating,
      connecting, and running nodes.
  - name: Jobs
    description: >-
      Endpoints for triggering saved Runchat jobs — scheduled flow runs and
      agent tasks.
paths:
  /job/{runchat_job_id}:
    parameters:
      - name: runchat_job_id
        in: path
        required: true
        description: >-
          The unique identifier for the Runchat job. Jobs are created from the
          Tasks dashboard and back either a flow run or a saved agent chat.
        schema:
          type: string
    post:
      tags:
        - Jobs
      summary: Trigger Agent Job with Message
      description: >-
        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 agent tasks.


        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.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentJobRequest'
            examples:
              explicitMessage:
                summary: Explicit user message
                value:
                  message: >-
                    Summarize today's incoming support tickets and post the
                    digest to #support.
              rawWebhook:
                summary: Raw webhook payload (no `message` key)
                value:
                  event: form.submitted
                  form_id: contact-us
                  fields:
                    name: Ada
                    email: ada@example.com
                    message: Hi, I'd like a demo.
      responses:
        '200':
          description: Successful agent execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentJobResponse'
        '400':
          description: >-
            Bad Request — body could not be parsed, or the job is a flow job
            (use GET).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Access denied — user does not have permission to the underlying
            Runchat.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Job or Runchat not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    AgentJobRequest:
      type: object
      description: >-
        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.
      properties:
        message:
          type: string
          description: >-
            User message to append to the saved chat template before running the
            agent loop.
      additionalProperties: true
    AgentJobResponse:
      type: object
      description: Response shape for agent-backed job runs.
      properties:
        metadata:
          type: string
          format: json
          description: >-
            Stringified JSON containing the agent run metadata (token counts,
            credits, etc.).
        messages:
          type: array
          items:
            type: object
          description: >-
            Final transcript including the saved template, any appended user
            message, and the agent's responses.
        job_id:
          type: string
          description: The job identifier.
        runchat_id:
          type: string
          description: The underlying Runchat identifier.
        status:
          type: string
          enum:
            - success
            - error
          description: Outcome of the agent run.
        error:
          type: string
          description: Error message, present only when `status` is `error`.
    Error:
      type: object
      properties:
        error:
          type: string
          description: A message describing the error.
      required:
        - error
  responses:
    InternalServerError:
      description: Internal Server Error - An unexpected error occurred on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication using Runchat API key. API keys can be
        created from the account menu

````