OpenVibe.Deals API

GET `/api/v1/flags`

Moderation: disable or enable an offer, record a person's review of imported or AI-assisted text (reviews are recorded for a usr_ subject only), read and resolve flags including vote-ring flags.

Capabilities: deals.offer.moderate
Visibility: first-party
Input: deals.moderation-request@1
Response: application/json deals.moderation-result@1
Errors: errors.problem@1 (application/problem+json)

Description

deals.offer.moderate (first-party): Moderation: disable or enable an offer, record a person's review of imported or AI-assisted text (reviews are recorded for a usr_ subject only), read and resolve flags including vote-ring flags. Audited.

POST `/api/v1/flags/{id}/resolve`

Moderation: disable or enable an offer, record a person's review of imported or AI-assisted text (reviews are recorded for a usr_ subject only), read and resolve flags including vote-ring flags.

Capabilities

deals.offer.moderate

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.moderation-request@1

Response

application/json deals.moderation-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.offer.moderate (first-party): Moderation: disable or enable an offer, record a person's review of imported or AI-assisted text (reviews are recorded for a usr_ subject only), read and resolve flags including vote-ring flags. Audited.

POST `/api/v1/offers`

Submit a deal for the acting person (X-OV-Subject): a link, title and what the person sees now (price with its currency, shipping, condition, availability — each optional, never defaulted).

Capabilities: deals.offer.submit
Visibility: first-party
Request body: application/json deals.offer-submit-request@1
Response: application/json deals.offer-result@1
Errors: errors.problem@1 (application/problem+json)

Description

deals.offer.submit (first-party): Submit a deal for the acting person (X-OV-Subject): a link, title and what the person sees now (price with its currency, shipping, condition, availability — each optional, never defaulted). The first observation is recorded with its time. A link already posted answers 409 offer.duplicate with the existing offer. With X-OV-Origin: ai the text is AI-assisted: disclosed and noindex until a person reviews it. Rate-limited per person.

PATCH `/api/v1/offers/{id}`

