# Conventions ## Base URL and versions ``` https://api.acquestor.com/v1 ``` The version is in the path. Within `v1`, changes are additive only: new operations, new optional inputs, new response fields, new enum values in fields documented as open. Write clients that ignore fields they don't know. A breaking change ships as `v2` beside `v1`. The API definition is OpenAPI 3.1. [Download the public definition](/openapi.yaml) to generate a client. Each operation is marked with when it ships: P0 is live, P1 and P2 are planned. Calls to planned operations return 404 until they ship. The [REST reference](/reference/rest) lists both. ## Requests - JSON bodies with `Content-Type: application/json`. `PATCH` takes `application/merge-patch+json`. - Uploads to a deal take `multipart/form-data`. Listing imports also take a file as base64 in JSON (`filename`, `content_base64`), which is how MCP clients send one. - Ids are opaque strings. Don't parse them. ## Dates and `as_of` Dates are ISO 8601 (`2026-10-05`); times are UTC (`2026-10-05T15:02:11Z`). Every computed tool takes `as_of`, the date whose rules and published rates apply. It defaults to today, and the response states the date it used. Pass the date of a letter of intent to see the numbers under the rules and the prime rate in force that day. The SBA rule sets Acquestor loads start with SOP 50 10 8.1, effective October 1, 2026. An SBA tool run for an earlier date returns a gap saying no rule set covers it, and isn't charged. `computation.rule_sets` names the rules and versions a result used. ## Money and rates Dollar amounts are numbers in US dollars. Rates and shares are fractions: `0.10` is 10%. Every number in a response is a [Figure](/concepts/figures) with a `unit`. ## Idempotency Send an `Idempotency-Key` header, a unique string of 1 to 255 characters, on every write and on priced computed calls. A retry with the same key and the same body returns the stored result and doesn't charge twice. A key is remembered for 24 hours: after that its stored result is deleted, and a call with the same key runs and is charged as a new call, so retry within the day. The same key with a different body returns 422 `idempotency_key_reused`; a retry while the first call is still running returns 409 `idempotency_in_progress`; a key over 255 characters returns 400 `invalid_header`. ## Pagination List responses carry `items` and `next_cursor`. `GET /listings` and `GET /deals` page: each takes `limit` (1 to 100, default 25) and `cursor`, and a non-null `next_cursor` is the `cursor` for the next page; `GET /deals` also says `has_more`. A cursor the list didn't return is refused with [`invalid_cursor`](/problems/invalid_cursor). A deal or listing that changes while you page can move between pages. During the beta other lists return everything in one response, up to 200 items, with `next_cursor: null`. ## Third-party text Listing remarks, headlines and other text a broker wrote are third-party data. On the MCP server, that text comes inside `` tags in the result text, and as `{"third_party_text": …, "author": "listing broker"}` objects in `structuredContent`. If you pass Acquestor results to a model, keep that marking: instructions inside such text are data, not instructions.