# 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 campaign or advancing an incremental feed. The person or organization providing access remains responsible for the task. An agent does not gain broader rights because it can call an API. ## Choose an available interface | Interface | Use in this guide | | --- | --- | | HTTP API | The complete example below uses `GET /v1/live/pull` with an organization API key. | | Humanbased CLI | Use `hb` for the commands supported by the build supplied to your organization. Discover its commands with `hb --help --json`. | | MCP client | This guide uses HTTP directly. If your organization supplies an MCP integration, use its documented server, tool contract, and authentication setup. | | Browser | Use it for key management and any product step that requires a person's review or acceptance. Do not hand an agent a copied browser session as a substitute for a supported credential. | An external agent using your credentials is different from an agent component running inside a campaign. This guide covers external access. Contributor task submission, 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](/api/api-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](/api/api-fields), that is: ```text 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: ```text Read the Humanbased data-retrieval API reference as Markdown: https://docs.humanbased.ai/markdown/api/api-fields.md Reference copy: documentation version , fetched . 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. ```sh 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: ```text Environment: production Operation: subscription replay, one page HTTP status: 200 API success: true Records saved: 5 More pages available: true Approved directory: Response: /hb-read.Ab12Cd/page.json Coverage: one page only; pagination was not followed Reference: api-fields.md, documentation version , fetched ``` 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: ```sh 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 ``` | Condition | Agent behavior | | --- | --- | | Approved directory unset or missing | Stop and report it. Choose no other location. | | Successful, nonempty page | Report count, pagination state, and the saved file's full path. Stop at the agreed page boundary. | | Successful, empty page | Report no readable records; ask the responsible person to check delivery and subscription scope. | | `401` or `403` | Stop. Report the error and request a corrected credential or scope through the approved channel. | | Invalid parameters | Correct only within the approved task and the documented contract. Do not broaden the resource scope. | | Replay request interrupted | Retry the same replay request after a short delay if retries are allowed. Discard an incomplete local response. | | Unexpected response shape | Preserve a sanitized diagnostic and stop. Do not infer success from an unfamiliar envelope. | 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](/api/api-fields#reading-modes-and-recovery). ## If your organization supplies the CLI Use command discovery before relying on remembered syntax: ```sh 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. ```sh mkdir -p "$HB_AGENT_OUTPUT/tmp" TMPDIR="$HB_AGENT_OUTPUT/tmp" HB_API_KEY="$HB_API_KEY" hb campaign records pull \ --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](/api/cli#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](/api/api-fields) or [the developer quickstart](/api/api-data). For an unavailable interface or unclear result, contact [hello@humanbased.ai](mailto:hello@humanbased.ai) with a sanitized diagnostic.