Hide, unhide, or replace metadata

PATCH

/v1/reviews/{id}

curl --request PATCH \
  --url https://api.proofql.dev/v1/reviews/2f1c9e5a-3b7d-4c1e-9f0a-6d2b8e4a1c3f \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "hidden": true }'

• Production.
• Local `wrangler dev` (see infra/environments.md).

hidden: true removes the review from every query result (sets hidden_at); hidden: false restores it. metadata replaces the whole map. At least one of the two must be present. A body that already describes the row changes nothing (no updated_at churn). Any change purges the project’s query cache. Body limit 64 KiB (413 payload_too_large).

Authorizations

• secretKey

Parameters

Path Parameters

id

required

string format: uuid

The review’s id. A value that is not a UUID is a 404.

Example

2f1c9e5a-3b7d-4c1e-9f0a-6d2b8e4a1c3f

Request Body^required

Media typeapplication/json

At least one of hidden, metadata.

object

>= 1 properties

hidden

boolean

metadata

Flat string-to-string map the customer can filter on at query time. At most 32 entries; keys 1–64 characters, values up to 512. Nested objects, arrays, numbers, and booleans are rejected, not coerced.

object

<= 32 properties

key

additional properties

string

<= 512 characters

Examples

{
  "hidden": true
}

{
  "metadata": {
    "location": "north",
    "campaign": "spring"
  }
}

Responses

200

The review after the change.

Media typeapplication/json

A stored review, as the management routes return it.

object

id

required

string format: uuid

external_id

required

string

source

required

Where the review came from. custom is the escape hatch for anything not listed.

string

Allowed values: google yelp facebook trustpilot custom

rating

required

integer | null

>= 1 <= 5

text

required

string

author_name

required

string | null

author_avatar_url

required

string | null

occurred_at

required

string | null format: date-time

url

required

string | null

language

required

string | null

metadata

required

Flat string-to-string map the customer can filter on at query time. At most 32 entries; keys 1–64 characters, values up to 512. Nested objects, arrays, numbers, and booleans are rejected, not coerced.

object

<= 32 properties

key

additional properties

string

<= 512 characters

sentiment

required

One of:

string

string

Allowed values: positive neutral negative

null

null

sentiment_source

required

One of:

string

rating when derived from the star rating (5–4 positive, 3 neutral, 2–1 negative), model when classified for an unrated review.

string

Allowed values: rating model

null

null

hidden

required

Hidden reviews never appear in query results.

boolean

status

required

indexing until the pipeline has embedded the review (seconds), then indexed and queryable.

string

Allowed values: indexing indexed

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "source": "google",
  "sentiment": "positive",
  "sentiment_source": "rating",
  "status": "indexing"
}

Headers

x-request-id

required

string

>= 1 characters <= 128 characters

This request’s id, on every response. Reuses the caller’s x-request-id when sent (up to 128 chars), else Cloudflare’s ray id, else a fresh UUID. Also inside every error envelope.

RateLimit-Policy

required

string

/^[0-9]+;w=[0-9]+$/

The key’s rate-limit policy as <limit>;w=<window seconds> (IETF draft ratelimit headers), e.g. 300;w=60 for a secret key, 120;w=60 for a publishable key. Present once the key is known.

RateLimit-Limit

required

integer

>= 1

The request limit per window for this key’s kind.

401

unauthorized: no Authorization header (and no ?key= where that is allowed), a header that is not Bearer <key>, a key that does not look like pq_(sk|pk)_(live|test)_…, a secret key in the URL, a ?key= on POST /v1/query, or an unknown or revoked key. Rate-limit headers are absent (the key was not resolved).

Media typeapplication/json

object

error

required

object

code

required

Stable error codes. Status by code: unauthorized 401, forbidden 403, not_found 404, payload_too_large 413, unsupported_media_type 415, validation_failed 422, review_limit_reached 422, rate_limited 429, query_quota_exceeded 429, internal 500, embedding_unavailable 503, service_unavailable 503.

string

Allowed values: unauthorized forbidden validation_failed review_limit_reached not_found payload_too_large unsupported_media_type rate_limited embedding_unavailable query_quota_exceeded service_unavailable internal

message

required

For humans; may change between releases. Switch on code.

string

doc_url

required

https://docs.proofql.dev/errors#<code>.

string format: uri

request_id

required

Same value as the x-request-id header.

string

details

Present for validation_failed only.

Array<object>

object

path

required

Dotted path to the offending field ("0.rating", "filters.since"); "" or "(body)" for the whole body.

string

message

required

string

error

required

object

code

Allowed value: unauthorized

Examples

Examplemissing

