Campaign API

The CampaignA developer's data-production project and its settings API lets a program read a Campaign's definition, check a candidate change, create a Campaign or apply a change to its draft, and run a launch that a person has confirmed. It is a separate contract from subscription data delivery. Delivered records come from the data API, and a data-delivery Key carries none of the grants below.

Hosts, credential, and grants

Use https://api.humanbased.ai with a Key issued for production, or https://api.staging.humanbased.ai with a staging Key. Every operation is under /api/v1/campaignapi/ and takes the header Authorization: Bearer <API_KEY>.

An organizationThe Developer-side unit that holds Campaigns, data access, and funds member creates the Key and chooses its Campaign grants in the portal; Create and use an API Key walks through the form. The server checks each grant on its own.

A Campaign outside the Key's organization or outside its list answers 404 with CAMPAIGN_NOT_FOUND, the same answer as a Campaign that does not exist.

The Key form issues campaign:author and campaign:launch only to a member who is an editor or owner of at least one Campaign in the organization. Create an organization's first Campaign in the Developer portal.

Check identity and read scope

Start with a read-only identity check:

curl --silent --show-error \
  'https://api.humanbased.ai/api/v1/auth/whoami' \
  --header "Authorization: Bearer $HB_API_KEY"

Read data.org_id, data.scopes, and data.managed_campaign_ids before continuing. Keep the Key in an environment variable or secret store, never in a copied command or URL. Then list the Campaigns visible to that identity:

curl --silent --show-error \
  'https://api.humanbased.ai/api/v1/campaignapi/campaigns' \
  --header "Authorization: Bearer $HB_API_KEY"

Every response carries success, errorCode, errorMessage, and data. The Campaign list accepts optional status, limit (1–200), and opaque cursor query parameters. Read data.items; if data.has_more is true, pass data.next_cursor unchanged in the next request. An empty page alone is not the end or proof that the organization has no Campaigns. Keep identifiers as strings.

Choose the operation

Identifiers travel in the query string of a GET and in the JSON body of a POST. The CLI wraps the same operations as commands.

Write a Campaign File

A candidate is a Campaign File: one JSON object that holds the whole Campaign definition. Every write sends the complete document, not a patch.

All eight sections are required. The platform publishes no standalone JSON Schema for this document: candidatevalidate is the authority, and it reports each problem by path.

To change an existing Campaign, read its latest version back and edit that document, as the next section shows. To create one, start from the document below. It describes one contributor step behind an access gate, with each submissionThe record created when work is submitted reviewed by a person. The name, amounts, and counts are illustrations; decide your own. Take template_id from GET /api/v1/campaignapi/templates.

{
  "spec_version": "1.0",
  "campaign": { "name": "Returns triage, round 1" },
  "eligibility": { "gates": [], "kyc_tier": "none", "reputation": {} },
  "workflow": {
    "nodes": [
      { "key": "gate", "node_key": "access_gate", "params": { "spec_version": 1 } },
      {
        "key": "collect",
        "node_key": "human_supply",
        "params": {
          "form_template_ref": { "template_id": "784210002001" },
          "task": { "totalCap": 200, "perUserQuota": 20 },
          "reward": { "asset_code": "USDC", "amount": 0.5 }
        }
      },
      { "key": "accept", "node_key": "data_accept", "params": { "acceptance": { "mode": "manual" } } }
    ],
    "next": [
      { "from": "gate", "to": "collect" },
      { "from": "collect", "to": "accept" },
      { "from": "accept", "to": "done" }
    ]
  },
  "reward_policy": {
    "base": { "asset_code": "USDC", "amount": 0.5 },
    "factors": [],
    "caps": {}
  },
  "quotas": { "per_node": {}, "budget_usd": 100 },
  "data_contract": { "scarcity_strata": [], "lineage": {} },
  "audit": {
    "intent": "Collect triage decisions for returned-goods cases.",
    "versions": []
  }
}

In the collect step, task.totalCap is how many submissions the step takes from all contributors together, and task.perUserQuota is how many one contributor may make. Both count tasksA specific item a contributor claims or enters in progress and submissions waiting for review. A submission that is rejected or found to be a duplicate stops counting, which frees its place. reward.amount is what one accepted submission pays.

In the accept step, acceptance.mode set to manual holds every submission until a person reviews it. Without that setting the step accepts each submission when it arrives.

hb campaign init --template writes the same sections and steps, including task and acceptance, with a <DECIDE: …> placeholder in place of each value you must decide.

Validate and plan a candidate

Both operations read; neither writes. Save the document above as candidate.json in a private working directory, then build the two request bodies for a new Campaign:

python3 - <<'PY'
import json
from pathlib import Path

