curl --request PUT \
  --url https://api.peakmetrics.com/mentions/customEnrichments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "enrichments": [
    {
      "mention_id": 7504398580,
      "enrichment_id": 1681,
      "value": "Substantiated"
    },
    {
      "mention_id": 7504391234,
      "enrichment_id": 1681,
      "value": "Mixed"
    }
  ]
}
'

{
  "summary": {
    "queued_count": 12,
    "invalid_count": 1
  },
  "errors": [
    {
      "enrichment": {
        "mention_id": 456,
        "enrichment_id": 1681,
        "value": "Mixed"
      },
      "message": "`mention_id` 456 does not exist"
    }
  ]
}

{
  "summary": {
    "queued_count": 0,
    "invalid_count": 3
  },
  "errors": [
    {
      "enrichment": {
        "mention_id": 123,
        "enrichment_id": 1680,
        "value": "Substantiated"
      },
      "message": "`enrichment_id` 1680 does not exist"
    },
    {
      "enrichment": {
        "mention_id": 456,
        "enrichment_id": 1681,
        "value": "Mixed"
      },
      "message": "`mention_id` 456 does not exist"
    },
    {
      "enrichment": {
        "mention_id": 789,
        "enrichment_id": 1681,
        "value": 60
      },
      "message": "`enrichment_id` 1681 must have a string `value`"
    }
  ]
}

{
  "error": "Rate limit exceeded: 50 requests per minute",
  "retryAfter": 45
}

Custom Enrichments

Add enrichments

Pushes custom enrichment values onto existing mentions. You can enrich both standard mentions and custom channel mentions, including historical mentions already stored in the platform.

The request body wraps up to 100 enrichment updates in an enrichments property. Each update identifies a mention by mention_id (the id field from GET /workspaces/{workspaceId}/mentions).

The response returns 202 if at least one enrichment is valid and queued. It returns 400 if zero enrichments could be queued. Invalid items appear in the errors array with the original enrichment object and an error message.

Updates are applied asynchronously after the request is accepted. Newly pushed values typically appear on the mention within a few minutes across the GET APIs, the MCP server, mention exports, and the workspace UI.

Replace semantics

Writing a value replaces the mention’s current value for that enrichment — the last write wins. Pushing a different value for the same mention_id and enrichment_id overwrites the previous one rather than adding to it, so the mention carries only the most recent value and stale values do not linger as extra filter matches.

PUT … "value": "Substantiated"    // mention's value is now "Substantiated"
PUT … "value": "Mixed"            // mention's value is now "Mixed" (prior value dropped)

Replace is scoped per enrichment, per mention: a write only affects the enrichment_id on the mention_id it names, leaving other enrichments on the mention and the same enrichment on other mentions untouched. Within one request, the same (mention_id, enrichment_id) may be set only once — a second update for that pair is rejected as an invalid item (the rest of the batch still queues).

For a multivalue_categorical enrichment the same rule applies to the whole array: the array you send becomes the mention’s complete value set for the field, and any value not in it is dropped. Removing a value is simply a matter of omitting it from the next PUT.

PUT … "value": ["Pricing", "Support"]   // field is now exactly ["Pricing", "Support"]
PUT … "value": ["Reliability"]          // field is now exactly ["Reliability"]

Rate limits

Two rolling limits apply, scoped to the authenticated team:

50 requests per minute (rolling 60-second window)
50,000 requests per day (resets at midnight UTC)

Only 2xx responses count toward the rate limit.

When either limit is exceeded, the endpoint returns a 429 response indicating which limit was hit and when it resets.

Storage and visibility

Enrichment values are stored on the underlying mention document, not scoped to a workspace. A single value pushed for a mention is visible from every workspace whose query matches that mention, as well as the MCP server, mention exports, and the customEnrichments field returned by the GET APIs.

PUT

mentions

customEnrichments

curl --request PUT \
  --url https://api.peakmetrics.com/mentions/customEnrichments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "enrichments": [
    {
      "mention_id": 7504398580,
      "enrichment_id": 1681,
      "value": "Substantiated"
    },
    {
      "mention_id": 7504391234,
      "enrichment_id": 1681,
      "value": "Mixed"
    }
  ]
}
'

{
  "summary": {
    "queued_count": 12,
    "invalid_count": 1
  },
  "errors": [
    {
      "enrichment": {
        "mention_id": 456,
        "enrichment_id": 1681,
        "value": "Mixed"
      },
      "message": "`mention_id` 456 does not exist"
    }
  ]
}

{
  "summary": {
    "queued_count": 0,
    "invalid_count": 3
  },
  "errors": [
    {
      "enrichment": {
        "mention_id": 123,
        "enrichment_id": 1680,
        "value": "Substantiated"
      },
      "message": "`enrichment_id` 1680 does not exist"
    },
    {
      "enrichment": {
        "mention_id": 456,
        "enrichment_id": 1681,
        "value": "Mixed"
      },
      "message": "`mention_id` 456 does not exist"
    },
    {
      "enrichment": {
        "mention_id": 789,
        "enrichment_id": 1681,
        "value": 60
      },
      "message": "`enrichment_id` 1681 must have a string `value`"
    }
  ]
}

{
  "error": "Rate limit exceeded: 50 requests per minute",
  "retryAfter": 45
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

enrichments

object[]

required

An array of up to 100 enrichment updates.

Required array length: 1 - 100 elements

Show child attributes

Response

At least one enrichment passed validation and has been queued for processing. Invalid items (if any) appear in the errors array.

summary

object

Show child attributes

errors

object[]

Present only when invalid_count > 0. Each entry describes a failed enrichment.

Show child attributes

⌘I