{
  "openapi": "3.0.3",
  "info": {
    "title": "Comet Commendations API",
    "version": "1.2.1",
    "description": "Create a personal key in Comet → Commendations → JSON API. Server is fixed at cs2.vavle.fun:27015. Only the key owner's saved accounts are used. 300 requests/minute per owner; optional Idempotency-Key is retained for 24 hours."
  },
  "servers": [
    {
      "url": "https://comet.vavle.fun"
    }
  ],
  "security": [
    {
      "BearerKey": []
    }
  ],
  "paths": {
    "/api/v1/commendations/machines": {
      "get": {
        "summary": "List owned connected headless machines",
        "responses": {
          "200": {
            "description": "Connected machines",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "server": {
                      "type": "string"
                    },
                    "machines": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "pcId": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "platform": {
                            "type": "string"
                          },
                          "version": {
                            "type": "string"
                          },
                          "compatible": {
                            "type": "boolean"
                          },
                          "busy": {
                            "type": "boolean"
                          },
                          "savedAccounts": {
                            "type": "integer"
                          },
                          "availableAccounts": {
                            "type": "integer",
                            "description": "Quota-eligible before filtering by a target"
                          },
                          "quotaAvailableAccounts": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "Distinct suitable saved accounts with remaining quota, ignoring task reservations. A busy VM does not imply quota is exhausted."
                          },
                          "remainingCommendations": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "Sum of saved GC/estimated remaining daily quota for those accounts, ignoring reservations; for different recipients, not one target."
                          },
                          "quotaSource": {
                            "type": "string",
                            "enum": [
                              "saved_gc_or_estimate"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/commendations/tasks": {
      "get": {
        "summary": "List the latest 20 owned tasks",
        "responses": {
          "200": {
            "description": "Latest tasks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "tasks": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Task"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Start or stop a task",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "For start only. Retained 24 hours; different target/count/pcId/allowPartial returns 409. Explicit false equals omitted allowPartial."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Start"
                  },
                  {
                    "$ref": "#/components/schemas/Stop"
                  }
                ]
              },
              "examples": {
                "start": {
                  "value": {
                    "action": "start",
                    "target": "de_m00n",
                    "count": 100
                  }
                },
                "stop": {
                  "value": {
                    "action": "stop",
                    "taskId": "11111111-1111-1111-1111-111111111111"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing task returned for an idempotent retry, or stop accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "task"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "task": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "replayed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Task created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "task"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "task": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "replayed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/commendations/tasks/{taskId}": {
      "get": {
        "summary": "Get owned task progress",
        "parameters": [
          {
            "in": "path",
            "name": "taskId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task progress",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "task"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "task": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "replayed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/commendations": {
      "get": {
        "summary": "Discover the fixed server and API endpoints",
        "responses": {
          "200": {
            "description": "API metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key"
          }
        }
      }
    },
    "/api/v1/commendations/availability": {
      "post": {
        "summary": "Check target-specific account capacity without starting or reserving accounts",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CapacityRequest"
              },
              "example": {
                "target": "de_m00n",
                "count": 10
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Current capacity snapshot; busy or incompatible machines report zero availableAccounts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capacity"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "cmt_..."
      }
    },
    "schemas": {
      "Start": {
        "type": "object",
        "required": [
          "action",
          "target",
          "count"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "start"
            ]
          },
          "target": {
            "type": "string",
            "description": "SteamID64, Steam profile URL, or vanity",
            "example": "de_m00n"
          },
          "count": {
            "type": "integer",
            "minimum": 1,
            "description": "Desired unique GC-confirmed successful accounts; positive safe integer, no arbitrary account cap. allowPartial permits a smaller initial pool. Exhaustion reports failed and an exact final shortfall."
          },
          "pcId": {
            "type": "string",
            "description": "Required when more than one owned machine is connected"
          },
          "allowPartial": {
            "type": "boolean",
            "default": false,
            "description": "If true, use the available pool even when smaller than count. Original requestedCount is preserved. Zero availability still returns 409 without creating a task."
          }
        }
      },
      "Stop": {
        "type": "object",
        "required": [
          "action",
          "taskId"
        ],
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "stop"
            ]
          },
          "taskId": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "Task": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "pcId": {
            "type": "string"
          },
          "target": {
            "type": "string"
          },
          "server": {
            "type": "string",
            "example": "cs2.vavle.fun:27015"
          },
          "state": {
            "type": "string",
            "enum": [
              "preparing",
              "running",
              "stopping",
              "stopped",
              "complete",
              "failed"
            ]
          },
          "total": {
            "type": "integer"
          },
          "completed": {
            "type": "integer",
            "description": "Processed account rows, including failures and skips. Use completedAccounts for confirmed successes."
          },
          "remaining": {
            "type": "integer"
          },
          "accepted": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "skipped": {
            "type": "integer"
          },
          "cancelled": {
            "type": "integer"
          },
          "reason": {
            "type": "string"
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "login": {
                  "type": "string"
                },
                "state": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                },
                "usage": {
                  "type": "object"
                }
              }
            }
          },
          "mode": {
            "type": "string",
            "enum": [
              "successful_accounts",
              "selected_accounts"
            ]
          },
          "completedAccounts": {
            "type": "integer",
            "minimum": 0
          },
          "requestedCount": {
            "type": "integer",
            "minimum": 0
          },
          "progress": {
            "type": "object",
            "properties": {
              "requested": {
                "type": "integer",
                "minimum": 0
              },
              "completed": {
                "type": "integer",
                "minimum": 0
              },
              "remaining": {
                "type": "integer",
                "minimum": 0
              },
              "active": {
                "type": "integer",
                "minimum": 0
              },
              "attempts": {
                "type": "integer",
                "minimum": 0
              },
              "retries": {
                "type": "integer",
                "minimum": 0
              },
              "failedAttempts": {
                "type": "integer",
                "minimum": 0
              },
              "sending": {
                "type": "integer",
                "minimum": 0
              },
              "preloading": {
                "type": "integer",
                "minimum": 0
              },
              "ready": {
                "type": "integer",
                "minimum": 0
              },
              "cleaning": {
                "type": "integer",
                "minimum": 0,
                "description": "Accounts stopping or being replaced, awaiting a newer stopped status."
              }
            },
            "description": "completed counts unique GC-confirmed accounts; remaining is the unfulfilled target, including after failure or Stop. Active workers are still cleaned up before completion."
          },
          "concurrency": {
            "type": "object",
            "description": "Up to 5 concurrent senders and 5 preloading Steam sessions; at most 10 managed workers including cleanup.",
            "properties": {
              "sending": {
                "type": "integer",
                "example": 5
              },
              "preloading": {
                "type": "integer",
                "example": 5
              },
              "maxWorkers": {
                "type": "integer",
                "example": 10
              }
            }
          },
          "finished": {
            "type": "boolean",
            "description": "True only for complete, failed or stopped. Wait for this before settling an order."
          },
          "allowPartial": {
            "type": "boolean"
          },
          "availableAtStart": {
            "type": "integer",
            "minimum": 0,
            "description": "Distinct eligible account pool at creation; null for historical tasks.",
            "nullable": true
          },
          "unfulfilledCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Final requestedCount minus completedAccounts when finished, otherwise zero."
          },
          "pendingCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Unconfirmed quantity while running/stopping; zero when finished."
          },
          "result": {
            "type": "object",
            "nullable": true,
            "description": "Null while preparing/running/stopping. Partial fulfillment retains state failed for compatibility; inspect this result even on failed or stopped tasks. Counts only GC-confirmed delivery.",
            "properties": {
              "requestedCount": {
                "type": "integer",
                "minimum": 0,
                "description": "Original requested quantity."
              },
              "completedAccounts": {
                "type": "integer",
                "minimum": 0,
                "description": "Unique GC-confirmed deliveries."
              },
              "unfulfilledCount": {
                "type": "integer",
                "minimum": 0,
                "description": "Unfulfilled quantity."
              },
              "status": {
                "type": "string",
                "enum": [
                  "complete",
                  "partial",
                  "unfulfilled"
                ]
              }
            }
          },
          "targetPresence": {
            "type": "string",
            "enum": [
              "present",
              "absent",
              "unknown"
            ]
          },
          "presenceCheckedAt": {
            "type": "integer",
            "nullable": true,
            "description": "Unix milliseconds of a fresh healthy server snapshot; null when unavailable."
          },
          "presenceRequired": {
            "type": "boolean"
          },
          "phase": {
            "type": "string",
            "description": "Execution detail: waiting_for_target, presence_unknown, starting_accounts, cleaning, or the compatible task state. state remains running while work is starting or cleaning."
          },
          "presenceWaitDeadline": {
            "type": "integer",
            "nullable": true
          },
          "failureCode": {
            "type": "string",
            "nullable": true,
            "description": "TARGET_WAIT_TIMEOUT, PRESENCE_UNAVAILABLE, GC_CONFIRMATION_TIMEOUT_STREAK or null."
          },
          "gcTimeoutStreak": {
            "type": "integer",
            "minimum": 0
          },
          "statusMessage": {
            "type": "string",
            "description": "Explanation of the current phase, including waiting for controller cleanup acknowledgement."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "available": {
                "type": "integer"
              },
              "requested": {
                "type": "integer"
              },
              "completedAccounts": {
                "type": "integer",
                "minimum": 0,
                "description": "Zero deliveries / full shortfall on an insufficient-capacity rejection."
              },
              "unfulfilledCount": {
                "type": "integer",
                "minimum": 0,
                "description": "Zero deliveries / full shortfall on an insufficient-capacity rejection."
              }
            }
          }
        }
      },
      "CapacityRequest": {
        "type": "object",
        "required": [
          "target",
          "count"
        ],
        "properties": {
          "target": {
            "type": "string",
            "description": "SteamID64, Steam profile URL, or vanity",
            "example": "de_m00n"
          },
          "count": {
            "type": "integer",
            "minimum": 1,
            "description": "Desired unique GC-confirmed successful accounts; positive safe integer, no arbitrary account cap. allowPartial permits a smaller initial pool. Exhaustion reports failed and an exact final shortfall."
          },
          "pcId": {
            "type": "string",
            "description": "Required when more than one owned machine is connected"
          }
        }
      },
      "Capacity": {
        "type": "object",
        "properties": {
          "requestedCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Original order quantity."
          },
          "eligibleAccounts": {
            "type": "integer",
            "minimum": 0,
            "description": "Distinct eligible saved logins for this target after quota, recipient and active task reservations."
          },
          "availableAccounts": {
            "type": "integer",
            "minimum": 0,
            "description": "Eligible accounts usable now; zero when machine is busy or incompatible."
          },
          "executableCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Minimum of requestedCount and availableAccounts; not a delivery guarantee."
          },
          "shortfallCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Requested count minus executableCount at this snapshot."
          },
          "checkedAt": {
            "type": "integer",
            "minimum": 0,
            "description": "Snapshot timestamp in Unix milliseconds."
          },
          "pcId": {
            "type": "string"
          },
          "target": {
            "type": "string"
          },
          "server": {
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          },
          "busy": {
            "type": "boolean"
          },
          "compatible": {
            "type": "boolean"
          },
          "canFullyComplete": {
            "type": "boolean"
          },
          "reserved": {
            "type": "boolean",
            "description": "Always false: this read-only check does not reserve capacity. Start rechecks availability atomically after resolving the target."
          },
          "source": {
            "type": "string",
            "enum": [
              "saved_account_snapshot"
            ],
            "description": "Uses persisted GC balance where available, otherwise an estimate; does not start accounts or query Steam."
          },
          "targetPresence": {
            "type": "string",
            "enum": [
              "present",
              "absent",
              "unknown"
            ]
          },
          "presenceCheckedAt": {
            "type": "integer",
            "nullable": true,
            "description": "Unix milliseconds of a fresh healthy server snapshot; null when unavailable."
          },
          "presenceRequired": {
            "type": "boolean"
          },
          "canStartNow": {
            "type": "boolean",
            "description": "Has usable account capacity and, where required, the target is present. Snapshot, not a delivery guarantee."
          }
        }
      }
    }
  }
}
