API docs by Redocly

Mangrove Server API (0.2.0)

Download OpenAPI specification:

Open Reviews Association: hello@open-reviews.net License: Apache-2.0

Submit and retrieve reviews, as well as aggregate statistics about reviews.

Documentation & Resources

Common

index

Responses

Review

Retrieve aggregates for multiple subjects or issuers.

Request Body schema: application/json
required
pems
required
Array of strings or null

List of issuer public keys to get information about.

Query allowing for retrieval of information about multiple subjects or issuers.

subs
required
Array of strings or null <uri> [ items <uri > ]

A map from Review identifiers (urn:maresi:<signature>) to information about the reviews of that review.

List of subject URIs to get information about.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "issuers": {
    },
  • "subjects": {
    }
}

Request reviews within provided coordinates.

query Parameters
xmin
required
number <float>

Minimum longitude

ymin
required
number <float>

Minimum latitude

xmax
required
number <float>

Maximum longitude

ymax
required
number <float>

Maximum latitude

Responses

Response samples

Content type
{
  • "issuers": {
    },
  • "maresi_subjects": {
    },
  • "reviews": [
    ]
}

Request aggregate information about the reviewer.

path Parameters
pem
required
string
Example: -----BEGIN PUBLIC KEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEDo6mN4kY6YFhpvF0u3hfVWD1RnDElPweX3U3KiUAx0dVeFLPAmeKdQY3J5agY3VspnHo1p/wH9hbZ63qPbCr6g==-----END PUBLIC KEY-----

Request aggregate information about the reviewer.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "credibility": 1
}

Request review with the specified signature.

path Parameters
signature
required
string
Example: PDSpnKtHioXykdBCMA15y5cLuYrRbSexscvySt_ryjppDWaW1I1AijjWercZE6K-cbS18bCwSmgIPqRIuL-cow

Signature of the review being requested.

Responses

Response samples

Content type
{
  • "jwt": "string",
  • "kid": "string",
  • "payload": {
    },
  • "signature": "string"
}

Request reviews matching the provided query.

query Parameters
q
string
Example: q=restaurants in zurich

Search for reviews that have this string in sub or opinion field.

signature
string

Review with this signature value.

kid
string
Example: kid=-----BEGIN PUBLIC KEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEDo6mN4kY6YFhpvF0u3hfVWD1RnDElPweX3U3KiUAx0dVeFLPAmeKdQY3J5agY3VspnHo1p/wH9hbZ63qPbCr6g==-----END PUBLIC KEY-----

Reviews by issuer with the following PEM public key.

iat
integer <int64>

Reviews issued at this UNIX time.

gt_iat
integer <int64>

Reviews with UNIX timestamp greater than this.

sub
string <uri>

Reviews of the given subject URI.

rating
integer <int16> [ 0 .. 100 ]

Reviews with the given rating.

opinion
string

Reviews with the given opinion.

limit
integer <int64> >= 1

Maximum number of reviews to return. Default is based on format. Requests exceeding format-specific recommended limits will be rejected: JSON/N-Triples max 3500, CSV/HTML max 7000.

offset
integer <int64> >= 0

Number of reviews to skip before returning results. Used for pagination. Must be non-negative.

opinionated
boolean

Only reviews which either contain or do not contain an opinion.

examples
boolean

Include reviews left for example subjects https://example.com and geo:0,0?q=*u=*.

issuers
boolean

Include aggregate information about review issuers.

maresi_subjects
boolean

Include aggregate information about reviews of returned reviews.

latest_edits_only
boolean

For edited reviews, return only the most recent version (true by default)

Responses

Response samples

Content type
{
  • "issuers": {
    },
  • "maresi_subjects": {
    },
  • "reviews": [
    ]
}

Request aggregate information about the subject.

path Parameters
sub
required
string
Example: https://nytimes.com

Request aggregate information about the subject.

Responses

Response samples

Content type
application/json
{
  • "confirmed_count": 0,
  • "count": 0,
  • "opinion_count": 0,
  • "positive_count": 0,
  • "quality": 0,
  • "sub": "http://example.com"
}

Submit a new review or perform actions on existing reviews

Submit a Mangrove Review as a JWT. The system automatically detects the operation type based on the payload structure.

Resources

Request Format

Standard JWT format: header.payload.signature

Header must include:

  • alg: "ES256" (ECDSA P-256)
  • typ: "JWT"
  • kid: Public key in PEM format

Payload can be one of 6 types (see Payload schema in the API documentation):

  • Review: Review any subject (requires sub (non-maresi), rating)
  • Rating: Rate a review (requires sub (maresi), rating)
  • Comment: Comment on a review (requires sub (maresi), opinion)
  • Edit: Edit your review (requires sub (maresi), action: "edit", same key)
  • Delete: Delete your review (requires sub (maresi), action: "delete", same key)
  • ReportAbuse: Report abuse (requires sub (maresi), action: "report_abuse")

Signature: ECDSA P-256 signature using the private key corresponding to the public key in header.

Key Concepts

  • Maresi URIs (urn:maresi:{signature}): Reference existing reviews for interactions and actions
  • Subject URIs: Regular URIs (https://, geo:, isbn:, lei:) for reviewing actual subjects
  • Timestamps: All iat fields must be Unix timestamp ≥ 2020-01-01 (Mangrove epoch)
  • Authentication: Edit and delete operations require the same public key as the original review
path Parameters
jwt_review
required
string <JWT>
Example: eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii0tLS0tQkVHSU4gUFVCTElDIEtFWS0tLS0tTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFcDc4Zms1eUNqYmlZYXZ5UjZGQ2xxcTlBRkJUaXpBSG1ZdU9rcTR3cy9aYmdleG41SVQ2bi83NGt2YlZ0UGxNc3A5Z2luTysxMVZ4ZUorbVFJQ1pZamc9PS0tLS0tRU5EIFBVQkxJQyBLRVktLS0tLSIsImp3ayI6IntcImNydlwiOlwiUC0yNTZcIixcImV4dFwiOnRydWUsXCJrZXlfb3BzXCI6W1widmVyaWZ5XCJdLFwia3R5XCI6XCJFQ1wiLFwieFwiOlwicDc4Zms1eUNqYmlZYXZ5UjZGQ2xxcTlBRkJUaXpBSG1ZdU9rcTR3c19aWVwiLFwieVwiOlwiNEhzWi1TRS1wXy0tSkwyMWJUNVRMS2ZZSXB6dnRkVmNYaWZwa0NBbVdJNFwifSJ9.eyJpYXQiOjE1ODA5MTAwMjIsInN1YiI6Imh0dHBzOi8vbWFuZ3JvdmUucmV2aWV3cyIsInJhdGluZyI6NzUsIm9waW5pb24iOiJHcmVhdCB3ZWJzaXRlIGZvciByZXZpZXdzLiIsIm1ldGFkYXRhIjp7Im5pY2tuYW1lIjoiam9objEyMyIsImNsaWVudF9pZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6MzAwMCJ9fQ.7xQtIlHuDdCVioyztj8i3zJ8dk3oCSfKr6VCR5RtBn6sBcqvpfyvs13PlKGJoamKzx8xUgQTQJjRPv5s91-VLQ

JWT string in format header.payload.signature. When decoded, the JWT contains: kid (public key in header), payload (Payload schema with review data), and signature (ECDSA signature). Use the JWT Inspector to construct and validate JWTs. For test reviews, use https://example.com or geo:0,0?q=*&u=* in the sub field.

Responses