openapi: 3.1.0
info:
  title: Aghanim Server-to-Server Achievements Creators 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: Creators
paths:
  /v1/creators/countries:
    get:
      tags:
      - Creators
      summary: Get Creator Countries
      operationId: get_creator_countries
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  type: string
                  pattern: ^[A-Z]{2}$
                type: array
                title: Response Get Creator Countries
      security:
      - HTTPBearer: []
  /v1/creators:
    get:
      tags:
      - Creators
      summary: Get Creators
      operationId: get_creators
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          title: Q
          type: string
      - name: platform
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/CreatorSocialPlatform'
      - name: terms_accepted
        in: query
        required: false
        schema:
          title: Terms Accepted
          type: boolean
      - name: creator_tier_group_id
        in: query
        required: false
        schema:
          title: Creator Tier Group Id
          type: string
      - name: country
        in: query
        required: false
        schema:
          title: Country
          pattern: ^[A-Z]{2}$
          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:
                $ref: '#/components/schemas/PaginatedResponse_list_aghanim.creator.schemas.CreatorRead__'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Creators
      summary: Create Creator
      operationId: create_creator
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Create
              $ref: '#/components/schemas/CreatorCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/creators/{creator_id}:
    get:
      tags:
      - Creators
      summary: Get Creator
      operationId: get_creator
      security:
      - HTTPBearer: []
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          title: Creator Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Creators
      summary: Update Creator
      operationId: update_creator
      security:
      - HTTPBearer: []
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          title: Creator Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Update
              $ref: '#/components/schemas/CreatorUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Creators
      summary: Delete Creator
      operationId: delete_creator
      security:
      - HTTPBearer: []
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          title: Creator Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/creators/{creator_id}/social-accounts:
    get:
      tags:
      - Creators
      summary: Get Creator Social Accounts
      operationId: get_creator_social_accounts
      security:
      - HTTPBearer: []
      parameters:
      - name: creator_id
        in: path
        required: true
        schema:
          title: Creator Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CreatorSocialAccountRead'
                title: Response Get Creator Social Accounts
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreatorUpdate:
      properties:
        name:
          type: string
          title: Name
        email:
          type: string
          title: Email
        avatar_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Avatar Url
        extra_terms_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Extra Terms Url
        extra_terms_text:
          type: string
          title: Extra Terms Text
        social_medias:
          items:
            $ref: '#/components/schemas/CreatorSocial'
          type: array
          title: Social Medias
        creator_tier_group_id:
          type: string
          title: Creator Tier Group Id
          description: New tier group to assign the creator to.
        revenue_share_override_enabled:
          type: boolean
          title: Revenue Share Override Enabled
          description: When true, the creator's revenue share is fixed at `revenue_share_override_bps` and ignores tier rates.
        revenue_share_override_bps:
          type: integer
          maximum: 10000.0
          minimum: 0.0
          title: Revenue Share Override Bps
          description: Override revenue share in basis points; required when enabling the override.
      type: object
      title: CreatorUpdate
    CreatorAnnotation:
      properties:
        note:
          type: string
          maxLength: 2000
          title: Note
        display_name:
          type: string
          maxLength: 120
          title: Display Name
      type: object
      title: CreatorAnnotation
    CreatorSocialPlatform:
      type: string
      enum:
      - tiktok
      - youtube
      - instagram
      - threads
      - x_twitter
      - facebook
      - reddit
      - twitch
      - other
      title: CreatorSocialPlatform
    SyncStatus:
      type: string
      enum:
      - pending
      - ok
      - error
      title: SyncStatus
    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
    SocialChannelRead:
      properties:
        followers:
          title: Followers
          type: integer
        total_views:
          title: Total Views
          type: integer
        total_content_count:
          title: Total Content Count
          type: integer
      type: object
      required:
      - followers
      - total_views
      - total_content_count
      title: SocialChannelRead
    UnitedStates:
      type: string
      enum:
      - US-AL
      - US-MS
      - US-NE
      - US-PR
      title: UnitedStates
      description: An enumeration.
    SocialContentItemRead:
      properties:
        url:
          type: string
          title: Url
        title:
          title: Title
          type: string
        thumbnail_url:
          title: Thumbnail Url
          type: string
        published_at:
          type: string
          format: date-time
          title: Published At
        views:
          title: Views
          type: integer
        likes:
          title: Likes
          type: integer
        comments:
          title: Comments
          type: integer
      type: object
      required:
      - url
      - title
      - thumbnail_url
      - published_at
      - views
      - likes
      - comments
      title: SocialContentItemRead
    SocialPerformanceMetricsRead:
      properties:
        views:
          title: Views
          type: integer
        likes:
          title: Likes
          type: integer
        comments:
          title: Comments
          type: integer
      type: object
      required:
      - views
      - likes
      - comments
      title: SocialPerformanceMetricsRead
    CreatorSocial:
      properties:
        url:
          type: string
          title: Url
        platform:
          $ref: '#/components/schemas/CreatorSocialPlatform'
      type: object
      required:
      - url
      title: CreatorSocial
    CreatorRead:
      properties:
        name:
          type: string
          title: Name
        email:
          type: string
          title: Email
        avatar_url:
          type: string
          title: Avatar Url
        extra_terms_url:
          type: string
          title: Extra Terms Url
        extra_terms_text:
          type: string
          title: Extra Terms Text
        social_medias:
          items:
            $ref: '#/components/schemas/CreatorSocial'
          type: array
          title: Social Medias
        id:
          type: string
          title: Id
        coupon_count:
          type: integer
          title: Coupon Count
          default: 0
        revenue:
          type: integer
          title: Revenue
          default: 0
        balance:
          type: integer
          title: Balance
          default: 0
        terms:
          $ref: '#/components/schemas/CreatorTermsRead'
        creator_tier_group_id:
          type: string
          title: Creator Tier Group Id
          description: Identifier of the tier group the creator is assigned to, if any.
        current_creator_tier_id:
          type: string
          title: Current Creator Tier Id
          description: Identifier of the tier the creator currently qualifies for based on lifetime gross revenue.
        revenue_share_override_enabled:
          type: boolean
          title: Revenue Share Override Enabled
          description: When true, revenue_share_override_bps takes precedence over the tier's revenue_share_bps.
          default: false
        revenue_share_override_bps:
          type: integer
          title: Revenue Share Override Bps
          description: Per-creator revenue share override in basis points (0-10000).
          default: 0
        lifetime_gross_usd_cents:
          type: integer
          title: Lifetime Gross USD Cents
          description: Cumulative gross revenue attributed to the creator, in USD cents.
          default: 0
        annotation:
          title: Annotation
          description: Operator-only annotation attached to the creator (notes, internal display name).
          $ref: '#/components/schemas/CreatorAnnotation'
      type: object
      required:
      - name
      - email
      - id
      title: CreatorRead
    PaginatedResponse_list_aghanim.creator.schemas.CreatorRead__:
      properties:
        data:
          items:
            $ref: '#/components/schemas/CreatorRead'
          type: array
          title: Data
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
        has_next:
          type: boolean
          description: Indicates if there are more items to fetch.
      type: object
      required:
      - data
      - total
      - limit
      - offset
      - has_next
      title: PaginatedResponse[list[aghanim.creator.schemas.CreatorRead]]
    CreatorTermsRead:
      properties:
        id:
          type: string
          title: Id
        accepted_at:
          type: integer
          title: Accepted At
        date_of_birth:
          type: string
          format: date
          title: Date Of Birth
        country:
          type: string
          pattern: ^[A-Z]{2}$
          title: Country
        state:
          $ref: '#/components/schemas/UnitedStates'
        age:
          type: integer
          title: Age
      type: object
      required:
      - id
      - accepted_at
      title: CreatorTermsRead
    SocialPerformanceSnapshotRead:
      properties:
        content_url:
          type: string
          title: Content Url
        title:
          title: Title
          type: string
        thumbnail_url:
          title: Thumbnail Url
          type: string
        published_at:
          type: string
          format: date-time
          title: Published At
        taken_at:
          type: string
          format: date-time
          title: Taken At
        window_days:
          type: integer
          title: Window Days
        metrics:
          $ref: '#/components/schemas/SocialPerformanceMetricsRead'
      type: object
      required:
      - content_url
      - title
      - thumbnail_url
      - published_at
      - taken_at
      - window_days
      - metrics
      title: SocialPerformanceSnapshotRead
    CreatorSocialAccountRead:
      properties:
        platform:
          $ref: '#/components/schemas/CreatorSocialPlatform'
        handle:
          type: string
          title: Handle
        sync_status:
          $ref: '#/components/schemas/SyncStatus'
        synced_at:
          title: Synced At
          type: number
        channel:
          $ref: '#/components/schemas/SocialChannelRead'
        content:
          items:
            $ref: '#/components/schemas/SocialContentItemRead'
          type: array
          title: Content
        performance:
          items:
            $ref: '#/components/schemas/SocialPerformanceSnapshotRead'
          type: array
          title: Performance
      type: object
      required:
      - platform
      - handle
      - sync_status
      - synced_at
      - channel
      - content
      - performance
      title: CreatorSocialAccountRead
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreatorCreate:
      properties:
        name:
          type: string
          title: Name
        email:
          type: string
          title: Email
        avatar_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Avatar Url
        extra_terms_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Extra Terms Url
        extra_terms_text:
          type: string
          title: Extra Terms Text
        social_medias:
          items:
            $ref: '#/components/schemas/CreatorSocial'
          type: array
          title: Social Medias
        creator_tier_group_id:
          type: string
          title: Creator Tier Group Id
          description: Tier group to assign the creator to on creation, if any.
        coupon_code:
          type: string
          maxLength: 20
          title: Coupon Code
          description: Override for the auto-generated promo code. If omitted, the code is derived from the creator's name.
      type: object
      required:
      - name
      - email
      title: CreatorCreate
  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.