{
  "error": {
    "code": "unauthorized",
    "message": "Missing Authorization header. Send `Authorization: Bearer <api key>`.",
    "doc_url": "https://docs.proofql.dev/errors#unauthorized",
    "request_id": "1b7c3d9e-2f4a-4b6c-8d0e-1f2a3b4c5d6e"
  }
}

Headers

x-request-id

required

string

>= 1 characters <= 128 characters

This request’s id, on every response. Reuses the caller’s x-request-id when sent (up to 128 chars), else Cloudflare’s ray id, else a fresh UUID. Also inside every error envelope.

403

forbidden: a publishable key (pq_pk_…) on a route that requires a secret key. Decided before the key is looked up, so rate-limit headers are absent.

Media typeapplication/json

object

error

required

object

code

required

Stable error codes. Status by code: unauthorized 401, forbidden 403, not_found 404, payload_too_large 413, unsupported_media_type 415, validation_failed 422, review_limit_reached 422, rate_limited 429, query_quota_exceeded 429, internal 500, embedding_unavailable 503, service_unavailable 503.

string

Allowed values: unauthorized forbidden validation_failed review_limit_reached not_found payload_too_large unsupported_media_type rate_limited embedding_unavailable query_quota_exceeded service_unavailable internal

message

required

For humans; may change between releases. Switch on code.

string

doc_url

required

https://docs.proofql.dev/errors#<code>.

string format: uri

request_id

required

Same value as the x-request-id header.

string

details

Present for validation_failed only.

Array<object>

object

path

required

Dotted path to the offending field ("0.rating", "filters.since"); "" or "(body)" for the whole body.

string

message

required

string

error

required

object

code

Allowed value: forbidden

Example

{
  "error": {
    "code": "forbidden"
  }
}

Headers

x-request-id

required

string

>= 1 characters <= 128 characters

This request’s id, on every response. Reuses the caller’s x-request-id when sent (up to 128 chars), else Cloudflare’s ray id, else a fresh UUID. Also inside every error envelope.

404

not_found: no review with this id in the key’s project and environment (another project’s or environment’s review looks the same as a nonexistent one), or an id that is not a UUID.

Media typeapplication/json

object

error

required

object

code

required

Stable error codes. Status by code: unauthorized 401, forbidden 403, not_found 404, payload_too_large 413, unsupported_media_type 415, validation_failed 422, review_limit_reached 422, rate_limited 429, query_quota_exceeded 429, internal 500, embedding_unavailable 503, service_unavailable 503.

string

Allowed values: unauthorized forbidden validation_failed review_limit_reached not_found payload_too_large unsupported_media_type rate_limited embedding_unavailable query_quota_exceeded service_unavailable internal

message

required

For humans; may change between releases. Switch on code.

string

doc_url

required

https://docs.proofql.dev/errors#<code>.

string format: uri

request_id

required

Same value as the x-request-id header.

string

details

Present for validation_failed only.

Array<object>

object

path

required

Dotted path to the offending field ("0.rating", "filters.since"); "" or "(body)" for the whole body.

string

message

required

string

error

required

object

code

Allowed value: not_found

Example

{
  "error": {
    "code": "not_found"
  }
}

Headers

x-request-id

required

string

>= 1 characters <= 128 characters

This request’s id, on every response. Reuses the caller’s x-request-id when sent (up to 128 chars), else Cloudflare’s ray id, else a fresh UUID. Also inside every error envelope.

RateLimit-Policy

required

string

/^[0-9]+;w=[0-9]+$/

The key’s rate-limit policy as <limit>;w=<window seconds> (IETF draft ratelimit headers), e.g. 300;w=60 for a secret key, 120;w=60 for a publishable key. Present once the key is known.

RateLimit-Limit

required

integer

>= 1

The request limit per window for this key’s kind.

413

payload_too_large: the body exceeds the route’s limit (1 MiB for POST /v1/reviews, 64 KiB for PATCH, 16 KiB for POST /v1/query). Checked before authentication, so rate-limit headers are absent.

Media typeapplication/json

object

error

required

object

code

required

Stable error codes. Status by code: unauthorized 401, forbidden 403, not_found 404, payload_too_large 413, unsupported_media_type 415, validation_failed 422, review_limit_reached 422, rate_limited 429, query_quota_exceeded 429, internal 500, embedding_unavailable 503, service_unavailable 503.

string

Allowed values: unauthorized forbidden validation_failed review_limit_reached not_found payload_too_large unsupported_media_type rate_limited embedding_unavailable query_quota_exceeded service_unavailable internal

message

required

For humans; may change between releases. Switch on code.

string

doc_url

required

https://docs.proofql.dev/errors#<code>.

string format: uri

request_id

required

Same value as the x-request-id header.

string

details

Present for validation_failed only.

Array<object>

object

path

required

