Xentral Report API
Create, manage and export reports and report results based on SQL queries against your data.
OpenAPI Specification
openapi: 3.0.0
info:
title: Xentral Account Report API
version: v0.1
description: Xentral is an ERP platform.
contact:
name: Xentral
url: https://xentral.com
email: api@xentral.com
servers:
- url: https://{xentralId}.xentral.biz
description: Your Xentral Instance
variables:
xentralId:
default: xentral
- url: https://{domain}
description: Xentral at a custom domain
variables:
domain:
default: xentral.com
security:
- BearerAuth: []
tags:
- name: Report
description: Create, manage and export reports and report results based on SQL queries against your data.
paths:
/api/v1/analytics/report:
get:
tags:
- Report
operationId: analytics.report.list
summary: List reports
description: Returns a list of reports (official Xentral reports and custom reports)
responses:
'200':
description: Report response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- data
properties:
data:
type: array
nullable: true
items:
type: object
additionalProperties: false
required:
- title
- sqlString
- collectionId
properties:
id:
type: number
description: Report ID
example: 1
title:
type: string
description: Report title
example: My report
description:
type: string
description: Report description
example: This is my report
userId:
type: number
description: User ID of the report creator
example: 1
sqlString:
type: string
description: SQL query string
example: SELECT * FROM users
isFavorite:
type: boolean
description: Is report marked as favorite
example: true
isReadOnly:
example: false
type: boolean
description: Is report read-only
collectionId:
example: 1
type: number
description: ID of the collection the report belongs to
lastEditedBy:
example: John Doe
type: string
description: User who last edited the report
tags:
type: array
example:
- id: 1
name: Official
description: This is my tag
palette: default
isOfficial: true
createdAt: '2023-01-01T00:00:00+00:00'
updatedAt: '2023-01-01T00:00:00+00:00'
items:
type: object
additionalProperties: false
required:
- id
- name
properties:
id:
type: number
description: Tag ID
example: 1
name:
type: string
description: Tag name
example: Official
description:
type: string
description: Tag description
example: This is my tag
palette:
type: string
enum:
- default
- warning
- success
- danger
- primary
description: The palette value of the tag
example: default
isOfficial:
type: boolean
description: Whether the tag is used for official Xentral reports
example: true
createdAt:
example: '2023-01-01T00:00:00+00:00'
type: string
format: date-time
description: Creation time
updatedAt:
example: '2023-01-01T00:00:00+00:00'
type: string
format: date-time
description: Last update time
parameters:
type: array
nullable: true
items:
type: object
additionalProperties: false
required:
- name
- type
- defaultValue
example:
name: date
type: string
defaultValue: '2021-01-01'
properties:
name:
type: string
description: Parameter name
example: date
type:
type: string
description: Parameter type
example: string
defaultValue:
type: string
description: Default value for parameter you want to store
example: '2021-01-01'
valueMap:
type: array
description: Array of dropdown options with label and value properties. Values will be rendered in the query, labels are displayed in the dropdown.
items:
type: object
required:
- label
- value
properties:
label:
type: string
description: Display label shown in the dropdown
value:
type: string
description: Value used in the query
example:
- label: Option 1
value: option1
- label: Option 2
value: option2
createdAt:
example: '2023-01-01T00:00:00+00:00'
type: string
format: date-time
description: Creation time
updatedAt:
example: '2023-01-01T00:00:00+00:00'
type: string
format: date-time
description: Last update time
'400':
description: IETF RFC 9457 Problem API compliant response
content:
application/problem+json:
schema:
oneOf:
- type: object
additionalProperties: false
required:
- type
- title
- violations
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/request-validation
title:
type: string
minLength: 1
example: Request payload validation failed.
violations:
oneOf:
- type: array
items:
type: object
example:
username:
- This value should not be blank.
email:
- This value is not a valid email address.
description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
- type: object
example:
_:
- This value should contain at most `9` elements.
description: This field will be a mirrored request payload with only invalid fields and values replaced by error messages.
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/generic-validation
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/conflict
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- items
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/conflictItems
title:
type: string
minLength: 1
items:
type: array
items:
type: object
additionalProperties: false
required:
- id
- title
- messages
properties:
id:
type: integer
title:
type: string
minLength: 1
messages:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- scopes
properties:
type:
type: string
enum:
- https://developer.xentral.com/reference/problems#token-scopes
title:
type: string
minLength: 1
scopes:
type: array
items:
type: string
- type: object
additionalProperties: false
required:
- type
- title
- messages
properties:
type:
type: string
enum:
- https://api.xentral.biz/problems/generic-validation
title:
type: string
minLength: 1
messages:
type: object
additionalProperties:
type: array
items:
type: string
'401':
description: Unable to authenticate the client
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message explaining why the request failed.
example: 'Missing required scopes: customer:create.'
example:
message: 'Missing required scopes: customer:create.'
text/html:
schema:
type: string
example: Unauthorized
'403':
description: Unable to authorize the client
'404':
description: Resource was not found or not enough access privileges
'415':
description: Resource representation send in the request is not supported.
post:
tags:
- Report
operationId: analytics.report.create
summary: Create report
description: Creates a new report and returns the new record
requestBody:
description: Create report request payload
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- report
example:
report:
title: My report
description: This is my report
userId: 1
sqlString: SELECT * FROM users
isFavorite: true
isReadOnly: false
collectionId: 1
parameters:
- name: date
type: string
defaultValue: '2021-01-01'
properties:
report:
type: object
additionalProperties: false
required:
- title
- collectionId
properties:
title:
type: string
description: Report title
example: My report
description:
type: string
description: Report description
example: This is my report
userId:
type: number
description: User ID of the report creator
example: 1
sqlString:
type: string
description: SQL query string
example: SELECT * FROM users
isFavorite:
type: boolean
description: Is report marked as favorite
example: true
isReadOnly:
type: boolean
description: Is report read-only
example: false
collectionId:
type: number
description: ID of the collection the report belongs to
example: 1
parameters:
type: array
nullable: true
items:
type: object
additionalProperties: false
required:
- name
- type
- defaultValue
example:
name: date
type: string
defaultValue: '2021-01-01'
properties:
name:
type: string
description: Parameter name
example: date
type:
type: string
description: Parameter type
example: string
defaultValue:
type: string
description: Default value for parameter you want to store
example: '2021-01-01'
valueMap:
type: array
description: Array of dropdown options with label and value properties. Values will be rendered in the query, labels are displayed in the dropdown.
items:
type: object
required:
- label
- value
properties:
label:
type: string
description: Display label shown in the dropdown
value:
type: string
description: Value used in the query
example:
- label: Option 1
value: option1
- label: Option 2
value: option2
examples:
example:
summary: Example report payload
value:
report:
title: My report
description: This is my report
userId: 1
sqlString: SELECT * FROM users
isFavorite: true
isReadOnly: false
collectionId: 1
parameters:
- name: date
type: string
defaultValue: '2021-01-01'
responses:
'200':
description: Report response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- data
properties:
data:
type: array
nullable: true
items:
type: object
additionalProperties: false
required:
- title
- sqlString
- collectionId
properties:
id:
type: number
description: Report ID
example: 1
title:
type: string
description: Report title
example: My report
description:
type: string
description: Report description
example: This is my report
userId:
type: number
description: User ID of the report creator
example: 1
sqlString:
type: string
description: SQL query string
example: SELECT * FROM users
isFavorite:
type: boolean
description: Is report marked as favorite
example: true
isReadOnly:
example: false
type: boolean
description: Is report read-only
collectionId:
example: 1
type: number
description: ID of the collection the report belongs to
lastEditedBy:
example: John Doe
type: string
description: User who last edited the report
tags:
type: array
example:
- id: 1
name: Official
description: This is my tag
palette: default
isOfficial: true
createdAt: '2023-01-01T00:00:00+00:00'
updatedAt: '2023-01-01T00:00:00+00:00'
items:
type: object
additionalProperties: false
required:
- id
- name
properties:
id:
type: number
description: Tag ID
example: 1
name:
type: string
description: Tag name
example: Official
description:
type: string
description: Tag description
example: This is my tag
palette:
type: string
enum:
- default
- warning
- success
- danger
- primary
description: The palette value of the tag
example: default
isOfficial:
type: boolean
description: Whether the tag is used for official Xentral reports
example: true
createdAt:
example: '2023-01-01T00:00:00+00:00'
type: string
format: date-time
description: Creation time
updatedAt:
example: '2023-01-01T00:00:00+00:00'
type: string
format: date-time
description: Last update time
parameters:
type: array
nullable: true
items:
type: object
additionalProperties: false
required:
- name
- type
- defaultValue
example:
name: date
type: string
defaultValue: '2021-01-01'
properties:
name:
type: string
description: Parameter name
example: date
type:
type: string
description: Parameter type
example: string
defaultValue:
type: string
description: Default value for parameter you want to store
example: '2021-01-01'
valueMap:
type: array
description: Array of dropdown options with label and value properties. Values will be rendered in the query, labels are displayed in the dropdown.
items:
type: object
required:
- label
- value
properties:
label:
type: string
description: Display label shown in the dropdown
value:
type: string
description: Value used in the query
example:
- label: Option 1
value: option1
- label: Option 2
value: option2
createdAt:
example: '2023-01-01T00:00:00+00:00'
type: string
format: date-time
description: Creation time
updatedAt:
example: '2023-01-01T00:00:00+00:00'
type: string
format: date-time
description: Last update time
'400':
description: Error response with message
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- message
properties:
message:
description: Error message
type: string
example: SQL statement is invalid
'401':
description: Unable to authenticate the client
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message explaining why the request failed.
example: 'Missing required scopes: customer:create.'
example:
message: 'Missing required scopes: customer:create.'
text/html:
schema:
type: string
example: Unauthorized
'403':
description: Unable to authorize the client
'404':
description: Resource was not found or not enough access privileges
'415':
description: Resource representation send in the request is not supported.
/api/v1/analytics/report/{id}:
get:
tags:
- Report
operationId: analytics.report.get
summary: View report
description: Returns a single report by ID
parameters:
- in: path
name: id
required: true
description: The resource's identifier.
schema:
type: string
pattern: \d+
example: '17'
description: Resource identifier.
responses:
'200':
description: Report response
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- data
properties:
data:
type: array
nullable: true
items:
type: object
additionalProperties: false
required:
- title
- sqlString
- collectionId
properties:
id:
type: number
description: Report ID
example: 1
title:
type: string
description: Report title
example: My report
description:
type: string
description: Report description
example: This is my report
userId:
type: number
description: User ID of the report creator
example: 1
sqlString:
type: string
description: SQL query string
example: SELECT * FROM users
isFavorite:
type: boolean
description: Is report marked as favorite
example: true
isReadOnly:
example: false
type: boolean
description: Is report read-only
collectionId:
example: 1
type: number
description: ID of the collection the report belongs to
lastEditedBy:
example: John Doe
type: string
description: User who last edited the report
tags:
type: array
example:
- id: 1
name: Official
description: This is my tag
palette: default
isOfficial: true
createdAt: '2023-01-01T00:00:00+00:00'
updatedAt: '2023-01-01T00:00:00+00:00'
items:
type: object
additionalProperties: false
required:
- id
- name
properties:
id:
type: number
description: Tag ID
example: 1
name:
type: string
description: Tag name
example: Official
description:
type: string
description: Tag description
example: This is my tag
palette:
type: string
enum:
- default
- warning
# --- truncated at 32 KB (185 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xentral/refs/heads/main/openapi/xentral-report-api-openapi.yml