---
title: "Provider-neutral control plane for hosted ALK harness jobs."
method: POST
path: "/simulate/api/harness-jobs/"
tags: ["simulate"]
---

# Provider-neutral control plane for hosted ALK harness jobs.

`POST /simulate/api/harness-jobs/`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/simulate/api/harness-jobs/`
- Auth: one of:
  - API key in header `X-Api-Key`
  - API key in header `X-Secret-Key`

Validates the v1.6 request contract and delegates execution to the public backend selected by
``settings.HARNESS_PROVIDER`` (``hosted`` or ``sandbox``). The hosted backend independently
selects its managed sandbox runtime.

## Request body

- HarnessJobCreate
  - `schema_version` 'futureagi.harness-job.v1'
  - `run_id` string, uuid
  - `source` HarnessSource
    - `kind` 'github' | 'archive' | 'remote' | 'provider', required
    - `repository` string, nullable
    - `ref` string, nullable
    - `commit_sha` string, nullable
    - `installation_id` string, nullable
    - `archive_artifact_id` string, uuid, nullable
    - `endpoint` string, uri, nullable
    - `visibility` 'public' | 'private'
    - `environment_values` object
  - `agent` HarnessAgent, required
    - `connector` 'livekit' | 'vapi' | 'retell' | 'retell_chat' | 'phone' | 'auto', required
    - `mode` 'connect_only' | 'environment_backed' | 'provider_import', nullable
    - `call_direction` 'inbound' | 'outbound', nullable: inbound: the simulated caller dials the agent. outbound: the agent dials the simulated caller. Voice connectors only.
    - `config` object
    - `secret_refs` object
  - `scenario_count` integer
  - `seed` integer, nullable
  - `runtime` HarnessRuntime
    - `isolation` 'dedicated_vm'
    - `cpu_units` integer
    - `memory_mb` integer
    - `parallelism` integer
    - `concurrency_weight` integer
    - `max_duration_seconds` integer
    - `network_policy` 'live'
  - `security` HarnessSecurity
    - `untrusted_source` boolean
    - `read_only_source` boolean
    - `allow_privileged` boolean
    - `allow_host_runtime_control` boolean
    - `allowed_egress_domains` string[]
  - `retry` HarnessRetry
    - `max_infrastructure_attempts` integer
    - `initial_backoff_seconds` number
    - `max_backoff_seconds` number
    - `retryable_domains` string[]
  - `artifacts` HarnessArtifact, required
    - `level` 'metadata-only' | 'traces' | 'traces-and-recordings' | 'full', required
    - `retention_days` integer
    - `allow_bundle_download` boolean
    - `max_artifact_bytes` integer
  - `platform_run_id` string, nullable
  - `metadata` object

## Response `202`

Accepted

- HarnessJobRead
  - `job` HarnessJobInfo, required
    - `job_id` string, uuid, required
    - `run_id` string, uuid, required
    - `source` object, required
    - `metadata` object, required
    - `runtime` object
    - `run_test_id` string, uuid, nullable, required
    - `test_execution_id` string, uuid, nullable, required
  - `status` HarnessJobStatus, required
    - `state` string, required
    - `stage` string, required
    - `updated_at` string, required
    - `attempt` integer, required
    - `completed_scenarios` integer, required
    - `failed_scenarios` integer, required
    - `active_scenarios` integer
    - `queued_scenarios` integer
    - `total_scenarios` integer, required
    - `deadline_at` string, required
    - `failure` object, nullable, required
  - `events` HarnessJobEvent[], required
    - `event_id` string, required
    - `sequence` integer, required
    - `stage` string, required
    - `type` string, required
    - `payload` object, nullable, required
    - `emitted_at` string, required
  - `stage_outputs` HarnessStageOutput[], required
    - `id` string, uuid, required
    - `title` string, required
    - `summary` string, required
    - `kind` string, required
    - `data` object, required
  - `scenarios` HarnessScenario[], required
    - `scenario_key` string, required
    - `scenario_id` string, uuid, required
    - `name` string, required
    - `instruction` string, nullable
    - `use_case` string, nullable
    - `call_execution_id` string, uuid, nullable
    - `status` string, nullable
  - `receipts` object[], required
  - `platform` HarnessPlatform, required
    - `run_test_id` string, uuid, nullable, required
    - `test_execution_id` string, uuid, nullable, required
    - `url` string, nullable, required
  - `runtime` HarnessRuntimeRead
    - `sandbox_id` string
    - `diagnostics` HarnessDiagnostics
      - `object_key` string
      - `sha256` string
      - `size` integer, required
      - `captured_at` string
      - `final` boolean, required
      - `error` string, required
  - `parallelism` HarnessParallelism
    - `requested` integer, required
    - `admitted` integer, required
    - `effective` integer, required
    - `degrade_reasons` string[], required
  - `conversation` HarnessConversationRead, nullable
    - `conversation_id` string, uuid, required
    - `job_id` string, uuid, required
    - `state` string, required
    - `stage` string, required
    - `active_invocation_id` string, nullable, required
    - `blocking_input` object, nullable, required
    - `messages` HarnessConversationMessage[], required
      - `message_id` string, uuid, required
      - `sequence` integer, required
      - `role` 'user' | 'assistant' | 'system', required
      - `kind` 'message' | 'question' | 'confirmation' | 'status', required
      - `state` 'queued' | 'delivered' | 'streaming' | 'completed' | 'failed', required
      - `stage` string, required
      - `content` string, required
      - `payload` object, required
      - `invocation_id` string, nullable
      - `function_call_id` string, nullable
      - `reply_to` string, uuid, nullable
      - `created_at` string, date-time, required
    - `events` HarnessConversationEventRead[], required
      - `event_id` string, required
      - `sequence` integer, required
      - `kind` string, required
      - `message_id` string, uuid, nullable
      - `stage` string, required
      - `invocation_id` string, nullable
      - `function_call_id` string, nullable
      - `payload` object, required
      - `emitted_at` string, date-time, required
    - `event_watermark` integer, required
    - `runtime` HarnessConversationRuntime, required
      - `state` string, required
      - `warm_until` string, date-time, nullable, required
      - `degraded` boolean, required
      - `available` boolean, required
  - `consumption` HarnessConsumption, nullable
    - `text_sim_tokens` integer, required
    - `voice_sim_minutes` number, required
    - `ai_credits` number, nullable, required
    - `sandbox_seconds` number, required
  - `usage_limit` object, nullable

## Other responses

- `default`: Default error response

---

[API](https://skmtc.dev/futureagi/apis/future-agi-management-api.md) · [All operations](https://skmtc.dev/futureagi/apis/future-agi-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/futureagi/apis/future-agi-management-api/revisions/c8684118e142?raw)