openapi: 3.1.0
info:
  title: Aghanim Server-to-Server Achievements Item Categories API
  description: "The Aghanim Server-to-Server API is designed for **backend server integrations only**. Use this API when you need to automate game hub updates from your server-side applications.\n\n\n## OpenAPI Specification\n\nYou can download the [OpenAPI](https://www.openapis.org/) specification for this API at the following link:\n[docs.aghanim.com/openapi.json](https://docs.aghanim.com/openapi.json).\n\n## Changelog\n\nSee the [S2S API Changelog](https://docs.aghanim.com/s2s-api/changelog/) for a history of changes to this API.\n\n## Authentication\n\nAghanim supports two methods of authentication: **Bearer token** and **Basic authentication**.\n\nTo authenticate, you will need your API key, which can be retrieved from\nthe Aghanim Dashboard → [**Game → Integration → API Keys**](https://dashboard.aghanim.com/go/integration/api-keys).\n\n**⚠️ Security Notice**: The S2S API key is **secret** and must be kept secure on your server. Never expose the S2S API key in client-side code, mobile apps, or any public-facing applications.\n\n### Bearer Token Authentication\n\nUse the Bearer method by including an `Authorization` header with the word `Bearer`\nfollowed by your API key. The `Authorization` header in your HTTP request should look like this: `Authorization: Bearer API_KEY`\n\n### Basic Authentication\n\nAlternatively, you can authenticate using Basic authentication. Your API key is used\nas the `username`, and the `password` should be left empty. Send an `Authorization`\nheader with the word `Basic` followed by a base64-encoded string\nin the format `API_KEY:` (note the colon at the end).\n\nThe `Authorization` header should look like this: `Authorization: Basic ZGVtbzpwQDU1dzByZA==`\n\n## Error Codes\n\nAghanim employs standard HTTP response codes to denote the success or failure of an API request.\nBelow is a table detailing error codes.\n\n| Code | Description |\n| ---- | ----------- |\n| 200  | OK          |\n| 400  | Bad request |\n| 401  | Not authenticated |\n| 403  | Not authorized |\n| 404  | Resource not found |\n| 409  | Conflict. Request conflicts with current state of resource |\n| 422  | Validation error |\n| 429  | Too many requests. Rate limit exceeded |\n| 503  | Server unavailable |\n\n### Generic error schema\n\n```json\n{\n  \"detail\": \"string\"\n}\n```\n\n### Validation error schema\n\n```json\n{\n  \"detail\": [\n    {\n      \"loc\": [\n        \"string\",\n        0\n      ],\n      \"msg\": \"string\",\n      \"type\": \"string\"\n    }\n  ]\n}\n```\n\n## Rate Limits\n\nThe Aghanim API has rate limiting in place to avoid overloading and to ensure it remains stable.\nThe allowable rate of requests is capped at 1,000 per minute for every game.\nGame developers who exceed this limit will receive a 429 error code.\n\nTo increase the rate limit, please contact us via [integration@aghanim.com](mailto:integration@aghanim.com).\n\n## Pagination\n\nIn the Aghanim API, pagination is managed through the use of the `limit` and `offset` query parameters.\nThese parameters allow to fine-tune your data retrieval requests by specifying:\n\n- `limit`: the number of records to be returned in a single request.\n- `offset`: indicates the number of records to skip from the start of the dataset.\n"
  contact:
    name: Aghanim
    email: integration@aghanim.com
  version: 2026.07.14
servers:
- url: https://api.aghanim.com/s2s
  description: Production
