> ## Documentation Index > Fetch the complete documentation index at: https://docs.trophy.so/llms.txt > Use this file to discover all available pages before exploring further. # Create points systems > Create points systems. Optionally include sub-entities (levels, boosts, triggers) in each system payload to create them alongside the system. ## OpenAPI ````yaml https://admin.trophy.so/v1/openapi post /points openapi: 3.1.0 info: title: Trophy version: 1.19.0 servers: - x-fern-server-name: Admin API url: https://admin.trophy.so/v1 description: Admin API security: [] paths: /points: servers: - url: https://admin.trophy.so/v1 description: Admin API parameters: - $ref: '#/components/parameters/TenantId' post: tags: - Admin summary: Create points systems description: >- Create points systems. Optionally include sub-entities (levels, boosts, triggers) in each system payload to create them alongside the system. operationId: admin_points_systems_create requestBody: description: Array of points systems to create. Maximum 100 systems per request. required: true content: application/json: schema: $ref: '#/components/schemas/CreatePointsSystemsRequest' examples: Create a system with levels: value: - name: XP key: xp description: Experience points levels: - name: Bronze key: bronze points: 100 - name: Silver key: silver points: 500 responses: '200': description: Successful operation (no systems created) content: application/json: schema: $ref: '#/components/schemas/CreatePointsSystemsResponse' examples: All requests had errors: value: created: [] issues: - index: 0 severity: error message: name must be a string '201': description: Created (at least one system created) content: application/json: schema: $ref: '#/components/schemas/CreatePointsSystemsResponse' examples: Success with no issues: value: created: - id: 550e8400-e29b-41d4-a716-446655440000 name: XP key: xp description: Experience points status: active badge: null maxPoints: null levels: - id: 550e8400-e29b-41d4-a716-446655440001 name: Bronze key: bronze points: 100 description: '' badge: null issues: [] '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/AdminErrorBody' '422': description: Unprocessible Entity content: application/json: schema: $ref: '#/components/schemas/AdminErrorBody' security: - ApiKeyAuth: [] x-codeSamples: - lang: javascript source: | import { TrophyApiClient } from '@trophyso/node'; const trophy = new TrophyApiClient({ apiKey: 'YOUR_API_KEY' }); const result = await trophy.admin.points.systems.create([ { name: 'XP', key: 'xp', description: 'Experience points', levels: [ { name: 'Bronze', key: 'bronze', points: 100 }, { name: 'Silver', key: 'silver', points: 500 } ] } ]); - lang: python source: | from trophy import TrophyApi client = TrophyApi(api_key='YOUR_API_KEY') result = client.admin.points.systems.create( request=[{ "name": "XP", "key": "xp", "description": "Experience points", "levels": [ {"name": "Bronze", "key": "bronze", "points": 100}, {"name": "Silver", "key": "silver", "points": 500} ] }] ) - lang: go source: > import ( "context" api "github.com/trophyso/trophy-go" trophyclient "github.com/trophyso/trophy-go/client" "github.com/trophyso/trophy-go/option" ) client := trophyclient.NewClient( option.WithApiKey("YOUR_API_KEY"), ) response, err := client.Admin.Points.Systems.Create(context.TODO(), api.CreatePointsSystemsRequest{}) components: parameters: TenantId: name: Tenant-ID in: header description: >- The tenant identifier for multi-tenant organisations. Required when the organisation has multi-tenancy enabled. Pass your own internal customer ID for the tenant. Ignored for single-tenant organisations. required: false schema: type: string example: customer_12345 schemas: CreatePointsSystemsRequest: title: CreatePointsSystemsRequest type: array description: Request body for creating points systems. items: $ref: '#/components/schemas/CreatePointsSystemRequestItem' minItems: 1 maxItems: 100 CreatePointsSystemsResponse: title: CreatePointsSystemsResponse type: object description: Response containing created points systems and any per-item issues. properties: created: type: array items: $ref: '#/components/schemas/CreatedAdminPointsSystem' description: Array of successfully created points systems. issues: type: array items: $ref: '#/components/schemas/AdminIssue' description: Array of issues encountered during creation. required: - created - issues AdminErrorBody: title: AdminErrorBody type: object properties: error: type: string required: - error CreatePointsSystemRequestItem: title: CreatePointsSystemRequestItem type: object description: A points system to create. Optionally include sub-entities. properties: name: type: string description: The points system name. example: XP key: type: string pattern: ^[a-zA-Z\d-_]+$ description: >- The points system key. Only alphanumeric characters, hyphens, and underscores are permitted. example: xp description: type: string description: A short description of the points system. example: Experience points badge: oneOf: - type: object properties: url: type: string description: Badge image URL. required: - url - type: 'null' description: An optional badge for the points system. maxPoints: type: - integer - 'null' minimum: 1 description: Optional maximum points a user can earn. levels: type: array description: Optional array of levels to create alongside the system. items: $ref: '#/components/schemas/CreatePointsLevelRequestItem' boosts: type: array description: Optional array of boosts to create alongside the system. items: $ref: '#/components/schemas/CreatePointsBoostRequestItem' triggers: type: array description: Optional array of triggers to create alongside the system. items: $ref: '#/components/schemas/CreatePointsTriggerRequestItem' required: - name - key CreatedAdminPointsSystem: title: CreatedAdminPointsSystem description: >- A points system returned from the creation endpoint. Extends AdminPointsSystem with optional sub-entity arrays that are present when those sub-entities were included in the creation request. allOf: - $ref: '#/components/schemas/AdminPointsSystem' - type: object properties: levels: type: array items: $ref: '#/components/schemas/AdminPointsLevel' description: >- Levels created alongside the system. Present when levels were provided in the request. boosts: type: array items: $ref: '#/components/schemas/AdminPointsBoost' description: >- Boosts created alongside the system. Present when boosts were provided in the request. triggers: type: array items: $ref: '#/components/schemas/AdminPointsTrigger' description: >- Triggers created alongside the system. Present when triggers were provided in the request. AdminIssue: title: AdminIssue type: object description: An issue encountered while processing an item in an admin API request. properties: id: type: string description: The ID of the resource the issue relates to, when applicable. example: 550e8400-e29b-41d4-a716-446655440000 userId: type: string description: The ID of the user the issue relates to, when applicable. example: user-123 boostId: type: string description: The ID of the points boost the issue relates to, when applicable. example: 550e8400-e29b-41d4-a716-446655440000 index: type: integer description: >- The zero-based index of the item the issue relates to, when no resource ID exists yet. example: 0 severity: type: string enum: - error - warning description: The severity level of the issue. example: warning message: type: string description: A human-readable description of the issue. example: Would exceed maximum freeze limit required: - severity - message CreatePointsLevelRequestItem: title: CreatePointsLevelRequestItem type: object description: A points level to create. properties: name: type: string description: The name of the level. example: Bronze key: type: string description: >- A unique key for the level. Only alphanumeric characters, hyphens, and underscores are permitted. pattern: ^[a-zA-Z\d-_]+$ example: bronze points: type: integer minimum: 0 description: The threshold points value for the level. example: 100 description: type: string description: An optional description of the level. example: Starting level badge: type: object description: An optional badge for the level. properties: url: type: string description: The URL of the badge image. example: https://example.com/bronze.png required: - url required: - name - key - points CreatePointsBoostRequestItem: title: CreatePointsBoostRequestItem type: object description: >- A points boost to create. May optionally target a specific user via `userId` or filter by user attributes via `userAttributes`. These two fields are mutually exclusive. properties: userId: type: - string - 'null' description: >- The ID of the user to create a boost for. Mutually exclusive with `userAttributes` — providing `userAttributes` when `userId` is set will result in an error. Omit for a global boost. example: user-123 name: type: string description: The name of the boost. maxLength: 255 example: Double XP Weekend start: type: string format: date description: The start date of the boost (YYYY-MM-DD). example: '2024-01-01' end: type: - string - 'null' format: date description: >- The end date of the boost (YYYY-MM-DD). If null, the boost has no end date. example: '2024-01-03' multiplier: type: number description: >- The points multiplier. Must be greater than 0, not equal to 1, and less than 100. example: 2 exclusiveMinimum: 0 exclusiveMaximum: 100 rounding: type: string enum: - down - up - nearest default: down description: How to round the boosted points. Defaults to 'down'. example: down userAttributes: type: - array - 'null' description: >- User attribute filters for the boost. Cannot be provided when `userId` is set. items: type: object properties: attributeId: type: string format: uuid description: The UUID of the user attribute. attributeValue: type: string description: The value to match. required: - attributeId - attributeValue example: - attributeId: 550e8400-e29b-41d4-a716-446655440000 attributeValue: premium required: - name - start - multiplier CreatePointsTriggerRequestItem: title: CreatePointsTriggerRequestItem type: object description: A points trigger to create. properties: type: type: string enum: - metric - achievement - streak - time - user_creation description: The type of trigger. example: metric points: type: integer description: >- The number of points to award or deduct when the trigger fires. Cannot be zero. example: 10 status: type: string enum: - active - inactive default: inactive description: The status of the trigger. Defaults to 'inactive'. example: inactive userAttributes: type: - array - 'null' description: Optional user attribute filters for the trigger. items: type: object properties: attributeId: type: string format: uuid description: The UUID of the user attribute. attributeValue: type: string description: The value to match. required: - attributeId - attributeValue metricId: type: string format: uuid description: Required if type is `metric`. The UUID of the metric. metricThreshold: type: integer minimum: 1 description: >- Required if type is `metric`. The metric increment that triggers the points. eventAttributes: type: - array - 'null' description: >- Optional event attribute filters. Only permitted if type is `metric`. items: type: object properties: attributeId: type: string format: uuid description: The UUID of the event attribute. attributeValue: type: string description: The value to match. required: - attributeId - attributeValue achievementId: type: string format: uuid description: Required if type is `achievement`. The UUID of the achievement. streakLength: type: integer minimum: 1 description: >- Required if type is `streak`. The number of streak periods that triggers the points. timeUnit: type: string enum: - hours - days description: Required if type is `time`. The unit for the time interval. timeInterval: type: integer minimum: 1 description: >- Required if type is `time`. The number of time units between recurring awards. blockIfOutOfPoints: type: boolean default: false description: >- Whether to block metric events that would reduce the user's points below zero. Defaults to false. required: - type - points AdminPointsSystem: title: AdminPointsSystem type: object description: A points system returned from the admin points systems endpoints. properties: id: type: string format: uuid description: The UUID of the points system. name: type: string description: The points system name. key: type: string description: The points system key. description: type: string description: The points system description. status: type: string enum: - active - archived description: The points system status. badge: oneOf: - type: object properties: url: type: string required: - url - type: 'null' description: The badge for the points system. maxPoints: type: - integer - 'null' description: The maximum points a user can earn. required: - id - name - key - description - status - badge - maxPoints AdminPointsLevel: title: AdminPointsLevel type: object description: A points level as returned from admin endpoints. properties: id: type: string format: uuid description: The UUID of the level. name: type: string description: The name of the level. key: type: string description: The level key. points: type: integer description: The threshold points value for the level. description: type: string description: The level description. badge: oneOf: - type: object properties: url: type: string description: The URL of the badge image. required: - url - type: 'null' description: The badge for the level, or null if no badge is set. required: - id - name - key - points - description - badge AdminPointsBoost: title: AdminPointsBoost type: object description: A points boost as returned from admin endpoints. properties: id: type: string format: uuid description: The UUID of the boost. name: type: string description: The name of the boost. status: type: string enum: - active - scheduled - finished description: The status of the boost. start: type: string format: date description: The start date (YYYY-MM-DD). end: type: - string - 'null' format: date description: The end date (YYYY-MM-DD) or null if no end date. multiplier: type: number description: The points multiplier. rounding: type: string enum: - down - up - nearest description: How boosted points are rounded. userId: type: - string - 'null' description: >- The ID of the user the boost was created for, or null for global/attribute-filtered boosts. userAttributes: type: array description: >- User attribute filters applied to the boost. Only present for non-user-specific boosts (i.e. when `userId` is null). Empty array if no filters are set. items: type: object properties: attributeId: type: string format: uuid description: The UUID of the user attribute. attributeValue: type: string description: The matched attribute value. required: - attributeId - attributeValue required: - id - name - status - start - end - multiplier - rounding - userId AdminPointsTrigger: title: AdminPointsTrigger type: object description: A points trigger as returned from admin endpoints. properties: id: type: string format: uuid description: The UUID of the trigger. type: type: string enum: - metric - achievement - streak - time - user_creation description: The type of trigger. points: type: integer description: The number of points awarded or deducted when the trigger fires. status: type: string enum: - active - inactive description: The status of the trigger. userAttributes: type: array description: User attribute filters applied to the trigger. items: type: object properties: attributeId: type: string format: uuid attributeValue: type: string required: - attributeId - attributeValue metricId: type: string format: uuid description: The UUID of the metric. Only present for metric triggers. metricThreshold: type: integer description: The metric threshold. Only present for metric triggers. eventAttributes: type: array description: >- Event attribute filters applied to the trigger. Only present for metric triggers. items: type: object properties: attributeId: type: string format: uuid attributeValue: type: string required: - attributeId - attributeValue achievementId: type: string format: uuid description: The UUID of the achievement. Only present for achievement triggers. streakLength: type: integer description: The streak length. Only present for streak triggers. timeUnit: type: string enum: - hours - days description: The time unit. Only present for time triggers. timeInterval: type: integer description: The time interval. Only present for time triggers. blockIfOutOfPoints: type: boolean description: >- Whether metric events that would reduce the user's points below zero are blocked. required: - id - type - points - status - userAttributes - blockIfOutOfPoints securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ````