--- title: "List the caller's grounded circular-economy opportunities." method: GET path: "/api/v1/opportunities" tags: ["opportunities"] --- # List the caller's grounded circular-economy opportunities. `GET /api/v1/opportunities` ## Request - Base URL: `https://api.prosp.cc` - URL: `https://api.prosp.cc/api/v1/opportunities` - Auth: OAuth 2 (client credentials, token URL `https://prosp-mcp-641053169627.auth.eu-central-1.amazoncognito.com/oauth2/token`, scopes: `mcp/execute`) The set of circular-economy opportunities inferred from YOUR OWN stored business profile: for each, the flow, asset, capacity or capability it rests on and the kind of company that completes it. Costs no credits and runs no search. The list is served from an already-computed portfolio and is dated by `computed_at`, which is when it was DERIVED - not when you asked. It is never padded: one grounded opportunity yields one entry. **Read `speech_act` before you use a label.** An element whose `grounding` is `IMPLIED` is a hypothesis - it carries `speech_act: ASK` and may only ever be put as a question, never stated as fact. The two elements are graded independently and mean different things: the `resource` is a claim about YOUR OWN business, the `counterpart` is a hypothesis about which kind of company would want it. `outreach_draft_eligible` answers only whether the entry may GROUND a draft, and it turns on the `resource`, because that is what a message would be about. An entry may be draft-eligible while its `counterpart` is still `ASK` - that is the ordinary case, not an edge case - and in that case the market hypothesis still may not be asserted in the message. Running one requires you to confirm or correct the resource first; see `POST /api/v1/discoveries` with `opportunityHandle`. Order is server-authoritative and is not a ranking you should re-apply - the same order is used on every surface these opportunities appear on. ## Response `200` The caller's grounded opportunities. - CircularOpportunityList: The caller's grounded circular-economy opportunities. - `opportunities` CircularOpportunity[], required: In server-authoritative order. Never padded - an empty array means nothing is well-grounded, which is a real answer and not a failure. - `handle` string, required: Opaque id of this entry, scoped to your portfolio. Pass it to run the counterpart search. - `category_group` string, required: The kind of opportunity - materials recovery is one of several and is never a default. A bounded vocabulary; treat an unfamiliar value as opaque rather than as an error. - `mode` string, required: The shape of the search this entry becomes. Bounded vocabulary. - `direction` 'CUSTOMER_HOLDS' | 'CUSTOMER_SEEKS', required: `CUSTOMER_HOLDS` - you hold underutilized value and the search finds who wants it. `CUSTOMER_SEEKS` - you would source value another company holds. - `resource` CircularClaim, required: One claim, together with what may be DONE with it. `label` is presented verbatim in its original language and is never translated - it may carry a product, brand or material designation. `speech_act` is the machine-readable form of a rule that is a sentence on a chat surface: an `IMPLIED` claim is something we inferred about your business, not something you told us, so it may only ever be put to you as a QUESTION. - `label` string, required: The flow, asset, capacity, capability or counterpart type, in plain commercial language. - `grounding` 'STATED' | 'CONFIRMED' | 'IMPLIED', required: `STATED` - appears in your business profile. `CONFIRMED` - you corrected or confirmed it and we retained that. `IMPLIED` - inferred, and not yet confirmed by you. - `speech_act` 'ASSERT' | 'ASK', required: `ASSERT` for a stated or confirmed claim. `ASK` for an unconfirmed hypothesis, which must be phrased as a question about your business and must not enter outreach. - `counterpart` CircularClaim, required: One claim, together with what may be DONE with it. `label` is presented verbatim in its original language and is never translated - it may carry a product, brand or material designation. `speech_act` is the machine-readable form of a rule that is a sentence on a chat surface: an `IMPLIED` claim is something we inferred about your business, not something you told us, so it may only ever be put to you as a QUESTION. - `label` string, required: The flow, asset, capacity, capability or counterpart type, in plain commercial language. - `grounding` 'STATED' | 'CONFIRMED' | 'IMPLIED', required: `STATED` - appears in your business profile. `CONFIRMED` - you corrected or confirmed it and we retained that. `IMPLIED` - inferred, and not yet confirmed by you. - `speech_act` 'ASSERT' | 'ASK', required: `ASSERT` for a stated or confirmed claim. `ASK` for an unconfirmed hypothesis, which must be phrased as a question about your business and must not enter outreach. - `markets` string[]: ISO-3166 alpha-2 markets the counterpart search would cover. - `proximity_bound` boolean: True when the exchange only transacts over short distances (heat, CO2, water, bulky low-value material, shared capacity), so reachability constrains the search. - `grounding_sources` string[]: Customer-safe CATEGORIES the claims rest on - where and when, never who. Paired with the list's `computed_at`, these are the provenance of everything shown here. - `outreach_draft_eligible` boolean: Whether this entry may GROUND an outreach draft. False when the `resource` - the thing a message would be ABOUT - is an unconfirmed hypothesis; such an entry must not be used to compose outreach in any form, not even as a question, until the customer confirms it. True does NOT license asserting the `counterpart`: that is a hypothesis about a MARKET rather than about the customer, it carries its own `speech_act`, and on a true entry it is very often still `ASK`. Read both. - `requires_resource_confirmation` boolean: True when running this entry requires `confirmedResource` on the trigger, because its resource is an unconfirmed hypothesis. - `credits_cost` integer: What running the counterpart search costs, shown before anything is spent. - `computed_at` integer, required: Epoch milliseconds when this portfolio was DERIVED. It is not recomputed to answer a read, so a value some days old is expected and is the honest date of these claims. - `opted_out` boolean: True when you have turned circular suggestions off. The list is then empty because you asked for it to be, which is a different thing from having no opportunities. ## Other responses - `401`: Missing/invalid/expired Bearer token. - `405`: HTTP method not allowed on this endpoint (rejected before any credit debit). - `429`: Rate limit exceeded (100 requests / 60s per customer). --- [API](https://skmtc.dev/prosp/apis/prosp-discovery-api.md) · [All operations](https://skmtc.dev/prosp/apis/prosp-discovery-api/llms.txt) · [OpenAPI document](https://skmtc.dev/prosp/apis/prosp-discovery-api/revisions/1f2e0c55da22?raw)