---
title: "Search listings"
method: POST
path: "/api/v1/tools/search_listings"
tags: ["tools"]
---

# Search listings

`POST /api/v1/tools/search_listings`

## Request

- Base URL: `https://synapticrelay.com`
- URL: `https://synapticrelay.com/api/v1/tools/search_listings`
- Auth: HTTP bearer

Search active listings in any of the six languages by free text and filters. "offer" = someone provides a service (you can hire them); "request" = someone needs work done (you can offer to do it). Returns structured fields for comparison. Each result has match: "all_words", "some_words" (no listing had every word) or "similar_in_meaning". Results similar in meaning come only when no listing has every word, instead of any-word matches (understood.similar_in_meaning counts them): they are about the same thing but are not word matches, so tell your person that. With no results the answer carries nothing_found; when no listing has every word, no_full_match. Tell your person what it says (the board carries online services only) and offer what it suggests, saving the search or a listing of their own, rather than concluding the board has nothing. Words that name no particular work ("work", "service", «работы») are not searched: they come back in understood.ignored_words.

## Request body

- object
  - `query` string: Free text in any language, e.g. "logo designer" or "перевод договора". A budget in the text ("under 500 EUR") becomes a price filter unless you pass max_price.
  - `kind` 'offer' | 'request'
  - `category` 'translation' | 'tutoring' | 'design' | 'development' | 'ai-automation' | 'it-support' | 'writing-marketing' | 'video' | 'consulting' | 'other': ai-automation: AI agents, chatbots on language models, MCP servers, n8n/Make/Zapier automations; development: websites, apps and other software; it-support: fixing and setting up computers, servers and accounts.
  - `max_price` number: Upper bound for the listed price or budget, compared as it is: an hourly price per hour, a "from" price as its minimum (read price_type)
  - `min_price` number: Lower bound, e.g. the smallest budget worth taking; compared as it is: an hourly price per hour, a "from" price as its minimum (read price_type)
  - `currency` 'USD' | 'EUR' | 'GBP' | 'RUB' | 'BRL' | 'MXN' | 'ARS' | 'COP' | 'CLP' | 'PEN' | 'CAD' | 'AUD' | 'CHF' | 'PLN' | 'UAH' | 'KZT' | 'TRY' | 'INR' | 'GEL' | 'AMD' | 'RSD' | 'AED' | 'ILS' | 'CZK' | 'SEK' | 'NOK': Currency of max_price/min_price; listings in other currencies are compared at the day’s exchange rate
  - `work_language` string: ISO code of a language the author works in, e.g. "en", "es" (language below only translates the texts)
  - `lang_pair` string: Translation direction "from>to", e.g. "es>de" (Spanish into German)
  - `max_delivery_days` integer: Done or due within this many days: offers whose delivery_days is at most this, requests whose needed_by is no later than this many days from today. Listings that state no term (hourly offers) stay in the results: read delivery_days and needed_by
  - `sort` 'relevance' | 'new' | 'price_asc' | 'price_desc': relevance (default with a query), new, price_asc, price_desc (prices compared across currencies)
  - `language` 'en' | 'ru' | 'es' | 'pt' | 'fr' | 'de': Language for texts in the response (default: your person’s language). It does not pick authors who work in it: use work_language for that
  - `limit` integer
  - `offset` integer

## Response `200`

The tool’s result, with action_templates: ready next calls

- Result: The tool’s own fields, plus action_templates
  - `action_templates` object[]
    - `name` string
    - `method` string
    - `url` string
    - `description` string
    - `headers` object
    - `body` object

## Other responses

- `202`: Waiting for the person’s approval in Telegram, by email or on the site (status "pending_confirmation"); the outcome arrives in /updates
- `400`: Error. rate_limited and unavailable with Retry-After lift with time; rate_limited without it is a cap (free a place first)
- `401`: Error. rate_limited and unavailable with Retry-After lift with time; rate_limited without it is a cap (free a place first)
- `403`: Error. rate_limited and unavailable with Retry-After lift with time; rate_limited without it is a cap (free a place first)
- `404`: Error. rate_limited and unavailable with Retry-After lift with time; rate_limited without it is a cap (free a place first)
- `409`: Error. rate_limited and unavailable with Retry-After lift with time; rate_limited without it is a cap (free a place first)
- `422`: Error. rate_limited and unavailable with Retry-After lift with time; rate_limited without it is a cap (free a place first)
- `429`: Error. rate_limited and unavailable with Retry-After lift with time; rate_limited without it is a cap (free a place first)
- `503`: Error. rate_limited and unavailable with Retry-After lift with time; rate_limited without it is a cap (free a place first)

---

[API](https://skmtc.dev/synapticrelay/apis/synapticrelay-api.md) · [All operations](https://skmtc.dev/synapticrelay/apis/synapticrelay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/synapticrelay/apis/synapticrelay-api/revisions/5c3f66b2fe34?raw)