Use an agent with Humanbased

In this guide, the agent retrieves one page of already-readable data and reports what it received without changing a campaignA developer's data-production project and its settings or advancing an incremental feed.

The person or organizationThe Developer-side unit that holds Campaigns, data access, and funds providing access remains responsible for the taskA specific item a contributor claims or enters. An agent does not gain broader rights because it can call an API.

Choose an available interface

An external agent using your credentials is different from an agent component running inside a campaign. This guide covers external access. Contributor task submissionThe record created when work is submitted, agreement signing, and payouts are outside this example.

1. Define the allowed task

Start with an outcome you can inspect. “Help me with my Humanbased account” is too broad. A useful first task names the environment, subscription, page size, allowed operation, and expected report.

Confirm these details before execution:

• Responsible organization: which organization's subscription the agent may read.
• Environment: staging or production, with the matching API host and credential.
• Resource: one Subscription ID and, if needed, an exact Campaign ID filter.
• Action: one replay request using from=beginning, with no automatic pagination.
• Output directory: one existing directory your organization approves for this data. The agent writes beneath it and nowhere else.
• Data handling: what the agent may disclose in its report.
• Completion: a successful response, record count, pagination state, and the full path of the saved response.

If the data's terms do not permit sending the records to the agent provider, run the retrieval in an approved environment and give the agent only an allowed summary. Access permission and permission to share data with another service are separate questions.

2. Supply a scoped credential

Follow Get your first authorized data to select the organization and obtain a key for the subscription. Provide the credential through the agent runtime's secret configuration or approved local environment. Keep it out of the prompt, repository, logs, screenshots, and generated report.

The example expects HB_API_KEY and HB_SUBSCRIPTION_ID to be available to the executing process. It also expects HB_AGENT_OUTPUT_PARENT, the absolute path of the approved output directory. It uses the production host explicitly. A key name or the masked value in the portal is not the full credential.

Organization data-delivery access is distinct from campaign authoring access. A key that can edit a campaign does not necessarily have access to this subscription. Likewise, a CLI browser sign-in session does not substitute for the organization key required by this data endpoint.

3. Give the agent a bounded instruction

The agent needs the reference in a form it can read whole. Every page of this documentation is also served as Markdown: put /markdown in front of the page's path and replace its trailing / with .md. For the data-retrieval reference, that is:

https://docs.humanbased.ai/markdown/api/api-fields.md

Give the agent that address, or the file saved from the page's Download Markdown link, in place of the HTML page. Note the documentation version shown in the site header and the date you fetched it, so the copy the agent used can be identified later.

Then use this brief:

Read the Humanbased data-retrieval API reference as Markdown:
https://docs.humanbased.ai/markdown/api/api-fields.md
Reference copy: documentation version <version>, fetched <date>.
Use that Markdown text, not the HTML page. If you cannot read it,
request it before executing.

Use the production API at https://api.humanbased.ai.
The approved subscription and key are supplied to your runtime as
HB_SUBSCRIPTION_ID and HB_API_KEY. Never print the key.

Request exactly one page from GET /v1/live/pull with:
  subscription_id: the supplied Subscription ID
  from: beginning
  limit: 5

HB_AGENT_OUTPUT_PARENT names the approved output directory.
Create one new directory beneath it and save the full response there.
Write nowhere else. If the variable is unset or the directory does
not exist, stop and report that; do not choose another location.

Do not follow pagination, switch to incremental mode, create a key,
change subscriptions, accept terms, or modify a campaign.

Report the HTTP status, success flag, item count, whether more pages
exist, and the saved file's full path. Do not include raw record content.
If access is denied or the response is incomplete, stop and report
the error without trying a different credential or scope.

These instructions limit the requested task. They do not replace server authorization or the isolation controls of the agent runtime.

4. Execute the read

An agent with an approved shell environment can use the same request a developer would use. This example refuses to run without the approved directory. Otherwise it creates one new directory beneath it, readable only by the current user, and saves the response there.

if [ -z "${HB_AGENT_OUTPUT_PARENT:-}" ] || [ ! -d "$HB_AGENT_OUTPUT_PARENT" ]; then
  printf 'Stop: HB_AGENT_OUTPUT_PARENT must name the approved, existing output directory.\n' >&2