tags:
- name: Item Categories
paths:
  /v1/item_categories/{item_category_id}:
    get:
      tags:
      - Item Categories
      summary: Get Item Category
      operationId: get_item_category
      security:
      - HTTPBearer: []
      parameters:
      - name: item_category_id
        in: path
        required: true
        schema:
          title: Item Category Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemCategoryRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Item Categories
      summary: Update Item Category
      operationId: update_item_category
      security:
      - HTTPBearer: []
      parameters:
      - name: item_category_id
        in: path
        required: true
        schema:
          title: Item Category Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Update
              $ref: '#/components/schemas/ItemCategoryUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemCategoryRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Item Categories
      summary: Delete Item Category
      operationId: delete_item_category
      security:
      - HTTPBearer: []
      parameters:
      - name: item_category_id
        in: path
        required: true
        schema:
          title: Item Category Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/item_categories:
    get:
      tags:
      - Item Categories
      summary: Get Item Categories
      operationId: get_item_categories
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          title: Limit
          description: A limit on the number of objects to be returned
          default: 10
          type: integer
        description: A limit on the number of objects to be returned
      - name: offset
        in: query
        required: false
        schema:
          title: Offset
          description: The number of objects to skip
          type: integer
        description: The number of objects to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Get Item Categories
                type: array
                items:
                  $ref: '#/components/schemas/ItemCategoryRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Item Categories
      summary: Bulk Update Item Categories
      description: Updates multiple categories.
      operationId: bulk_update_item_categories
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Bulk Update
              type: array
              items:
                $ref: '#/components/schemas/ItemCategoryBulkUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Bulk Update Item Categories
                type: array
                items:
                  $ref: '#/components/schemas/ItemCategoryRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Item Categories
      summary: Create Item Category
      operationId: create_item_category
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Create
              $ref: '#/components/schemas/ItemCategoryCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemCategoryRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Item Categories
      summary: Bulk Delete Item Categories
      operationId: bulk_delete_item_categories
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Bulk Delete
              type: array
              items:
                $ref: '#/components/schemas/ItemCategoryBulkDelete'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Expression:
      properties:
        tokens:
          items:
            $ref: '#/components/schemas/Token'
          type: array
          title: Tokens
        variables:
          items:
            $ref: '#/components/schemas/MathExpression'
          type: array
          title: Variables
      type: object
      title: Expression
    StoreCategoryRenderOptions:
      properties:
        delay:
          type: integer
          title: Delay
        loop:
          type: boolean
          title: Loop
        autoplay:
          type: boolean
          title: Autoplay
        show_dots:
          type: boolean
          title: Show Dots
        display_type:
          $ref: '#/components/schemas/CarouselDisplayType'
      type: object
      title: StoreCategoryRenderOptions
    StoreCategoryDividerPosition:
      type: string
      enum:
      - top
      - bottom
      title: StoreCategoryDividerPosition
      description: An enumeration.
    BackgroundSize:
      type: string
      enum:
      - contain
      - repeat
      - cover
      title: BackgroundSize
      description: An enumeration.
    ItemCategoryBulkDelete:
      properties:
        id:
          type: string
          title: Id
      type: object
      required:
      - id
      title: ItemCategoryBulkDelete
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    MathExpression:
      properties:
        tokens:
          items:
            $ref: '#/components/schemas/Token'
          type: array
          title: Tokens
        name:
          type: string
          title: Name
      type: object
      required:
      - name
      title: MathExpression
    ItemCategoryBulkUpdate:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        position:
          type: integer
          title: Position
        parent_id:
          type: string
          title: Parent Id
        item_template_id:
          type: string
          title: Item Template Id
        pinned_expression:
          $ref: '#/components/schemas/Expression'
        slug:
          type: string
          title: Slug
        icon:
          type: string
          title: Icon
        image_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Image Url
        divider_image_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Divider Image Url
        divider_position:
          $ref: '#/components/schemas/StoreCategoryDividerPosition'
        divider_type:
          $ref: '#/components/schemas/StoreCategoryDividerType'
        background_color:
          type: string
          title: Background Color
        background_image_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Background Image Url
        background_size:
          $ref: '#/components/schemas/BackgroundSize'
        render_type:
          $ref: '#/components/schemas/StoreCategoryRenderType'
        render_options:
          $ref: '#/components/schemas/StoreCategoryRenderOptions'
        id:
          type: string
          title: Id
      type: object
      required:
      - id
      title: ItemCategoryBulkUpdate
    ItemCategoryCreate:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        position:
          type: integer
          title: Position
        parent_id:
          type: string
          title: Parent Id
        item_template_id:
          type: string
          title: Item Template Id
        pinned_expression:
          $ref: '#/components/schemas/Expression'
        slug:
          type: string
          title: Slug
        icon:
          type: string
          title: Icon
        image_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Image Url
        divider_image_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Divider Image Url
        divider_position:
          default: top
          $ref: '#/components/schemas/StoreCategoryDividerPosition'
        divider_type:
          default: image
          $ref: '#/components/schemas/StoreCategoryDividerType'
        background_color:
          type: string
          title: Background Color
        background_image_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Background Image Url
        background_size:
          $ref: '#/components/schemas/BackgroundSize'
        render_type:
          $ref: '#/components/schemas/StoreCategoryRenderType'
        render_options:
          $ref: '#/components/schemas/StoreCategoryRenderOptions'
      type: object
      required:
      - name
      - position
      title: ItemCategoryCreate
    ItemCategoryRead:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        position:
          type: integer
          title: Position
        parent_id:
          type: string
          title: Parent Id
        item_template_id:
          type: string
          title: Item Template Id
        pinned_expression:
          $ref: '#/components/schemas/Expression'
        slug:
          type: string
          title: Slug
        icon:
          type: string
          title: Icon
        image_url:
          type: string
          title: Image Url
        divider_image_url:
          type: string
          title: Divider Image Url
        divider_position:
          default: top
          $ref: '#/components/schemas/StoreCategoryDividerPosition'
        divider_type:
          default: image
          $ref: '#/components/schemas/StoreCategoryDividerType'
        background_color:
          type: string
          title: Background Color
        background_image_url:
          type: string
          title: Background Image Url
        background_size:
          $ref: '#/components/schemas/BackgroundSize'
        render_type:
          $ref: '#/components/schemas/StoreCategoryRenderType'
        render_options:
          $ref: '#/components/schemas/StoreCategoryRenderOptions'
        id:
          type: string
          title: Id
      type: object
      required:
      - name
      - position
      - id
      title: ItemCategoryRead
    CarouselDisplayType:
      type: string
      enum:
      - default
      - compact
      - alone
      title: CarouselDisplayType
      description: An enumeration.
    TokenType:
      type: string
      enum:
      - attribute
      - custom_attribute
      - event_attribute
      - custom_event_attribute
      - operator
      - number
      - date
      - string
      - boolean
      - list
      - variable
      - virtual_currency
      title: TokenType
    Token:
      properties:
        type:
          $ref: '#/components/schemas/TokenType'
        value:
          title: Value
      type: object
      required:
      - type
      title: Token
    StoreCategoryRenderType:
      type: string
      enum:
      - default
      - carousel
      title: StoreCategoryRenderType
      description: An enumeration.
    ItemCategoryUpdate:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        position:
          type: integer
          title: Position
        parent_id:
          type: string
          title: Parent Id
        item_template_id:
          type: string
          title: Item Template Id
        pinned_expression:
          $ref: '#/components/schemas/Expression'
        slug:
          type: string
          title: Slug
        icon:
          type: string
          title: Icon
        image_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Image Url
        divider_image_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Divider Image Url
        divider_position:
          $ref: '#/components/schemas/StoreCategoryDividerPosition'
        divider_type:
          $ref: '#/components/schemas/StoreCategoryDividerType'
        background_color:
          type: string
          title: Background Color
        background_image_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Background Image Url
        background_size:
          $ref: '#/components/schemas/BackgroundSize'
        render_type:
          $ref: '#/components/schemas/StoreCategoryRenderType'
        render_options:
          $ref: '#/components/schemas/StoreCategoryRenderOptions'
      type: object
      title: ItemCategoryUpdate
    StoreCategoryDividerType:
      type: string
      enum:
      - image
      - mask
      title: StoreCategoryDividerType
      description: An enumeration.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: Refer to the [Authentication](https://docs.aghanim.com/api-reference/) section for instructions on obtaining an API key and use it as the `Bearer` token.