Edit an offer the acting person submitted (title, description, category, stated expiry, product link), or record a new observation of any active offer for the acting person (POST …/observations: price

Capabilities

deals.offer.update

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.offer-update-request@1

Response

application/json deals.offer-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.offer.update (first-party): Edit an offer the acting person submitted (title, description, category, stated expiry, product link), or record a new observation of any active offer for the acting person (POST …/observations: price with currency, shipping, condition, availability, with the time it was observed). Prices are never edited in place; each observation is a new row. Services may state observed_at (never in the future).

POST `/api/v1/offers/{id}/disable`

Moderation: disable or enable an offer, record a person's review of imported or AI-assisted text (reviews are recorded for a usr_ subject only), read and resolve flags including vote-ring flags.

Capabilities

deals.offer.moderate

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.moderation-request@1

Response

application/json deals.moderation-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.offer.moderate (first-party): Moderation: disable or enable an offer, record a person's review of imported or AI-assisted text (reviews are recorded for a usr_ subject only), read and resolve flags including vote-ring flags. Audited.

POST `/api/v1/offers/{id}/enable`

Moderation: disable or enable an offer, record a person's review of imported or AI-assisted text (reviews are recorded for a usr_ subject only), read and resolve flags including vote-ring flags.

Capabilities

deals.offer.moderate

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.moderation-request@1

Response

application/json deals.moderation-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.offer.moderate (first-party): Moderation: disable or enable an offer, record a person's review of imported or AI-assisted text (reviews are recorded for a usr_ subject only), read and resolve flags including vote-ring flags. Audited.

POST `/api/v1/offers/{id}/expire`

Mark an active offer expired (the person who submitted it, or a moderator).

Capabilities

deals.offer.expire

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.offer-action-request@1

Response

application/json deals.offer-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.offer.expire (first-party): Mark an active offer expired (the person who submitted it, or a moderator). Unknown expiry is never assumed; offers with a stated end expire on their own.

POST `/api/v1/offers/{id}/flags`

Report a problem with an offer for the acting person (expired, price_wrong, duplicate, spam, other).

Capabilities

deals.flag.create

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.flag-request@1

Response

application/json deals.flag-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.flag.create (first-party): Report a problem with an offer for the acting person (expired, price_wrong, duplicate, spam, other). One open report per person and offer; rate-limited. Flags never change an offer by themselves.

POST `/api/v1/offers/{id}/merge`

Duplicate resolution (moderation): merge an offer into another, or unmerge it.

Capabilities

deals.offer.merge

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.offer-action-request@1

Response

application/json deals.offer-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.offer.merge (first-party): Duplicate resolution (moderation): merge an offer into another, or unmerge it. Nothing is copied or deleted: votes, observations, sources and comments stay where they were written and the canonical offer reads across the group (a voter counts once). Audited with the tallies before and after; reversible.

POST `/api/v1/offers/{id}/observations`

Edit an offer the acting person submitted (title, description, category, stated expiry, product link), or record a new observation of any active offer for the acting person (POST …/observations: price

Capabilities

deals.offer.update

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.offer-update-request@1

Response

application/json deals.offer-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.offer.update (first-party): Edit an offer the acting person submitted (title, description, category, stated expiry, product link), or record a new observation of any active offer for the acting person (POST …/observations: price with currency, shipping, condition, availability, with the time it was observed). Prices are never edited in place; each observation is a new row. Services may state observed_at (never in the future).

POST `/api/v1/offers/{id}/review`

Moderation: disable or enable an offer, record a person's review of imported or AI-assisted text (reviews are recorded for a usr_ subject only), read and resolve flags including vote-ring flags.

Capabilities

deals.offer.moderate

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.moderation-request@1

Response

application/json deals.moderation-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.offer.moderate (first-party): Moderation: disable or enable an offer, record a person's review of imported or AI-assisted text (reviews are recorded for a usr_ subject only), read and resolve flags including vote-ring flags. Audited.

POST `/api/v1/offers/{id}/unmerge`

Duplicate resolution (moderation): merge an offer into another, or unmerge it.

Capabilities

deals.offer.merge

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.offer-action-request@1

Response

application/json deals.offer-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.offer.merge (first-party): Duplicate resolution (moderation): merge an offer into another, or unmerge it. Nothing is copied or deleted: votes, observations, sources and comments stay where they were written and the canonical offer reads across the group (a voter counts once). Audited with the tallies before and after; reversible.

PUT `/api/v1/offers/{id}/vote`

Set the acting person's vote (+1 / -1) on an offer.

Capabilities

deals.vote.set

Visibility

first-party

Parameters

id (path, required)

Request body

application/json deals.vote-request@1

Response

application/json deals.vote-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.vote.set (first-party): Set the acting person's vote (+1 / -1) on an offer. Server-authoritative: weight and hotness are computed by Deals (hot@1), never taken from the request. Rate-limited per person, per IP hash and per offer; no votes on one's own offer; vote-ring detection flags moderators.

DELETE `/api/v1/offers/{id}/vote`

Remove the acting person's vote on an offer (kept as a removed row for history).

Capabilities

deals.vote.remove

Visibility

first-party

Parameters

id (path, required)

Response

application/json deals.vote-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.vote.remove (first-party): Remove the acting person's vote on an offer (kept as a removed row for history). Same abuse controls as deals.vote.set.

POST `/api/v1/products/resolve`

Resolve a product by its aliases (gtin, mpn, sku, exact name, url), creating it when none matches (create: false to only look up).

Capabilities: deals.product.resolve
Visibility: first-party
Request body: application/json deals.product-resolve-request@1
Response: application/json deals.product-resolve-result@1
Errors: errors.problem@1 (application/problem+json)

Description

deals.product.resolve (first-party): Resolve a product by its aliases (gtin, mpn, sku, exact name, url), creating it when none matches (create: false to only look up). Aliases that already name another product are reported as conflicts, never re-pointed.

GET `/api/v1/watches`

List the acting person's watches and saved searches with their notification counts.

Capabilities: deals.watch.read
Visibility: first-party
Response: application/json deals.watch-result@1
Errors: errors.problem@1 (application/problem+json)

Description

deals.watch.read (first-party): List the acting person's watches and saved searches with their notification counts.

POST `/api/v1/watches`

Create a keyword, product or price-below watch, or a saved search (never notifies), for the acting person.

Capabilities: deals.watch.create
Visibility: first-party
Request body: application/json deals.watch-request@1
Response: application/json deals.watch-result@1
Errors: errors.problem@1 (application/problem+json)

Description

deals.watch.create (first-party): Create a keyword, product or price-below watch, or a saved search (never notifies), for the acting person. A watch notifies at most once per observation (deals.watch.matched, internal; Deals never emails).

DELETE `/api/v1/watches/{id}`

Delete one of the acting person's watches or saved searches.

Capabilities

deals.watch.delete

Visibility

first-party

Parameters

id (path, required)

Response

application/json deals.watch-result@1

Errors

errors.problem@1 (application/problem+json)

Description

deals.watch.delete (first-party): Delete one of the acting person's watches or saved searches.

GET /api/v1/flags

POST /api/v1/flags/{id}/resolve

POST /api/v1/offers

PATCH /api/v1/offers/{id}

POST /api/v1/offers/{id}/disable

POST /api/v1/offers/{id}/enable

POST /api/v1/offers/{id}/expire

POST /api/v1/offers/{id}/flags

POST /api/v1/offers/{id}/merge

POST /api/v1/offers/{id}/observations

POST /api/v1/offers/{id}/review

POST /api/v1/offers/{id}/unmerge

PUT /api/v1/offers/{id}/vote

DELETE /api/v1/offers/{id}/vote

POST /api/v1/products/resolve

GET /api/v1/watches

POST /api/v1/watches

DELETE /api/v1/watches/{id}

GET `/api/v1/flags`

POST `/api/v1/flags/{id}/resolve`

POST `/api/v1/offers`

PATCH `/api/v1/offers/{id}`

POST `/api/v1/offers/{id}/disable`

POST `/api/v1/offers/{id}/enable`

POST `/api/v1/offers/{id}/expire`

POST `/api/v1/offers/{id}/flags`

POST `/api/v1/offers/{id}/merge`

POST `/api/v1/offers/{id}/observations`

POST `/api/v1/offers/{id}/review`

POST `/api/v1/offers/{id}/unmerge`

PUT `/api/v1/offers/{id}/vote`

DELETE `/api/v1/offers/{id}/vote`

POST `/api/v1/products/resolve`

GET `/api/v1/watches`

POST `/api/v1/watches`

DELETE `/api/v1/watches/{id}`