else
  HB_AGENT_OUTPUT="$(mktemp -d "$HB_AGENT_OUTPUT_PARENT/hb-read.XXXXXX")" &&
    printf 'Response directory: %s\n' "$HB_AGENT_OUTPUT" &&
    curl --silent --show-error --get \
      'https://api.humanbased.ai/v1/live/pull' \
      --header "Authorization: Bearer $HB_API_KEY" \
      --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
      --data-urlencode 'from=beginning' \
      --data-urlencode 'limit=5' \
      --output "$HB_AGENT_OUTPUT/page.json" \
      --write-out 'HTTP %{http_code}\n'
fi

The agent should inspect the JSON response without copying the whole dataset into its conversation. A useful completion report looks like this:

Environment: production
Operation: subscription replay, one page
HTTP status: 200
API success: true
Records saved: 5
More pages available: true
Approved directory: <value of HB_AGENT_OUTPUT_PARENT>
Response: <approved directory>/hb-read.Ab12Cd/page.json
Coverage: one page only; pagination was not followed
Reference: api-fields.md, documentation version <version>, fetched <date>

This is an illustrative report, not a claim that these records exist in your subscription. The actual count may be zero. An empty response must be reported as empty, not as a completed data acquisition.

5. Verify the result and recover safely

Check the HTTP status and success together. Confirm data.count matches the number of returned data.items, and distinguish the result from the command merely finishing.

Then check where the response landed. The reported path must lie beneath the approved directory, and the file must exist there:

case "$HB_AGENT_OUTPUT" in
  "$HB_AGENT_OUTPUT_PARENT"/*) ls -l "$HB_AGENT_OUTPUT/page.json" ;;
  *) printf 'Outside the approved directory: %s\n' "$HB_AGENT_OUTPUT" >&2 ;;
esac

This API is synchronous: a complete response is the result. It does not return a job ID or an action receipt that can be polled. Do not invent a status endpoint.

Keep replay and incremental recovery distinct. An incremental GET changes the subscription's shared reading position and may charge for newly delivered records. If its response is lost, another incremental request may retrieve the next records, not repeat the lost page. Recovery requires replaying the acquired range and reconciling locally saved records. See reading modes and recovery.

If your organization supplies the CLI

Use command discovery before relying on remembered syntax:

hb --help --json
hb capabilities --json

Check the selected environment and principal. Capabilities describe what the credential may attempt; the server still checks the actual resource. A data-only key can report the Campaign API catalog as unavailable while still supporting data retrieval.

A CLI build that includes campaign records pull can read one campaign's delivered records within a subscription. Give the agent the same boundary as the HTTP example: one page, the key passed to that one command, and the output beneath the approved directory.

mkdir -p "$HB_AGENT_OUTPUT/tmp"
TMPDIR="$HB_AGENT_OUTPUT/tmp" HB_API_KEY="$HB_API_KEY" hb campaign records pull <campaign-id> \
  --subscription "$HB_SUBSCRIPTION_ID" \
  --limit 5 --json > "$HB_AGENT_OUTPUT/records-page.json"

With --json, the CLI first writes the records to a temporary file that only your user can read, and removes it when the command ends. TMPDIR keeps that file beneath the approved directory too. Without it, the file goes to the system's temporary directory.

Without --all, the command reads one page and returns next_cursor. Exporting every page has its own completion rules: hand the agent Export every delivered record before you allow --all.

If hb --help --json does not list the command in your build, use the HTTP request above. Confirm the supported CLI build and distribution with your organization before installing.

Before adding writes

Expand one operation at a time. For a proposed write, establish its exact scope, effects, approval requirements, request-key behavior, and a way to verify its final state before allowing automated retries.

A network timeout does not prove a write failed. Do not repeat a launch, purchase, or publication under a fresh request key just to obtain a clearer response. Human review and commercial acceptance remain required wherever the platform requires them.

Next, review the API contract or the developer quickstart. For an unavailable interface or unclear result, contact hello@humanbased.ai with a sanitized diagnostic.