openapi: 3.1.0
info:
  title: Aghanim Server-to-Server Achievements Price Templates 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: Price Templates
paths:
  /v1/price_templates:
    get:
      tags:
      - Price Templates
      summary: Get Price Templates
      description: Returns a list of price templates.
      operationId: get_price_templates
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          title: Q
          type: string
      - 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: starting_after
        in: query
        required: false
        schema:
          title: Starting After
          description: The cursor for pagination
          type: string
        description: The cursor for pagination
      - name: ending_before
        in: query
        required: false
        schema:
          title: Ending Before
          description: The cursor for pagination
          type: string
        description: The cursor for pagination
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfinitePaginatedResponse_PriceTemplateShort_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Price Templates
      summary: Create Price Template
      description: Creates a new price template.
      operationId: create_price_template
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceTemplateCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceTemplateRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/price_templates/{price_template_id}:
    get:
      tags:
      - Price Templates
      summary: Get Price Template
      description: Returns a single price template.
      operationId: get_price_template
      security:
      - HTTPBearer: []
      parameters:
      - name: price_template_id
        in: path
        required: true
        schema:
          title: Price Template Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceTemplateRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Price Templates
      summary: Update Price Template
      description: Updates a price template.
      operationId: update_price_template
      security:
      - HTTPBearer: []
      parameters:
      - name: price_template_id
        in: path
        required: true
        schema:
          title: Price Template Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceTemplateUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceTemplateRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Price Templates
      summary: Delete Price Template
      description: Deletes a price template.
      operationId: delete_price_template
      security:
      - HTTPBearer: []
      parameters:
      - name: price_template_id
        in: path
        required: true
        schema:
          title: Price Template Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Country:
      type: string
      enum:
      - VA
      - MM
      - PE
      - DK
      - PY
      - SV
      - US
      - SI
      - SG
      - CZ
      - KE
      - JP
      - KR
      - NZ
      - KZ
      - AE
      - IQ
      - AU
      - CL
      - QA
      - NL
      - IN
      - GE
      - EE
      - BM
      - AT
      - VN
      - LI
      - KW
      - TC
      - BR
      - PL
      - MY
      - HK
      - MC
      - VG
      - GI
      - SE
      - EG
      - GH
      - CH
      - LK
      - SA
      - SM
      - PK
      - DE
      - TW
      - LU
      - BO
      - FM
      - CA
      - SK
      - LT
      - FR
      - KY
      - LV
      - CY
      - MX
      - RO
      - TZ
      - HU
      - PH
      - MO
      - FI
      - RS
      - EC
      - IE
      - ID
      - OM
      - BD
      - PA
      - UA
      - ZA
      - ES
      - PT
      - 'NO'
      - NG
      - TH
      - IL
      - GB
      - JO
      - IT
      - BG
      - TR
      - BH
      - CR
      - MA
      - HR
      - GR
      - KH
      - CO
      - BE
      - DZ
      - CN
      - AD
      - AL
      - BA
      - IS
      - MD
      - ME
      - MK
      - MT
      - RU
      - AR
      title: Country
    PriceCategory:
      type: string
      enum:
      - none
      - platform
      title: PriceCategory
    PriceTemplateRead:
      properties:
        key:
          title: Key
          description: Unique key for the price template
          type: string
        name:
          type: string
          title: Name
          description: Name of the price template
        price:
          type: integer
          title: Price
          description: Price point used to derive pricing details
        category:
          $ref: '#/components/schemas/PriceCategory'
          description: Category of the price template (e.g., none or platform)
        id:
          type: string
          maxLength: 32
          title: Id
          description: Unique identifier for the price template
        items_count:
          type: integer
          title: Items Count
          description: Number of items linked to the template
          default: 0
        created_at:
          type: integer
          title: Created At
          description: Timestamp (in epoch seconds) when the template was created
        modified_at:
          title: Modified At
          description: Timestamp (in epoch seconds) when the template was last modified
          type: integer
        prices:
          items:
            $ref: '#/components/schemas/TemplatePrice'
          type: array
          title: Prices
          description: List of prices derived from the template
      type: object
      required:
      - name
      - price
      - category
      - id
      - created_at
      - prices
      title: PriceTemplateRead
    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
    Currency:
      type: string
      enum:
      - USD
      - EUR
      - AED
      - AFN
      - ALL
      - AMD
      - ANG
      - AOA
      - ARS
      - AUD
      - AWG
      - AZN
      - BAM
      - BBD
      - BDT
      - BGN
      - BHD
      - BIF
      - BMD
      - BND
      - BOB
      - BRL
      - BSD
      - BTN
      - BWP
      - BYN
      - BZD
      - CAD
      - CDF
      - CHF
      - CLP
      - CNY
      - COP
      - CRC
      - CUP
      - CVE
      - CZK
      - DJF
      - DKK
      - DOP
      - DZD
      - EGP
      - ERN
      - ETB
      - FJD
      - FKP
      - GBP
      - GEL
      - GHS
      - GIP
      - GMD
      - GNF
      - GTQ
      - GYD
      - HKD
      - HNL
      - HTG
      - HUF
      - IDR
      - ILS
      - INR
      - IQD
      - IRR
      - ISK
      - JMD
      - JOD
      - JPY
      - KES
      - KGS
      - KHR
      - KMF
      - KPW
      - KRW
      - KWD
      - KYD
      - KZT
      - LAK
      - LBP
      - LKR
      - LRD
      - LSL
      - LYD
      - MAD
      - MDL
      - MGA
      - MKD
      - MMK
      - MNT
      - MOP
      - MRU
      - MUR
      - MVR
      - MWK
      - MXN
      - MYR
      - MZN
      - NAD
      - NGN
      - NIO
      - NOK
      - NPR
      - NZD
      - OMR
      - PAB
      - PEN
      - PGK
      - PHP
      - PKR
      - PLN
      - PYG
      - QAR
      - RON
      - RSD
      - RUB
      - RWF
      - SAR
      - SBD
      - SCR
      - SDG
      - SEK
      - SGD
      - SHP
      - SLE
      - SOS
      - SRD
      - SSP
      - STN
      - SVC
      - SYP
      - SZL
      - THB
      - TJS
      - TMT
      - TND
      - TOP
      - TRY
      - TTD
      - TWD
      - TZS
      - UAH
      - UGX
      - UYU
      - UZS
      - VED
      - VES
      - VND
      - VUV
      - WST
      - XAF
      - XCD
      - XCG
      - XOF
      - XPF
      - YER
      - ZAR
      - ZMW
      - ZWG
      - ZWL
      - RP
      - VC
      title: Currency
    InfinitePaginatedResponse_PriceTemplateShort_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/PriceTemplateShort'
          type: array
          title: Data
        has_more:
          type: boolean
          title: Has More
        next_cursor:
          title: Next Cursor
          type: string
      type: object
      required:
      - data
      - has_more
      title: InfinitePaginatedResponse[PriceTemplateShort]
    PriceTemplateUpdate:
      properties:
        key:
          title: Key
          description: Unique key for the price template
          type: string
        name:
          title: Name
          description: Updated name of the price template
          type: string
        price:
          title: Price
          description: Updated price point
          type: integer
        category:
          description: Updated category of the price template)
          $ref: '#/components/schemas/PriceCategory'
        customs:
          title: Customs
          description: List of price customizations overwriting platform suggested prices
          items:
            $ref: '#/components/schemas/Price'
          type: array
      type: object
      title: PriceTemplateUpdate
    PriceTemplateShort:
      properties:
        key:
          title: Key
          description: Unique key for the price template
          type: string
        name:
          type: string
          title: Name
          description: Name of the price template
        price:
          type: integer
          title: Price
          description: Price point used to derive pricing details
        category:
          $ref: '#/components/schemas/PriceCategory'
          description: Category of the price template (e.g., none or platform)
        id:
          type: string
          maxLength: 32
          title: Id
          description: Unique identifier for the price template
        items_count:
          type: integer
          title: Items Count
          description: Number of items linked to the template
          default: 0
        created_at:
          type: integer
          title: Created At
          description: Timestamp (in epoch seconds) when the template was created
        modified_at:
          title: Modified At
          description: Timestamp (in epoch seconds) when the template was last modified
          type: integer
      type: object
      required:
      - name
      - price
      - category
      - id
      - created_at
      title: PriceTemplateShort
    PriceTemplateCreate:
      properties:
        key:
          title: Key
          description: Unique key for the price template
          type: string
        name:
          type: string
          title: Name
          description: Name of the price template
        price:
          type: integer
          title: Price
          description: Price point used to derive pricing details
        category:
          $ref: '#/components/schemas/PriceCategory'
          description: Category of the price template (e.g., none or platform)
        customs:
          items:
            $ref: '#/components/schemas/Price'
          type: array
          title: Customs
          description: List of price customizations overwriting platform suggested prices
      type: object
      required:
      - name
      - price
      - category
      - customs
      title: PriceTemplateCreate
    TemplatePrice:
      properties:
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        platform:
          $ref: '#/components/schemas/Platform'
        price:
          type: integer
          maximum: 1000000000000.0
          minimum: 0.0
          title: Price
        is_custom:
          type: boolean
          title: Is Custom
          description: Flag indicating whether the price is a custom value
      type: object
      required:
      - country
      - currency
      - platform
      - price
      - is_custom
      title: TemplatePrice
    Price:
      properties:
        country:
          $ref: '#/components/schemas/Country'
        currency:
          $ref: '#/components/schemas/Currency'
        platform:
          $ref: '#/components/schemas/Platform'
        price:
          type: integer
          maximum: 1000000000000.0
          minimum: 0.0
          title: Price
      type: object
      required:
      - country
      - currency
      - platform
      - price
      title: Price
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Platform:
      type: string
      enum:
      - any
      - ios
      - android
      - other
      title: Platform
  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.