Dotted path to the offending field ("0.rating", "filters.since"); "" or "(body)" for the whole body.

string

message

required

string

error

required

object

code

Allowed value: payload_too_large

Example

{
  "error": {
    "code": "payload_too_large"
  }
}

Headers

x-request-id

required

string

>= 1 characters <= 128 characters

This request’s id, on every response. Reuses the caller’s x-request-id when sent (up to 128 chars), else Cloudflare’s ray id, else a fresh UUID. Also inside every error envelope.

415

unsupported_media_type: the request has a body whose Content-Type is not application/json (or has none). Refused before the body is read and before authentication, so rate-limit headers are absent. A request with no body at all (an empty POST /v1/query asking for the newest reviews) needs no Content-Type.

Media typeapplication/json

object

error

required

object

code

required

Stable error codes. Status by code: unauthorized 401, forbidden 403, not_found 404, payload_too_large 413, unsupported_media_type 415, validation_failed 422, review_limit_reached 422, rate_limited 429, query_quota_exceeded 429, internal 500, embedding_unavailable 503, service_unavailable 503.

string

Allowed values: unauthorized forbidden validation_failed review_limit_reached not_found payload_too_large unsupported_media_type rate_limited embedding_unavailable query_quota_exceeded service_unavailable internal

message

required

For humans; may change between releases. Switch on code.

string

doc_url

required

https://docs.proofql.dev/errors#<code>.

string format: uri

request_id

required

Same value as the x-request-id header.

string

details

Present for validation_failed only.

Array<object>

object

path

required

Dotted path to the offending field ("0.rating", "filters.since"); "" or "(body)" for the whole body.

string

message

required

string

error

required

object

code

Allowed value: unsupported_media_type

Example

{
  "error": {
    "code": "unsupported_media_type",
    "message": "Request bodies must be JSON: send `Content-Type: application/json`.",
    "doc_url": "https://docs.proofql.dev/errors#unsupported_media_type",
    "request_id": "1b7c3d9e-2f4a-4b6c-8d0e-1f2a3b4c5d6e"
  }
}

Headers

x-request-id

required

string

>= 1 characters <= 128 characters

This request’s id, on every response. Reuses the caller’s x-request-id when sent (up to 128 chars), else Cloudflare’s ray id, else a fresh UUID. Also inside every error envelope.

422

validation_failed: the body or query string is not valid JSON, does not match the schema, or carries an unknown field. details lists every issue with a dotted path ("0.rating", "filters.limt"; "" or "(body)" for the body as a whole).

Media typeapplication/json

object

error

required

object

code

required

Stable error codes. Status by code: unauthorized 401, forbidden 403, not_found 404, payload_too_large 413, unsupported_media_type 415, validation_failed 422, review_limit_reached 422, rate_limited 429, query_quota_exceeded 429, internal 500, embedding_unavailable 503, service_unavailable 503.

string

Allowed values: unauthorized forbidden validation_failed review_limit_reached not_found payload_too_large unsupported_media_type rate_limited embedding_unavailable query_quota_exceeded service_unavailable internal

message

required

For humans; may change between releases. Switch on code.

string

doc_url

required

https://docs.proofql.dev/errors#<code>.

string format: uri

request_id

required

Same value as the x-request-id header.

string

details

Present for validation_failed only.

Array<object>

object

path

required

Dotted path to the offending field ("0.rating", "filters.since"); "" or "(body)" for the whole body.

string

message

required

string

error

required

object

code

Allowed value: validation_failed

details

required

array

Examples

ExampleunknownField

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid request: limt is not a recognized field.",
    "doc_url": "https://docs.proofql.dev/errors#validation_failed",
    "request_id": "1b7c3d9e-2f4a-4b6c-8d0e-1f2a3b4c5d6e",
    "details": [
      {
        "path": "limt",
        "message": "is not a recognized field"
      }
    ]
  }
}

Headers

x-request-id

required

string

>= 1 characters <= 128 characters

This request’s id, on every response. Reuses the caller’s x-request-id when sent (up to 128 chars), else Cloudflare’s ray id, else a fresh UUID. Also inside every error envelope.

RateLimit-Policy

required

string

/^[0-9]+;w=[0-9]+$/

The key’s rate-limit policy as <limit>;w=<window seconds> (IETF draft ratelimit headers), e.g. 300;w=60 for a secret key, 120;w=60 for a publishable key. Present once the key is known.

RateLimit-Limit

required

integer

>= 1

The request limit per window for this key’s kind.

429

rate_limited: over this key’s per-minute limit. Wait Retry-After seconds.

Media typeapplication/json

object

error

required

object

code

required

