POST /job-submit launches a remote rollout.
The examples below use $BASE and $KEY. Get a key from
Harbor Hub API key.
Idempotency-Key header is required. Requests without it are rejected, and the key may be
at most 200 characters. Reusing a key returns the job that key already created instead of launching
a second one, so generate a fresh key per launch and reuse it only when retrying that same launch.
If Idempotency-Key is reused, the server will return the previous launch URL even if the config changes.
The top level of the request body takes these fields:
job_secrets and registry_credentials are siblings of config, not fields inside it. This is
deliberate: it keeps plaintext secrets out of the job config that gets stored and replayed. Placing
either one inside config is rejected. Upon submission these credentials are routed through an encryptor and decrypted only at runtime.
Plaintext secrets are never stored on our platform.
Here is a launch using a registry dataset and a built-in agent:
owner_org reports which organization ended up owning the job, and agent_sources echoes any
resolved custom agent sources including their pinned commits. On a dry run no job is created, so
job_id comes back null, but every source is still resolved and validated.
When present, owner_org.max_running_trials is the organization’s effective
concurrent-trial limit. It applies across the organization’s jobs, independently
of a job’s requested n_concurrent_trials.
To submit a request stored in launch.json:
Job Config
config mirrors the JobConfig the CLI sends, so unrecognized keys pass through untouched.
The fields the API validates directly are:
You need at least one of
tasks or datasets, and together they must resolve to at least one task.
The total number of trials is n_attempts × tasks × agents, and must land between 1 and 50,000.
On each agent, name is the Harbor agent type, model_name is the model it uses, and secrets is
the list of credentials that agent receives. Agent versions installed from a package manager are
pinned when the job is submitted, so every trial in a job installs the same release even if the job
sits queued across an upstream publish.
Retry Settings
config.retry.max_retries is the maximum number of additional executions for each trial after an
eligible exception. It defaults to 0, so retries are disabled unless you request them. A non-empty
include_exceptions list limits retries to those exception names; an empty or null list allows
any exception not excluded. exclude_exceptions takes precedence over the include list. Omitting
it preserves the default exclusions.
A retry requires both an eligible exception and remaining retry budget. A low score alone does not
trigger a retry, and retries do not add scored samples. For example, n_attempts: 4 with
retry.max_retries: 3 allows up to 4 × (1 + 3) = 16 executions per task per agent, while keeping
4 trial slots. A trial that exhausts its retries may finish with an error instead of a score.
Agent Secrets
Each agent selects its own credentials throughsecrets. Every selection requires
three fields:
OPENAI_API_KEY under different delivered names.
model_api_key_name explicitly tells Harbor which delivered credential the model
uses; an alias alone does not set it. Delivery names must be unique within an
agent, which can select up to 64 secrets. Use "secrets": [] for an agent that
needs no credentials, such as oracle or nop.
For tag: "default", a job one-off with the source name takes
precedence over the organization’s stored default. Renaming happens afterward.
Other tags select only that exact stored variant.
The CLI shorthand is --stored-secret NAME[@TAG][=AS]. Omitting the tag selects
default; omitting the alias keeps the source name. For example,
--stored-secret OPENAI_API_KEY expands to
{"name": "OPENAI_API_KEY", "tag": "default", "as": "OPENAI_API_KEY"}.
Use --api-key-name MODEL_KEY for the CLI equivalent of model_api_key_name.
Config files require all three fields; string entries are rejected.
With credential_mode: "direct", real secret values enter the task sandbox.
In gateway mode, every selected secret arrives as a proxy handle instead.
Keep secret values in job_secrets or the organization’s stored
credentials. Agent env is for nonsensitive environment variables only.
Tasks
Usetasks for individual tasks. Each entry is either a registry task or a git task, never both.
A registry task takes a name in org/name form and an optional ref, which is a version ref like
"latest", or a semantic version string.
A git task takes a git_url and a path, where path is the task directory relative to the repository
root and is required. Pin the revision with either git_ref (a branch, tag, or SHA) or
git_commit_id (a resolved 40-character SHA), but not both. Git tasks use those fields rather than
ref, and local filesystem paths cannot be used for remote rollouts.
Datasets
Usedatasets for registry or git repo datasets.
A registry dataset takes a name in org/name form and either ref or version, but never both.
You can narrow it with n_tasks to cap how many tasks are drawn, and with the task_names and
exclude_task_names glob patterns.
A git repo dataset uses Harbor’s repo source string, the same grammar as harbor run --repo. That
accepts org/name, github.com/org/name, a full https or ssh URL, or a GitHub /tree/<ref>/<subdir>
URL, each with an optional trailing @<branch|tag|sha>. The optional path is the tasks directory
relative to the repository root, which Harbor defaults to tasks.
ref or version.
They also do not accept git_url, git_ref, or git_commit_id — those belong to tasks.
Whatever a latest or a tag resolves to is pinned into the stored config, so a saved job records the
concrete version that actually ran rather than a moving reference.
Job Secrets
job_secrets is a flat map of environment variable name to value:
config are automatically moved into this
encrypted channel before anything is saved, so plaintext never lands in a stored config. If the same
name appears in both places, the explicit job_secrets entry wins.
Sending a value here makes it available to the job. Select it in each agent’s
secrets using the matching source name and tag: "default".
To use a stored credential instead, leave its value out of job_secrets.
Job Status
GET /job-status returns trial counts for one or more jobs.
job_id once per job to check several at a time, or a comma-separated job_ids list. Add
force_combined=true to get the combined overview shape even for a single job. The same request
works as a POST with a {"job_ids": [...], "force_combined": false} body.
A single-job response reports pending, running, completed, failed, canceled, and total.
Automatic concurrency
Eligible gateway-mode jobs adjust concurrency automatically and share capacity by organization, stored credential, model and endpoint. OpenAI and Anthropic use provider-specific controllers; other gateway providers use a slow-start AIMD controller that backs off on rate limits. Pass--n-concurrent or set
n_concurrent_trials for a fixed count. Automatic mode needs a provider-prefixed
model such as anthropic/... or openai/.... Direct credentials, custom routes,
unprefixed models and unsupported configurations retain fixed mode, at 4 trials
unless you set a count.
