---
title: "Starts a conversation with the agent and returns a credential for the turn"
method: POST
path: "/api/v1/agent/conversations"
tags: ["Agent"]
---

# Starts a conversation with the agent and returns a credential for the turn

`POST /api/v1/agent/conversations`

## Request

- Base URL: `https://api.flexiple.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.flexiple.com/api/v1/agent/conversations`
- Auth: HTTP bearer

## Request body

- object
  - `message` string, required
  - `client_id` string: A uuid the browser gave the message before sending it. The message is stored under it, so the bubble on screen and the stored message share one id. Refused if already used.
  - `reply_id` string: A uuid the browser gave the reply before sending, so it can draw the reply straight away. The reply is stored under it. Refused if already used, or if it is the message's own id.
  - `job_post_id` integer, nullable
  - `page_context` object
    - `job_post_id` integer, nullable
    - `talent_profile_id` integer, nullable
    - `application_id` integer, nullable
    - `tab` string, nullable

## Response `201`

Conversation started

- object
  - `data` AgentConversation, required
    - `id` integer, required
    - `status` 'idle' | 'running' | 'awaiting_approval' | 'done' | 'stopped' | 'failed', required
    - `job_post_id` integer, nullable, required
    - `subject_type` string, nullable, required
    - `subject_id` number, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `title` string, required
    - `job_title` string, nullable, required
    - `search_title` string, nullable, required
    - `waiting_on` 'approval' | 'question' | 'rating' | 'null', nullable, required
    - `asks` string, nullable, required
    - `asked_at` string, nullable, required
    - `purpose` 'chat' | 'sourcing' | 'sourcing_agent', required
    - `mode` 'fast' | 'detailed' | 'null', nullable, required
    - `live_stream` object, nullable
      - `url` string, required
      - `stream` string, required
    - `messages` AgentMessage[]
      - `role` 'user' | 'assistant', required
      - `content` string, required
      - `stop_reason` string, nullable, required
      - `created_at` string, date-time, required
      - `status` 'running' | 'done' | 'failed' | 'stopped', required
      - `from_app` boolean, required
      - `sources` object[], required
        - `title` string, required
        - `url` string, required
      - `id` string, required
      - `pending_changes` AgentPendingChange[], required
        - `id` integer, required
        - `action` string, required
        - `risk` 'read' | 'reversible' | 'consequential' | 'destructive', required
        - `summary` string, required
        - `status` 'pending' | 'applying' | 'declined' | 'applied' | 'failed' | 'cancelled', required
        - `applied_at` string, date-time, nullable, required
        - `reason` string, nullable, required
        - `chosen_option_id` string, nullable, required
        - `options` object[], required
          - `id` string, required
          - `kind` string, required
          - `label` string, required
        - `args` object, required
        - `result` object, required
        - `evidence` object, required
          - `agreement` object
            - `ups_kept` number, required
            - `ups_total` number, required
            - `downs_dropped` number, required
            - `downs_total` number, required
            - `people` object[]
              - …
          - `blast_radius` object
            - `searches` number, required
            - `pipeline` object, required
              - …
          - `before_metrics` object[]
            - `name` string, required
            - `scale_max` number, required
            - `weight` number
            - `mandatory` boolean
            - `levels` object[], required
              - …
          - `preview` object
            - `status` 'pending' | 'done' | 'failed', required
            - `inversions_before` number, nullable
            - `inversions_after` number, nullable
            - `ranks_all_ups_above_downs` boolean, nullable
            - `people` object[]
              - …
          - `pool` object
            - `before` number, required
            - `after` number, required
          - `outreach` object
            - `flow_id` number, required
            - `flow_name` string, required
            - `job_post_id` number, required
            - `preview` AutomationExecutePreview, required
              - …
          - `task` object
            - `job_post_id` number, required
            - `job_title` string, required
            - `count` number, required
            - `will_change` number, required
            - `skipped` object[], required
              - …
            - `application_ids` number[], required
            - `credit_cost` number, nullable
            - `automations` string[], required
        - `task` AgentTask, required
          - `id` integer, required
          - `operation` 'reject' | 'move' | 'shortlist' | 'restore' | 'add_tag' | 'remove_tag' | 'rescore', required
          - `status` 'queued' | 'running' | 'done' | 'failed' | 'cancelled', required
          - `total` integer, required
          - `job_post_id` integer, required
          - `finished_at` string, nullable, required
          - `done` integer, required
          - `failed` integer, required
          - `skipped` integer, required
          - `failures` object[], required
            - `name` string, required
            - `error` string, required
        - `affected_names` object, required
          - `listed` string[], required
          - `total` number, required
      - `proposal_test` JobProposalTest
        - `id` integer, required
        - `status` 'pending' | 'done' | 'failed', required
        - `error` string, nullable, required
        - `sample_size` integer, required
        - `pool_count` number, nullable, required
        - `filters_digest` string, required
        - `rubric_version_id` number, nullable, required
        - `filters_change_id` number, nullable, required
        - `rubric_change_id` number, nullable, required
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
        - `rows` object[], required
          - `talent_profile_id` string, required
          - `name` string, required
          - `headline` string, nullable
          - `score` number, nullable
          - `band` 'strong' | 'partial' | 'weak', nullable
          - `failed_mandatory` string[], required
          - `metric_scores` object[], required
            - `name` string, required
            - `score` number, required
            - `reasoning` string, required
        - `overview` object, nullable, required
          - `average` number, nullable
          - `highest` number, nullable
          - `lowest` number, nullable
          - `strong_count` number, required
          - `partial_count` number, required
          - `weak_count` number, required
          - `gate_failed_count` number, required
          - `scored_count` number, required
          - `metrics` object[], required
            - `name` string, required
            - `weight` number, nullable
            - `scale_max` number, required
            - `mandatory` boolean, required
            - `average` number, nullable
            - `fail_count` number, required
            - `signal` 'separating' | 'flat_high' | 'flat_low' | 'too_few', required
          - `verdict` string, required
          - `top` object[], required
            - `talent_profile_id` string, required
            - `name` string, required
            - `score` number, required
      - `tool_calls` object[], required
        - `name` string, required
        - `args` object, required
        - `result` object, nullable
      - `thoughts` object[], required
        - `text` string, required
        - `at` integer, required
      - `prompt` object, nullable, required
        - `id` string, required
        - `kind` string, required
        - `options` object[], required
          - `id` string, required
          - `label` string, required
          - `description` string
          - `hint` string
          - `count` integer
          - `recommended` boolean
          - `filters` object
          - `opens` 'filters' | 'rubric' | 'search'
        - `chosen_id` string, nullable
        - `authored_by` string
        - `question` string
        - `multi` boolean
        - `other` boolean
        - `chosen_ids` string[]
        - `other_text` string, nullable
        - `on_page` boolean
        - `intake_step` 'questions' | 'directions'
        - `intake_run_id` string
      - `ratings` object[], nullable, required
        - `id` string, required
        - `name` string, required
        - `fit` 'strong' | 'partial' | 'weak', nullable
        - `verdict` 'up' | 'down', required
        - `dexter_fit` 'strong' | 'partial' | 'weak', nullable
        - `reason` string, nullable
  - `meta` object, required
    - `turn` object, required
      - `handle` string
      - `agent_url` string
      - `stream` object
        - `url` string, required
        - `stream` string, required
      - `reply_message_id` string, required

## Other responses

- `422`: The message id was already used

---

[API](https://skmtc.dev/flexiple/apis/flexiple-platform-api-v1.md) - [All operations](https://skmtc.dev/flexiple/apis/flexiple-platform-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/flexiple/apis/flexiple-platform-api-v1/revisions/27e7987859f2?raw)