Agents API

The Agents API creates configurations and install commands, reads run activity, sends follow-up messages and manages permission decisions. API requests configure an agent; you execute its install command on the machine where it should run.

Authentication and API surfaces

Create a public key in the dashboard's API Access page. Older keys without an Agents organization binding must be replaced. Public API authentication requires an active subscription or eligible trial. Pass X-API-Key or Authorization: Bearer as described in API overview.

Organization and user identity come from your credentials. Do not submit org_id or created_by_user_id in public API bodies. A model provider key is separate from the Codity API key and pays for model usage. Agents endpoints authenticate through the public API but do not use the review/scan job submission flow or return a job_id.

Examples use curl and jq. Set CODITY_API_KEY and OPENAI_API_KEY securely in your environment, then:

export CODITY_AGENTS_API='https://api.codity.ai/v1/agents'
umask 077

Keep responses containing install commands or tokens private. The examples write them to local files with private permissions.

One-step launch

Create a headless agent with read/write access to an absolute working folder:

jq -n '{
  label: "hello-agent",
  task: "Write a short hello message to /tmp/codity-agent-demo/hello.txt.",
  workdir: "/tmp/codity-agent-demo",
  os_shell: "linux_bash",
  model_provider: "openai",
  model_name: "gpt-5.6-luna",
  llm_api_key: env.OPENAI_API_KEY,
  permission_mode: "strict"
}' | curl --fail-with-body -sS "$CODITY_AGENTS_API/launch" \
  -H "X-API-Key: $CODITY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- > agent-launch.json

Success returns 201 with config_id, run_id, token, token_expires_at, api_url, install_command and dashboard_url. Create /tmp/codity-agent-demo on the target machine and run install_command from that folder. Use the returned service URL rather than substituting the public API base URL. The bootstrap expires after five minutes and works once.

Launch requires an absolute workdir. Task defaults to empty but must be nonempty for headless mode. model_provider and model_name must be supplied together, or both omitted to use the deployment's default. interactive defaults to false, and permission_mode defaults to request; the example deliberately selects strict. Additional permissions supplement the workdir grants and standard denies.

If llm_api_key is omitted on a public launch, the agent must find its provider key in the target machine's environment. The CLI surface may also use the signed-in user's matching stored model key. One-step launch currently has no recovery or team field; use configuration creation below for those features.

Create a recovery-enabled configuration

Unlike launch, configuration creation grants only the permissions you list, plus inherited policies and default denies. It does not infer access from a working folder.

jq -n '{
  label: "resume-demo",
  os_shell: "linux_bash",
  task: "",
  model_provider: "openai",
  model_name: "gpt-5.6-luna",
  llm_api_key: env.OPENAI_API_KEY,
  interactive: true,
  permission_mode: "strict",
  recovery_enabled: true,
  permissions: [{
    path_pattern: "/tmp/codity-resume-demo/**",
    kind: "filesystem",
    access: "write",
    effect: "allow"
  }]
}' | curl --fail-with-body -sS "$CODITY_AGENTS_API/configs" \
  -H "X-API-Key: $CODITY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- > agent-config.json

AGENT_ID=$(jq -er '.id' agent-config.json)

Success returns 201 and the configuration detail. The provider key is encrypted before storage and is never returned.

Secret mappings use provider (aws, gcp, vault or env), secret_arn (the reference), key_to_env_var (mapping from a secret field to a destination variable), and optional provider_config. The machine resolves the value with its own identity. Never put a raw secret in secret_arn.

Mint an install command

curl --fail-with-body -sS -X POST "$CODITY_AGENTS_API/configs/$AGENT_ID/install-script" \
  -H "X-API-Key: $CODITY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}' > agent-install.json

The 200 response includes run_id, curl_command, bootstrap_token_expires_at, reusable, install_token_id and max_installs. Run the returned command on the target machine from its intended working folder. A standard command creates a pending run, expires in five minutes and is single-use.

To mint a reusable command, send:

{
  "reusable": true,
  "label": "staging machines",
  "max_installs": 3,
  "expires_in_days": 7
}

Each handshake creates a separate run; the response's run_id is null until a machine installs. The default expiry is seven days. max_installs may be omitted for no cap (otherwise 1-10,000). Expiry can be 1-365 days; null deliberately creates a token without an expiry. Tokens are shown once and cannot be recovered from configuration detail.

Public endpoints

Paths below are relative to /v1/agents. The /cli/agents surface has the same routes and request shapes.

Use the configuration detail's runs list to find a run ID. Events include id, event_type, payload and created_at. Read the last event ID before your next incremental request.

Send a follow-up:

RUN_ID='replace-with-a-run-id'
curl --fail-with-body -sS -X POST "$CODITY_AGENTS_API/configs/$AGENT_ID/runs/$RUN_ID/messages" \
  -H "X-API-Key: $CODITY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize your findings so far."}'

Messages must be nonempty after trimming and at most 8,000 characters. A 201 means the message was queued; the live runner receives it on a later heartbeat. It does not start a stopped session.

Permission decisions accept one of these values:

{"decision": "approved_once"}

Use approved_run for the current run, approved_permanent for an enduring configuration grant, or denied to refuse. Shared denies remain enforced. Approval requests can expire while you are deciding.

Dashboard policy and recovery endpoints

These routes belong to the authenticated dashboard API. They are not mounted under /v1/agents and do not accept the public API key in place of a dashboard session. Prefer the dashboard controls or codity-agent resume for normal use.

A policy save with a stale revision returns 409; reload before saving. The first empty policy has revision 0. Dashboard requests use camelCase for configuration fields such as modelProvider, modelName, llmApiKey, teamId and recoveryEnabled; public API configuration requests use snake_case as shown above.

For a normal eligible resume, the dashboard body can be {}. An interrupted action requires reconciliation: "completed" or "retry" after checking its effects. Only send workspaceReconciled: true after preparing and reviewing changed files. The response includes a new run_id, resume_command, fallback curl_command and bootstrap expiry. Execute the returned command on the target machine; the request itself does not start it. See Session recovery.

Errors and retries

Creation, launch and install minting are not idempotent: retrying can create another configuration or pending run. Check prior results before resubmitting after a network timeout. Do not cache a one-machine install command or reuse it as a resume command.