> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a new action
> Create a new action.
## OpenAPI
````yaml /openapi/admin.json post /actions
openapi: 3.1.0
info:
title: Nudj Admin API
version: 1.0.0
servers:
- url: https://{subdomain}.nudj.cx/api/v2/admin
description: Organization API Server
variables:
subdomain:
description: Your organization's subdomain (required)
default: your-org
security:
- ApiToken: []
paths:
/actions:
post:
tags:
- Action
summary: Create a new action
description: Create a new action.
operationId: createAction
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
communityId:
type: string
pattern: ^[0-9a-fA-F]{24}$
description: The community that the action belongs to
allocationId:
type:
- string
- 'null'
pattern: ^[0-9a-fA-F]{24}$
description: >-
The allocation this action is assigned to. When null,
indicates this is a template action.
allocatedTo:
type: string
enum:
- achievement
- action
- community
- challenge
- leaderboard
- post
- reward
- reward-asset
- reward-entry
description: >-
The entity type this action is allocated to. This can be set
to a 'challenge' only at the moment.
category:
type: string
enum:
- nudj
- discord
- facebook
- imageAnalysis
- instagram
- interaction
- linkedin
- question
- platform
- spotify
- tiktok
- twitter
- youtube
description: The category of this action
key:
type: string
enum:
- facebook-comment
- facebook-follow
- facebook-like
- image-analysis-object-detection
- image-analysis-receipt-detection
- instagram-follow
- instagram-like
- instagram-comment
- instagram-share
- instagram-post
- interaction-engage-with-content
- interaction-external-link
- interaction-image-upload
- interaction-spot-object
- platform-comment-on-post
- platform-complete-achievement
- platform-generative-action
- platform-like-post
- platform-play-game
- platform-validate-event
- question-multiple-choice
- question-open-ended
- question-rate-your-experience
- question-secret-access-code
- question-select-date
- question-select-from-images
- question-select-value-in-range
- question-select-from-list
- question-closed-ended
- question-vote
- spotify-follow
- spotify-listen
- spotify-save
- tiktok-follow
- tiktok-watch
- tiktok-post
- youtube-like
- youtube-comment
- youtube-subscribe
description: The specific type of this action
attributes:
$ref: '#/components/schemas/ActionAttributes'
progressPeriod:
type: string
enum:
- daily
- weekly
- monthly
- yearly
- open
description: The progress period of the action
maxCompletionsPerPeriod:
anyOf:
- type: number
minimum: 0
- type: string
const: Infinity
description: The maximum number of completions per period for the action
isGlobalTemplate:
type:
- boolean
- 'null'
description: >-
Indicates if this action is available as a template globally
across all organisations
availableAsTemplateForOrganisations:
type:
- array
- 'null'
items:
type: string
pattern: ^[0-9a-fA-F]{24}$
description: >-
List of organisation IDs that can use this action as a
template
videoMetadata:
oneOf:
- $ref: '#/components/schemas/VideoMetadata'
- type: 'null'
description: Video metadata for actions with video content
xpConfig:
allOf:
- $ref: '#/components/schemas/UserXPBreakdown'
- description: >-
XP breakdown for this action. Can be customized per
action or set to match platform config defaults.
description: >-
XP breakdown for this action. Can be customized per action
or set to match platform config defaults.
details:
$ref: '#/components/schemas/DetailsCreateInput'
config:
$ref: '#/components/schemas/ActionConfigInput'
required:
- communityId
- allocationId
- allocatedTo
- category
- key
- attributes
- details
description: The input required to create an action
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Action'
'400':
description: Invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/error.BAD_REQUEST'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
components:
schemas:
ActionAttributes:
oneOf:
- $ref: '#/components/schemas/MultipleChoiceActionAttributes'
- $ref: '#/components/schemas/OpenEndedActionAttributes'
- $ref: '#/components/schemas/RateYourExperienceActionAttributes'
- $ref: '#/components/schemas/SecretAccessCodeActionAttributes'
- $ref: '#/components/schemas/SelectFromImagesActionAttributes'
- $ref: '#/components/schemas/SelectFromListActionAttributes'
- $ref: '#/components/schemas/SingleFixedAnswerActionAttributes'
- $ref: '#/components/schemas/VoteActionAttributes'
- $ref: '#/components/schemas/SelectADateActionAttributes'
- $ref: '#/components/schemas/SelectValueInRangeActionAttributes'
- $ref: '#/components/schemas/ExternalLinkActionAttributes'
- $ref: '#/components/schemas/EngageWithContentActionAttributes'
- type: object
properties:
key:
type: string
const: interaction-image-upload
description:
type: string
disclaimers:
type: array
items:
$ref: '#/components/schemas/ImageUploadDisclaimer'
allowBypassUpload:
type:
- boolean
- 'null'
aiValidation:
type: boolean
aiValidationPrompt:
type:
- string
- 'null'
required:
- key
- description
- disclaimers
- aiValidation
- allOf:
- $ref: '#/components/schemas/SpotObjectActionAttributes'
type: object
properties:
timestamps:
type: array
items:
type: number
minimum: 0
minItems: 1
description: >-
Array of timestamps in milliseconds where objects appear in the
video
required:
- timestamps
description: >-
An interaction action where users must spot objects at specific
timestamps with configurable tolerance ranges. The timestamps array
contains the correct moments (in milliseconds) where objects appear,
and toleranceMs defines the acceptable range before and after each
timestamp.
- $ref: '#/components/schemas/ObjectDetectionActionAttributes'
- $ref: '#/components/schemas/ReceiptDetectionActionAttributes'
- $ref: '#/components/schemas/FacebookCommentActionAttributes'
- $ref: '#/components/schemas/FacebookFollowActionAttributes'
- $ref: '#/components/schemas/FacebookLikeActionAttributes'
- $ref: '#/components/schemas/InstagramFollowActionAttributes'
- $ref: '#/components/schemas/InstagramLikeActionAttributes'
- $ref: '#/components/schemas/InstagramCommentActionAttributes'
- $ref: '#/components/schemas/InstagramShareActionAttributes'
- $ref: '#/components/schemas/InstagramPostActionAttributes'
- $ref: '#/components/schemas/CommentOnPostActionAttributes'
- $ref: '#/components/schemas/CompleteAchievementActionAttributes'
- $ref: '#/components/schemas/GenerativeActionActionAttributes'
- $ref: '#/components/schemas/LikePostActionAttributes'
- $ref: '#/components/schemas/PlayGameActionAttributes'
- $ref: '#/components/schemas/ValidateEventActionAttributes'
- $ref: '#/components/schemas/SpotifyFollowActionAttributes'
- $ref: '#/components/schemas/SpotifyListenActionAttributes'
- $ref: '#/components/schemas/SpotifySaveActionAttributes'
- $ref: '#/components/schemas/YoutubeCommentActionAttributes'
- $ref: '#/components/schemas/YoutubeSubscribeActionAttributes'
- $ref: '#/components/schemas/YoutubeLikeActionAttributes'
- $ref: '#/components/schemas/TikTokFollowActionAttributes'
- $ref: '#/components/schemas/TikTokPostActionAttributes'
- $ref: '#/components/schemas/TikTokWatchActionAttributes'
description: The attributes of an action
title: Action Attributes
VideoMetadata:
type: object
properties:
startsAtMs:
type: number
minimum: 0
description: >-
The start time of the action in milliseconds from the start of the
video
shouldPause:
type: boolean
description: Whether the video should pause at the validation point
validatesAtMs:
type:
- number
- 'null'
minimum: 0
description: >-
The validation time in milliseconds, null if the user will validate
themselves
endsAtMs:
type: number
minimum: 0
description: >-
The end time of the action in milliseconds from the start of the
video
required:
- startsAtMs
- shouldPause
- validatesAtMs
- endsAtMs
description: Video metadata for actions with video content
title: Video Metadata
UserXPBreakdown:
type: object
properties:
total:
type: number
minimum: 0
knowledge:
type: number
minimum: 0
creativity:
type: number
minimum: 0
loyalty:
type: number
minimum: 0
influence:
type: number
minimum: 0
participation:
type: number
minimum: 0
contribution:
type: number
minimum: 0
required:
- total
- knowledge
- creativity
- loyalty
- influence
- participation
- contribution
description: User XP Breakdown
title: User XP Breakdown
DetailsCreateInput:
type: object
properties:
title:
type: string
description: The title of the entity
description:
type:
- string
- 'null'
description: The description of the entity
light:
type: object
properties:
primaryImageUrl:
type:
- string
- 'null'
description: The url of the primary image for this theme mode
secondaryImageUrl:
type:
- string
- 'null'
description: The url of the secondary image for this theme mode
description: Light theme images
dark:
type: object
properties:
primaryImageUrl:
type:
- string
- 'null'
description: The url of the primary image for this theme mode
secondaryImageUrl:
type:
- string
- 'null'
description: The url of the secondary image for this theme mode
description: Dark theme images
required:
- title
description: Input for creating entity details with required title
title: Details Create Input
ActionConfigInput:
type: object
properties:
isOptional:
type: boolean
description: Whether this action is optional
socialValidation:
type: string
enum:
- validation-on
- validation-off
- user-choice
description: >-
Controls how social media validation is handled:
- validation-on: Strict validation is enforced. The action will only
be marked as complete if the social media activity is verified.
- validation-off: No validation is performed. The action is
automatically marked as complete.
- user-choice: Allows users to choose whether to bypass validation
by setting isBypass=true in their action input. If isBypass=false,
full validation will be performed.
prerequisites:
$ref: '#/components/schemas/ActionPrerequisite'
requiresCorrectAnswer:
type: boolean
description: >-
Whether the action must be answered correctly to count toward
challenge completion. When false, any participation counts toward
completion but only correct answers earn rewards.
description: Used to configure an action
title: ActionConfigInput
Action:
type: object
properties:
id:
type: string
pattern: ^[0-9a-fA-F]{24}$
description: The id of the action
organisationId:
type: string
pattern: ^[0-9a-fA-F]{24}$
description: The organisation that the action belongs to
communityId:
type: string
pattern: ^[0-9a-fA-F]{24}$
description: The community that the action belongs to
allocationId:
type:
- string
- 'null'
pattern: ^[0-9a-fA-F]{24}$
description: >-
The allocation this action is assigned to. When null, indicates this
is a template action.
allocatedTo:
type: string
enum:
- achievement
- action
- community
- challenge
- leaderboard
- post
- reward
- reward-asset
- reward-entry
description: >-
The entity type this action is allocated to. This can be set to a
'challenge' only at the moment.
actionGroupId:
type:
- string
- 'null'
pattern: ^[0-9a-fA-F]{24}$
description: The action group this action belongs to
actionGroupIndex:
type:
- number
- 'null'
description: The index of this action within its action group
position:
type: number
description: The display position of this action
category:
type: string
enum:
- nudj
- discord
- facebook
- imageAnalysis
- instagram
- interaction
- linkedin
- question
- platform
- spotify
- tiktok
- twitter
- youtube
description: The category of this action
key:
type: string
enum:
- facebook-comment
- facebook-follow
- facebook-like
- image-analysis-object-detection
- image-analysis-receipt-detection
- instagram-follow
- instagram-like
- instagram-comment
- instagram-share
- instagram-post
- interaction-engage-with-content
- interaction-external-link
- interaction-image-upload
- interaction-spot-object
- platform-comment-on-post
- platform-complete-achievement
- platform-generative-action
- platform-like-post
- platform-play-game
- platform-validate-event
- question-multiple-choice
- question-open-ended
- question-rate-your-experience
- question-secret-access-code
- question-select-date
- question-select-from-images
- question-select-value-in-range
- question-select-from-list
- question-closed-ended
- question-vote
- spotify-follow
- spotify-listen
- spotify-save
- tiktok-follow
- tiktok-watch
- tiktok-post
- youtube-like
- youtube-comment
- youtube-subscribe
description: The specific type of this action
details:
allOf:
- $ref: '#/components/schemas/Details'
description: >-
The details of this action such as title, description, bannerUrl,
logoUrl
progressPeriod:
type: string
enum:
- daily
- weekly
- monthly
- yearly
- open
description: The progress period of the action
maxCompletionsPerPeriod:
anyOf:
- type: number
minimum: 0
- type: string
const: Infinity
description: The maximum number of completions per period for the action
attributes:
$ref: '#/components/schemas/ActionAttributes'
config:
allOf:
- $ref: '#/components/schemas/ActionConfig'
description: The configuration settings for this action
xpConfig:
allOf:
- $ref: '#/components/schemas/UserXPBreakdown'
description: >-
XP breakdown for this action. Can be customized per action or set to
match platform config defaults.
videoMetadata:
oneOf:
- $ref: '#/components/schemas/VideoMetadata'
- type: 'null'
description: Video metadata for actions with video content
createdAt:
type: string
description: The date when this action was created
availableAsTemplateForOrganisations:
type:
- array
- 'null'
items:
type: string
pattern: ^[0-9a-fA-F]{24}$
description: List of organisation IDs that can use this action as a template
isGlobalTemplate:
type:
- boolean
- 'null'
description: >-
Indicates if this action is available as a template globally across
all organisations
rewardDistribution:
oneOf:
- $ref: '#/components/schemas/EntityRewardDistribution'
- type: 'null'
description: Reward distribution information for this action
createdBy:
type: string
updatedAt:
type:
- string
- 'null'
updatedBy:
type:
- string
- 'null'
required:
- id
- organisationId
- communityId
- allocationId
- allocatedTo
- position
- category
- key
- details
- progressPeriod
- maxCompletionsPerPeriod
- attributes
- config
- xpConfig
- videoMetadata
- createdAt
- rewardDistribution
- createdBy
description: An action
title: Action
error.BAD_REQUEST:
type: object
properties:
message:
type: string
description: The error message
example: Invalid input data
code:
type: string
description: The error code
example: BAD_REQUEST
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: An array of issues that were responsible for the error
example: []
required:
- message
- code
title: Error
description: The error information
example:
code: BAD_REQUEST
message: Invalid input data
issues: []
error.INTERNAL_SERVER_ERROR:
type: object
properties:
message:
type: string
description: The error message
example: Internal server error
code:
type: string
description: The error code
example: INTERNAL_SERVER_ERROR
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: An array of issues that were responsible for the error
example: []
required:
- message
- code
title: Error
description: The error information
example:
code: INTERNAL_SERVER_ERROR
message: Internal server error
issues: []
MultipleChoiceActionAttributes:
type: object
properties:
key:
type: string
const: question-multiple-choice
description: The multiple choice question action key
question:
type: string
minLength: 1
description: >-
The multiple choice question to be answered ie 'What is your
favorite color?'
options:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The id of the option. This is used to identify the option and
each option must be unique ie '1' or '2'
label:
type: string
description: The label of the option ie 'Red' or 'Blue'
required:
- id
- label
minItems: 2
description: The multiple choice options available to answer the question
minimumNumberOfAnswersRequired:
type: number
minimum: 1
description: The minimum number of answers required
maximumNumberOfAnswersAllowed:
type: number
minimum: 1
description: The maximum number of answers allowed
correctAnswers:
type: array
items:
type: string
description: >-
The correct answers for this question. This must match the ids of
the options array.
required:
- key
- question
- options
- minimumNumberOfAnswersRequired
- maximumNumberOfAnswersAllowed
- correctAnswers
description: >-
A multiple choice question with configurable options and correct answer
validation. The question text is stored in the details.title field of
the action, while technical configuration remains in attributes.
x-action-category: Question
title: Multiple Choice Question
OpenEndedActionAttributes:
type: object
properties:
key:
type: string
const: question-open-ended
description: The open ended question action key
question:
type: string
minLength: 1
description: >-
The open ended question to be answered ie 'Tell us about your
skillset?'
required:
- key
- question
description: A question with a free response
x-action-category: Question
title: Open Ended Question
RateYourExperienceActionAttributes:
type: object
properties:
key:
type: string
const: question-rate-your-experience
description: The rate your experience question action key
question:
type: string
minLength: 1
description: The text to be displayed to the user ie 'How was your experience?'
ratingStyle:
type:
- string
- 'null'
required:
- key
- question
description: A question with a rating scale
x-action-category: Question
title: Rate Your Experience Question
SecretAccessCodeActionAttributes:
type: object
properties:
key:
type: string
const: question-secret-access-code
description: The secret access code question action key
question:
type: string
minLength: 1
description: >-
The secret access code question to be answered ie 'What is the
secret access code found on your badge?'
singleUse:
type: boolean
description: >-
If true, a secret access code can only be used once from the options
array
validation:
type: string
enum:
- pre-defined-options
- regex
description: The validation type for the secret access code question
regex:
type:
- string
- 'null'
description: >-
Must be supplied if validation is Regex. Will used to validate the
secret access code ie '^[A-Z0-9]{6}$' which is a 6 character
uppercase alphanumeric code
options:
type:
- array
- 'null'
items:
type: string
description: >-
Must be supplied if validation is PreDefinedOptions. This is an
array of unique secret access codes that can be used to answer the
question
required:
- key
- question
- singleUse
- validation
description: A question which requires a secret access code
x-action-category: Question
title: Secret Access Code Question
SelectFromImagesActionAttributes:
type: object
properties:
key:
type: string
const: question-select-from-images
description: The select from images question action key
question:
type: string
minLength: 1
description: The question to be answered ie 'Which image is a cat?'
images:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The id of the image. This is used to identify the image and
each image must be unique ie '1' or '2'
name:
type: string
description: The display name of the image
uri:
type: string
description: The uri of the image
required:
- id
- name
- uri
minItems: 2
description: The images to select from
numberOfAnswersRequired:
type:
- number
- 'null'
description: The number of selections required
correctAnswers:
type:
- array
- 'null'
items:
type: string
description: The correct answers to the question. This is an array of image ids
required:
- key
- question
- images
description: A question with images to select from
x-action-category: Question
title: Select From Images Question
SelectFromListActionAttributes:
type: object
properties:
key:
type: string
const: question-select-from-list
description: The select from list question action key
question:
type: string
minLength: 1
description: >-
The question to be answered ie 'Which color is your favorite?' from
a list of options
minimumNumberOfAnswersRequired:
type: number
minimum: 1
description: The minimum number of answers required
maximumNumberOfAnswersAllowed:
type: number
minimum: 1
description: The maximum number of answers allowed
options:
type: array
items:
type: object
properties:
id:
type: string
minLength: 1
description: >-
The id of the option. This is used to identify the option and
each option must be unique ie '1' or '2'
label:
type: string
minLength: 1
description: The label of the option
required:
- id
- label
minItems: 2
description: The list of options to select from
required:
- key
- question
- minimumNumberOfAnswersRequired
- maximumNumberOfAnswersAllowed
- options
description: A question with a list of options to select from
x-action-category: Question
title: Select From List Question
SingleFixedAnswerActionAttributes:
type: object
properties:
key:
type: string
const: question-closed-ended
description: The single fixed answer question action key
question:
type: string
minLength: 1
description: The question to be answered ie 'What is the capital of France?'
correctAnswers:
type: array
items:
type: string
minItems: 2
description: >-
The possible correct answers to the question. This is an array of
strings and must contain at least 2 answers ie ['Paris', 'paris',
'London', 'london']
required:
- key
- question
- correctAnswers
description: A question with a single fixed answer
x-action-category: Question
title: Single Fixed Answer Question
VoteActionAttributes:
type: object
properties:
key:
type: string
const: question-vote
description: The vote question action key
question:
type: string
minLength: 1
description: The voting question to be answered ie 'What is your favorite color?'
options:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The id of the option. This is used to identify the option and
each option must be unique ie '1' or '2'
label:
type: string
minLength: 1
description: The label of the option ie 'Red' or 'Blue'
required:
- id
- label
minItems: 2
description: The voting options available (minimum 2, no maximum)
allowMultipleVotes:
type: boolean
description: >-
If true, users can vote multiple times in repeatable challenges
(each vote counts separately). If false (default), votes are
overwritten when the user repeats the action.
required:
- key
- question
- options
description: >-
A voting/polling action where users select one option from a list.
Results are calculated in real-time by counting all participations for
this action.
x-action-category: Question
title: Vote/Polling Question
SelectADateActionAttributes:
type: object
properties:
key:
type: string
const: question-select-date
description: The select a date question action key
allowDates:
type: string
enum:
- past
- future
- all
description: The dates to allow ie 'past', 'future' or 'all'
allowCurrentDate:
type: boolean
description: Whether to allow the current date
question:
type: string
minLength: 1
description: The question to be answered ie 'When is your birthday?'
required:
- key
- allowDates
- allowCurrentDate
- question
description: A question with a date to select from
x-action-category: Question
title: Select A Date Question
SelectValueInRangeActionAttributes:
type: object
properties:
key:
type: string
const: question-select-value-in-range
description: The select value in range question action key
question:
type: string
minLength: 1
description: The text to be displayed to the user ie 'How much would you invest?'
minValue:
type: number
description: Minimum value of the range
maxValue:
type: number
description: Maximum value of the range
step:
type: number
description: Step size between values
unit:
type:
- string
- 'null'
description: Optional unit for the values (e.g., '£', '%')
unitPlacement:
type:
- string
- 'null'
enum:
- before
- after
description: Whether the unit appears before or after the value
progressionType:
type: string
enum:
- linear
- logarithmic
description: >-
Type of progression for the slider values: linear (equal intervals
throughout the range, e.g., 0,10,20,30...) or logarithmic
(increasing intervals, better for large ranges where precision is
needed at lower values, e.g., 1,2,5,10,20,50,100...)
required:
- key
- question
- minValue
- maxValue
- step
- progressionType
description: A question with a value slider within a defined range
x-action-category: Question
title: Select Value In Range Question
ExternalLinkActionAttributes:
type: object
properties:
key:
type: string
const: interaction-external-link
externalLinkSiteName:
type: string
minLength: 1
externalLinkSource:
type: string
externalLinkUrl:
type: string
minLength: 1
opensInNewTab:
type: boolean
showMetadata:
type:
- boolean
- 'null'
description: >-
Whether to show metadata on the external link. Including the title,
description, and image.
validateWithEvent:
type:
- boolean
- 'null'
event:
oneOf:
- $ref: '#/components/schemas/ExternalLinkActionEvent'
- type: 'null'
required:
- key
- externalLinkSiteName
- externalLinkSource
- externalLinkUrl
- opensInNewTab
x-action-category: Interaction
title: External Link Interaction
description: >-
A task that directs users to visit an external website by clicking a
link. This action type is commonly used to drive traffic to specific
webpages for promotional purposes, provide additional information, or
engage users with related content. The link can be configured to open in
a new tab and optionally validate that the user visited the destination.
EngageWithContentActionAttributes:
type: object
properties:
key:
type: string
const: interaction-engage-with-content
title:
type: string
content:
type: string
required:
- key
- title
- content
x-action-category: Interaction
title: Engage With Content Interaction
description: >-
Creates rich, interactive content experiences using HTML formatting.
Features include:
- Full HTML support for advanced content formatting
- Embedded media integration (YouTube videos, images)
- Structured content with headings, lists, and paragraphs
- Custom styling and layout options
Common use cases include:
- Interactive tutorials and guides
- Rich text announcements and updates
- Educational content with embedded videos
- Formatted instructions and documentation
Example YouTube embed format:
Text content
ImageUploadDisclaimer:
type: object
properties:
id:
type: string
label:
type: string
required:
- id
- label
title: ImageUploadDisclaimer
description: An image upload disclaimer
SpotObjectActionAttributes:
type: object
properties:
key:
type: string
const: interaction-spot-object
description: The spot object interaction action key
toleranceMs:
type: number
minimum: 0
description: >-
Tolerance in milliseconds before and after each timestamp that will
be accepted as correct
required:
- key
- toleranceMs
description: >-
An interaction action where users must spot objects at specific
timestamps with configurable tolerance ranges. The timestamps array
contains the correct moments (in milliseconds) where objects appear, and
toleranceMs defines the acceptable range before and after each
timestamp.
x-action-category: Interaction
title: Spot Object Action
ObjectDetectionActionAttributes:
type: object
properties:
key:
type: string
const: image-analysis-object-detection
description:
type: string
minLength: 1
objects:
type: array
items:
type: string
allObjectsRequired:
type: boolean
required:
- key
- description
- objects
- allObjectsRequired
x-action-category: Image Analysis
title: Object Detection Action Attributes
description: The attributes of an object detection action
ReceiptDetectionActionAttributes:
type: object
properties:
key:
type: string
const: image-analysis-receipt-detection
description:
type: string
minLength: 1
minimumAmount:
type: number
items:
type:
- array
- 'null'
items:
type: string
allItemsRequired:
type: boolean
required:
- key
- description
- minimumAmount
- allItemsRequired
x-action-category: Image Analysis
title: Receipt Detection Action Attributes
description: The attributes of a receipt detection action
FacebookCommentActionAttributes:
type: object
properties:
key:
type: string
const: facebook-comment
title:
type: string
minLength: 1
postUrl:
type: string
minLength: 1
required:
- key
- title
- postUrl
x-action-category: Facebook
title: Facebook Comment Action Attributes
description: The attributes of a Facebook comment action
FacebookFollowActionAttributes:
type: object
properties:
key:
type: string
const: facebook-follow
title:
type: string
minLength: 1
businessAccountUsername:
type: string
minLength: 1
required:
- key
- title
- businessAccountUsername
x-action-category: Facebook
title: Facebook Follow Action Attributes
description: The attributes of a Facebook follow action
FacebookLikeActionAttributes:
type: object
properties:
key:
type: string
const: facebook-like
title:
type: string
minLength: 1
postUrl:
type: string
format: uri
required:
- key
- title
- postUrl
x-action-category: Facebook
title: Facebook Like Action Attributes
description: The attributes of a Facebook like action
InstagramFollowActionAttributes:
type: object
properties:
key:
type: string
const: instagram-follow
title:
type: string
minLength: 1
businessAccountUsername:
type: string
minLength: 1
businessAccountId:
type:
- string
- 'null'
minLength: 1
required:
- key
- title
- businessAccountUsername
x-action-category: Instagram
title: Instagram Follow Action Attributes
description: The attributes of an Instagram follow action
InstagramLikeActionAttributes:
type: object
properties:
key:
type: string
const: instagram-like
title:
type: string
minLength: 1
postId:
type: string
minLength: 1
required:
- key
- title
- postId
x-action-category: Instagram
title: Instagram Like Action Attributes
description: The attributes of an Instagram like action
InstagramCommentActionAttributes:
type: object
properties:
key:
type: string
const: instagram-comment
title:
type: string
minLength: 1
postId:
type: string
minLength: 1
numberOfMentions:
type:
- number
- 'null'
required:
- key
- title
- postId
x-action-category: Instagram
title: Instagram Comment Action Attributes
description: The attributes of an Instagram comment action
InstagramShareActionAttributes:
type: object
properties:
key:
type: string
const: instagram-share
title:
type: string
minLength: 1
postId:
type: string
minLength: 1
required:
- key
- title
- postId
x-action-category: Instagram
title: Instagram Share Action Attributes
description: The attributes of an Instagram share action
InstagramPostActionAttributes:
type: object
properties:
key:
type: string
const: instagram-post
title:
type: string
minLength: 1
postContent:
type: string
minLength: 1
postType:
type: string
minLength: 1
required:
- key
- title
- postContent
- postType
x-action-category: Instagram
title: Instagram Post Action Attributes
description: The attributes of an Instagram post action
CommentOnPostActionAttributes:
type: object
properties:
key:
type: string
const: platform-comment-on-post
title:
type: string
minLength: 1
postId:
type: string
pattern: ^[0-9a-fA-F]{24}$
imageRequired:
type: boolean
required:
- key
- title
- postId
- imageRequired
x-action-category: Platform
title: Comment On Post Action Attributes
description: >-
Enables commenting on posts with optional image attachments. Features:
direct commenting via postId, configurable image requirements, custom
titles. Used for discussions, photo responses, feedback, and community
engagement.
CompleteAchievementActionAttributes:
type: object
properties:
key:
type: string
const: platform-complete-achievement
title:
type: string
minLength: 1
achievementId:
type: string
pattern: ^[0-9a-fA-F]{24}$
required:
- key
- title
- achievementId
x-action-category: Platform
title: Complete Achievement Action Attributes
description: >-
Enables users to complete specific achievements. Used for tracking
achievement progress, gamification, and user engagement metrics.
GenerativeActionActionAttributes:
type: object
properties:
key:
type: string
const: platform-generative-action
description: The generative action key
title:
type: string
minLength: 1
description: The title of the generative action
minifiedCode:
type: string
minLength: 1
description: The minified code that will be executed on the client side
code:
type: string
minLength: 1
description: The original, unminified code for development and debugging
images:
type: array
items:
type: object
properties:
key:
type: string
minLength: 1
description: The image identifier/key
value:
type: string
minLength: 1
description: The image URL or base64 data
required:
- key
- value
description: Array of images used within the generative action
texts:
type: array
items:
type: object
properties:
key:
type: string
minLength: 1
description: The text identifier/key
value:
type: string
minLength: 1
description: The text content value
required:
- key
- value
description: >-
Array of text content used in the code that can be dynamically
replaced
variables:
type: array
items:
type: object
properties:
key:
type: string
minLength: 1
description: The variable identifier/key
value:
type: string
minLength: 1
description: The variable value
required:
- key
- value
description: >-
Array of variables used within the generative action for dynamic
configuration
validationFunction:
type: string
description: >-
Custom validation function logic for the action when validation is
not handled in the code itself
aiValidationPrompt:
type: string
description: AI prompt for validating the action results or user input
required:
- key
- title
- minifiedCode
- code
- images
- texts
- variables
description: >-
Enables users to interact with generated code or content. Contains both
the original code and minified version for execution, along with
associated assets and validation logic.
x-action-category: Platform
title: Generative Action Attributes
LikePostActionAttributes:
type: object
properties:
key:
type: string
const: platform-like-post
title:
type: string
minLength: 1
postId:
type: string
pattern: ^[0-9a-fA-F]{24}$
required:
- key
- title
- postId
x-action-category: Platform
title: Like Post Action Attributes
description: >-
Enables users to like/upvote specific posts. Used for engagement
tracking, content popularity, and community interaction metrics.
PlayGameActionAttributes:
type: object
properties:
key:
type: string
const: platform-play-game
title:
type: string
minLength: 1
gameConfigId:
type: string
pattern: ^[0-9a-fA-F]{24}$
gameType:
type: string
enum:
- catch
- memory
- scratch
required:
- key
- title
- gameConfigId
- gameType
x-action-category: Platform
title: Play Game Action Attributes
description: Triggers a game defined by a game configuration.
ValidateEventActionAttributes:
type: object
properties:
key:
type: string
const: platform-validate-event
title:
type: string
minLength: 1
description: Display title for the action
eventType:
type: string
enum:
- achievement-completion
- facebook-comment
- facebook-follow
- facebook-like
- image-analysis-object-detection
- image-analysis-receipt-detection
- instagram-follow
- instagram-like
- instagram-comment
- instagram-share
- instagram-post
- interaction-engage-with-content
- interaction-external-link
- interaction-image-upload
- interaction-spot-object
- platform-comment-on-post
- platform-complete-achievement
- platform-generative-action
- platform-like-post
- platform-play-game
- platform-validate-event
- question-multiple-choice
- question-open-ended
- question-rate-your-experience
- question-secret-access-code
- question-select-date
- question-select-from-images
- question-select-value-in-range
- question-select-from-list
- question-closed-ended
- question-vote
- spotify-follow
- spotify-listen
- spotify-save
- tiktok-follow
- tiktok-watch
- tiktok-post
- youtube-like
- youtube-comment
- youtube-subscribe
- action-completion
- skip-action
- 42-school
- api-auth-link
- api-token-link
- apple
- asgardeo
- atlassian
- auth0
- authentik
- azure-ad-b2c
- azure-ad
- azure-devops
- battlenet
- beyondidentity
- box
- boxyhq-saml
- bungie
- click-up
- cognito
- coinbase
- descope
- discord
- dribbble
- dropbox
- duende-identity-server6
- email
- eveonline
- facebook
- faceit
- foursquare
- freshbooks
- fusionauth
- github
- gitlab
- google
- hubspot
- identity-server4
- instagram
- kakao
- keycloak
- line
- linkedin
- mailchimp
- mailru
- mastodon
- mattermost
- medium
- naver
- netlify
- notion
- okta
- onelogin
- organisation-oidc
- osso
- osu
- passage
- patreon
- pinterest
- pipedrive
- reddit
- salesforce
- slack
- spotify
- strava
- tiktok
- todoist
- trakt
- twitch
- twitter
- united-effects
- vk
- wikimedia
- wordpress
- workos
- yandex
- youtube
- zitadel
- zoho
- zoom
- blog-comment
- blog-like
- blog-share
- blog-view
- challenge-started
- challenge-completion
- challenge-unlock
- community-visit
- parental-approval-requested
- parental-approval-approved
- parental-approval-rejected
- custom
- game-started
- game-completed
- leaderboard-finish
- invite-admin-user
- points-credit
- points-spend
- post-comment
- post-like
- post-view
- reward-redemption
- reward-allocation-purchase
- reward-giveaway-winner
- reward-claim
- reward-distribution
- manual-distribution
- referral-link-used
- shop-purchase
- share-challenge-details
- share-challenge-results
- share-community
- share-reward
- share-post
- share-profile
- share-anything
- streak-extended
- profile-picture-added
- bio-added
- variable-captured
- xp-gained
- xp-total
- xp-leaderboard-topper
description: Type of the event to validate
eventSourceId:
type:
- string
- 'null'
pattern: ^[0-9a-fA-F]{24}$
description: Source ID to a specific event source
eventName:
type:
- string
- 'null'
minLength: 1
description: Event name. This is required for custom events
required:
- key
- title
- eventType
- eventSourceId
- eventName
x-action-category: Platform
title: Validate Event Action Attributes
description: Configuration for validating user completion of specific events
SpotifyFollowActionAttributes:
type: object
properties:
key:
type: string
const: spotify-follow
spotifyURL:
type: string
minLength: 1
required:
- key
- spotifyURL
x-action-category: Spotify
title: Spotify Follow Action Attributes
description: The attributes of a Spotify follow action
SpotifyListenActionAttributes:
type: object
properties:
key:
type: string
const: spotify-listen
spotifyURL:
type: string
minLength: 1
playCount:
type: number
minimum: 1
required:
- key
- spotifyURL
- playCount
x-action-category: Spotify
title: Spotify Listen Action Attributes
description: The attributes of a Spotify listen action
SpotifySaveActionAttributes:
type: object
properties:
key:
type: string
const: spotify-save
spotifyURL:
type: string
minLength: 1
required:
- key
- spotifyURL
x-action-category: Spotify
title: Spotify Save Action Attributes
description: The attributes of a Spotify save action
YoutubeCommentActionAttributes:
type: object
properties:
key:
type: string
const: youtube-comment
videoUrl:
type: string
minLength: 1
required:
- key
- videoUrl
x-action-category: Youtube
title: Youtube Comment Action Attributes
description: The attributes of a Youtube comment action
YoutubeSubscribeActionAttributes:
type: object
properties:
key:
type: string
const: youtube-subscribe
username:
type: string
minLength: 1
required:
- key
- username
x-action-category: Youtube
title: Youtube Subscribe Action Attributes
description: The attributes of a Youtube subscribe action
YoutubeLikeActionAttributes:
type: object
properties:
key:
type: string
const: youtube-like
videoUrl:
type: string
minLength: 1
required:
- key
- videoUrl
x-action-category: Youtube
title: Youtube Like Action Attributes
description: The attributes of a Youtube like action
TikTokFollowActionAttributes:
type: object
properties:
key:
type: string
const: tiktok-follow
title:
type: string
minLength: 1
maxLength: 100
accountUsername:
type: string
minLength: 1
required:
- key
- title
- accountUsername
x-action-category: TikTok
title: TikTok Follow Action Attributes
description: The attributes of a TikTok follow action
TikTokPostActionAttributes:
type: object
properties:
key:
type: string
const: tiktok-post
title:
type: string
minLength: 1
maxLength: 100
hashtags:
type: array
items:
type: string
pattern: ^#?[A-Za-z0-9_]+$
minLength: 1
minItems: 1
required:
- key
- title
- hashtags
x-action-category: TikTok
title: TikTok Post Video With Hashtag Action Attributes
description: The attributes of a TikTok post video with hashtags action
TikTokWatchActionAttributes:
type: object
properties:
key:
type: string
const: tiktok-watch
title:
type: string
minLength: 1
maxLength: 100
videoUrl:
type: string
minLength: 1
required:
- key
- title
- videoUrl
x-action-category: TikTok
title: TikTok Watch Video Action Attributes
description: The attributes of a TikTok watch video action
ActionPrerequisite:
type: object
properties:
requiredActionCount:
type: number
description: >-
Number of actions that must be completed within the same allocation
to unlock this action
actionIds:
type: array
items:
type: string
description: >-
Array of specific action IDs that must be completed in the same
allocation
required:
- requiredActionCount
- actionIds
description: Used to configure a prerequisite for an action
title: ActionPrerequisite
Details:
type: object
properties:
title:
type: string
description: The title of the entity
description:
type:
- string
- 'null'
description: The description of the entity
light:
type: object
properties:
primaryImageUrl:
type:
- string
- 'null'
description: The url of the primary image for this theme mode
secondaryImageUrl:
type:
- string
- 'null'
description: The url of the secondary image for this theme mode
required:
- primaryImageUrl
- secondaryImageUrl
description: Light theme images
dark:
type: object
properties:
primaryImageUrl:
type:
- string
- 'null'
description: The url of the primary image for this theme mode
secondaryImageUrl:
type:
- string
- 'null'
description: The url of the secondary image for this theme mode
required:
- primaryImageUrl
- secondaryImageUrl
description: Dark theme images
required:
- title
- description
- light
- dark
description: Used to describe an entity
title: Details
ActionConfig:
type: object
properties:
isOptional:
type: boolean
description: Whether this action is optional
socialValidation:
type: string
enum:
- validation-on
- validation-off
- user-choice
description: >-
Controls how social media validation is handled:
- validation-on: Strict validation is enforced. The action will only
be marked as complete if the social media activity is verified.
- validation-off: No validation is performed. The action is
automatically marked as complete.
- user-choice: Allows users to choose whether to bypass validation
by setting isBypass=true in their action input. If isBypass=false,
full validation will be performed.
prerequisites:
$ref: '#/components/schemas/ActionPrerequisite'
requiresCorrectAnswer:
type: boolean
description: >-
Whether the action must be answered correctly to count toward
challenge completion. When false, any participation counts toward
completion but only correct answers earn rewards.
required:
- isOptional
- socialValidation
description: Used to configure an action
title: ActionConfig
EntityRewardDistribution:
type: object
properties:
points:
type: number
minimum: 0
description: Number of points awarded upon completion
xp:
type: number
minimum: 0
description: XP awarded upon completion
rewardSelectionMethod:
type: string
enum:
- all
- priority
- random
- select
description: Method for selecting rewards when multiple are available
distributionEventId:
type: string
pattern: ^[0-9a-fA-F]{24}$
description: ID of the distribution event managing these rewards
rewardAllocations:
type: array
items:
$ref: '#/components/schemas/RewardAllocationReference'
description: >-
Array of reward allocations with their types. Filter by
allocationType to get counts: assets for tangible rewards, entries
for giveaway entries
numberOfRewardsToReceive:
type: number
minimum: 0
description: Number of rewards the user will receive from the available rewards
required:
- points
- xp
- rewardSelectionMethod
- distributionEventId
- rewardAllocations
- numberOfRewardsToReceive
description: >-
Reward distribution for a single entity with distribution event
reference
title: Entity Reward Distribution
ExternalLinkActionEvent:
type: object
properties:
eventCategory:
type: string
enum:
- achievement
- action
- auth
- blog
- challenge
- community
- custom
- game
- leaderboard
- organisation
- points
- post
- referral
- reward
- shop
- social
- social-connection
- streak
- user
- variable
- xp
description: The category of the event.
eventSubCategory:
type: string
enum:
- achievement-completion
- facebook-comment
- facebook-follow
- facebook-like
- image-analysis-object-detection
- image-analysis-receipt-detection
- instagram-follow
- instagram-like
- instagram-comment
- instagram-share
- instagram-post
- interaction-engage-with-content
- interaction-external-link
- interaction-image-upload
- interaction-spot-object
- platform-comment-on-post
- platform-complete-achievement
- platform-generative-action
- platform-like-post
- platform-play-game
- platform-validate-event
- question-multiple-choice
- question-open-ended
- question-rate-your-experience
- question-secret-access-code
- question-select-date
- question-select-from-images
- question-select-value-in-range
- question-select-from-list
- question-closed-ended
- question-vote
- spotify-follow
- spotify-listen
- spotify-save
- tiktok-follow
- tiktok-watch
- tiktok-post
- youtube-like
- youtube-comment
- youtube-subscribe
- action-completion
- skip-action
- 42-school
- api-auth-link
- api-token-link
- apple
- asgardeo
- atlassian
- auth0
- authentik
- azure-ad-b2c
- azure-ad
- azure-devops
- battlenet
- beyondidentity
- box
- boxyhq-saml
- bungie
- click-up
- cognito
- coinbase
- descope
- discord
- dribbble
- dropbox
- duende-identity-server6
- email
- eveonline
- facebook
- faceit
- foursquare
- freshbooks
- fusionauth
- github
- gitlab
- google
- hubspot
- identity-server4
- instagram
- kakao
- keycloak
- line
- linkedin
- mailchimp
- mailru
- mastodon
- mattermost
- medium
- naver
- netlify
- notion
- okta
- onelogin
- organisation-oidc
- osso
- osu
- passage
- patreon
- pinterest
- pipedrive
- reddit
- salesforce
- slack
- spotify
- strava
- tiktok
- todoist
- trakt
- twitch
- twitter
- united-effects
- vk
- wikimedia
- wordpress
- workos
- yandex
- youtube
- zitadel
- zoho
- zoom
- blog-comment
- blog-like
- blog-share
- blog-view
- challenge-started
- challenge-completion
- challenge-unlock
- community-visit
- parental-approval-requested
- parental-approval-approved
- parental-approval-rejected
- custom
- game-started
- game-completed
- leaderboard-finish
- invite-admin-user
- points-credit
- points-spend
- post-comment
- post-like
- post-view
- reward-redemption
- reward-allocation-purchase
- reward-giveaway-winner
- reward-claim
- reward-distribution
- manual-distribution
- referral-link-used
- shop-purchase
- share-challenge-details
- share-challenge-results
- share-community
- share-reward
- share-post
- share-profile
- share-anything
- streak-extended
- profile-picture-added
- bio-added
- variable-captured
- xp-gained
- xp-total
- xp-leaderboard-topper
description: The sub-category of the event.
eventSourceId:
type:
- string
- 'null'
pattern: ^[0-9a-fA-F]{24}$
description: The source ID of the event.
eventName:
type:
- string
- 'null'
description: The name of the event, required when using a custom event category.
required:
- eventCategory
- eventSubCategory
x-action-category: Interaction
title: External Link Event
description: An event that is triggered when a user clicks on an external link.
RewardAllocationReference:
type: object
properties:
rewardId:
type: string
pattern: ^[0-9a-fA-F]{24}$
description: ID of the reward
allocationId:
type: string
pattern: ^[0-9a-fA-F]{24}$
description: ID of the specific allocation within the reward
allocationType:
type: string
enum:
- assets
- entries
description: >-
The type of allocation - either 'assets' for tangible rewards or
'entries' for giveaway entries
amountToDistribute:
type: number
minimum: 1
description: >-
The quantity of this specific reward to distribute when this
allocation is selected
required:
- rewardId
- allocationId
- allocationType
- amountToDistribute
description: Reference to a specific reward and its allocation
title: Reward Allocation Reference
securitySchemes:
ApiToken:
type: apiKey
in: header
name: x-api-token
````