> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an existing custom field

> Update an existing custom field

## OpenAPI

````json PUT /v1/teams/{team_id}/custom-fields/{custom_field_id}
{
  "openapi": "3.0.3",
  "info": {
    "title": "Management API Reference",
    "version": "2.0.0",
    "description": "API Documentation for the Supermetrics Management API. For more information, visit https://supermetrics.com.",
    "termsOfService": "https://supermetrics.com/terms-of-service",
    "contact": {
      "name": "Supermetrics Suppot",
      "email": "support@supermetrics.com",
      "url": "https://supermetrics.com/support"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "x-api-id": "sm-management-api",
    "x-audience": "public"
  },
  "servers": [
    {
      "url": "https://api.supermetrics.com/v2",
      "description": "Global production public Supermetrics Management API base path.",
      "x-internal": "false"
    },
    {
      "url": "https://api.supermetrics.com",
      "description": "Global production public Supermetrics API base path (for Connector Builder and Team endpoints).",
      "x-internal": "false"
    }
  ],
  "tags": [
    {
      "name": "API Keys",
      "description": "Manage API keys to access Supermetrics API"
    },
    {
      "name": "Data Source Logins",
      "description": "Access your data source authentications"
    },
    {
      "name": "Data Source Login Links",
      "description": "Create single-use data source login links"
    },
    {
      "name": "Saved Queries",
      "description": "Manage queries saved in Query Manager"
    },
    {
      "name": "Table Groups",
      "description": "Manage your team's table groups"
    },
    {
      "name": "Team Lists",
      "description": "Manage centralized team lists for your queries"
    },
    {
      "name": "Team Settings",
      "description": "Configure general settings for your team"
    },
    {
      "name": "Data Transfers",
      "description": "Create, configure, and manage Data Warehouse transfers"
    },
    {
      "name": "Transfer Runs",
      "description": "Monitor execution history of Data Warehouse transfers"
    },
    {
      "name": "Data Backfills",
      "description": "Manage historical data backfills for your Data Warehouse transfers"
    },
    {
      "name": "Data Destinations",
      "description": "Create, configure, and manage Data Warehouse destinations"
    },
    {
      "name": "Data Source Connections",
      "description": "Create and manage data source connections for Data Warehouse transfers"
    },
    {
      "name": "Data Blending",
      "description": "Create and manage Data Blending"
    },
    {
      "name": "Custom Fields",
      "description": "Create and manage Custom Fields"
    },
    {
      "name": "Connectors",
      "description": "Create and manage custom connectors"
    },
    {
      "name": "Connector Secrets",
      "description": "Manage encrypted secrets for connectors"
    },
    {
      "name": "Connector Logs",
      "description": "Access connector execution logs"
    },
    {
      "name": "Connector Logo",
      "description": "Manage connector logos"
    },
    {
      "name": "Connector Schema",
      "description": "Retrieve connector configuration schemas"
    },
    {
      "name": "Datasource",
      "description": "Retrieve datasource configuration details"
    }
  ],
  "externalDocs": {
    "description": "Find out more about Supermetrics Management API",
    "url": "https://docs.supermetrics.com/apidocs/management-api"
  },
  "paths": {
    "/v1/teams/{team_id}/custom-fields/{custom_field_id}": {
      "put": {
        "summary": "Update an existing custom field",
        "description": "Update an existing custom field",
        "operationId": "TeamTransformationController::updateTransformationAction",
        "x-middlewares": [
          {
            "name": "team-access-check",
            "options": {
              "team-id-param": "team_id"
            }
          },
          {
            "name": "permission-check",
            "options": {
              "permission-id": "custom_field.edit"
            }
          },
          {
            "name": "team-transformations-access-check"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/TeamId"
          },
          {
            "name": "custom_field_id",
            "in": "path",
            "required": "true",
            "description": "ID of the custom field",
            "example": "42",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": "1",
              "maximum": "9223372036854776000"
            }
          }
        ],
        "requestBody": {
          "required": "true",
          "description": "Payload for updating an existing custom field transformation",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomFieldUpdateRequest"
              },
              "example": {
                "display_name": "Spec Example Field Updated",
                "description": "Updated temporary transformation for spec examples",
                "data_type": "string.text.value",
                "definition": [
                  {
                    "type": "function",
                    "name": "upper_case",
                    "arguments": [
                      {
                        "name": "value",
                        "value": {
                          "type": "data_source_field",
                          "value": "platform"
                        }
                      }
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transformation updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleTransformationOutput"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Transformation not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFoundError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "security": [
          {
            "BearerAuth": [
              "custom_fields_write"
            ]
          }
        ],
        "tags": [
          "Custom Fields"
        ]
      }
    }
  },
  "components": {
    "parameters": {
      "TeamId": {
        "name": "team_id",
        "in": "path",
        "description": "ID of the team",
        "required": "true",
        "schema": {
          "type": "integer",
          "format": "int64",
          "minimum": "1",
          "maximum": "9223372036854776000"
        },
        "example": "936506"
      }
    },
    "schemas": {
      "CustomFieldUpdateRequest": {
        "type": "object",
        "description": "Payload for updating an existing custom field. The `field_type` cannot be changed and is therefore omitted.",
        "required": [
          "display_name",
          "data_type",
          "definition"
        ],
        "properties": {
          "display_name": {
            "type": "string",
            "maxLength": "255",
            "pattern": "^.+$",
            "description": "User-facing name of the custom field shown in the UI.",
            "example": "Spec Example Field Updated"
          },
          "description": {
            "type": "string",
            "maxLength": "2048",
            "pattern": "^.+$",
            "description": "Free-text description of the custom field.",
            "example": "Updated temporary transformation for spec examples"
          },
          "data_type": {
            "type": "string",
            "maxLength": "100",
            "pattern": "^(bool|(float|int|string)(\\.[a-z]+)+)$",
            "description": "Data type of the custom field (e.g. string.text.value, float.number.value, int.number.value, bool).",
            "example": "string.text.value"
          },
          "definition": {
            "type": "array",
            "maxItems": "100",
            "description": "Ordered pipeline of transformation steps (function, lookup, or condition) used to compute the custom field.",
            "items": {
              "$ref": "#/components/schemas/TransformationStep"
            },
            "example": [
              {
                "type": "function",
                "name": "upper_case",
                "arguments": [
                  {
                    "name": "value",
                    "value": {
                      "type": "data_source_field",
                      "value": "platform"
                    }
                  }
                ]
              }
            ]
          }
        }
      },
      "SingleTransformationOutput": {
        "description": "Success envelope wrapping a single custom field transformation.",
        "allOf": [
          {
            "$ref": "#/components/schemas/AbstractResponse"
          },
          {
            "type": "object",
            "required": [
              "data"
            ],
            "properties": {
              "data": {
                "$ref": "#/components/schemas/TeamTransformationOutput"
              }
            }
          }
        ],
        "example": {
          "meta": {
            "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "data": {
            "id": "42",
            "name": "spec_example_field",
            "data_source_id": "GAWA",
            "display_name": "Spec Example Field",
            "description": "Temporary transformation for spec examples",
            "field_type": "dim",
            "data_type": "string.text.value",
            "modified_time_utc": "2026-04-06T10:59:04+00:00",
            "modified_user": {
              "email": "user@supermetrics.com",
              "first_name": "John",
              "last_name": "Doe"
            },
            "definition": {
              "items": [
                {
                  "type": "function",
                  "name": "upper_case",
                  "arguments": [
                    {
                      "name": "value",
                      "value": {
                        "type": "data_source_field",
                        "value": "platform"
                      }
                    }
                  ],
                  "description": null
                }
              ]
            },
            "report_types": [
              "Default"
            ]
          }
        }
      },
      "NotFoundError": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "maxLength": "255",
            "pattern": "^.+$",
            "description": "Not found"
          },
          "code": {
            "type": "string",
            "enum": [
              "NOT_FOUND"
            ],
            "description": "NOT_FOUND"
          }
        }
      },
      "TransformationStep": {
        "description": "A single step in a custom field's transformation pipeline. The concrete shape is selected by the `type` discriminator: `function`, `lookup`, or `condition`.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/FunctionStep"
          },
          {
            "$ref": "#/components/schemas/LookupStep"
          },
          {
            "$ref": "#/components/schemas/ConditionStep"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "function": "#/components/schemas/FunctionStep",
            "lookup": "#/components/schemas/LookupStep",
            "condition": "#/components/schemas/ConditionStep"
          }
        }
      },
      "AbstractResponse": {
        "type": "object",
        "description": "Base envelope for all successful API responses. Concrete responses extend this via `allOf` and add a `data` property.",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "meta"
        ]
      },
      "TeamTransformationOutput": {
        "type": "object",
        "description": "A persisted custom field (field transformation) as returned by read operations.",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "minimum": "1",
            "maximum": "9223372036854776000",
            "example": "42",
            "description": "Unique identifier of the custom field."
          },
          "name": {
            "type": "string",
            "maxLength": "255",
            "pattern": "^[A-Za-z0-9_-]+$",
            "example": "spec_example_field",
            "description": "Unique machine name of the field transformation."
          },
          "data_source_id": {
            "type": "string",
            "maxLength": "100",
            "pattern": "^[a-zA-Z0-9_]{2,5}$",
            "example": "GAWA",
            "description": "ID of the data source the transformation belongs to."
          },
          "display_name": {
            "type": "string",
            "maxLength": "255",
            "pattern": "^.+$",
            "example": "Spec Example Field Updated",
            "description": "User-facing name of the transformation shown in the UI."
          },
          "description": {
            "type": "string",
            "maxLength": "2048",
            "pattern": "^.*$",
            "example": "Updated temporary transformation for spec examples",
            "description": "Free-text description of the transformation."
          },
          "field_type": {
            "type": "string",
            "enum": [
              "dim",
              "met"
            ],
            "example": "dim",
            "description": "Field kind: `dim` (dimension) or `met` (metric)."
          },
          "data_type": {
            "type": "string",
            "maxLength": "100",
            "pattern": "^(bool|(float|int|string)(\\.[a-z]+)+)$",
            "example": "string.text.value",
            "description": "Data type of the transformed field."
          },
          "modified_time_utc": {
            "type": "string",
            "format": "date-time",
            "maxLength": "32",
            "description": "Timestamp of the last modification, in UTC. Serialized with a numeric offset (e.g. \"+0000\") rather than a trailing \"Z\".",
            "example": "2026-04-06T10:59:04+00:00"
          },
          "modified_user": {
            "$ref": "#/components/schemas/TransformationUserOutput"
          },
          "definition": {
            "type": "object",
            "description": "Wrapper holding the ordered transformation steps.",
            "properties": {
              "items": {
                "type": "array",
                "maxItems": "100",
                "description": "The ordered pipeline of transformation steps.",
                "example": [
                  {
                    "type": "function",
                    "name": "upper_case",
                    "arguments": [
                      {
                        "name": "value",
                        "value": {
                          "type": "data_source_field",
                          "value": "platform"
                        }
                      }
                    ]
                  }
                ],
                "items": {
                  "$ref": "#/components/schemas/TransformationStep"
                }
              }
            }
          },
          "report_types": {
            "type": "array",
            "maxItems": "100",
            "description": "Report types associated with the transformation.",
            "example": [
              "Default"
            ],
            "items": {
              "type": "string",
              "maxLength": "100",
              "pattern": "^.+$",
              "description": "A single report type name."
            }
          }
        },
        "example": {
          "id": "42",
          "name": "spec_example_field",
          "data_source_id": "GAWA",
          "display_name": "Spec Example Field Updated",
          "description": "Updated temporary transformation for spec examples",
          "field_type": "dim",
          "data_type": "string.text.value",
          "modified_time_utc": "2026-04-06T10:59:04+00:00",
          "modified_user": {
            "email": "user@supermetrics.com",
            "first_name": "John",
            "last_name": "Doe"
          },
          "definition": {
            "items": [
              {
                "type": "function",
                "name": "upper_case",
                "arguments": [
                  {
                    "name": "value",
                    "value": {
                      "type": "data_source_field",
                      "value": "platform"
                    }
                  }
                ],
                "description": null
              }
            ]
          },
          "report_types": [
            "Default"
          ]
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard envelope returned by all error (4xx/5xx) responses.",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        },
        "required": [
          "meta",
          "error"
        ],
        "additionalProperties": "false"
      },
      "FunctionStep": {
        "type": "object",
        "description": "A transformation step that applies a named function to its arguments.",
        "required": [
          "type",
          "name",
          "arguments"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "function"
            ],
            "example": "function",
            "description": "Discriminator value identifying this step as a function step."
          },
          "name": {
            "type": "string",
            "maxLength": "255",
            "pattern": "^[A-Za-z0-9_-]+$",
            "example": "upper_case",
            "description": "Name of the function to apply."
          },
          "arguments": {
            "type": "array",
            "maxItems": "100",
            "description": "Arguments passed to this function.",
            "items": {
              "$ref": "#/components/schemas/FunctionArgument"
            }
          },
          "description": {
            "type": "string",
            "maxLength": "2048",
            "pattern": "^[\\s\\S]+$",
            "nullable": "true",
            "description": "Optional free-text description of the transformation step.",
            "example": null
          }
        },
        "example": {
          "type": "function",
          "name": "upper_case",
          "arguments": [
            {
              "name": "value",
              "value": {
                "type": "data_source_field",
                "value": "platform"
              }
            }
          ],
          "description": null
        }
      },
      "LookupStep": {
        "type": "object",
        "description": "A transformation step that maps input values to output values using a key/value lookup table and a matching rule.",
        "required": [
          "type",
          "rule",
          "map"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "lookup"
            ],
            "example": "lookup",
            "description": "Discriminator value identifying this step as a lookup step."
          },
          "source": {
            "$ref": "#/components/schemas/DefinitionValue"
          },
          "rule": {
            "type": "string",
            "maxLength": "100",
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "The matching rule applied when looking up a value (e.g. equals).",
            "example": "equals"
          },
          "map": {
            "type": "object",
            "description": "Key/value mapping table used by the lookup.",
            "additionalProperties": {
              "type": "string",
              "maxLength": "2048",
              "description": "Output value produced for the matching key."
            },
            "example": {
              "1": "2",
              "a": "b"
            }
          },
          "default": {
            "$ref": "#/components/schemas/DefinitionValue"
          },
          "description": {
            "type": "string",
            "maxLength": "2048",
            "pattern": "^[\\s\\S]+$",
            "nullable": "true",
            "description": "Optional free-text description of the transformation step.",
            "example": null
          }
        }
      },
      "ConditionStep": {
        "type": "object",
        "description": "A transformation step that evaluates an ordered list of cases and returns the result of the first matching case, falling back to `default` when none match.",
        "required": [
          "type",
          "cases",
          "default"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "condition"
            ],
            "example": "condition",
            "description": "Discriminator value identifying this step as a condition step."
          },
          "default": {
            "description": "Value returned when no case matches. May be a plain DefinitionValue or a nested FunctionStep.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/DefinitionValue"
              },
              {
                "$ref": "#/components/schemas/FunctionStep"
              }
            ]
          },
          "cases": {
            "type": "array",
            "maxItems": "100",
            "description": "Condition cases evaluated in order; the first match wins.",
            "items": {
              "$ref": "#/components/schemas/ConditionCase"
            }
          },
          "description": {
            "type": "string",
            "maxLength": "2048",
            "pattern": "^[\\s\\S]+$",
            "nullable": "true",
            "description": "Optional free-text description of the transformation step.",
            "example": null
          }
        }
      },
      "Meta": {
        "type": "object",
        "description": "Metadata included in every API response.",
        "properties": {
          "request_id": {
            "$ref": "#/components/schemas/RequestId"
          }
        },
        "required": [
          "request_id"
        ],
        "additionalProperties": "false"
      },
      "TransformationUserOutput": {
        "type": "object",
        "description": "The user who last modified a custom field transformation.",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": "254",
            "description": "Email address of the user.",
            "example": "user@supermetrics.com"
          },
          "first_name": {
            "type": "string",
            "maxLength": "100",
            "pattern": "^.+$",
            "description": "First name of the user.",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "maxLength": "100",
            "pattern": "^.+$",
            "description": "Last name of the user.",
            "example": "Doe"
          }
        },
        "example": {
          "email": "user@supermetrics.com",
          "first_name": "John",
          "last_name": "Doe"
        }
      },
      "Error": {
        "type": "object",
        "description": "Machine- and human-readable detail for a failed request.",
        "properties": {
          "code": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]*$",
            "maxLength": "100",
            "description": "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.",
            "example": "BAD_REQUEST"
          },
          "message": {
            "type": "string",
            "maxLength": "255",
            "pattern": "^.+$",
            "description": "Short, human-readable summary of the error.",
            "example": "The request was invalid."
          },
          "description": {
            "type": "string",
            "maxLength": "2048",
            "description": "Optional longer explanation specific to this occurrence.",
            "example": "The field 'display_name' must not be empty."
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": "false"
      },
      "FunctionArgument": {
        "type": "object",
        "description": "A named argument supplied to a function step.",
        "required": [
          "name",
          "value"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": "255",
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "Argument name as expected by the function.",
            "example": "value"
          },
          "value": {
            "$ref": "#/components/schemas/DefinitionValue"
          }
        },
        "example": {
          "name": "value",
          "value": {
            "type": "data_source_field",
            "value": "platform"
          }
        }
      },
      "DefinitionValue": {
        "type": "object",
        "description": "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.",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "data_source_field",
              "output_from_previous",
              "static"
            ],
            "description": "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).",
            "example": "data_source_field"
          },
          "value": {
            "type": "string",
            "maxLength": "255",
            "description": "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`.",
            "example": "platform"
          }
        },
        "example": {
          "type": "data_source_field",
          "value": "platform"
        }
      },
      "ConditionCase": {
        "type": "object",
        "description": "A single case within a condition step: when `condition` evaluates true, the `return` value is produced.",
        "required": [
          "return",
          "condition"
        ],
        "properties": {
          "return": {
            "$ref": "#/components/schemas/DefinitionValue"
          },
          "condition": {
            "type": "object",
            "description": "The rule-based condition evaluated for this case.",
            "required": [
              "type",
              "rule",
              "source",
              "target"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "rule"
                ],
                "description": "Discriminator value identifying the condition kind (always `rule`).",
                "example": "rule"
              },
              "rule": {
                "type": "string",
                "maxLength": "100",
                "pattern": "^[A-Za-z0-9_-]+$",
                "description": "The comparison operator applied between `source` and `target`.",
                "example": "equals"
              },
              "source": {
                "$ref": "#/components/schemas/DefinitionValue"
              },
              "target": {
                "$ref": "#/components/schemas/DefinitionValue"
              }
            }
          }
        },
        "example": {
          "return": {
            "type": "output_from_previous"
          },
          "condition": {
            "type": "rule",
            "rule": "equals",
            "source": {
              "type": "output_from_previous"
            },
            "target": {
              "type": "static",
              "value": "1"
            }
          }
        }
      },
      "RequestId": {
        "type": "string",
        "description": "Unique identifier for the request, for tracking and debugging.",
        "pattern": "^[A-Za-z0-9_-]+$",
        "minLength": "8",
        "maxLength": "64",
        "example": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN",
        "x-faker": {
          "random.alphaNumeric": "30"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request - invalid parameters",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "BAD_REQUEST",
                "message": "The request was invalid."
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized",
        "headers": {
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WWW-Authenticate"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "UNAUTHORIZED",
                "message": "Authentication is required."
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Access forbidden",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "FORBIDDEN",
                "message": "You do not have access to this resource."
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "TOO_MANY_REQUESTS",
                "message": "Rate limit exceeded. Retry later."
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal server error",
        "headers": {
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "INTERNAL_SERVER_ERROR",
                "message": "An unexpected error occurred."
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "otok",
        "description": "Bearer token authentication. Include the token in the Authorization header:\n`Authorization: Bearer <your-token>`\n"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "description": "Request limit per hour",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": "1",
          "maximum": "10000",
          "example": "5000"
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Remaining requests in current window",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": "0",
          "maximum": "10000",
          "example": "4999"
        }
      },
      "Access-Control-Allow-Origin": {
        "description": "CORS header",
        "schema": {
          "type": "string",
          "maxLength": "255",
          "enum": [
            "*"
          ],
          "example": "*"
        }
      },
      "WWW-Authenticate": {
        "description": "Bearer token required",
        "schema": {
          "type": "string",
          "maxLength": "255",
          "pattern": "^Bearer.*"
        }
      },
      "Retry-After": {
        "description": "Seconds until rate limit resets",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": "1",
          "maximum": "86400",
          "example": "3600"
        }
      }
    }
  }
}
````