Stable error codes. Status by code: unauthorized 401, forbidden 403, not_found 404, payload_too_large 413, unsupported_media_type 415, validation_failed 422, review_limit_reached 422, rate_limited 429, query_quota_exceeded 429, internal 500, embedding_unavailable 503, service_unavailable 503.

string

Allowed values: unauthorized forbidden validation_failed review_limit_reached not_found payload_too_large unsupported_media_type rate_limited embedding_unavailable query_quota_exceeded service_unavailable internal

message

required

For humans; may change between releases. Switch on code.

string

doc_url

required

https://docs.proofql.dev/errors#<code>.

string format: uri

request_id

required

Same value as the x-request-id header.

string

details

Present for validation_failed only.

Array<object>

object

path

required

Dotted path to the offending field ("0.rating", "filters.since"); "" or "(body)" for the whole body.

string

message

required

string

error

required

object

code

Allowed value: rate_limited

Example

{
  "error": {
    "code": "rate_limited"
  }
}

Headers

x-request-id

required

string

>= 1 characters <= 128 characters

This request’s id, on every response. Reuses the caller’s x-request-id when sent (up to 128 chars), else Cloudflare’s ray id, else a fresh UUID. Also inside every error envelope.

RateLimit-Policy

required

string

/^[0-9]+;w=[0-9]+$/

The key’s rate-limit policy as <limit>;w=<window seconds> (IETF draft ratelimit headers), e.g. 300;w=60 for a secret key, 120;w=60 for a publishable key. Present once the key is known.

RateLimit-Limit

required

integer

>= 1

The request limit per window for this key’s kind.

Retry-After

required

integer

>= 1

Whole seconds to wait. For rate_limited, until the current window ends; for query_quota_exceeded, until the next UTC month begins.

500

internal: something unexpected. The message carries the request id and nothing about the cause.

Media typeapplication/json

object

error

required

object

code

required

Stable error codes. Status by code: unauthorized 401, forbidden 403, not_found 404, payload_too_large 413, unsupported_media_type 415, validation_failed 422, review_limit_reached 422, rate_limited 429, query_quota_exceeded 429, internal 500, embedding_unavailable 503, service_unavailable 503.

string

Allowed values: unauthorized forbidden validation_failed review_limit_reached not_found payload_too_large unsupported_media_type rate_limited embedding_unavailable query_quota_exceeded service_unavailable internal

message

required

For humans; may change between releases. Switch on code.

string

doc_url

required

https://docs.proofql.dev/errors#<code>.

string format: uri

request_id

required

Same value as the x-request-id header.

string

details

Present for validation_failed only.

Array<object>

object

path

required

Dotted path to the offending field ("0.rating", "filters.since"); "" or "(body)" for the whole body.

string

message

required

string

error

required

object

code

Allowed value: internal

Example

{
  "error": {
    "code": "internal"
  }
}

Headers

x-request-id

required

string

>= 1 characters <= 128 characters

This request’s id, on every response. Reuses the caller’s x-request-id when sent (up to 128 chars), else Cloudflare’s ray id, else a fresh UUID. Also inside every error envelope.

503

service_unavailable: the database refused or timed out a connection (a connection storm, a paused compute; Retry-After: 1), or a daily platform allowance is spent (Retry-After is the seconds until it renews, at most a day). Nothing about the request was wrong; retry after Retry-After seconds. The message carries the request id and nothing about the cause.

Media typeapplication/json

object

error

required

object

code

required

Stable error codes. Status by code: unauthorized 401, forbidden 403, not_found 404, payload_too_large 413, unsupported_media_type 415, validation_failed 422, review_limit_reached 422, rate_limited 429, query_quota_exceeded 429, internal 500, embedding_unavailable 503, service_unavailable 503.

string

Allowed values: unauthorized forbidden validation_failed review_limit_reached not_found payload_too_large unsupported_media_type rate_limited embedding_unavailable query_quota_exceeded service_unavailable internal

message

required

For humans; may change between releases. Switch on code.

string

doc_url

required

https://docs.proofql.dev/errors#<code>.

string format: uri

request_id

required

Same value as the x-request-id header.

string

details

Present for validation_failed only.

Array<object>

object

path

required

Dotted path to the offending field ("0.rating", "filters.since"); "" or "(body)" for the whole body.

string

message

required

string

error

required

object

code

Allowed value: service_unavailable

Example

{
  "error": {
    "code": "service_unavailable"
  }
}

Headers

x-request-id

required

string

>= 1 characters <= 128 characters

This request’s id, on every response. Reuses the caller’s x-request-id when sent (up to 128 chars), else Cloudflare’s ray id, else a fresh UUID. Also inside every error envelope.

Retry-After

required

integer

>= 1

Whole seconds to wait. For rate_limited, until the current window ends; for query_quota_exceeded, until the next UTC month begins.