SDKs

The official TypeScript package is @investorlift/godmode. It is in beta, and its version starts at 0. It wraps every endpoint of this reference as one method. Every guide on this site shows each request in five forms: curl, Node.js, Python, TypeScript and the CLI. The TypeScript tab is the package. The CLI tab is the official command-line tool, @investorlift/cli (CLI).

Investorlift generates the package from the same OpenAPI document that generates this reference. A new field or endpoint reaches the package at the next release. A field the package does not know yet still comes back in the response.

Install the package

npm install @investorlift/godmode

The package needs Node 18.17 or later. It has no runtime dependency. Use it on a server. Do not put the key in a browser page.

Put the key in your shell

export GM_API_KEY="zpka_..."

The client reads GM_API_KEY. You can also pass apiKey to the constructor. Get an API key explains the console.

Make one call

import { GodMode } from "@investorlift/godmode";

const gm = new GodMode();

const summary = await gm.deals.summary({ lat: 33.476917, lng: -111.920385, radius_miles: 2 });

console.log(summary.data.n_deals);
console.log(summary.meta.coverage[0]?.data_end);
console.log(summary.requestId);

A method returns the response body and the response headers as fields beside it.

Field	Header	What it holds
`requestId`	`X-Request-Id`	The id of the call. Quote it to support@investorlift.com.
`credits`	`X-Credits-Charged`, `X-Credits-Remaining`	The cost of the call and the balance after it. Null on a route that costs 0 credits.
`datasetVersion`	`X-Dataset-Version`	The cache key. See Coverage and freshness.
`dataEnd`	`X-Data-End`	The last deed date per market.
`etag`	`ETag`	Send it back as `etag` to get a 304 while the data is unchanged.
`rows`	`X-Rows`	The number of rows in the body.

Find the method

The client has one group per resource. The method name is on each endpoint page, under the request, in the TypeScript tab. A method with an id in the path takes the id first. The parcel search takes its body.

await gm.investors.get("inv_0a20a550f33b", { market: "phx" });
await gm.properties.search({ location: { zip: ["85251"] }, limit: 25 });

Group	Methods
`deals`	`list`, `cells`, `summary`, `get`
`buyers`	`match`
`investors`	`list`, `search`, `get`, `deals`, `wholesalePurchases`
`properties`	`resolve`, `get`, `search`, `financing`, `permits`, `history`, `listingHistory`, `comps`
`markets`	`changes`
`agents`	`search`, `get`, `listings`
`wholesaleListings`	`list`, `get`
`wholesalers`	`search`, `get`, `listings`
`lenders`	`search`, `list`, `get`, `loans`, `borrowers`, `rankings`, `cells`
`strParcels`	`list`
`dataset`	`get`
`coverage`	`get`

Page a list

for await (const deal of gm.deals.list({ zip: ["85251"], limit: 100 }).items({ maxPages: 5 })) {
  console.log(deal.id);
}

pages() gives each page. items() gives each row. Both follow page.next_cursor until it is null. See Pagination.A list that costs credits requires maxPages, because every page adds to the bill. A list that costs 0 credits takes no bound. A 400 invalid_cursor stops the loop with an error. The client never starts again from page 1 on its own.

Catch an error

import { CoverageError, QuotaError, RateLimitedError } from "@investorlift/godmode";

try {
  await gm.deals.summary({ lat: 40.7, lng: -74.0, radius_miles: 2 });
} catch (error) {
  if (error instanceof CoverageError) console.log(error.recovery);
  if (error instanceof QuotaError) console.log(error.extras.used, error.extras.line);
  if (error instanceof RateLimitedError) console.log(error.retryAfterSeconds);
  throw error;
}

Every refusal the API sends is a GodModeError. It carries status, code, title, detail, recovery, requestId, errors and extras. The recovery sentence is the same one the Errors page shows. A code the package does not know yet keeps its wire value in code. A request that gets no answer is a ConnectionError, a plain Error.

Class	Status and codes
`AuthenticationError`	401
`RateLimitedError`	429
`QuotaError`	403 `quota_exceeded`, `subscription_required`, `payment_overdue`, `plan_limit`
`RequestError`	every 400 and 406, and every 422 that is not a coverage fact or an ambiguity
`NotFoundError`	404
`GoneError`	410, with `supersededBy`
`CoverageError`	422 `outside_coverage` and every 422 `*_unavailable` code
`AmbiguousError`	422 `ambiguous_apn` and `ambiguous_address`, with `candidates`
`ServerError`	500, 503, 504
`ConnectionError`	no answer: a network failure, a timeout, or your abort

Retries

The client follows the rule on Rate limits and the recovery sentence of internal_error on Errors, and no other rule.

On a 429 the client waits Retry-After seconds and sends the identical request again, at most maxRetries times.
On a 503 pool_saturated or 503 ledger_unavailable the client does the same. The API charged nothing.
On a 500 internal_error the client sends the request again once.
On a connection failure before any answer the client sends the request again once.
The client never retries a 504, any other 4xx, or a timeout.

maxRetries bounds every one of these retries. Set maxRetries: 0 to turn them all off. A Retry-After longer than maxRetryDelayMs throws at once: RateLimitedError on a 429, ServerError on a 503.

Check for a refresh

const first = await gm.dataset.get();
const again = await gm.dataset.get({ etag: first.etag! });
if (again.notModified) console.log("same data");

Every GET that is not a page loop accepts etag. The client does not cache. It gives you datasetVersion for your cache key. The cache window is the rule.

Options

const gm = new GodMode({
  apiKey: process.env.GM_API_KEY,
  baseUrl: "https://api.investorlift.com",
  timeoutMs: 30_000,
  maxRetries: 2,
  maxRetryDelayMs: 30_000,
  appName: "my-app/2.1",
});

appName goes at the end of the User-Agent header. The client sends its own name, its version and the Node version first. Each call also takes { etag, signal, timeoutMs, maxRetries, headers } as its last argument.

What the package does not do

It does not run in a browser.
It does not read the CSV export of a lender’s loans. That export is a plain request from the Growth plan. The endpoint page shows it.
It does not connect to the MCP endpoint. An AI client uses its own MCP client.
It does not cache answers and does not enforce the plan limits. The API reports both in the headers.
It does not validate a response at run time. The types come from the contract.

The command-line tool

The official command-line tool, @investorlift/cli, runs every method of this package as one command from a shell, with no code: investorlift deals summary --lat 33.476917 --lng -111.920385 --radius-miles 2. It reads the same key, prints a table, JSON, CSV or NDJSON, and states the cost of every call on stderr. CLI explains it.

Versions and other languages

GodMode.version is the package. GodMode.apiVersion is the API version that generated the package. A minor API change is a minor package release. A removal follows the 30-day notice of the Developer Agreement. Investorlift marks the method deprecated one minor release before it goes. A Python package follows when the request log shows Python callers. Until then, the Python tab on every page shows requests, and the OpenAPI document at https://api.investorlift.com/openapi.json generates a client with openapi-python-client.

Start here

Coverage

Keys and plans

Core concepts

Walkthroughs

Terms and policies

Retries

Check for a refresh

Options

What the package does not do

The command-line tool

Versions and other languages

​Retries

​Check for a refresh

​Options

​What the package does not do

​The command-line tool

​Versions and other languages

Retries

Check for a refresh

Options

What the package does not do

The command-line tool

Versions and other languages