{"openapi":"3.1.0","info":{"title":"Spark API (BYOK) API","version":"0.1.0","description":"Spark API (BYOK) lets an AI assistant read your own Spark API data through the Spark API API with a key you supply (Spark API access token). Read-only: 7 tools (search_listings, get_listing, list_open_houses, get_market_statistics, list_property_types, get_standard_field, list_standard_field_values). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-sparkapi.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-sparkapi/docs"},"termsOfService":"https://connectorbay.com/byok-sparkapi/terms"},"servers":[{"url":"https://byok-sparkapi.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-sparkapi/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_listings":{"post":{"operationId":"search_listings","summary":"Search MLS listings that the token's role may read, with a SparkQL filter such as \"City Eq 'Fargo' And ListPrice Le 4000","description":"Search MLS listings that the token's role may read, with a SparkQL filter such as \"City Eq 'Fargo' And ListPrice Le 400000\"; returns the selected standard fields per listing and a paging block. Up to 25 per page (replication keys more). Use for \"Find listings in Fargo priced under 400000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"SparkQL filter, for example \"City Eq 'Fargo' And BedsTotal Ge 3 And ListPrice Le 400000\". Quote text values with single quotes.","title":"Filter"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":"ListingKey,ListingId,MlsStatus,ListPrice,StreetNumber,StreetName,City,StateOrProvince,PostalCode,BedsTotal,BathsTotal,BuildingAreaTotal,YearBuilt,PropertyType,ModificationTimestamp","description":"Comma-separated standard fields to return per listing (keeps answers small).","title":"Select"},"orderby":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field with + or - prefix, for example -ListPrice or +ModificationTimestamp.","title":"Orderby"},"limit":{"anyOf":[{"maximum":25,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many listings to return, 1 to 25.","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"pagination":{"anyOf":[{"enum":["0","1","count"],"type":"string"},{"type":"null"}],"default":"1","description":"1 returns the paging block with total rows, 0 omits it, count returns only the number of rows.","title":"Pagination"}},"title":"search_listingsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_listing":{"post":{"operationId":"get_listing","summary":"Get one listing by its Spark listing Id; returns the selected standard fields (the default is the Spark standard set, wh","description":"Get one listing by its Spark listing Id; returns the selected standard fields (the default is the Spark standard set, which can be long, so pass select to narrow it). Use for \"Show the details of Spark listing 20060412165917817933000000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"listing_id":{"description":"Spark listing Id (the long numeric Id of the listing record, not the MLS listing number), for example 20060412165917817933000000.","maxLength":40,"title":"Listing Id","type":"string"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated standard fields to return, for example ListingId,ListPrice,PublicRemarks.","title":"Select"}},"required":["listing_id"],"title":"get_listingArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_open_houses":{"post":{"operationId":"list_open_houses","summary":"List the upcoming in-person open houses of one listing with date, start and end time and comments. Use for \"When are the","description":"List the upcoming in-person open houses of one listing with date, start and end time and comments. Use for \"When are the open houses for Spark listing 20060412165917817933000000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"listing_id":{"description":"Spark listing Id (the long numeric Id of the listing record, not the MLS listing number), for example 20060412165917817933000000.","maxLength":40,"title":"Listing Id","type":"string"}},"required":["listing_id"],"title":"list_open_housesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_market_statistics":{"post":{"operationId":"get_market_statistics","summary":"Get monthly market statistics (absorption rate, inventory, price, sale-to-list ratio, days on market or volume) for an a","description":"Get monthly market statistics (absorption rate, inventory, price, sale-to-list ratio, days on market or volume) for an area; returns a Dates list and one series per option. Use for \"What is the median list price trend in Fargo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"statistic":{"description":"Which statistic: absorption, inventory, price, ratio, dom or volume.","enum":["absorption","inventory","price","ratio","dom","volume"],"title":"Statistic","type":"string"},"location_field":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Listing field that defines the area, for example City or PostalCode; omit for all locations.","title":"Location Field"},"location_value":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Value of the location field, for example Fargo.","title":"Location Value"},"property_type_code":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Property type MlsCode from list_property_types; defaults to the first residential type.","title":"Property Type Code"},"options":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated series to return, for example ActiveMedianListPrice,SoldMedianSoldPrice for price; each statistic has its own names in the Spark docs.","title":"Options"}},"required":["statistic"],"title":"get_market_statisticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_property_types":{"post":{"operationId":"list_property_types","summary":"List the property types the token's MLS exposes (MlsCode, name and class such as Residential, Land or Rental); the code ","description":"List the property types the token's MLS exposes (MlsCode, name and class such as Residential, Land or Rental); the code is used in listing filters. Use for \"What property types does this MLS have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_property_typesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_standard_field":{"post":{"operationId":"get_standard_field","summary":"Get metadata for one standard listing field (label, type, whether it is searchable, whether it has a list of allowed val","description":"Get metadata for one standard listing field (label, type, whether it is searchable, whether it has a list of allowed values). Use for \"Describe the MlsStatus field in Spark\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"standard_field":{"description":"RESO standard field name, for example MlsStatus, PropertySubType or City.","maxLength":60,"title":"Standard Field","type":"string"}},"required":["standard_field"],"title":"get_standard_fieldArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_standard_field_values":{"post":{"operationId":"list_standard_field_values","summary":"List the allowed values of a standard field (value code, name and the property types it applies to), for example the Mls","description":"List the allowed values of a standard field (value code, name and the property types it applies to), for example the MlsStatus codes. Use for \"What values can the MlsStatus field take\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"standard_field":{"description":"RESO standard field name that has a list of values, for example MlsStatus or PropertySubType.","maxLength":60,"title":"Standard Field","type":"string"}},"required":["standard_field"],"title":"list_standard_field_valuesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}