# Get record versions
- Operation ID: `getRecordVersions`
- HTTP method: `GET`
- Path: `/brickworks/v1/schemas/{SchemaIdentifier}/records/{RecordIdentifier}/versions`
- [Human-readable API reference](https://hub.synerise.com/api-reference/brickworks#tag/Brickworks:-Record-versions/operation/getRecordVersions)
## Self-contained OpenAPI method
The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required.
```yaml
openapi: 3.0.0
info:
title: Synerise Public API
version: 1.9.1
paths:
/brickworks/v1/schemas/{SchemaIdentifier}/records/{RecordIdentifier}/versions:
get:
tags:
- "Brickworks: Record versions"
summary: Get record versions
description: |
Retrieve all versions of a record. You can paginate, sort, and refine the results. By default, the versions are sorted from newest to oldest.
---
**API consumers:** Synerise User, Workspace (Business Profile)
**API key permission required:** `BRICKWORKS_RECORDS_READ`
**User role permission required:** `assets_brickworks: read`
operationId: getRecordVersions
security:
- JWT: []
parameters:
- name: SchemaIdentifier
in: path
required: true
description: Schema identifier - can be a UUID (SchemaId) or a human-readable string (Schema AppId/API name, 3-25 characters)
schema:
oneOf:
- type: string
format: uuid
title: Schema UUID
- type: string
minLength: 3
maxLength: 25
pattern: ^(?!__)(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)[\w\-]+$
title: Schema AppId
examples:
uuid:
value: 550e8400-e29b-41d4-a716-446655440000
summary: Schema UUID
appId:
value: my_schema_app_id
summary: Schema AppId (API name)
- name: RecordIdentifier
in: path
required: true
description: Record identifier - can be a UUID (RecordId) or a human-readable slug (RecordSlug, 6-40 characters)
schema:
oneOf:
- type: string
format: uuid
title: Record UUID
- type: string
minLength: 6
maxLength: 40
pattern: ^(?!__)(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)[\w\-]+$
title: Record slug
examples:
uuid:
value: f6ce33ee-bdf2-4a23-87be-07de936ceeab
summary: Record UUID
slug:
value: my-record-slug
summary: Record slug
- name: limit
in: query
required: false
description: Limit of items per page
schema:
type: integer
format: int32
default: 50
- name: page
in: query
required: false
description: The number of the page to retrieve
schema:
type: integer
format: int32
minimum: 1
default: 1
- name: filters
in: query
required: false
schema:
type: string
description: |
An RSQL query to filter the results.
You can use these fields:
- fields configured as searchable
- `__id`
- `__schemaId`
- `__name`
- `__slug`
- `__status`
- `__updatedAt`
- `__createdAt`
- `__publishedAt`
- `__recordVersion`
- name: sortBy
description: |
You can change the default sorting. The sorting direction is selected by adding `asc` or `desc`, for example `sortBy=createdAt:desc`.
You can sort by:
- `appId`
- `displayName`
- `createdAt`
- `updatedAt`
in: query
required: false
style: form
explode: true
schema:
type: string
example: updatedAt:asc
default: updatedAt:desc
- name: statuses
in: query
description: Comma-separated list of record statuses to filter the results.
required: false
style: form
explode: false
schema:
type: string
enum:
- PUBLISHED
- DRAFT
- UNPUBLISHED
- SCHEDULED
responses:
"200":
description: A page of record versions
content:
application/json:
schema:
type: object
x-class-name: RecordVersionPagingResult
x-interface-name-ts: RecordVersionPagingResult
required:
- meta
- data
properties:
meta:
type: object
description: Pagination metadata
x-class-name: Meta
x-interface-name-ts: Meta
properties:
links:
type: array
description: Links to the neighboring pages and the first page
items:
type: object
x-class-name: Link
x-interface-name-ts: Link
required:
- url
- rel
properties:
url:
type: string
description: URL of the page, used for navigation
rel:
type: string
description: The type of relation to the current page. `first` is always the first page.
enum:
- first
- prev
- next
limit:
type: integer
format: int32
description: Limit of items per page
count:
type: integer
nullable: true
description: Currently unused
data:
type: array
description: Array of record versions
items:
x-class-name: RecordVersion
x-interface-name-ts: RecordVersion
allOf:
- type: object
properties:
versionId:
format: uuid
type: string
description: Unique identifier of a record version
- x-class-name: Record
x-interface-name-ts: Record
allOf:
- type: object
required:
- id
- schemaId
- values
- createdBy
- updatedBy
- createdAt
- updatedAt
- status
- recordVersion
properties:
id:
type: string
format: uuid
description: |
Unique identifier of a record, generated by the system. Can't be changed.
This identifier is common to all versions of the record, even when the slug changes.
In singleton-type schemas, use the schema's `appId` or `id` in place of record identifiers for generating content.
name:
type: string
maxLength: 255
minLength: 1
nullable: true
description: The name of the record. If not defined and there are no fields with `useAsRecordName = true`, GET requests return `Unnamed`.
schemaId:
type: string
format: uuid
description: Unique ID of the schema, generated automatically.
createdBy:
type: integer
format: int64
description: ID of the user who created the resource. If created by a workspace, the value is `0`.
updatedBy:
type: integer
format: int64
description: ID of the user who last updated the resource. If last updated by a workspace, the value is `0`.
publishedBy:
type: integer
format: int64
nullable: true
description: ID of the user who published the resource. If published by a workspace, the value is `0`.
deletedBy:
type: integer
format: int64
nullable: true
description: ID of the user who deleted the resource. If deleted by a workspace, the value is `0`.
createdAt:
type: string
format: date-time
description: Time when the resource was created
updatedAt:
type: string
format: date-time
description: Time when the resource was last updated
publishedAt:
type: string
format: date-time
nullable: true
description: Time when the resource was published
deletedAt:
type: string
format: date-time
nullable: true
description: Time when the resource was deleted
slug:
type: string
minLength: 6
maxLength: 40
pattern: ^([a-zA-Z0-9\-]|_[a-zA-Z0-9\-])[\w\-]*
description: |
Unique (within a schema) identifier of a record. Can't be a UUID.
In singleton-type schemas, use the schema's `appId` or `id` in place of record identifiers for generating content.
status:
type: string
x-class-name: RecordStatus
x-interface-name-ts: RecordStatus
description: |
Status of the record. When generating an object from a record, the last published version is used.
- In simple schemas, a record can only be published. Updates overwrite the record without changing the version number.
- In versioned schemas:
- A published record can't be edited directly. You need to send an update which changes to the draft status (this increases the version number, and the existing published version isn't modified), and then publish again.
- An unpublished record can't be published immediately. It must receive the draft status first.
- When unpublishing a record, you can't edit any data in the record.
enum:
- DRAFT
- SCHEDULED
- PUBLISHED
- UNPUBLISHED
values:
type: object
x-class-name: RecordValues
x-interface-name-ts: RecordValues
description: |
Values included in the record. Each key is the name of a field. The value must match the configuration of the field in the schema.
**Default values aren't explicitly saved in the record** or shown in GET requests which retrieve the record, but are returned when an object is generated from the record.
Supported value types:
- Float (number)
- Integer
- String
- Boolean
- Date (string, format: date)
- Date-time (string, format: date-time)
- Profile attribute (object with attributeName)
- Typed array
- UUID (string, format: uuid)
- Jinjava (string)
- Catalog (object with itemKey, id)
- Object (free-form)
- External source (empty object)
- One-to-one reference (string - record ID)
- One-to-many reference (array of record IDs)
- Analysis (string, format: uuid)
- Promotion (string - promotion ID)
- File/Image (string - file ID)
- Recommendation (object with id, params)
- Voucher (object with id)
- Untyped JSON (object)
- Untyped array
additionalProperties: true
example:
stringField: example string
numberField: 123.45
integerField: 42
booleanField: true
dateField: 2024-01-15
dateTimeField: 2024-01-15T10:30:00Z
uuidField: 550e8400-e29b-41d4-a716-446655440000
arrayField:
- item1
- item2
objectField:
key: value
profileAttribute:
attributeName: email
catalog:
itemKey: SKU123
id: catalog-id
recommendation:
id: recommendation-campaign-id
params:
itemId: item-123
schemaVersion:
type: integer
format: int32
description: The ID of the schema version that was used when this record was last updated. For simple schemas, this is always `1`.
recordVersion:
type: number
format: int32
description: |
Identifier of the record version.
- In simple schemas, this is always `1`
- In versioned schemas, the versions start with `1` on creation and are increased by 1 when you create a new draft. Publishing from a draft does NOT increase the version number.
schedule:
type: object
x-class-name: ScheduleEntry
x-interface-name-ts: ScheduleEntry
description: Time when the record is published - for example, every Monday, from 12:00 to 14:00
properties:
timezone:
type: string
description: Timezone of the schedule, as `UTC+offset` or according to the [tz database](https://en.wikipedia.org/wiki/Tz_database).
example: UTC+01:00
startType:
type: string
description: If `NOW`, the record is published immediately upon saving.
enum:
- NOW
- SCHEDULED
startDate:
type: string
description: Time when the schedule becomes active. If `startType` is NOW, this field is null.
format: date-time
endType:
type: string
description: Mode of inactivating the schedule
enum:
- NEVER
- DATE
endDate:
type: string
description: Time when the schedule becomes inactive, if `endType = DATE`
format: date-time
periodType:
type: string
description: |
Defines when the schedule applies within its activity period.
- ENTIRE: schedule is applied at all time since it becomes active until it becomes inactive.
- DAILY: schedule is active every day, at specific times
- WEEKLY: schedule is applied at specified days of the week (and optionally at specific times during those days)
- MONTHLY: schedule is applied at specified days of the month (and optionally at specific times during those days)
- WEEKDAY: schedule is applied on specified weekdays of a month; for example on the second Tuesday of each month
enum:
- ENTIRE
- DAILY
- WEEKLY
- MONTHLY
- WEEKDAY
parts:
type: array
description: |
An array of time rules that allow more granularity. All objects must match the period type set in `periodType` (for example, you cannot mix weekly and monthly conditions).
If `periodType` is `ENTIRE`, this array is empty.
items:
type: object
x-class-name: EntryScheduleRepeatPart
x-interface-name-ts: EntryScheduleRepeatPart
properties:
startDay:
type: integer
format: int32
example: 1
description: |
If `periodType` is:
- DAILY, the value is always 1.
- WEEKLY or WEEKDAY, the values are 1-7 (1 is Monday).
- MONTHLY, the values are 1-31 (days of the month).
**Note:**
If you want to define two time rules for a day (for example, the schedule is active on Monday at 06:00-07:00 and 15:00-16:00), create a separate `part` object for each time period.
startTime:
type: string
example: 08:18:03
description: The hour when the schedule becomes active.
endDay:
type: integer
format: int32
example: 1
description: Must be identical to `startDay`.
endTime:
type: string
example: 12:18:03
description: The hour when the schedule becomes inactive.
ordinal:
type: string
description: |
Applies only if `periodType` is WEEKDAY.
**Example:**
If you want a schedule to be active on every third Tuesday of the month, set `ordinal` to THIRD and `startDay` to 2.
**Note:**
If you want a schedule to be active on every second and third Tuesday, you must create two separate `part` objects.
enum:
- FIRST
- SECOND
- THIRD
- FOURTH
- FIFTH
- LAST
required:
- startDay
- startTime
- endDay
- endTime
enabled:
type: boolean
description: Defines if the schedule configuration is enabled. A schedule must be enabled in order to become active at the selected time.
required:
- timezone
- startType
- startDate
- endType
- enabled
"400":
description: Incorrect request (malformed JSON, wrong parameters, etc.). See error message for details.
content:
application/json:
schema:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
"401":
description: "Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc. See error message for details."
content:
application/json:
schema:
type: object
x-class-name: GatewayError
x-interface-name-ts: GatewayError
properties:
error:
type: string
description: Summary of the error
status:
type: integer
format: int32
description: Status code
timestamp:
type: string
description: Time when the message was sent
message:
type: string
description: Description of the problem
"403":
description: Forbidden; insufficient permissions. See error message for details.
content:
application/json:
schema:
type: object
x-class-name: GatewayError
x-interface-name-ts: GatewayError
properties:
error:
type: string
description: Summary of the error
status:
type: integer
format: int32
description: Status code
timestamp:
type: string
description: Time when the message was sent
message:
type: string
description: Description of the problem
"404":
description: Resource not found. See error message for details.
content:
application/json:
schema:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
"409":
description: The request could not be completed due to a conflict with the current state of the resource. See error message for details.
content:
application/json:
schema:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
"422":
description: The request was well-formed but could not be processed due to semantic or domain-related constraints. See error message for details.
content:
application/json:
schema:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
"500":
description: See error message for details.
content:
application/json:
schema:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
x-snr-doc-urls:
- /api-reference/brickworks#tag/Brickworks:-Record-versions/operation/getRecordVersions
servers:
- description: Microsoft Azure EU
url: https://api.synerise.com
- description: Microsoft Azure USA
url: https://api.azu.synerise.com
- description: Google Cloud Platform
url: https://api.geb.synerise.com
tags:
- name: "Brickworks: Record versions"
components:
schemas:
brickworks-service-ObjectsError:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
securitySchemes:
JWT:
type: http
scheme: bearer
description: |-
JWT Bearer token. The header looks like this: `Bearer {JWT}`
Remember to include the space between 'Bearer' and the token.
Generate a token via the **Authorization** endpoints.
```