> ## 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. # Create a custom enrichment > Creates a custom enrichment for your team and returns its full definition — the same shape `GET /customEnrichments` lists — including the `enrichment_id` to use when pushing values with `PUT /mentions/customEnrichments`. `constraints.enum` is **required**: - For `categorical` and `multivalue_categorical` enrichments it may be `[]` (create the enrichment with no options yet) or an array of initial option strings. Options are also registered automatically when `PUT /mentions/customEnrichments` writes a value that is not yet listed, up to 5000 per enrichment. - For `integer` enrichments it must be exactly `[]` — integer enrichments never have options. ## OpenAPI ````yaml /api/api_docs.yaml post /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: /customEnrichments: post: tags: - Custom Enrichments summary: Create a custom enrichment description: > Creates a custom enrichment for your team and returns its full definition — the same shape `GET /customEnrichments` lists — including the `enrichment_id` to use when pushing values with `PUT /mentions/customEnrichments`. `constraints.enum` is **required**: - For `categorical` and `multivalue_categorical` enrichments it may be `[]` (create the enrichment with no options yet) or an array of initial option strings. Options are also registered automatically when `PUT /mentions/customEnrichments` writes a value that is not yet listed, up to 5000 per enrichment. - For `integer` enrichments it must be exactly `[]` — integer enrichments never have options. requestBody: required: true content: application/json: schema: type: object required: - name - type - constraints properties: name: type: string maxLength: 255 description: > The display name. Must be unique among your team's custom enrichments (compared case-insensitively). example: Disinformation Analysis type: type: string enum: - categorical - multivalue_categorical - integer description: > The data type of the enrichment's `value`. Cannot be changed after creation. - `categorical` — one string value per mention. - `multivalue_categorical` — several string values per mention on one field; `PUT /mentions/customEnrichments` takes an array. - `integer` — one integer value per mention. example: categorical constraints: type: object required: - enum properties: enum: type: array items: type: string description: > The initial option list. `[]` or an array of distinct, non-empty strings (at most 5000) for `categorical` and `multivalue_categorical`; exactly `[]` for `integer`. example: - Uncorroborated - Substantiated - Mixed examples: categorical: summary: A categorical enrichment with initial options value: name: Disinformation Analysis type: categorical constraints: enum: - Uncorroborated - Substantiated - Mixed categorical_empty: summary: A categorical enrichment whose options will self-register value: name: Topic type: categorical constraints: enum: [] multivalue: summary: A multi-value categorical enrichment value: name: Themes type: multivalue_categorical constraints: enum: - Pricing - Support - Reliability integer: summary: An integer enrichment value: name: Relevance Score type: integer constraints: enum: [] responses: '201': description: >- The created custom enrichment, in the same shape as `GET /customEnrichments`. content: application/json: schema: $ref: '#/components/schemas/CustomEnrichment' examples: created: summary: The created enrichment value: enrichment_id: 1681 name: Disinformation Analysis type: categorical constraints: enum: - Uncorroborated - Substantiated - Mixed '400': description: > The request is invalid. Causes include a missing or empty `name`, an unknown `type`, a missing `constraints.enum`, a non-empty `constraints.enum` on an `integer` enrichment, blank or duplicate option values, or more than 5000 options. content: application/json: schema: $ref: '#/components/schemas/CustomEnrichmentError' examples: integer_with_options: summary: Options on an integer enrichment value: error: >- 'constraints.enum' must be [] for an integer enrichment — integer enrichments never have options '401': description: Missing or invalid access token. '409': description: Your team already has a custom enrichment with this name. content: application/json: schema: $ref: '#/components/schemas/CustomEnrichmentError' examples: name_taken: summary: The name is already in use value: error: >- A custom enrichment named 'Disinformation Analysis' already exists for this team security: - BearerAuth: [] components: schemas: CustomEnrichment: type: object description: A custom enrichment definition, as listed by `GET /customEnrichments`. properties: enrichment_id: type: integer description: >- The unique identifier. Use it as `enrichment_id` when pushing values with `PUT /mentions/customEnrichments`. example: 1681 name: type: string description: The display name. example: Disinformation Analysis type: type: string enum: - categorical - multivalue_categorical - integer description: The data type of the enrichment's `value`. Fixed at creation. example: categorical constraints: type: object properties: enum: type: array items: type: string description: > For `categorical` and `multivalue_categorical` enrichments, the currently listed options. For `integer` enrichments, always `[]`. example: - Uncorroborated - Substantiated - Mixed CustomEnrichmentError: type: object properties: error: type: string description: A human-readable description of what was rejected. example: '''constraints.enum'' contains a duplicate value: ''Mixed''' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````