candidate = json.loads(Path('candidate.json').read_text())
Path('validate.json').write_text(json.dumps({'candidate': candidate}))
Path('plan.json').write_text(json.dumps({'mode': 'create', 'candidate': candidate}))
PY

To plan a change instead, set HB_CAMPAIGN_ID to a Campaign the Key may edit and read its latest version:

curl --fail-with-body --silent --show-error --get \
  'https://api.humanbased.ai/api/v1/campaignapi/version' \
  --header "Authorization: Bearer $HB_API_KEY" \
  --data-urlencode "campaign_id=$HB_CAMPAIGN_ID" \
  --output version.json

data.version.version_number and data.version.spec_hash identify the base. data.campaign_file is the complete stored document, and data.server_assigned_fields names the keys under campaign that a candidate must leave out. This illustrative edit changes only the name:

python3 - <<'PY'
import json
from pathlib import Path

response = json.loads(Path('version.json').read_text())
assert response['success'] and response['data']['campaign_file']
data = response['data']
candidate = data['campaign_file']
for field in data.get('server_assigned_fields', []):
    candidate['campaign'].pop(field, None)
candidate['campaign']['name'] = 'Reviewed example name'
Path('validate.json').write_text(json.dumps({'candidate': candidate}))
Path('plan.json').write_text(json.dumps({
    'mode': 'update', 'campaign_id': data['campaign_id'],
    'candidate': candidate,
    'expected_version_number': data['version']['version_number'],
    'expected_spec_hash': data['version']['spec_hash'],
}))
PY

Send either pair of bodies the same way:

curl --fail-with-body --silent --show-error \
  'https://api.humanbased.ai/api/v1/campaignapi/candidatevalidate' \
  --header "Authorization: Bearer $HB_API_KEY" \
  --header 'Content-Type: application/json' --data-binary @validate.json \
  --output validation.json
curl --fail-with-body --silent --show-error \
  'https://api.humanbased.ai/api/v1/campaignapi/candidateplan' \
  --header "Authorization: Bearer $HB_API_KEY" \
  --header 'Content-Type: application/json' --data-binary @plan.json \
  --output plan-result.json

A plan with applicable: false is not ready to apply. If the base version or hash has moved, the plan is refused with BASE_VERSION_STALE: read the new version and review a new candidate and plan.

Create a Campaign

After the accountable person approves the document, add a request_key to the create plan body and send it to candidateapply. Choose the key yourself: a stable string of up to 200 characters that names this one write.

python3 - <<'PY'
import json
from pathlib import Path

body = json.loads(Path('plan.json').read_text())
assert body['mode'] == 'create'
body['request_key'] = 'create-returns-triage-2026-10-10'
Path('apply.json').write_text(json.dumps(body))
PY
curl --fail-with-body --silent --show-error \
  'https://api.humanbased.ai/api/v1/campaignapi/candidateapply' \
  --header "Authorization: Bearer $HB_API_KEY" \
  --header 'Content-Type: application/json' --data-binary @apply.json \
  --output receipt.json

A create body holds mode, candidate, and request_key. It names no campaign_id and no expected base.

One create performs these steps in order, under the one request_key:

The response is a receipt. Hashes are shortened in this illustration:

{
  "data": {
    "replayed": false,
    "action_id": "784210008001",
    "action": "campaignfile.apply",
    "status": "succeeded",
    "request_key": "create-returns-triage-2026-10-10",
    "request_hash": "5d0c…a917",
    "campaign_id": "784210001001",
    "result": {
      "campaign_id": "784210001001",
      "external_pipeline_id": "784210011001",
      "file_version_id": "784210007001",
      "version_number": 1,
      "persisted_file_hash": "8a41…c2f0",
      "state": "draft",
      "granted_to_key": true
    }
  },
  "success": true,
  "errorCode": 0,
  "errorMessage": "SUCCESS"
}

Keep data.campaign_id: every later operation names it. data.result.granted_to_key: false means the Campaign exists and this Key was not given it; change it in the Developer portal or with a replacement Key that names it. To confirm the create, read GET /api/v1/campaignapi/campaign?campaign_id=<campaign_id> and check that data.campaign.status is draft.

persisted_file_hash differs from the candidate_hash you validated, because the stored document includes the server-assigned fields.

Apply a change to a draft

Add a request_key to the update plan body and send it to the same operation. An update body holds mode, campaign_id, candidate, expected_version_number, expected_spec_hash, and request_key.

A successful update stores the candidate as that Campaign's newest draft version and changes nothing else. The receipt has the shape shown above; data.result.version_number is the new version, and data.result carries no granted_to_key.

Both pins are compared again at the moment of the write. If another editor saved first, the request is refused with 409 and BASE_VERSION_STALE, and nothing is written: read the new version, rebuild the candidate, and plan again.

Read the receipt and recover

