Skip to main content
POST /job-submit launches a remote rollout. The examples below use $BASE and $KEY. Get a key from Harbor Hub API key.
Request headers:
The 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:
A successful launch returns the job and its viewer URL:
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 through secrets. Every selection requires three fields:
This selects two variants of 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

Use tasks 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.
Private GitHub repositories have to be connected or shared through the profile settings flow before they can be used as a task or agent source. TODO: add pics here.

Datasets

Use datasets 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.
Git repo datasets pin their revision inside the repo string, so they do not take 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:
Names must be uppercase and start with a letter, values must be non-empty and at most 16,384 characters, and you can send at most 50 entries. Values are encrypted before storage and never returned. Secret-looking environment variables found inside 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.
Pass 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.