Agent setup guide

​

Your job

• One script. If the user asks for a language, use it. Otherwise match the machine: PowerShell on Windows, the default shell elsewhere. One client, not two.
• A copy of the .env file they download from Dealroom.
• A short README.md so a new chat can pick the work up. See Leave the folder ready to pick up.

• Use the standard library. Install no dependencies.
• Create no project scaffold, no framework, no package manifest, no tests.
• Write no second client, no wrapper layer, no abstraction over the requests.
• If the user wants more once this works, add it then.

​

Getting credentials

https://beta.dealroom.app/settings/api

​

Token exchange

curl -sS -X POST "https://accounts.beta.dealroom.co/oauth/token" \
  -H "Content-Type: application/json" \
  -d "{
    \"client_id\": \"$DEALROOM_CLIENT_ID\",
    \"client_secret\": \"$DEALROOM_CLIENT_SECRET\",
    \"audience\": \"https://api-next.beta.dealroom.co\",
    \"grant_type\": \"client_credentials\"
  }"

• The audience is https://api-next.beta.dealroom.co. It is an OAuth2 identifier, not a host you call, and it differs from the API base URL https://api.beta.dealroom.app on purpose. Send both values exactly as configured.
• The response carries access_token, token_type, and expires_in. Cache the token and reuse it until shortly before expires_in elapses. Do not request a new token per call.
• On a 401, refresh the token once and retry. If the retry fails too, the key was probably revoked. Stop and tell the user to check it in the dashboard.

​

Verify

curl -sSg "https://api.beta.dealroom.app/data/companies?sort=-latest_valuation&limit=10&include_total=true&filter=and(is_vc_backed[eq]:true,launch_date[gte]:2020)" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Client-Id: $DEALROOM_CLIENT_ID" \
  -H "User-Agent: my-app/1.0"

​

Things you would otherwise guess

• Records are keyed by uuid. Entity records carry no id field. id exists only as a filter key.
• The cursor changes name between response and request. The response field is page.next_cursor; the request parameter is cursor. Send next_cursor= and the API ignores it and returns page one again, with no error. Every loop written that way runs forever on the same page.
• Discover filters, do not guess them. A GET on https://api.beta.dealroom.app/reference/filters?scope=companies returns the authoritative inventory for that scope, with operators and value types. The parameter is scope.
• Money fields are objects, not numbers. latest_valuation has .value, .year, and .month. Formatting the object itself prints nothing useful.
• Read 4xx bodies. They name the missing parameter and list the accepted values, so the fix is usually already in the response you have.
• On Windows, the default shell is Windows PowerShell 5.1. When the user has not asked for a language, write the script in PowerShell with Invoke-RestMethod, which parses JSON itself, so there is no jq. If you run cURL directly, call curl.exe: bare curl there is an alias for Invoke-WebRequest and rejects cURL arguments. The Quickstart Windows PowerShell tab is the reference translation of the requests on this page.
• Windows PowerShell 5.1 writes a BOM when you pass -Encoding utf8, and the next shell to read that file sees a stray prefix on the first key. Prefer not to write files another shell will read. If you must, use [IO.File]::WriteAllText or PowerShell 7’s utf8NoBOM. Never rewrite the user’s .env.

​

Leave the folder ready to pick up

• What the script does and the exact command to run it.
• Where the credentials are (.env in this folder) and that the client secret must never be committed or pasted anywhere.
• That tokens last 24 hours and the script fetches a fresh one when needed.
• Links to this page and to https://developers.beta.dealroom.co/llms.txt.
• One line the user can paste into a new chat to continue: “Read README.md in this folder and continue from there.”

​

How to talk to the user

• Report outcomes, not mechanics. “Your key works, here are the ten companies” beats a walkthrough of the token exchange.
• Do not explain OAuth unless they ask.
• On failure, say what to do next: create a new key, add a scope, check the file path. Say what to do, not why it broke.
• Ask one question at a time, and only when you cannot continue without the answer.

​

Where to look next

• https://developers.beta.dealroom.co/llms.txt first. It is the complete page index in a single fetch, so you get the real page list instead of a guessed URL.
• Filtering for the filter syntax, operators, and taxonomy value lookup.
• Pagination before you walk past the first page.
• The Quickstart Node.js and Python tabs: a complete single-file script each, standard library only, that reads the .env, exchanges the token, and runs the verification request. Start from the one in the user’s language instead of writing your own.
• Token caching and refresh: Node.js and Python helpers that cache the token by expires_in and refresh once on 401. Use one when the script will run longer than a session.
• Top fintech startups for a complete worked query.
• https://developers.beta.dealroom.co/openapi.yaml for the exact parameters and response schema of every endpoint.