Job Search API tools for LlamaIndex

Canonical submission and original-command recovery

Use POST /v1/quotes, then POST /v1/tasks with productId, the approved input, the quoted expectedPricingVersion, and the canonical Idempotency-Key. The host creates a key once for explicitly approved new work, using new_command_key() from the bundled REST engine, and persists it with the approved input before submission. Keys have the form v1.<13-digit Unix milliseconds>.<22–64 base64url characters>. Do not generate keys in model arguments or a workflow retry expression.

Creation requires allow_write=True, the persisted request_key, and explicit command_mode="new". The default command_mode="recover" performs an original-command GET and never obtains another quote or submits again. Repeated invocation in the same new-intent toolset also reads the original after its first submission attempt. Changed input is refused. After a restart or any lost response, use this host-only path; it needs no input, quote or model call:

import os
from truefetch_rest import recover_command, observed_task_id

original = recover_command(
    os.environ["TRUEFETCH_API_KEY"], "tasks.create", os.environ["TRUEFETCH_COMMAND_KEY"]
)
if original["receipt"]["outcome"] == "accepted":
    saved_task_id = observed_task_id(original)
    # Persist the reference before reading the existing task/results.

HTTP 200 is not acceptance. Inspect receipt.outcome: accepted supplies an authoritative task reference even when the current task projection is null; processing and unknown require another explicit original GET, respecting the returned retry interval. rejected and not_accepted_final establish nonacceptance and require deliberate new work if you still want a collection. receipt_expired remains unconfirmed: inspect Tasks or contact support. The helper never seals, replays a POST or creates a replacement key. The server accepts new keys for 24 hours, allows five minutes of future clock skew, and retains terminal receipts for at least seven days; it can still answer a retained original after the new-command window ends. A current Task state does not establish a particular command’s outcome.

Cancellation is a separate command: bind a different persisted canonical cancel_key for the newly created task, or pass cancel_task_ids=(saved_task_id,) and cancel_command_keys={saved_task_id: saved_cancel_key} for an explicitly approved saved target. POST /v1/tasks/{taskId}/cancel sends {} and that cancellation key. Unknown cancellation is recovered with recover_command(api_key, "tasks.cancel", saved_cancel_key), never the creation key. Acceptance of cancellation does not promise the task ended as cancelled. The budget, keys and cancellation mapping remain host-only arguments.

Native tools, application-controlled spending

Preview: tested with Python 3.12, llama-index-core==0.14.25, native FunctionTool calls and a simulated HTTP API. Real-model and live-account acceptance are pending. This example uses REST and does not depend on MCP being open or require LangChain.

Dependency security: the current LlamaIndex tree includes NLTK with an unresolved model artifact path advisory. Keep this preview in an isolated development environment and do not expose model file paths to untrusted input. Review the dependency risks and usage boundaries before installation or production use.

Download these files into the same folder:

Install the requirements in a Python virtual environment. Keep TRUEFETCH_API_KEY outside source files and prompts. Your application binds the per-collection credit budget, persisted request key and cancellation scope; model tool arguments cannot raise them.

import os
from truefetch_llamaindex import make_tools, recover_results

tools = make_tools(os.environ["TRUEFETCH_API_KEY"], max_credits=100)
by_name = {tool.metadata.name: tool for tool in tools}
quote = (
    by_name["truefetch_estimate"]
    .call(
        input={
            "keyword": "Software engineer",
            "country": "Germany",
            "platforms": ["arbeitnow"],
            "maxResults": 10,
        }
    )
    .raw_output
)
# Resume a saved task without creating another collection:
result = recover_results(tools, "YOUR_SAVED_TASK_ID")

Read-only mode exposes usage, estimates, task/results reads and task listing. Enabling writes adds one-intent collection and scoped cancellation; follow the full workflow before enabling it. Creation refreshes the quote and checks the application budget. A transport failure may have occurred after acceptance: retain the original key/input, or resume the saved task ID. Do not start another collection merely because a local request timed out.

Recovery reads all pages, verifies record order and count, and preserves partial status. Missing pages or size bounds fail explicitly instead of returning an apparently complete dataset. Download authorization is not proof of a completed download.

The included agent workflow accepts your separately configured LlamaIndex model and enforces host-owned iteration and total tool-call limits. It returns observed task IDs alongside model output and preserves them in AgentRunError on failure. Model output is not proof of a complete export. Model calls can have additional costs; keep deterministic recovery outside the model loop. Source text is untrusted. Review external tracing before sending customer inputs or results to a model or observability service.

See Job Search API, credit pricing, and API conventions. This is an unpublished example, not a LlamaHub listing or a claim of verified live-model support.

The shared REST reader requires UTF-8 JSON and rejects nonfinite numbers, including numeric overflow. Interrupted or oversized HTTP error bodies keep a redacted HTTP-status diagnostic, and truncated successful transfers fail without returning data. It also rejects duplicate member names within an object, including names written with equivalent Unicode escapes; repeated names in separate records are allowed. Recovery also rejects nonfinite values from tool output instead of marking the export complete. Preserve the saved task ID and original request key after an error; these checks do not create or retry collection.

For each available result page, the reader checks the task again after receiving the page, including the final page. This adds one read-only task GET per page. Changed identity, status, availability or count, or a failed recheck, prevents a complete export. The check is a point-in-time observation; files can expire or become unavailable afterward.

Before collection, the creation tool checks that the estimate matches the requested input and that reserved billing units equal the record limit multiplied by the unit price. Amounts must be positive ASCII integers, and the reservation must fit the host credit budget. Invalid estimates stop before submission; server-side pricing and budget checks still apply.