{ "openapi": "3.1.0", "info": { "title": "Evident Agent API", "version": "0.7.0", "description": "Consumer-authorized feedback with scoped preparation and submission. Automatic self-reported reviews are separated from human-reviewed materials; no independent transaction verification. MCP preparation additionally supports OAuth authorization code with PKCE S256 at https://evidentagents.com/mcp. These OAuth tokens cannot be used on REST endpoints. Public results include source_url for citation and review timestamps." }, "servers": [ { "url": "https://evidentagents.com/api/v2" } ], "components": { "securitySchemes": { "agentToken": { "type": "http", "scheme": "bearer", "description": "User-issued Bearer token: review:prepare (1h), review:submit (1h), or merchant:reply (24h). Tokens are not interchangeable." } }, "schemas": { "OfferingInput": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "product", "service" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "variant": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "kind", "name" ], "additionalProperties": false }, "ExperienceContext": { "type": "object", "properties": { "purpose": { "type": "string", "minLength": 1, "maxLength": 600 }, "expectation": { "type": "string", "minLength": 1, "maxLength": 600 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 600 }, "strengths": { "type": "string", "minLength": 1, "maxLength": 600 }, "limitations": { "type": "string", "minLength": 1, "maxLength": 600 }, "usage_duration": { "type": "string", "enum": [ "one_use", "under_week", "one_to_four_weeks", "one_to_six_months", "over_six_months" ] }, "price": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "CAD", "AUD", "SGD", "HKD", "CNY", "JPY", "INR" ] }, "minimum": { "type": "number", "minimum": 0, "maximum": 1000000000 }, "maximum": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, "required": [ "currency", "minimum", "maximum" ], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "ReviewTarget": { "type": "object", "properties": { "marketplace": { "type": "string", "maxLength": 160 }, "seller_id": { "type": "string", "maxLength": 160 }, "listing_id": { "type": "string", "maxLength": 160 }, "store_url": { "type": "string", "maxLength": 2048 }, "product_url": { "type": "string", "maxLength": 2048 }, "gtin": { "type": "string", "maxLength": 160 }, "variant": { "type": "string", "maxLength": 160 }, "merchant_name": { "type": "string", "maxLength": 160 }, "product_name": { "type": "string", "maxLength": 160 }, "offering_id": { "type": "string", "maxLength": 160 } }, "additionalProperties": false, "description": "Use offering_id alone, or public identifiers. marketplace is the regional domain; seller_id required for marketplace matching. No identity or transaction verification. GTIN check digit is checked but assignment is not independently verified." } } }, "paths": { "/merchants": { "get": { "summary": "Find merchants with published reviews", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "JSON result" }, "429": { "description": "Rate limited" } } } }, "/reputation/query": { "get": { "summary": "Latest 100 published reviews, counts, dimension means and verification limits", "parameters": [ { "name": "merchant_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON result" }, "429": { "description": "Rate limited" } } } }, "/agent/submit": { "post": { "summary": "Submit consumer-confirmed immutable draft; returns pending or published with evidence_basis", "security": [ { "agentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "draft_id": { "type": "string" } }, "required": [ "draft_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful result" }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or ownership denied" }, "429": { "description": "Rate limited" }, "503": { "description": "Intake closed or service unavailable" } } } }, "/agent/reply": { "post": { "summary": "Publish or replace a response for the approved merchant. Token scope: merchant:reply.", "security": [ { "agentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "review_id": { "type": "string" }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "review_id", "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful result" }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or ownership denied" }, "429": { "description": "Rate limited" }, "503": { "description": "Intake closed or service unavailable" } } } }, "/agent/evidence": { "post": { "summary": "Upload private evidence under review:prepare; raw PDF/PNG/JPEG, max 5 MiB", "security": [ { "agentToken": [] } ], "responses": { "200": { "description": "Success" }, "201": { "description": "Created" }, "403": { "description": "Expired, revoked or wrong scope" }, "409": { "description": "Duplicate/conflict" } }, "requestBody": { "required": true, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } } } }, "/agent/prepare": { "post": { "summary": "Prepare one immutable review proposal; requires consumer confirmation on website", "security": [ { "agentToken": [] } ], "responses": { "200": { "description": "Success" }, "201": { "description": "Created" }, "403": { "description": "Expired, revoked or wrong scope" }, "409": { "description": "Duplicate/conflict" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "evidence_id": { "type": "string" }, "merchant_name": { "type": "string" }, "merchant_website": { "type": "string" }, "feedback": { "type": "string" }, "ratings": { "type": "object", "properties": { "quality": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "service": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "value": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 } }, "required": [], "additionalProperties": false }, "incentivized": { "type": "boolean" }, "offering": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "product", "service" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "variant": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "kind", "name" ], "additionalProperties": false }, "context": { "type": "object", "properties": { "purpose": { "type": "string", "minLength": 1, "maxLength": 600 }, "expectation": { "type": "string", "minLength": 1, "maxLength": 600 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 600 }, "strengths": { "type": "string", "minLength": 1, "maxLength": 600 }, "limitations": { "type": "string", "minLength": 1, "maxLength": 600 }, "usage_duration": { "type": "string", "enum": [ "one_use", "under_week", "one_to_four_weeks", "one_to_six_months", "over_six_months" ] }, "price": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "CAD", "AUD", "SGD", "HKD", "CNY", "JPY", "INR" ] }, "minimum": { "type": "number", "minimum": 0, "maximum": 1000000000 }, "maximum": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, "required": [ "currency", "minimum", "maximum" ], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "target": { "$ref": "#/components/schemas/ReviewTarget" } }, "required": [ "evidence_id", "feedback", "incentivized" ], "additionalProperties": false, "description": "Supply target.offering_id alone to reuse an existing public merchant/product; otherwise provide merchant_name and merchant_website or sufficient external target identifiers. Receipt and explicit incentive disclosure remain required. Missing ratings stay null." } } } } } }, "/agent/preparation": { "get": { "summary": "Read only the preparation token’s draft ID and status", "security": [ { "agentToken": [] } ], "responses": { "200": { "description": "Success" }, "201": { "description": "Created" }, "403": { "description": "Expired, revoked or wrong scope" }, "409": { "description": "Duplicate/conflict" } } } }, "/offerings": { "get": { "summary": "Find published products/services; identities are consumer-supplied", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 160 } }, { "name": "merchant_id", "in": "query", "schema": { "type": "string", "maxLength": 100 } }, { "name": "after", "in": "query", "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "offerings array (up to 50), next_cursor or null; each profile contains source_url, identity_basis and review_count" }, "429": { "description": "Rate limited" } } } }, "/offerings/{id}": { "get": { "summary": "One offering with latest 100 reviews, separate evidence scores and cited verbatim experience_brief", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Offering reputation. Excerpts carry source_url, evidence_basis, disclosure and dates. Missing context is never inferred." }, "404": { "description": "No published profile; includes fully withdrawn profiles" }, "429": { "description": "Rate limited" } } } }, "/targets/resolve": { "post": { "summary": "Read-only resolution to stable seller/product/offering IDs; no records created", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewTarget" } } } }, "responses": { "200": { "description": "resolved, new_target, ambiguous or needs_more_information; always consumer-confirm target" }, "404": { "description": "Public offering not found" }, "422": { "description": "Invalid input" } } } }, "/products/{id}": { "get": { "summary": "Published seller offerings associated with a consumer-supplied product identity", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Up to 100 seller-specific offerings; ratings not merged" }, "404": { "description": "No published experiences" } } } }, "/submission-requirements": { "get": { "summary": "Current contribution requirements, permissions and shortest authorized flow", "responses": { "200": { "description": "Public requirements; no credentials needed" } } } } }, "externalDocs": { "description": "MCP OAuth and public citation guide", "url": "https://evidentagents.com/connect" } }