> ## Documentation Index > Fetch the complete documentation index at: https://docs.peakmetrics.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```jsonc 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`. ```jsonc 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. ## OpenAPI ````yaml /api/api_docs.yaml put /mentions/customEnrichments openapi: 3.1.0 info: title: PeakMetrics API description: > The PeakMetrics API provides programmatic access to narrative intelligence data. Access millions of mentions across news, social media, and online platforms, enriched with custom AI-powered smart categories and over 50 metadata properties. The API enables you to identify, analyze, and act on emerging narratives in real-time. version: 2.0.0 servers: - url: https://api.peakmetrics.com description: Main (production) server security: - BearerAuth: [] tags: - name: Authorization - name: Workspaces - name: Folders - name: Channels - name: Custom Channels - name: Custom Enrichments description: > Custom enrichments let you push external context about mentions into PeakMetrics, attached to individual mentions and used alongside all other mention metadata across the platform. Once written, enrichment values feed into narrative analysis, workspace summaries, and notifications, and are available through the customer API and the MCP server. Your team manages its own custom enrichments through the API: create one with `POST /customEnrichments`, list them with `GET /customEnrichments`, rename one or replace its option list with `PUT /customEnrichments/{enrichmentId}`, retire one with `DELETE /customEnrichments/{enrichmentId}`, and push values for individual mentions with `PUT /mentions/customEnrichments`. paths: /mentions/customEnrichments: put: tags: - Custom Enrichments summary: Add enrichments description: > 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. ```jsonc 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`. ```jsonc 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. requestBody: required: true content: application/json: schema: type: object required: - enrichments properties: enrichments: type: array maxItems: 100 minItems: 1 description: An array of up to 100 enrichment updates. items: type: object required: - mention_id - enrichment_id - value properties: mention_id: type: integer description: > The ID of the mention to enrich. This is the `id` field from `GET /workspaces/{workspaceId}/mentions`. The mention must already exist in PeakMetrics. Both standard and custom channel mentions are supported. example: 7504398580 enrichment_id: type: integer description: > The identifier of the custom enrichment, as returned by `GET /customEnrichments`. The custom enrichment must be accessible to the authenticated team. example: 1681 value: oneOf: - type: string - type: integer - type: array items: type: string minItems: 1 maxItems: 100 description: > The value(s) to write for this enrichment on this mention. This replaces the mention's current value(s) for the enrichment (see Replace semantics above). Any string is accepted; values outside the custom enrichment's current `constraints.enum` are recorded and will appear in future `GET /customEnrichments` responses as new categories (up to 5000 per enrichment). - For `categorical` enrichments, send a single **string**. - For `integer` enrichments, send a JSON **number** (a safe integer). A quoted string such as `"24"` is rejected for that item. - For `multivalue_categorical` enrichments, send a **non-empty array of strings** — it becomes the mention's complete value set for the field (duplicates within the array are de-duplicated, and at most 100 values per item). example: Substantiated examples: single: summary: Push single values to one custom enrichment value: enrichments: - mention_id: 7504398580 enrichment_id: 1681 value: Substantiated - mention_id: 7504391234 enrichment_id: 1681 value: Mixed multivalue: summary: Push an array of values to a multi-value enrichment value: enrichments: - mention_id: 7504398580 enrichment_id: 4821 value: - Pricing - Support - mention_id: 7504391234 enrichment_id: 4821 value: - Reliability responses: '202': description: > At least one enrichment passed validation and has been queued for processing. Invalid items (if any) appear in the `errors` array. content: application/json: schema: type: object properties: summary: type: object properties: queued_count: type: integer description: The number of enrichments successfully queued. example: 12 invalid_count: type: integer description: The number of enrichments that failed validation. example: 1 errors: type: array description: >- Present only when `invalid_count > 0`. Each entry describes a failed enrichment. items: type: object properties: enrichment: type: object description: The original enrichment object from the request. properties: mention_id: type: integer enrichment_id: type: integer value: type: string message: type: string description: Human-readable error message. example: '`mention_id` 456 does not exist' examples: partial_success: summary: Partial success — some items queued, one failed value: summary: queued_count: 12 invalid_count: 1 errors: - enrichment: mention_id: 456 enrichment_id: 1681 value: Mixed message: '`mention_id` 456 does not exist' '400': description: > Zero enrichments could be queued. All items in the request failed validation. Common causes: - `mention_id` does not exist in PeakMetrics - `enrichment_id` does not exist or is not accessible by the authenticated team - `value` is not a valid category for strict enrichments - The enrichment has reached the 5000-category cap content: application/json: schema: type: object properties: summary: type: object properties: queued_count: type: integer example: 0 invalid_count: type: integer example: 2 errors: type: array items: type: object properties: enrichment: type: object properties: mention_id: type: integer enrichment_id: type: integer value: type: string message: type: string examples: all_invalid: summary: All items failed validation value: 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`' '429': description: > The team's rate limit has been exceeded. The response indicates which limit (per-minute or per-day) was hit and when it resets. Only 2xx responses count toward the rate limit. content: application/json: schema: type: object properties: error: type: string example: 'Rate limit exceeded: 50 requests per minute' retryAfter: type: integer description: Seconds until the exceeded limit resets. example: 45 security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````