openapi: 3.1.0
info:
  title: Aghanim Server-to-Server Achievements Leaderboards 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: Leaderboards
paths:
  /v1/leaderboards:
    get:
      tags:
      - Leaderboards
      summary: Get Leaderboards
      description: Returns a list of leaderboards.
      operationId: get_leaderboards
      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:
                type: array
                items:
                  $ref: '#/components/schemas/LeaderboardRead'
                title: Response Get Leaderboards
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Leaderboards
      summary: Create Leaderboard
      description: Creates a new leaderboard.
      operationId: create_leaderboard
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaderboardCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/leaderboards/{leaderboard_id}:
    get:
      tags:
      - Leaderboards
      summary: Get Leaderboard
      description: Returns a single leaderboard.
      operationId: get_leaderboard
      security:
      - HTTPBearer: []
      parameters:
      - name: leaderboard_id
        in: path
        required: true
        schema:
          title: Leaderboard Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Leaderboards
      summary: Update Leaderboard
      description: Updates a leaderboard.
      operationId: update_leaderboard
      security:
      - HTTPBearer: []
      parameters:
      - name: leaderboard_id
        in: path
        required: true
        schema:
          title: Leaderboard Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaderboardUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Leaderboards
      summary: Delete Leaderboard
      description: Deletes a leaderboard.
      operationId: delete_leaderboard
      security:
      - HTTPBearer: []
      parameters:
      - name: leaderboard_id
        in: path
        required: true
        schema:
          title: Leaderboard Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/leaderboards/{leaderboard_id}/members:
    get:
      tags:
      - Leaderboards
      summary: Get Leaderboard Members
      description: Returns a list of leaderboard members.
      operationId: get_leaderboard_members
      security:
      - HTTPBearer: []
      parameters:
      - name: leaderboard_id
        in: path
        required: true
        schema:
          title: Leaderboard Id
          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: 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:
                type: array
                items:
                  $ref: '#/components/schemas/LeaderboardMemberRead'
                title: Response Get Leaderboard Members
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/leaderboards/{leaderboard_id}/members/{member_id}:
    put:
      tags:
      - Leaderboards
      summary: Update Leaderboard Member
      operationId: update_leaderboard_member
      security:
      - HTTPBearer: []
      parameters:
      - name: member_id
        in: path
        required: true
        schema:
          title: Member Id
          type: string
      - name: leaderboard_id
        in: path
        required: true
        schema:
          title: Leaderboard Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaderboardMemberUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Update Leaderboard Member
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/leaderboards/{leaderboard_id}/submit_score:
    post:
      tags:
      - Leaderboards
      summary: Submit Score
      operationId: submit_score
      security:
      - HTTPBearer: []
      parameters:
      - name: leaderboard_id
        in: path
        required: true
        schema:
          title: Leaderboard Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaderboardMemberUpdate'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    LeaderboardMemberRead:
      properties:
        member_id:
          type: string
          title: Member Id
          description: The unique identifier of the member.
        member_data:
          type: string
          title: Member Data
          description: The data of the member. This might be a members's name.
        member_subdata:
          title: Member Subdata
          description: The additional subdata related to the member, such as a clan, team or guild they belong to.
          type: string
        image_url:
          title: Image Url
          description: The image URL of the member.
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
        score:
          type: integer
          title: Score
          description: The score of the member.
        id:
          type: string
          maxLength: 32
          title: Id
          description: The unique identifier of the leaderboard member.
        created_at:
          type: integer
          title: Created At
          description: The unix timestamp of when the leaderboard member was created.
        modified_at:
          title: Modified At
          description: The unix timestamp of when the leaderboard member was last modified.
          type: integer
      type: object
      required:
      - member_id
      - member_data
      - score
      - id
      - created_at
      title: LeaderboardMemberRead
    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
    LeaderboardMemberUpdate:
      properties:
        member_id:
          title: Member Id
          description: The unique identifier of the member.
          type: string
        member_data:
          title: Member Data
          description: The data of the member.
          type: string
        image_url:
          title: Image Url
          description: The image URL of the member.
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
        score:
          title: Score
          description: The score of the member.
          type: integer
      type: object
      title: LeaderboardMemberUpdate
    LeaderboardVisibility:
      type: string
      enum:
      - general
      - personal
      title: LeaderboardVisibility
    LeaderboardRead:
      properties:
        name:
          type: string
          maxLength: 255
          title: Name
          description: The name of the leaderboard.
        description:
          type: string
          maxLength: 512
          title: Description
          description: The description of the leaderboard.
        visibility:
          $ref: '#/components/schemas/LeaderboardVisibility'
          description: The visibility of the leaderboard. It can be either 'general' or 'personal'. General leaderboards are visible to all users, while personal leaderboards are only visible to leaderboard participants.
          default: general
        start_at:
          title: Start At
          description: The start date of the leaderboard in Unix timestamp.If set, the leaderboard will only be visible in game-hub after this date.
          type: integer
        end_at:
          title: End At
          description: The end date of the leaderboard in Unix timestamp.If set, the leaderboard will only be visible in game-hub before this date.
          type: integer
        id:
          type: string
          maxLength: 32
          title: Id
          description: The unique identifier of the leaderboard.
      type: object
      required:
      - name
      - description
      - id
      title: LeaderboardRead
    LeaderboardUpdate:
      properties:
        start_at:
          title: Start At
          type: integer
        end_at:
          title: End At
          type: integer
        name:
          title: Name
          description: The name of the leaderboard.
          type: string
          maxLength: 255
        description:
          title: Description
          description: The description of the leaderboard.
          type: string
          maxLength: 512
        visibility:
          $ref: '#/components/schemas/LeaderboardVisibility'
      type: object
      title: LeaderboardUpdate
    LeaderboardCreate:
      properties:
        name:
          type: string
          maxLength: 255
          title: Name
          description: The name of the leaderboard.
        description:
          type: string
          maxLength: 512
          title: Description
          description: The description of the leaderboard.
        visibility:
          $ref: '#/components/schemas/LeaderboardVisibility'
          description: The visibility of the leaderboard. It can be either 'general' or 'personal'. General leaderboards are visible to all users, while personal leaderboards are only visible to leaderboard participants.
          default: general
        start_at:
          title: Start At
          description: The start date of the leaderboard in Unix timestamp.If set, the leaderboard will only be visible in game-hub after this date.
          type: integer
        end_at:
          title: End At
          description: The end date of the leaderboard in Unix timestamp.If set, the leaderboard will only be visible in game-hub before this date.
          type: integer
      type: object
      required:
      - name
      - description
      title: LeaderboardCreate
    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.