Generic CRUD surface for the foundational building blocks of a program - rewards, challenges, stores, products, transactions, and customer lists - addressed as entities under a module namespace, with list, create, retrieve, update, archive, and bulk submission.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/antavo-entities-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.0.0
info:
contact: {}
title: Antavo Entities API
version: 1.0.0
servers:
- url: https://api.staging.antavo.com
description: The Antavo staging environment
paths:
/entities/core/customer-list/{entity_id}:
delete:
tags:
- Customer lists
summary: Archive a customer list
description: This endpoint allows archiving a customer list and removing users from it. Only inactive
lists can be archived. Once archived, lists cannot be restored.
parameters:
- name: entity_id
in: path
required: true
description: The ID of the customer list.
schema:
type: string
responses:
'200':
description: Customer list archived
content:
application/json:
schema:
type: array
items:
type: string
example: ok
'400':
description: Customer list not found
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentError'
get:
tags:
- Customer lists
summary: Retrieve information of a specific customer list
description: This endpoint returns a specific customer list.
parameters:
- name: entity_id
in: path
required: true
description: The ID of the customer list.
example: 66810d9683aeae307b712d43
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentResponse'
'400':
description: Customer list not found
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentErrorResponse'
deprecated: false
post:
tags:
- Customer lists
summary: Update a customer list
description: This endpoint allows you to update a customer list.
parameters:
- name: entity_id
in: path
required: true
description: The ID of the customer list.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: VIP members
description: New name of the customer list.
status:
type: string
example: inactive
description: New status of the customer list.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentResponse'
'400':
description: Customer list not found
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentErrorResponse'
deprecated: false
/entities/{module}/{entity}/{entity_id}:
delete:
tags:
- Generic
summary: Archive an inactive entity
description: This endpoint archives a specific deactivated entity, effectively removing it from
the system. The reward will be completely non-visible and inaccessible for member and Management
UI users as well.
operationId: Entitydelete
parameters:
- in: path
name: module
required: true
description: Name of the entity module e.g., rewards, accounts, custom (for custom entities).
example: wardsre
schema:
type: string
- in: path
name: entity
required: true
description: The entity's unique ID - typically the singular form of the entity module.
example: reward
schema:
type: string
- in: path
name: entity_id
required: true
description: The unique ID of a specific entity.
example: 63eaabe8b0fe6815c91425b6
schema:
type: string
responses:
'200':
description: Entity archived
content:
application/json:
schema:
type: array
items:
type: string
example: OK
'404':
description: Entity not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Failure:
value:
type: BadRequestException
code: 0
message: Entity not found
deprecated: false
get:
tags:
- Generic
summary: Retrieve all information regarding a specific entity
description: This endpoint returns all information regarding a specific entity item.
operationId: entityget
parameters:
- name: module
in: path
required: true
description: Name of the entity module e.g., rewards, accounts, custom (for custom entities).
example: rewards
schema:
type: string
- name: entity
in: path
required: true
description: The entity's unique ID - typically the singular form of the entity module name.
example: reward
schema:
type: string
- name: entity_id
in: path
required: true
description: The unique ID of a specific entity.
example: 63eaabe8b0fe6815c91425b6
schema:
type: string
- name: additional queries
in: query
description: '
Custom queries can be added here.
'
schema:
type: object
additionalProperties:
type: string
example:
query_field: query_text
responses:
'200':
description: Entity indformation provided - example data is based on a reward entity with translations
included.
content:
application/json:
schema:
$ref: '#/components/schemas/RewardResponse'
'400':
description: Entity not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Failure:
value:
type: BadRequestException
code: 0
message: Entity not found
deprecated: false
post:
tags:
- Generic
summary: Update a specific entity
description: Any pre-configured attribute in an entity itek can be modified using this API endpoint.
Modification requires the use of attribute's unique ID, set in the Management UI.
operationId: entityupdate
parameters:
- in: path
name: module
required: true
description: Name of the entity module e.g., rewards, accounts, custom (for custom entities).
example: rewards
schema:
type: string
- in: path
name: entity
required: true
description: The entity's unique ID - typically the singular form of the entity module.
example: reward
schema:
type: string
- in: path
name: entity_id
required: true
description: The unique id for the specific entity item.
example: 63eaabe8b0fe6815c91425b6
schema:
type: string
requestBody:
description: The entities and corresponding attributes to be modified. Required attributes depend
on the configuration of the entity in the Management UI.
content:
application/json:
schema:
type: object
additionalProperties:
type: string
example:
name: test entity
description: This is the description field
required: true
responses:
'200':
description: Entity has been successfully updated - example data is based on a reward entity.
content:
application/json:
schema:
$ref: '#/components/schemas/RewardPut'
'400':
description: Entity not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Failure:
value:
type: BadRequestException
code: 0
message: Entity not found
put:
tags:
- Generic
summary: Create a new entity with a specific entity ID
description: An entity item with a specified ID can be created in an entity module using this endpoint.
Any parameter can be set as long as there is the corresponding attribute pre-configured in the
Management UI.
operationId: Genericspeccreate
parameters:
- in: path
name: module
required: true
description: Name of the entity module e.g., rewards, accounts, custom (for custom entities).
example: rewards
schema:
type: string
- in: path
name: entity
required: true
description: The entity's unique ID - typically the singular form of the entity module.
example: reward
schema:
type: string
- in: path
name: entity_id
required: true
description: The unique ID for the new entity.
example: 63eaabe8b0fe6815c91425b6
schema:
type: string
requestBody:
description: The entities and corresponding attributes to be created. Required attributes depend
on the configuration of the entity in the Management UI.
content:
application/json:
schema:
type: object
additionalProperties:
type: string
example:
name: test entity
description: This is the description field
required: true
responses:
'200':
description: Successful entity creation - example data is based a reward entity.
content:
application/json:
schema:
$ref: '#/components/schemas/RewardPut'
'400':
description: Bad request - A required attribute is not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Error:
value:
type: BadRequestException
message: '''<attribute>'' property is required'
code: 0
/entities/rewards/reward/{entity_id}:
delete:
tags:
- Rewards
summary: Archive an inactive reward
description: This endpoint archives a specific deactivated reward, effectively removing it from
the system. The reward will be completely non-visible and inaccessible for members and Management
UI users as well.
operationId: Rewarddelete
parameters:
- name: entity_id
in: path
required: true
description: The unique ID of the reward.
schema:
type: string
responses:
'200':
description: Reward archived
content:
application/json:
schema:
type: array
items:
type: string
example: OK
'400':
description: Reward not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Failure:
value:
type: BadRequestException
code: 0
message: Entity not found
deprecated: false
post:
tags:
- Rewards
summary: Update specific reward attributes
description: An attribute of a reward can be updated via this endpoint.
operationId: Rewardupdate
parameters:
- name: entity_id
in: path
description: The unique identifier of the reward.
example: 63dcb7736123782ba6336425
required: true
style: simple
schema:
type: string
requestBody:
description: The attributes of the reward to be updated. These must match attributes available
in the Management UI.
content:
application/json:
schema:
type: object
additionalProperties:
type: string
example:
name: Reward name
description: This is the description field
price: 100
type: coupon
required: true
responses:
'200':
description: Successful update - updated reward
content:
application/json:
schema:
$ref: '#/components/schemas/GetRewardResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Error:
value:
type: BadRequestException
message: '''<attribute>'' property is required'
code: 0
get:
tags:
- Rewards
summary: Returns all information regarding a specific reward
description: A detailed breakdown of all parameters for the specific reward is returned.
operationId: Rewardget
parameters:
- name: entity_id
in: path
required: true
description: The unique ID of the reward.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetRewardResponse'
'400':
description: Reward not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Failure:
value:
type: BadRequestException
code: 0
message: Entity not found
deprecated: false
/entities/core/customer-list:
get:
tags:
- Customer lists
summary: List all available customer lists
description: This endpoint returns all available customer lists.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentResponse'
put:
tags:
- Customer lists
summary: Create a new customer list
description: This endpoint allows you to create a new customer list.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: VIP members
description: New name of the customer list.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PUTlistresponse'
deprecated: false
/entities/{module}/{entity}:
get:
tags:
- Generic
summary: List all available entity of an entity module
description: This endpoint lists all available entity items within the specified entity module.
This interaction is customer-independent.
parameters:
- name: module
in: path
required: true
description: Name of the entity module e.g., rewards, accounts, custom (for custom entities).
example: rewards
schema:
type: string
- name: entity
in: path
required: true
description: The entity's unique ID - typically the singular form of the entity module name.
example: reward
schema:
type: string
- name: offset
in: query
required: false
description: Offsets the starting number of entity items to return. This is used in pagination
in conjunction with the limit query.
schema:
type: integer
default: 0
example: 10
- name: limit
in: query
required: false
description: Limits the number of entity items to be returned in one response. Other values are
accessible by pagination made accessible via the offset.
schema:
type: integer
default: 100
example: 50
- name: additional queries
in: query
description: '
Custom queries can be added here.
'
schema:
type: object
additionalProperties:
type: string
example:
query_field: query_text
responses:
'200':
description: Lists all entities - Example data is based on a reward entity.
content:
application/json:
schema:
$ref: '#/components/schemas/GetRewardsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
fail:
summary: Entity type does not exist
value:
type: BadRequestException
message: Entity type does not exist
code: 350300
deprecated: false
put:
tags:
- Generic
summary: Create a new entity
description: This endpoint created an entity in an entity module. Any parameter can be set as long
as there is the corresponding attribute pre-configured in the Management UI.
operationId: Genericcreate
parameters:
- name: module
in: path
required: true
description: Name of the entity module e.g., rewards, accounts, custom (for custom entities).
example: rewards
schema:
type: string
- name: entity
in: path
required: true
description: The entity's unique ID - typically the singular form of the module.
example: reward
schema:
type: string
requestBody:
description: The entities and corresponding attributes to be created. Required attributes depend
on the configuration of the entity in the Management UI.
content:
application/json:
schema:
type: object
additionalProperties:
type: string
example:
name: test entity
description: This is the description field
required: true
responses:
'200':
description: Successful entity creation - example data is based on a reward entity.
content:
application/json:
schema:
$ref: '#/components/schemas/RewardPut'
'400':
description: Bad request - a required attribute is not provided
content:
application/json:
schema:
$ref: '#/components/schemas/PUTError'
examples:
Failure:
summary: Bad request
value:
type: BadRequestException
code: 0
message: The ID is required and needs to be unique
deprecated: false
/entities/rewards/reward:
get:
tags:
- Rewards
summary: List all available rewards
description: This endpoint lists all available rewards.<br>It allows filtering by stores configured
in the Stores module.
parameters:
- name: stores
in: query
required: false
description: Filters the return rewards by stores, using a store ID.
schema:
type: string
example: 667f3f88527d2e6c00319373
responses:
'200':
description: List of all rewards - this example includes translations.
content:
application/json:
schema:
$ref: '#/components/schemas/GetRewardResponse'
deprecated: false
put:
tags:
- Rewards
summary: Create a new reward
description: This endpoint facilitates the creation of rewards.
operationId: Rewardcreate
parameters: []
requestBody:
description: The attributes of the reward to be created. These must match attributes available
in the Management UI.
content:
application/json:
schema:
type: object
example:
name: 20% Off on Winter Collection
description: Enjoy a 20% discount on our Winter Collection items.
price: 100
type: coupon
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RewardPut'
'400':
description: Bad request - a required attribute is not provided
content:
application/json:
schema:
$ref: '#/components/schemas/PUTError'
examples:
Failure:
summary: Bad request - a required attribute is not provided
value:
type: BadRequestException
code: 0
message: '''<attribute>'' property is required'
deprecated: false
/entities:
post:
tags:
- Generic
summary: Submit entities in bulk
description: 'Multiple calls to various entity endpoints can be made by submitting a request with
data in array format. The following options are available for error checking the submitted data:
- `skip`: Erroneous data is not added, and the whole entry is skipped.
- `pre-check`: The submitted data is checked for validity but not entered into the Antavo system.
Any error messages are returned.
- `fail`: The submission is stopped when an error is encountered.'
requestBody:
content:
application/json:
schema:
type: object
properties:
entities:
type: array
description: Name of the entity module e.g., rewards, accounts, custom (for custom entities).
items:
$ref: '#/components/schemas/Entity'
description: Array containing all data to be processed by the request.
error_handling:
type: string
description: 'Error processing protocol for submitted functions: Options: `skip`, `pre-check`
and `fail`.'
example:
entities:
- method: PUT
type: custom/demo_entity
id: 63eaabe8b0fe6815c91425b6
data:
name: Test Entity
- method: GET
type: custom/demo_entity
id: 63eaabe8b0fe6815c91425b6
error_handling: pre-check
responses:
'200':
description: Successful pre-check response
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Bulkentityone'
total:
type: number
description: Number of processed entity calls.
example: 2
errors:
type: number
description: Number of errors.
example: 0
example:
results:
- method: PUT
type: custom/demo_entity
id: 63eaabe8b0fe6815c91425b6
- method: GET
type: custom/demo_entity
id: 6679a7fd6348cc7c466f27b4
entity:
id: i6679a7fd6348cc7c466f27b1
name: 10% coupon
total: 2
errors: 0
'404':
description: Erroneous pre-check response
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Bulkentitytwo'
total:
type: number
description: Number of processed entity calls.
example: 2
errors:
type: number
description: Number of errors.
example: 1
example:
results:
- method: PUT
type: custom/demo_entity
id: 63eaabe8b0fe6815c91425b6
- method: GET
type: custom/demo_entity
id: 63eaabe8b0fe6815c91425b6
error:
error:
type: RuntimeException
code: 0
message: Entity not found
total: 2
errors: 1
components:
schemas:
SegmentError:
title: Error
type: object
properties:
type:
type: string
description: Type of the error occurred.
example: BadRequestException
code:
type: number
description: A 6-digit number to uniquely identify the place the error occurred.
example: 300400
message:
type: string
description: Human readable error message.
example: Customer List not found
ErrorResponse:
title: Error
type: object
properties:
type:
description: Type of the error occurred.
example: BadRequestException
code:
type: number
description: Error code.
message:
type: string
description: Human readable error message.
SegmentResponse:
type: object
properties:
name:
type: string
description: Name of the list.
example: VIP list
id:
type: string
example: 63f2cc942d6ef241c0167e6c
description: ID of the list.
status:
type: string
example: active
description: Status of the list.
SegmentErrorResponse:
title: SegmentErrorResponse
type: object
properties:
error:
$ref: '#/components/schemas/SegmentError'
description: This describes the generic structure returned if an error occurred - A reward entity
has been used as an example.
RewardResponse:
title: RewardResponse
type: object
properties:
id:
type: string
description: ID of the reward.
example: 5f05b989a44bc1c44008b4590
name:
$ref: '#/components/schemas/Name'
description:
$ref: '#/components/schemas/Description'
redeem_instructions:
$ref: '#/components/schemas/RedeemInstructions'
terms:
$ref: '#/components/schemas/Terms'
account:
$ref: '#/components/schemas/Account'
type:
type: string
description: Type of the reward.
example: coupon
starts_at:
type: string
format: date-time
description: Start date for claiming the reward.
example: '2020-07-21T12:00:00+00:00'
ends_at:
type: string
format: date-time
description: End date for claiming the reward.
example: '2020-12-21T12:00:00+00:00'
claim_button_label:
$ref: '#/components/schemas/ClaimButtonLabel'
category:
$ref: '#/components/schemas/Category'
segments:
type: array
items:
$ref: '#/components/schemas/Segment'
description: ''
cost:
type: string
description: Business cost of the reward.
example: '150.5'
hide_restricted:
type: boolean
description: Indicates whether the reward should be displayed for customer outside of selected
segments.
example: false
hidden:
type: boolean
description: Indicates whether the reward should be displayed to customers.
example: false
restricted_message:
$ref: '#/components/schemas/RestrictedMessage'
repeat_interval:
type: string
description: The time between two reward claims.
example: 1 week
stock:
type: integer
description: Number of reward items available.
example: 42
max_claims:
type: integer
description: Number of times a customer can claim the reward.
example: 90
notifications:
type: boolean
description: Deprecated. Indicates whether customers should be notified by Antavo when the reward
is claimed.
example: false
user_notifications:
type: boolean
description: Indicates whether a workspace admin should be notified by Antavo when the reward
is claimed.
example: false
status:
type: string
description: Status of the reward.
example: inactive
price:
$ref: '#/components/schemas/Price'
Category:
title: Category
type: object
description: Reward category associated with the reward.
properties:
id:
type: string
example: 5ef1ad79a44b5e15008b456e
ClaimButtonLabel:
title: ClaimButtonLabel
type: object
description: Label of the claim button.
properties:
en:
type: string
example: Get Discount
de:
type: string
example: Rabatt Sichern
Description:
title: Description
type: object
description: Description of the reward.
properties:
en:
type: string
example: Enjoy a 20% discount on our Winter Collection items.
de:
type: string
example: Sichern Sie sich 20% Rabatt auf Artikel aus unserer Winterkollektion.
Name:
title: Name
type: object
description: The name of the reward.
properties:
en:
type: string
example: 20% Off on Winter Collection
de:
type: string
example: 20% Rabatt auf die Winterkollektion
Price:
title: Price
type: object
description: Price of the reward in different currencies.
properties:
EUR:
type: integer
format: int32
example: 500
USD:
type: integer
format: int32
example: 500
RedeemInstructions:
title: RedeemInstructions
type: object
description: Instructions on how to redeem the reward.
properties:
en:
type: string
example: Present this coupon at checkout to apply the discount. Valid on Winter Collection items
only.
de:
type: string
example: Zeigen Sie diesen Gutschein an der Kasse vor, um den Rabatt zu erhalten. Gültig nur
für Artikel aus der Winterkollektion.
RestrictedMessage:
title: RestrictedMessage
type: object
descrip
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/antavo/refs/heads/main/openapi/antavo-entities-openapi.yml