Skip to content
BetterJobs Docs
API v1 preview — endpoints and fields may change before general availability.

Agent quickstart

What prompt do I paste into my coding agent to integrate BetterJobs?

View .md

Paste the prompt below into Claude Code, Cursor, or any coding agent that can read files and fetch URLs. It points the agent at the docs and the spec, and lists the traps it must handle.

  1. Set your key where the agent’s shell and your app can read it. A bj_test_ key is enough while you build. See Authentication.

    Terminal window
    export BETTERJOBS_API_KEY="bj_test_..."

  2. Open your repo in the agent and paste this prompt.

    Prompt
    Integrate the BetterJobs job-data API into this repository.
    

    Context
    - BetterJobs sends one job search to several job-data providers plus its own index,
      merges duplicates and returns canonical jobs. 1 credit per unique job returned.
    - Docs index: https://docs.betterjobs.cc/llms.txt. Follow its "Rules for AI agents".
    - Exact contract: https://docs.betterjobs.cc/openapi.yaml. Use its field names, paths and error codes
      verbatim. Do not guess fields. Fetch the .md version of any docs page you need:
      Replace the trailing / of a docs URL with .md (e.g. /concepts/waterfall/ → /concepts/waterfall.md). API reference pages under /api/ have no Markdown twin; read /openapi.yaml instead.
    

    Requirements
    1. Put the client in one module that matches this repo's existing structure and
       HTTP library. No new dependencies unless the repo has no HTTP client.
    2. Read the key from the BETTERJOBS_API_KEY environment variable. Fail at startup if
       it is not set. Never hard-code a key, never log it, never send it to a browser.
       Add BETTERJOBS_API_KEY to the repo's env example file with an empty value.
    3. Base URL https://api.betterjobs.cc/v1. Send on every request:
       Authorization: Bearer <key>
       BetterJobs-Version: 2026-10-01
    4. Implement searchJobs(filters, options) on POST /jobs/search:
       - Always set waterfall.max_credits. Expose it as a required argument.
       - Support dry_run: true (free estimate). Call it first when a search may cost more
         than 50 credits.
       - Page with next_cursor until it is null or the caller's limit is reached.
       - Send a fresh Idempotency-Key (UUID) per logical request and reuse it on retries.
    5. Handle results correctly:
       - metadata.status "partial" is a success. Log metadata.providers.failed; do not retry
         the whole search.
       - Deduplicate and store jobs by their canonical id. Re-reading a paid job is free.
       - null means unknown, [] means verified none. Never coerce null to false or 0.
    6. Handle errors by error.code, not by message text:
       - rate_limited: wait Retry-After seconds, then retry.
       - internal_error: retry with the same Idempotency-Key and backoff.
       - unknown_filter / invalid_request: raise with error.param. Do not retry.
       - insufficient_credits / plan_required: raise with upgrade_url. Do not retry.
       Log X-Request-Id on every failure.
    7. Tests: use the keyless sandbox https://api.betterjobs.cc/v1/sandbox/jobs/search (no auth, fixed
       illustrative data, nothing charged) or a bj_test_ key. Never call the API with
       a bj_live_ key in tests.
    8. Run the repo's existing lint, type check and tests. Then show me the diff and one
       example call I can run.

  3. Review the diff. Check the list below before you merge.

  4. Swap in a bj_live_ key in production.

Review checklist

Section titled “Review checklist”
  • The key comes from BETTERJOBS_API_KEY and the app fails at startup without it.
  • Every request sends BetterJobs-Version: 2026-10-01.
  • Every search sets waterfall.max_credits.
  • Large searches call dry_run: true first.
  • metadata.status: partial is treated as success.
  • Jobs are stored by canonical id.
  • null is never turned into false, 0 or an empty string.
  • Errors branch on error.code. rate_limited honours Retry-After.
  • Retries reuse the same Idempotency-Key.
  • Tests never use a bj_live_ key.

Each item links back to one page: The waterfall, Canonical jobs, Errors, Idempotency, Rate limits, Versioning.

Let the agent use BetterJobs live

Section titled “Let the agent use BetterJobs live”

The prompt writes code that calls the API. If you also want the agent itself to search jobs or check companies while it works, connect the MCP server. Its tools carry credit costs and follow the same consent rule.

Section titled “Related”