Create a new custom field. Returns HTTP 201 Created with the created resource.
API key authentication. Create API keys in the Supermetrics Hub and send
them in the Authorization header:
Authorization: Bearer <your-api-key>
Application identifier
ID of the team
Payload for creating a new custom field transformation
{
"display_name": "Spec Example Field",
"description": "Temporary transformation for spec examples",
"field_type": "dim",
"data_type": "string.text.value",
"definition": [
{
"type": "function",
"name": "upper_case",
"arguments": [
{
"name": "value",
"value": {
"type": "data_source_field",
"value": "platform"
}
}
]
}
]
}Payload for creating a new custom field (field transformation).
Data sources associated with the custom field. Each entry pairs a data source ID with an optional report type.
A data source (and optional report type) the custom field applies to.
ID of the data source.
Report type associated with the data source, if any.
User-facing name of the new custom field shown in the UI.
Free-text description of the new custom field.
Field kind: dim (dimension) or met (metric).
Data type of the custom field (e.g. string.text.value, float.number.value, int.number.value, bool).
Ordered pipeline of transformation steps (function, lookup, or condition) used to compute the custom field.
A single step in a custom field's transformation pipeline. The concrete shape is selected by the type discriminator: function, lookup, or condition.
Discriminator value identifying this step as a function step.
Name of the function to apply.
Arguments passed to this function.
A named argument supplied to a function step.
Argument name as expected by the function.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
Optional free-text description of the transformation step.
Discriminator value identifying this step as a lookup step.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
The matching rule applied when looking up a value (e.g. equals).
Key/value mapping table used by the lookup.
Output value produced for the matching key.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
Optional free-text description of the transformation step.
Discriminator value identifying this step as a condition step.
Value returned when no case matches. May be a plain DefinitionValue or a nested FunctionStep.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
Discriminator value identifying this step as a function step.
Name of the function to apply.
Arguments passed to this function.
A named argument supplied to a function step.
Argument name as expected by the function.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
Optional free-text description of the transformation step.
Condition cases evaluated in order; the first match wins.
A single case within a condition step: when condition evaluates true, the return value is produced.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
The rule-based condition evaluated for this case.
Discriminator value identifying the condition kind (always rule).
The comparison operator applied between source and target.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
Optional free-text description of the transformation step.
Transformation successfully created
Success envelope wrapping a single custom field transformation.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
A persisted custom field (field transformation) as returned by read operations.
Unique identifier of the custom field.
Unique machine name of the field transformation.
ID of the data source the transformation belongs to.
User-facing name of the transformation shown in the UI.
Free-text description of the transformation.
Field kind: dim (dimension) or met (metric).
Data type of the transformed field.
Timestamp of the last modification, in UTC. Serialized with a numeric offset (e.g. "+0000") rather than a trailing "Z".
The user who last modified a custom field transformation.
Email address of the user.
First name of the user.
Last name of the user.
Wrapper holding the ordered transformation steps.
The ordered pipeline of transformation steps.
A single step in a custom field's transformation pipeline. The concrete shape is selected by the type discriminator: function, lookup, or condition.
Discriminator value identifying this step as a function step.
Name of the function to apply.
Arguments passed to this function.
A named argument supplied to a function step.
Argument name as expected by the function.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
Optional free-text description of the transformation step.
Discriminator value identifying this step as a lookup step.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
The matching rule applied when looking up a value (e.g. equals).
Key/value mapping table used by the lookup.
Output value produced for the matching key.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
Optional free-text description of the transformation step.
Discriminator value identifying this step as a condition step.
Value returned when no case matches. May be a plain DefinitionValue or a nested FunctionStep.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
Discriminator value identifying this step as a function step.
Name of the function to apply.
Arguments passed to this function.
A named argument supplied to a function step.
Argument name as expected by the function.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
Optional free-text description of the transformation step.
Condition cases evaluated in order; the first match wins.
A single case within a condition step: when condition evaluates true, the return value is produced.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
The rule-based condition evaluated for this case.
Discriminator value identifying the condition kind (always rule).
The comparison operator applied between source and target.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
A value reference used in transformation steps. Depending on type the value is read from a data-source field, taken from the previous step's output, or supplied as a static literal.
Where the value comes from: data_source_field (a named field on the data source), output_from_previous (the result of the preceding step), or static (a literal value).
The value itself: the field name when type is data_source_field, a literal when type is static, and omitted when type is output_from_previous.
Optional free-text description of the transformation step.
Report types associated with the transformation.
A single report type name.
Bad request - invalid parameters
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "BAD_REQUEST",
"message": "The request was invalid."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.
Unauthorized
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.
Permission denied
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "PERMISSION_ERROR",
"message": "You do not have permission to perform this action."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.
Resource not found
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.
Too Many Requests
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "Rate limit exceeded. Retry later."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.
Internal server error
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.