A 200 from candidateapply is always a receipt with status: succeeded. Any other outcome arrives as an error response; the receipt lookup below shows the other three statuses.

The request_key is what makes a retry safe. Keep the request body and its key together, and decide by what the retry returns:

actionreceipt takes exactly one of request_key or action_id. A lookup by request_key searches Campaign File applies unless you add action=template.apply. It does not find a launch.

Launch a Campaign

A launch moves a draft Campaign to live and locks its budget from the organization's balance. A Key cannot decide that alone: the Key proposes, a person confirms the exact proposal, and the Key executes it.

Before you propose, check four things:

1. Propose

curl --fail-with-body --silent --show-error \
  'https://api.humanbased.ai/api/v1/campaignapi/launchpropose' \
  --header "Authorization: Bearer $HB_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "{\"campaign_id\": \"$HB_CAMPAIGN_ID\"}" \
  --output proposal.json

A proposal writes one record. No money moves and the Campaign does not change. Save the response: it is the only place the proposal_id is returned.

{
  "data": {
    "proposal_id": "784210010001",
    "campaign_id": "784210001001",
    "operation": "launch",
    "state": "proposed",
    "amount_usd": "100.0000",
    "base_version_number": 1,
    "base_spec_hash": "8a41…c2f0",
    "proposal_hash": "clp1_77be…09d3",
    "expires_at": "2026-10-10T10:30:00+00:00",
    "confirmed_by": null,
    "confirmed_at": null,
    "executed_action_id": null
  },
  "success": true,
  "errorCode": 0,
  "errorMessage": "SUCCESS"
}

amount_usd is the budget the launch would commit, as a string with four decimal places. base_version_number and base_spec_hash name the draft it would run. proposal_hash binds all of them together. expires_at is one hour after the proposal was made; confirmation and execution both have to happen before it.

A Key holds one open proposal per Campaign. A second launchpropose for the same Campaign is refused with PROPOSAL_OPEN_ALREADY until the first is executed or expires.

2. A person confirms

Send the person who owns the decision to the Developer portal's confirmation page:

https://developer.humanbased.ai/campaigns/<campaign_id>/launch/confirm?proposal=<proposal_id>

They sign in as an editor or owner of that Campaign. The page shows the Campaign, the amount, the draft version, the expiry, and the proposal hash as the server holds them. Selecting Confirm this launch records their agreement to that exact hash. It does not launch.

Read GET /api/v1/campaignapi/launchproposal?proposal_id=<proposal_id> with the Key that proposed. Continue when data.state is confirmed.

3. Execute

python3 - <<'PY'
import json
from pathlib import Path

proposal = json.loads(Path('proposal.json').read_text())['data']
Path('launch.json').write_text(json.dumps({
    'proposal_id': proposal['proposal_id'],
    'request_key': 'launch-returns-triage-2026-10-10',
}))
PY
curl --fail-with-body --silent --show-error \
  'https://api.humanbased.ai/api/v1/campaignapi/launch' \
  --header "Authorization: Bearer $HB_API_KEY" \
  --header 'Content-Type: application/json' --data-binary @launch.json \
  --output launch-receipt.json

The body holds proposal_id and a request_key you choose. Only the Key that proposed may execute. Before any money moves, the server recomputes the proposal hash from the Campaign as it is now. A budget, draft, or payment term changed after the confirmation makes the launch a different action, and it is refused with PROPOSAL_STALE.

A successful launch returns a receipt with action: campaign.launch and status: succeeded. Its data.result holds campaign_id, the Campaign's new status, the proposal_id, and confirmed_by.

Confirm or recover a launch

Errors

A refusal has success: false, data: null, an errorCode equal to the HTTP status, and an errorCodeName. Branch on errorCodeName. errorMessage is usually prose and can be reworded. For CANDIDATE_INVALID it is an object instead, carrying the validation result:

{
  "data": null,
  "success": false,
  "errorCode": 400,
  "errorCodeName": "CANDIDATE_INVALID",
  "errorMessage": {
    "error": "CANDIDATE_INVALID",
    "message": "the candidate did not pass validation, so nothing was applied",
    "findings": {
      "valid": false,
      "checks": [
        {"check": "schema", "ran": true, "passed": false, "violations": [{"path": "…", "code": "…", "message": "…"}]}
      ],
      "candidate_hash": "…"
    }
  }
}

findings is the object candidatevalidate returns in data; the example shortens it. Check whether errorMessage is a string before you print it.

A refusal raised before the request reaches this API, such as a 401 for a missing or invalid Key, can arrive without an errorCodeName. Keep a default branch for it. The same holds for 429 Too many requests from the gateway: wait Retry-After seconds, as described under Rate limits.

To launch from the Developer portal instead, see launch and budget checks.