Prosp
Prosp (prosp.cc): B2B company finder. Describe the companies you want, get matches with contacts.
Sollte ich dies verwenden
Qualität und Sicherheit
Befunde (1)
- LOWin get_credit_balance
Basierend auf einer automatisierten Analyse der Tool-Definitionen und der Einhaltung des Protokolls.
Kontextkosten
Dies ist die ungefähre Anzahl der Tokens, die jedes Mal verbraucht werden, wenn die Tools des Servers in den Kontext eines Modells geladen werden. Höhere Werte verringern die Aufmerksamkeit, die für andere Aufgaben verfügbar ist.
Installieren
Installation mit einem Klick
Fügen Sie dies Ihrer Datei `claude_desktop_config.json` hinzu:
{
"mcpServers": {
"prosp": {
"url": "https://api.prosp.cc/mcp-rpc"
}
}
}Remote-Endpunkte
https://api.prosp.cc/mcp-rpcstreamable-httpWas es kann
Tool-Inventar
Tools (24)
🟢find_prospects(criteria)
Start a B2B prospect-discovery job. Debits 100 credits and returns a jobId immediately; the job runs asynchronously (~5-25 min). Poll get_discovery_status with the jobId, then call get_discovery_results when it reaches a terminal state.
Eingabe-Schema
{
"type": "object",
"properties": {
"criteria": {
"additionalProperties": false,
"description": "Ideal-customer-profile criteria for a discovery job.\n\nField names match the REST ``parameters`` object exactly (including the\ncamelCase ``maxResults``) so this serialises straight onto the wire.",
"properties": {
"query": {
"description": "Natural-language description of the target companies to find, e.g. 'Find retail partners for a Ukrainian menswear manufacturer that sell business clothing'.",
"minLength": 1,
"type": "string"
},
"industries": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Industry filters, e.g. ['Retail', 'Fashion']."
},
"locations": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Country/region filters, e.g. ['Germany', 'Austria']. Any of 22+ served markets."
},
"company_sizes": {
"anyOf": [
{
"items": {
"description": "Company-size brackets accepted by the discovery pipeline.\n\nKept in lock-step with the REST openapi ``company_sizes`` enum\n(``[micro, small, medium, large, enterprise]``) — the MCP tool schema is a SEPARATE\nclient-side artifact and must not drift from the REST spec, or an agent cannot send a\nvalue the REST API accepts (e.g. ``micro``).",
"enum": [
"micro",
"small",
"medium",
"large",
"enterprise"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Size brackets: micro (≤10), small (up to ~50), medium (up to ~200), large (up to ~500), enterprise (500+). Advisory — the engine may relax to adjacent brackets in thin markets."
},
"keywords": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Keyword hints for the search."
},
"exclusions": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Domains/terms to exclude from results."
},
"sub_country_regions": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO-3166-2 sub-country regions (validated server-side against the shared region set)."
},
"target_business_models": {
"anyOf": [
{
"items": {
"description": "Value-chain roles accepted by the discovery pipeline's ``target_business_models`` filter.\n\nKept in lock-step with the REST openapi ``target_business_models`` enum\n(``[manufacturer, retailer, distributor, service_provider, unknown]``) — the MCP tool\nschema is a SEPARATE client-side artifact and must not drift from the REST spec, or an\nagent cannot send a value the REST API accepts.",
"enum": [
"manufacturer",
"retailer",
"distributor",
"service_provider",
"unknown"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Value-chain-role filter: keep only companies classified as one of manufacturer, retailer, distributor, service_provider or unknown. Omit to accept any role (default — no role filtering). The role is what the TARGET company IS, taken from the noun the customer used for the targets in their own language (roasters, farms, makers, producers -> manufacturer), NEVER inferred from the customer's own business or supply chain (a coffee shop asking for roasters wants manufacturer, not distributor). If the request names no target role, or you are unsure, omit it: a wrong role silently drops every genuine match."
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional market-language hint as an ISO-639-1 code (e.g. 'de', 'cs', 'pl'). Steers the query->ICP expansion so keyword/industry expansion is generated in the market's language rather than inferred solely from `query`. Advisory, not a hard filter — company and person names are never translated, and results are not restricted to a single content language. Omit to let the engine infer the language from `query` itself."
},
"website": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The caller's own website — self-excluded from results."
},
"maxResults": {
"anyOf": [
{
"maximum": 200,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": 50,
"description": "Soft cap on the number of companies to return (server-capped at 200)."
},
"acknowledge_low_yield": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Set true to run this discovery anyway when the saturation pre-check estimates ~0 net-new companies (the default holds a saturated ICP with a 409 and does NOT charge). Steers the warn-and-confirm gate only — not a search criterion."
}
},
"required": [
"query"
],
"type": "object"
}
},
"required": [
"criteria"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟢get_discovery_status(job_id, cursor)
Poll a discovery job by its jobId. Returns the lifecycle state (queued, processing, completed, failed, exhausted), `total_prospects` (the canonical count of validated prospects delivered so far — the SAME field name get_discovery_results carries, so you can group/count across both; `prospectsFound` is a deprecated alias of it) and `target` counts, and `found`: the prospect DOMAINS discovered so far — which accumulate PROGRESSIVELY while the job runs, so you see results before it finishes. For incremental polling, pass the previous response's `next_cursor` as `cursor` to receive only the domains added since your last poll (`has_more` stays true until the job reaches a terminal state; omit `cursor` to get the full list so far). Call get_prospect(domain) — or get_discovery_results once terminal — for full detail on any domain in `found`.
Eingabe-Schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"job_id"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟢get_discovery_results(job_id)
Fetch the result summary + discovered companies (with verified contacts) for a jobId. Call once get_discovery_status reports a terminal state.
Eingabe-Schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string"
}
},
"required": [
"job_id"
],
"additionalProperties": false
}🟢get_discovery_export(job_id)
The download link for a finished discovery's companies as an Excel (.xlsx) workbook: one row per company plus a Contacts sheet, the same customer-safe fields as the CSV. The link is a GET that needs the same bearer token as the other tools. Free; call once get_discovery_status reports a terminal state.
Eingabe-Schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string"
}
},
"required": [
"job_id"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟢search_prospects(query, limit, cursor)
Semantic free-text search over the companies you have already discovered. Does not run a new discovery and does not cost credits. Returns LEAN prospect SUMMARIES (domain, name, industry, size, location, employee_count, logo, a short description and a semantic_score) — not the full record. To get every field for one company (contacts, emails, registry data, social profiles, ...), call get_prospect(domain) with the summary's `domain`. Pagination is progressive: the response carries `has_more` and an opaque `next_cursor`; pass that cursor back to fetch the next page. When `has_more` is false / `next_cursor` is null you have seen everything above the relevance floor — stop paging.
Eingabe-Schema
{
"type": "object",
"properties": {
"query": {
"type": "string"
},
"limit": {
"default": 20,
"type": "integer"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"query"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟢get_prospect(domain)
Fetch the FULL record for one already-discovered company by its `domain` — the detail behind a `search_prospects` summary or a `found[]` domain. Returns every field (contacts, personal + company emails, registry data, address, social profiles, scores, description), not the lean summary. Does not run a new discovery and does not cost credits. A domain you have not discovered comes back as a structured `not_found` status rather than an error.
Eingabe-Schema
{
"type": "object",
"properties": {
"domain": {
"type": "string"
}
},
"required": [
"domain"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🔴cancel_discovery(job_id)
Cancel a running discovery job by its jobId, freeing its slot so a new find_prospects can start. Credits are refunded ONLY when the run had delivered zero prospects at cancel time; if prospects were already delivered you keep them and are not refunded (they stay retrievable via get_discovery_results). Only the job's owner may cancel; cancelling an already-finished job is a harmless no-op that returns its current state.
Eingabe-Schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string"
}
},
"required": [
"job_id"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}⚪acknowledge_prospects(domains)
Mark one or more company domains as delivered so they are not returned again in future discoveries or searches. Pass the `domains` list. Job-blind: each domain is acknowledged across ALL your discoveries. Idempotent — an unknown or already-acknowledged domain is a harmless no-op that contributes 0 to the returned count. Does not cost credits.
Eingabe-Schema
{
"type": "object",
"properties": {
"domains": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"domains"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟢list_icps
List your saved ICPs (Ideal Customer Profiles) — reusable discovery criteria you can re-run by id. Each entry carries its `icpId`, optional `name`, and stored `criteria`. Pass an `icpId` to run_icp to start a discovery from it. Does not cost credits.
Eingabe-Schema
{
"type": "object",
"properties": {},
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟡save_icp(icp)
Save a reusable ICP (Ideal Customer Profile) from an optional display `name` plus discovery `criteria` (same shape as find_prospects). Returns the stored ICP with a server-assigned `icpId` you can later pass to run_icp. Saving does NOT run a discovery and does not cost credits.
Eingabe-Schema
{
"type": "object",
"properties": {
"icp": {
"additionalProperties": false,
"description": "Body to create a saved ICP (Ideal Customer Profile) — an optional display\nname plus the discovery criteria it re-runs.\n\nMirrors the openapi ``IcpRequest`` schema field-for-field (``additionalProperties:\nfalse``, ``required: [criteria]``) so it serialises straight onto the wire. The\nnested ``criteria`` reuses :class:`DiscoveryCriteria`, so a saved ICP is validated\nby the SAME single-source schema an inline discovery is — no divergent copy.",
"properties": {
"name": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional human-readable label for this ICP, e.g. 'EU Retail SMEs'. When present it must be non-empty."
},
"criteria": {
"additionalProperties": false,
"description": "The discovery criteria this ICP re-runs (same shape as find_prospects).",
"properties": {
"query": {
"description": "Natural-language description of the target companies to find, e.g. 'Find retail partners for a Ukrainian menswear manufacturer that sell business clothing'.",
"minLength": 1,
"type": "string"
},
"industries": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Industry filters, e.g. ['Retail', 'Fashion']."
},
"locations": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Country/region filters, e.g. ['Germany', 'Austria']. Any of 22+ served markets."
},
"company_sizes": {
"anyOf": [
{
"items": {
"description": "Company-size brackets accepted by the discovery pipeline.\n\nKept in lock-step with the REST openapi ``company_sizes`` enum\n(``[micro, small, medium, large, enterprise]``) — the MCP tool schema is a SEPARATE\nclient-side artifact and must not drift from the REST spec, or an agent cannot send a\nvalue the REST API accepts (e.g. ``micro``).",
"enum": [
"micro",
"small",
"medium",
"large",
"enterprise"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Size brackets: micro (≤10), small (up to ~50), medium (up to ~200), large (up to ~500), enterprise (500+). Advisory — the engine may relax to adjacent brackets in thin markets."
},
"keywords": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Keyword hints for the search."
},
"exclusions": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Domains/terms to exclude from results."
},
"sub_country_regions": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO-3166-2 sub-country regions (validated server-side against the shared region set)."
},
"target_business_models": {
"anyOf": [
{
"items": {
"description": "Value-chain roles accepted by the discovery pipeline's ``target_business_models`` filter.\n\nKept in lock-step with the REST openapi ``target_business_models`` enum\n(``[manufacturer, retailer, distributor, service_provider, unknown]``) — the MCP tool\nschema is a SEPARATE client-side artifact and must not drift from the REST spec, or an\nagent cannot send a value the REST API accepts.",
"enum": [
"manufacturer",
"retailer",
"distributor",
"service_provider",
"unknown"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Value-chain-role filter: keep only companies classified as one of manufacturer, retailer, distributor, service_provider or unknown. Omit to accept any role (default — no role filtering). The role is what the TARGET company IS, taken from the noun the customer used for the targets in their own language (roasters, farms, makers, producers -> manufacturer), NEVER inferred from the customer's own business or supply chain (a coffee shop asking for roasters wants manufacturer, not distributor). If the request names no target role, or you are unsure, omit it: a wrong role silently drops every genuine match."
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional market-language hint as an ISO-639-1 code (e.g. 'de', 'cs', 'pl'). Steers the query->ICP expansion so keyword/industry expansion is generated in the market's language rather than inferred solely from `query`. Advisory, not a hard filter — company and person names are never translated, and results are not restricted to a single content language. Omit to let the engine infer the language from `query` itself."
},
"website": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The caller's own website — self-excluded from results."
},
"maxResults": {
"anyOf": [
{
"maximum": 200,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": 50,
"description": "Soft cap on the number of companies to return (server-capped at 200)."
},
"acknowledge_low_yield": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Set true to run this discovery anyway when the saturation pre-check estimates ~0 net-new companies (the default holds a saturated ICP with a 409 and does NOT charge). Steers the warn-and-confirm gate only — not a search criterion."
}
},
"required": [
"query"
],
"type": "object"
}
},
"required": [
"criteria"
],
"type": "object"
}
},
"required": [
"icp"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟡run_icp(icp_id)
Start a discovery from a saved ICP by its `icpId` (get one from list_icps or save_icp). Debits 100 credits and returns a jobId immediately; the job runs asynchronously (~5-25 min) — poll get_discovery_status, then get_discovery_results, exactly as for find_prospects. An unknown icpId is rejected and the debit is refunded.
Eingabe-Schema
{
"type": "object",
"properties": {
"icp_id": {
"type": "string"
}
},
"required": [
"icp_id"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟢get_credit_balance
Return your remaining credit balance and the per-job cost (100 credits).
Eingabe-Schema
{
"type": "object",
"properties": {},
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟢get_credit_ledger(limit)
Show your credit transaction history: every debit and refund behind the current balance, most recent first. Each entry has a `type` ('debit' or 'refund'), the `job_id` it belongs to, the `amount`, a `reason` and a `timestamp`. Use this to explain WHY the balance is what it is — e.g. a job that debited 100 credits and was then refunded on exhaustion/failure shows up as a matching debit + refund pair, so the balance returning to its prior value is a legitimate refund, not the debit having failed to apply. Does not run a new discovery and does not cost credits. Pass `limit` to bound how many recent transactions are returned (default 50, max 200).
Eingabe-Schema
{
"type": "object",
"properties": {
"limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟢list_circular_opportunities
List circular-economy opportunities inferred from the customer's OWN stored business profile: for each, the flow, asset, spare capacity or capability it rests on and the kind of company that completes it. Does not run a discovery and does not cost credits. The list is dated by `computed_at` — when it was DERIVED, not when you asked — and is never padded, so an empty list means nothing is well-grounded. READ `speech_act` BEFORE YOU USE A LABEL. Each of `resource` and `counterpart` carries one, graded independently. `ASSERT` means the customer told us this and you may state it back. `ASK` means WE INFERRED IT, so refer to it only as a question ('do you have spare kiln capacity?'), never as a fact ('your spare kiln capacity'). The two elements are NOT the same kind of claim. `resource` is about the customer's OWN business; `counterpart` is a hypothesis about which kind of company would want it, and it is `ASK` on nearly every entry — that is normal and does not make the entry unusable. `outreach_draft_eligible` answers ONE question: may this entry ground a draft at all. It turns on the `resource`, because that is what a message would be ABOUT. `false` means do not compose outreach from it in any form, not even as a question. `true` means you may write about the resource — it does NOT license asserting the `counterpart`; that element's own `speech_act` still governs it, so write the market as an open question, not as a need you have established. Do not re-order the list: the order is server-authoritative and shared with every other surface these opportunities appear on. Pass an entry's `handle` to run_circular_opportunity to search for its counterparts.
Eingabe-Schema
{
"type": "object",
"properties": {},
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟡run_circular_opportunity(handle, confirmed_resource)
Start a counterpart search for one circular opportunity, by the `handle` from list_circular_opportunities. Debits credits and returns a jobId immediately; poll get_discovery_status then get_discovery_results exactly as for find_prospects. What is searched for is derived server-side from the graded opportunity — you pass a handle, not criteria. When the entry has `requires_resource_confirmation: true`, its resource is something WE INFERRED rather than something the customer stated, and this call is REFUSED (404 `resource_confirmation_required`, no charge) unless you pass `confirmed_resource`. ASK THE CUSTOMER FIRST and send THEIR WORDING — do not echo our label back and do not invent one. Their answer is retained as a stated fact about their business and informs every later inference, so a guess becomes a durable error. An unknown handle is refused with a refund.
Eingabe-Schema
{
"type": "object",
"properties": {
"handle": {
"type": "string"
},
"confirmed_resource": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"handle"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🔴set_odoo_credentials(credentials)
Connect your own Odoo CRM so your discovered prospects sync into it. Provide your Odoo URL, database name, API-user id and API key (generate one under Preferences -> Account Security -> New API Key). The connection is validated live against your Odoo before it is saved; your API key is stored encrypted and is NEVER shown back — present a masked confirmation (e.g. odoo_api_key: ****) to the user. Calling this again updates the existing connection.
Eingabe-Schema
{
"type": "object",
"properties": {
"credentials": {
"additionalProperties": false,
"description": "A customer's own Odoo CRM connection details.\n\nMirrors the ``POST /api/v1/tenant/odoo-connection`` request body the odoo-sync\nonboarding router expects (``_validate_shape``) field-for-field — the endpoint\ncontract is the single source of truth, so we do NOT invent a divergent schema.\n\n``customer_id`` is deliberately absent: identity is the JWT-derived\n``X-Customer-Id`` header set at the gateway, so a customer can only ever set\nTHEIR OWN credentials. The connector adds no validation of its own — the live\n``/jsonrpc`` auth probe + SSRF guard + FK audit all run server-side before\nanything is stored (a thin bridge; business logic lives behind the gateway).\n\n``odoo_api_key`` is a SECRET: it is sent in the request body (never a query\nparam, never logged) and is never echoed back — the gateway + odoo-sync\nresponse filters strip it, so any confirmation the agent shows must mask it.",
"properties": {
"odoo_url": {
"description": "Your Odoo base URL, e.g. 'https://acme.odoo.com' (https; validated for SSRF safety server-side).",
"minLength": 1,
"type": "string"
},
"odoo_db": {
"description": "Your full Odoo database name, including any '-scm-NNNN' suffix (Odoo.sh).",
"minLength": 1,
"type": "string"
},
"odoo_uid": {
"description": "The numeric id of the Odoo API user (visible in the Odoo URL on the user form).",
"exclusiveMinimum": 0,
"type": "integer"
},
"odoo_api_key": {
"description": "Your Odoo API key (generate under Preferences -> Account Security -> New API Key). SECRET: stored encrypted, never logged, and never echoed back.",
"minLength": 1,
"type": "string"
},
"stage_id": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional CRM stage FK for new leads (validated live against your Odoo)."
},
"team_id": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional sales-team FK (validated live)."
},
"user_id": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional salesperson FK (validated live)."
},
"enrichment_stage_id": {
"anyOf": [
{
"exclusiveMinimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional stage FK for leads still needing contact enrichment (validated live)."
},
"lead_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Odoo lead type, defaults to 'opportunity' server-side."
}
},
"required": [
"odoo_url",
"odoo_db",
"odoo_uid",
"odoo_api_key"
],
"type": "object"
}
},
"required": [
"credentials"
],
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟢get_crm_connection
Show your currently configured Odoo CRM connection (Odoo URL, database, user id and status). Never shows the API key. Returns a 'not connected' error if you have not called set_odoo_credentials yet.
Eingabe-Schema
{
"type": "object",
"properties": {},
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🔴disconnect_crm
Disconnect your Odoo CRM. Future discovered prospects will no longer sync to it. Idempotent — safe to call even if nothing is connected.
Eingabe-Schema
{
"type": "object",
"properties": {},
"additionalProperties": false
}Ausgabe-Schema
{
"type": "object",
"additionalProperties": true
}🟡generate_message(recipient, sender, channel, objective, constraints, ...)
Registers one message generation and returns immediately with `202 Accepted`. Poll the status resource named in `Location` (or honour `Retry-After`) until `status` is terminal; the finished message is embedded in that resource. The API composes text; it does **not** send it, and it does not replace the recipient's WhatsApp opt-in. ## What the message may say Every candidate fact about the recipient and the sender carries a tier. The message **asserts only facts of tier `verified`**. `reported` and `estimated` facts may influence which angle is chosen but are never stated as fact; `unknown` facts are never mentioned. The tier of each field is derived from the provenance the record already carries (field by field, from its source and verification evidence), not chosen by the model. Personal data - contacts, officers, phone numbers, e-mail addresses, social handles, and, for a sole trader, the person's own name and address - is **never** asserted. After generation, code re-checks that each claim in the text maps to `fact_ids` of `verified` facts; an unsupported claim is removed, or the request fails - it is never shipped. ## Language The message is written in the language of the **recipient company's website main page**. There is no caller override. The decision is reported on the result as `language` (ISO 639-1) and `language_source`. If the homepage language cannot be determined the request fails with error code `language_undetermined` and the credits are returned; the language is never guessed. ## Unknown companies If the recipient or sender company is not yet known, the status passes through `enriching`, which runs the existing discovery/validation pipeline for that single domain, then `composing`. The wait for an unknown **sender** is bounded. If the sender is still unknown to the knowledge base afterwards, and the caller's seller profile (used only when its website is that same sender domain) holds no offering or description for it, nothing true can be written about the sender's offer: the generation ends `failed` with `error.error` = `sender_unknown` **before any model call**, and its credits are returned. Another company's seller profile is never used as the sender's facts. ## Cost and balance There is exactly **one debit, at `POST`**, for the whole generation including any enrichment. Enrichment never debits again and never changes the balance mid-job; a generation that ends `failed` for any reason below, or `canceled` before composition starts, returns that one debit. `402 insufficient_credits` is therefore only ever returned by `POST`. ## Jurisdiction Checked at `POST` against what is already known: `422 jurisdiction_excluded`. A company whose jurisdiction only becomes known **after** enrichment is excluded late: the generation ends `failed` with `error.error` = `jurisdiction_excluded` and the credits are returned. The text is never composed for an excluded jurisdiction. ## Validation done before `202` Invalid body or hostname: `400 invalid_request`. `sender.company_domain` is the sender's own company domain: the service reads the sender's facts from the knowledge base by it and does not verify that the caller controls it. When `sender` or `sender.company_domain` is omitted, the caller's seller profile website is the sender; with no profile website either, the request is `400 invalid_request` (`sender.company_domain is required when no seller profile website is set`). Recipient or sender in a policy-excluded jurisdiction: `422 jurisdiction_excluded`. Insufficient credits: `402 insufficient_credits`. `constraints.max_characters` that no message can meet: `422 max_characters_unmeetable`; when this only shows during composition the generation ends `failed` with the same code and the credits are returned. `callback_url` must be an `https` URL on a public host: a URL resolving to a private, loopback, link-local, reserved, multicast or cloud-metadata address is rejected with `422 unsafe_url` (the same rule as `odoo_url` on the tenant Odoo endpoint). The service being temporarily unable to accept work: `503 service_unavailable` with `Retry-After`; nothing is debited. ## Error codes Every error uses the surface's single `Error` shape `{error, message, request_id}`. `error` is a snake_case code: `invalid_request`, `missing_idempotency_key`, `idempotency_key_reused`, `request_in_flight`, `jurisdiction_excluded`, `insufficient_credits`, `unsafe_url`, `max_characters_unmeetable`, `not_cancelable`, `generation_expired`, `service_unavailable`, and, on a `failed` generation only, the `MessageFailureCode` values: `insufficient_verified_facts` (too few verified facts exist to write anything true), `enrichment_failed`, `sender_unknown` (the sender company is unknown to the knowledge base after its bounded enrichment wait and no seller-profile fact describes it), `language_undetermined`, `language_failed`, `claim_verification_failed`, `jurisdiction_excluded`, `max_characters_unmeetable`, `compose_failed`, `compose_timeout` and `timed_out`. A `failed` generation always returns its credits. ## Idempotency (draft-ietf-httpapi-idempotency-key-header-07) `Idempotency-Key` is **required**. Missing: `400 missing_idempotency_key`. Same key with a different payload: `422 idempotency_key_reused`. Same key while the original request is still being processed: `409 request_in_flight`. Same key with the same payload: **`200`** (not `202`) with the EXISTING resource in its current state (same `id`, no second debit). A key is remembered for **24 hours** from its first use; after that the same key starts a new generation.
Eingabe-Schema
{
"type": "object",
"properties": {
"recipient": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"company_domain"
],
"properties": {
"name": {
"type": "string",
"maxLength": 200,
"description": "The person's name, as the caller knows it."
},
"role": {
"type": "string",
"maxLength": 200,
"description": "The person's role at the company."
},
"company_domain": {
"type": "string",
"pattern": "^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+([a-z]{2,63}|xn--[a-z0-9-]{1,59})$",
"description": "Lowercase hostname (internationalised names in punycode); no scheme, path or port.",
"examples": [
"acme.de"
]
}
}
},
"sender": {
"type": "object",
"additionalProperties": false,
"description": "The sender's own company domain. The service reads the sender's facts from the knowledge base by it; ownership is not verified. If sender is omitted, the caller's seller profile website is the sender; the profile's offering and description are used as sender facts. If sender.company_domain differs from the profile website, the profile is not used.",
"properties": {
"company_domain": {
"type": "string",
"pattern": "^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+([a-z]{2,63}|xn--[a-z0-9-]{1,59})$",
"description": "Lowercase hostname (internationalised names in punycode); no scheme, path or port.",
"examples": [
"example.com"
]
}
}
},
"channel": {
"type": "string",
"enum": [
"email",
"whatsapp",
"telegram"
]
},
"objective": {
"type": "string",
"maxLength": 1000,
"description": "What the message should achieve, in the caller's words."
},
"constraints": {
"type": "object",
"additionalProperties": false,
"properties": {
"max_characters": {
"type": "integer",
"minimum": 1,
"description": "Bounds the message text only. The email subject has its own fixed cap of 80 characters and is not counted against this limit."
},
"tone": {
"type": "string",
"maxLength": 64
}
}
},
"callback_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"pattern": "^https://",
"description": "RESERVED. Accepted and stored, but no callback is delivered yet; poll the status resource. Must be an `https` URL on a public host: private, loopback, link-local, reserved, multicast and cloud-metadata addresses are rejected with `422 unsafe_url` (same rule as `odoo_url` on the tenant Odoo endpoint)."
}
},
"required": [
"recipient",
"channel",
"objective"
],
"additionalProperties": false,
"description": "What to write, to whom, from whom. There is NO language field: the message language is the language of the recipient company's website main page, reported on the result. If sender is omitted, the caller's seller profile website is the sender; the profile's offering and description are used as sender facts. If sender.company_domain differs from the profile website, the profile is not used."
}🟢get_message_generation(id)
Always `200` for a known id owned by the caller; a non-terminal state is a status, not an error. An unknown id, or one owned by another tenant, is `404`. While `status` is non-terminal the response carries `Retry-After`. When `succeeded`, `result` is embedded in this response (there is no redirect to a second resource). When `failed`, `error` is the surface's `Error` shape with a snake_case code. When `canceled`, `canceled_reason` says why. The resource is retained for **7 days after it reaches a terminal state**; `expires_at` says when, and the response carries a matching `Expires` header. After that the id is **`410 Gone`** (`generation_expired`), distinct from `404` for an id that never existed or is not yours.
Eingabe-Schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[a-zA-Z0-9-]+$",
"description": "The generation id returned by `POST /api/v1/message-intelligence`."
}
},
"required": [
"id"
],
"additionalProperties": false
}🔴cancel_message_generation(id)
Moves a `queued`, `enriching` or `composing` generation to the terminal state `canceled` with `canceled_reason` = `caller_request`. **Refund rule:** the debit is returned if composition has not started (`status` is `queued` or `enriching`); once `composing` has started the cancel is accepted but the credits are not returned. Canceling an already `canceled` generation is idempotent and returns it unchanged. Canceling a `succeeded` or `failed` generation is **`409 not_cancelable`**. An expired id is `410 generation_expired`.
Eingabe-Schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^[a-zA-Z0-9-]+$",
"description": "The generation id returned by `POST /api/v1/message-intelligence`."
}
},
"required": [
"id"
],
"additionalProperties": false
}🟢get_seller_profile
The one seller profile the caller keeps: the business description and website used to ground outreach messages. **No credit cost.** `derivation_status` says whether an offering was derived from the website (`derived`), is still being derived (`pending`), could not be derived after the bounded retries (`unavailable`, terminal until the profile's website is changed; editing only the description does not retry), or there is no website (`none`). `404 not_found` when no profile is set.
Eingabe-Schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}🔴set_seller_profile(description, website)
Replaces the whole profile with the body. **No credit cost.** Send at least one of `description` or `website`. A `description` longer than 1500 characters is truncated to 1500 characters, the same cap the `/profile` bot command applies, so both surfaces store the same record. A `website` is a URL or a bare domain; the site is crawled into the shared knowledge base in the background, and `derived_offering` fills in later (`derivation_status` is `pending` until then). The offering is kept while the website is unchanged and cleared when the website changes.
Eingabe-Schema
{
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "The business description (truncated to 1500 characters)."
},
"website": {
"type": "string",
"maxLength": 2048,
"description": "The seller's website, a URL or a bare domain. Blank clears it."
}
},
"additionalProperties": false,
"description": "The profile to store. Both fields are optional, but at least one must be non-blank. A description longer than 1500 characters is truncated, not refused."
}🔴delete_seller_profile
Removes the profile. Idempotent: deleting when no profile is set also returns `204`. **No credit cost.**
Eingabe-Schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Community
Nachweis