{
  "openapi": "3.1.0",
  "info": {
    "title": "Donatty public API",
    "version": "1.0.0",
    "summary": "Read-only data of one Donatty streamer: profile, donations, goals, top donors and totals.",
    "description": "Every route returns data of exactly the streamer who issued the key; there is no way to ask for another streamer. Authentication: `Authorization: Bearer dnt_...` only — a secret key `dnt_pat_...` (servers, bots) or the public key `dnt_pk_...` (static sites: profile, goals and statistics, accepted from the streamer's allowed site Origins only). Keys in the query string are rejected with `400 token_in_query`; cookies are ignored.\n\nFormats: ids are `<prefix>_<uuid>` strings; time is RFC 3339 in UTC; money is `{value, currency}` with a decimal string and an ISO 4217 code. Clients must ignore unknown fields and enum values: v1 only adds.\n\nErrors are `application/problem+json` (RFC 9457) with `type`, `title`, `status`, `detail` and `code`.\n\nRate limits (per minute): `app-user` 600 (app × streamer), `app` 6000 (app over all streamers), `user` 1200 (streamer over all apps), `publishable-ip` 60 (public key × client address). `app-user`, `app` and `user` are counted separately for the secret keys and for the public key; all secret keys of a streamer share one budget. Responses after successful key authentication carry `RateLimit-Policy` and `RateLimit` (draft-ietf-httpapi-ratelimit-headers-08); responses before it (401, `wrong_token_type`, `token_in_query`, `origin_not_allowed`) and this document do not."
  },
  "x-donatty-access": {
    "secretKeyLifetimeDays": [
      30,
      90,
      365
    ],
    "maxActiveKeys": 20
  },
  "servers": [
    {
      "url": "https://api.donatty.com"
    }
  ],
  "tags": [
    {
      "name": "v1",
      "description": "Public API v1"
    }
  ],
  "paths": {
    "/v1/streamer": {
      "get": {
        "operationId": "getStreamer",
        "summary": "Streamer profile",
        "description": "Your public profile: nickname, name, avatar and the donation page link.",
        "tags": [
          "v1"
        ],
        "security": [
          {
            "personalToken": [
              "profile:read"
            ]
          },
          {
            "publishableKey": [
              "profile:read"
            ]
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Streamer"
                },
                "example": {
                  "id": "str_5b0c2f4e-8d61-4f43-9a7e-2f1d3c6b9a10",
                  "slug": "teststreamer",
                  "displayName": "Test Streamer",
                  "avatarUrl": "https://storage.donatty.com/avatars/teststreamer.png",
                  "donatePageUrl": "https://donatty.com/teststreamer"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is invalid, or the key was sent in the request address.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-invalid-parameter": {
                    "$ref": "#/components/examples/error-invalid-parameter"
                  },
                  "error-token-in-query": {
                    "$ref": "#/components/examples/error-token-in-query"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, unknown, deleted or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-missing-token": {
                    "$ref": "#/components/examples/error-missing-token"
                  },
                  "error-invalid-token": {
                    "$ref": "#/components/examples/error-invalid-token"
                  },
                  "error-token-expired": {
                    "$ref": "#/components/examples/error-token-expired"
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "403": {
            "description": "Wrong kind of key, the key lacks the `profile:read` scope, or the public key came from an address that is not in its list.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-wrong-token-type": {
                    "$ref": "#/components/examples/error-wrong-token-type"
                  },
                  "error-insufficient-scope": {
                    "$ref": "#/components/examples/error-insufficient-scope"
                  },
                  "error-origin-not-allowed": {
                    "$ref": "#/components/examples/error-origin-not-allowed"
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-rate-limited": {
                    "$ref": "#/components/examples/error-rate-limited"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            }
          },
          "500": {
            "description": "The request failed on our side.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-internal-error": {
                    "$ref": "#/components/examples/error-internal-error"
                  }
                }
              }
            }
          },
          "503": {
            "description": "The API is temporarily unavailable.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-service-unavailable": {
                    "$ref": "#/components/examples/error-service-unavailable"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          }
        }
      }
    },
    "/v1/donations": {
      "get": {
        "operationId": "listDonations",
        "summary": "Donations",
        "description": "Your donations, newest first: from Donatty and from Donation Alerts when it is connected. Without a filter you get every donation with its full text, including ones rejected by moderation or still waiting for a decision. To get only what can be shown on stream, add `moderation=PASSED,NONE`. The response has no donor contacts, order or service fee; of the payment details it has only `feeCompensation` (the extra amount the donor paid to cover the fee) and `paymentMethod` (`CARD`, `SBP` or `null`).",
        "tags": [
          "v1"
        ],
        "security": [
          {
            "personalToken": [
              "donations:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          },
          {
            "$ref": "#/components/parameters/since"
          },
          {
            "$ref": "#/components/parameters/source"
          },
          {
            "$ref": "#/components/parameters/moderation"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DonationPage"
                },
                "example": {
                  "items": [
                    {
                      "id": "don_5d2e8f31-6a47-4c19-9b0e-7f3a2d1c8e46",
                      "createdAt": "2026-11-09T10:21:47Z",
                      "source": "DONATTY",
                      "donorName": "Алексей",
                      "message": "Спасибо за стрим!",
                      "amount": {
                        "value": "500.00",
                        "currency": "RUB"
                      },
                      "feeCompensation": {
                        "value": "27.00",
                        "currency": "RUB"
                      },
                      "paymentMethod": "CARD",
                      "goal": null,
                      "moderation": {
                        "status": "PASSED",
                        "deadline": null
                      },
                      "media": null
                    },
                    {
                      "id": "don_0f6e2a4c-91b3-4d7a-8c5e-3b2a1f0e9d84",
                      "createdAt": "2026-11-09T10:15:30.123456Z",
                      "source": "DONATTY",
                      "donorName": "Alex",
                      "message": "Thanks for the stream!",
                      "amount": {
                        "value": "500.00",
                        "currency": "RUB"
                      },
                      "feeCompensation": null,
                      "paymentMethod": "SBP",
                      "goal": {
                        "id": "goal_7e3a9c10-4b2d-4f8e-a1c6-0d9b8e7f6a52",
                        "title": "New microphone"
                      },
                      "moderation": {
                        "status": "PENDING",
                        "deadline": "2026-11-09T10:16:30Z"
                      },
                      "media": {
                        "title": "Song of the day",
                        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                        "provider": "YOUTUBE",
                        "durationSeconds": 212,
                        "moderation": {
                          "status": "PENDING",
                          "deadline": "2026-11-09T10:16:30Z"
                        }
                      }
                    },
                    {
                      "id": "don_3c9d7b21-5e84-4a6f-b0d2-8e1f4a7c6b35",
                      "createdAt": "2026-11-09T10:02:11Z",
                      "source": "DONATTY",
                      "donorName": "Anonymous",
                      "message": "This text was rejected by moderation but is returned in full.",
                      "amount": {
                        "value": "150.50",
                        "currency": "RUB"
                      },
                      "feeCompensation": null,
                      "paymentMethod": "CARD",
                      "goal": null,
                      "moderation": {
                        "status": "BLOCKED",
                        "deadline": null
                      },
                      "media": null
                    },
                    {
                      "id": "don_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
                      "createdAt": "2026-11-09T09:58:00Z",
                      "source": "DONATION_ALERTS",
                      "donorName": "Maria",
                      "message": "Hi from Donation Alerts",
                      "amount": {
                        "value": "5.00",
                        "currency": "USD"
                      },
                      "feeCompensation": null,
                      "paymentMethod": null,
                      "goal": null,
                      "moderation": {
                        "status": "NONE",
                        "deadline": null
                      },
                      "media": null
                    }
                  ],
                  "nextCursor": "MTc5NDIxODI4MDAwMDAwMC45YTFiMmMzZC00ZTVmLTRhNmItOGM3ZC0wZTFmMmEzYjRjNWQ"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is invalid, or the key was sent in the request address.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-invalid-parameter": {
                    "$ref": "#/components/examples/error-invalid-parameter"
                  },
                  "error-token-in-query": {
                    "$ref": "#/components/examples/error-token-in-query"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, unknown, deleted or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-missing-token": {
                    "$ref": "#/components/examples/error-missing-token"
                  },
                  "error-invalid-token": {
                    "$ref": "#/components/examples/error-invalid-token"
                  },
                  "error-token-expired": {
                    "$ref": "#/components/examples/error-token-expired"
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "403": {
            "description": "Wrong kind of key, or the key lacks the `donations:read` scope. The public key never has it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-wrong-token-type": {
                    "$ref": "#/components/examples/error-wrong-token-type"
                  },
                  "error-insufficient-scope": {
                    "$ref": "#/components/examples/error-insufficient-scope"
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-rate-limited": {
                    "$ref": "#/components/examples/error-rate-limited"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            }
          },
          "500": {
            "description": "The request failed on our side.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-internal-error": {
                    "$ref": "#/components/examples/error-internal-error"
                  }
                }
              }
            }
          },
          "503": {
            "description": "The API is temporarily unavailable.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-service-unavailable": {
                    "$ref": "#/components/examples/error-service-unavailable"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          }
        }
      }
    },
    "/v1/goals": {
      "get": {
        "operationId": "listGoals",
        "summary": "Fundraising goals",
        "description": "Your fundraising goals, newest first. `raised` includes the amount you started the goal with (the «Начать сбор с» (Start collecting from) field) and every Donatty donation to the goal, including ones rejected by moderation. Donation Alerts goals and widget settings are not counted, so the amount may differ from what the widget shows on stream.",
        "tags": [
          "v1"
        ],
        "security": [
          {
            "personalToken": [
              "goals:read"
            ]
          },
          {
            "publishableKey": [
              "goals:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/goalStatus"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GoalPage"
                },
                "example": {
                  "items": [
                    {
                      "id": "goal_7e3a9c10-4b2d-4f8e-a1c6-0d9b8e7f6a52",
                      "title": "New microphone",
                      "target": {
                        "value": "15000.00",
                        "currency": "RUB"
                      },
                      "raised": {
                        "value": "6420.50",
                        "currency": "RUB"
                      },
                      "status": "ACTIVE",
                      "endsAt": "2026-12-31T21:00:00Z",
                      "createdAt": "2026-10-01T12:00:00Z"
                    }
                  ],
                  "nextCursor": "MTc5MDg1NjAwMDAwMDAwMC43ZTNhOWMxMC00YjJkLTRmOGUtYTFjNi0wZDliOGU3ZjZhNTI"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is invalid, or the key was sent in the request address.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-invalid-parameter": {
                    "$ref": "#/components/examples/error-invalid-parameter"
                  },
                  "error-token-in-query": {
                    "$ref": "#/components/examples/error-token-in-query"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, unknown, deleted or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-missing-token": {
                    "$ref": "#/components/examples/error-missing-token"
                  },
                  "error-invalid-token": {
                    "$ref": "#/components/examples/error-invalid-token"
                  },
                  "error-token-expired": {
                    "$ref": "#/components/examples/error-token-expired"
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "403": {
            "description": "Wrong kind of key, the key lacks the `goals:read` scope, or the public key came from an address that is not in its list.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-wrong-token-type": {
                    "$ref": "#/components/examples/error-wrong-token-type"
                  },
                  "error-insufficient-scope": {
                    "$ref": "#/components/examples/error-insufficient-scope"
                  },
                  "error-origin-not-allowed": {
                    "$ref": "#/components/examples/error-origin-not-allowed"
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-rate-limited": {
                    "$ref": "#/components/examples/error-rate-limited"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            }
          },
          "500": {
            "description": "The request failed on our side.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-internal-error": {
                    "$ref": "#/components/examples/error-internal-error"
                  }
                }
              }
            }
          },
          "503": {
            "description": "The API is temporarily unavailable.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-service-unavailable": {
                    "$ref": "#/components/examples/error-service-unavailable"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          }
        }
      }
    },
    "/v1/stats/top": {
      "get": {
        "operationId": "getStatsTop",
        "summary": "Top donors",
        "description": "The donors with the largest totals for today, this week, month, year or all time. Donations from all connected sources are counted and converted to rubles. Donors with the same name in different sources are counted as one.",
        "tags": [
          "v1"
        ],
        "security": [
          {
            "personalToken": [
              "stats:read"
            ]
          },
          {
            "publishableKey": [
              "stats:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/topPeriod"
          },
          {
            "$ref": "#/components/parameters/topLimit"
          },
          {
            "$ref": "#/components/parameters/timeZone"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Top"
                },
                "example": {
                  "period": "WEEK",
                  "from": "2026-11-08T21:00:00Z",
                  "to": "2026-11-15T21:00:00Z",
                  "items": [
                    {
                      "rank": 1,
                      "name": "Alex",
                      "total": {
                        "value": "12500.00",
                        "currency": "RUB"
                      }
                    },
                    {
                      "rank": 2,
                      "name": "Maria",
                      "total": {
                        "value": "4300.75",
                        "currency": "RUB"
                      }
                    },
                    {
                      "rank": 3,
                      "name": "Ivan",
                      "total": {
                        "value": "1000.00",
                        "currency": "RUB"
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "A parameter is invalid, or the key was sent in the request address.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-invalid-parameter": {
                    "$ref": "#/components/examples/error-invalid-parameter"
                  },
                  "error-token-in-query": {
                    "$ref": "#/components/examples/error-token-in-query"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, unknown, deleted or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-missing-token": {
                    "$ref": "#/components/examples/error-missing-token"
                  },
                  "error-invalid-token": {
                    "$ref": "#/components/examples/error-invalid-token"
                  },
                  "error-token-expired": {
                    "$ref": "#/components/examples/error-token-expired"
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "403": {
            "description": "Wrong kind of key, the key lacks the `stats:read` scope, or the public key came from an address that is not in its list.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-wrong-token-type": {
                    "$ref": "#/components/examples/error-wrong-token-type"
                  },
                  "error-insufficient-scope": {
                    "$ref": "#/components/examples/error-insufficient-scope"
                  },
                  "error-origin-not-allowed": {
                    "$ref": "#/components/examples/error-origin-not-allowed"
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-rate-limited": {
                    "$ref": "#/components/examples/error-rate-limited"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            }
          },
          "500": {
            "description": "The request failed on our side.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-internal-error": {
                    "$ref": "#/components/examples/error-internal-error"
                  }
                }
              }
            }
          },
          "503": {
            "description": "The API is temporarily unavailable.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-service-unavailable": {
                    "$ref": "#/components/examples/error-service-unavailable"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          }
        }
      }
    },
    "/v1/stats/total": {
      "get": {
        "operationId": "getStatsTotal",
        "summary": "Total donated",
        "description": "The total donated for today, this week, month, year or all time. Donations from all connected sources are counted, including ones rejected by moderation, and converted to rubles.",
        "tags": [
          "v1"
        ],
        "security": [
          {
            "personalToken": [
              "stats:read"
            ]
          },
          {
            "publishableKey": [
              "stats:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/totalPeriod"
          },
          {
            "$ref": "#/components/parameters/totalTimeZone"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Total"
                },
                "example": {
                  "period": "DAY",
                  "from": "2026-11-09T17:00:00Z",
                  "to": "2026-11-10T17:00:00Z",
                  "total": {
                    "value": "18250.25",
                    "currency": "RUB"
                  }
                }
              }
            }
          },
          "400": {
            "description": "A parameter is invalid, or the key was sent in the request address.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-invalid-parameter": {
                    "$ref": "#/components/examples/error-invalid-parameter"
                  },
                  "error-token-in-query": {
                    "$ref": "#/components/examples/error-token-in-query"
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, unknown, deleted or expired.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-missing-token": {
                    "$ref": "#/components/examples/error-missing-token"
                  },
                  "error-invalid-token": {
                    "$ref": "#/components/examples/error-invalid-token"
                  },
                  "error-token-expired": {
                    "$ref": "#/components/examples/error-token-expired"
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "403": {
            "description": "Wrong kind of key, the key lacks the `stats:read` scope, or the public key came from an address that is not in its list.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-wrong-token-type": {
                    "$ref": "#/components/examples/error-wrong-token-type"
                  },
                  "error-insufficient-scope": {
                    "$ref": "#/components/examples/error-insufficient-scope"
                  },
                  "error-origin-not-allowed": {
                    "$ref": "#/components/examples/error-origin-not-allowed"
                  }
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "$ref": "#/components/headers/WWW-Authenticate"
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-rate-limited": {
                    "$ref": "#/components/examples/error-rate-limited"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            }
          },
          "500": {
            "description": "The request failed on our side.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-internal-error": {
                    "$ref": "#/components/examples/error-internal-error"
                  }
                }
              }
            }
          },
          "503": {
            "description": "The API is temporarily unavailable.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                },
                "examples": {
                  "error-service-unavailable": {
                    "$ref": "#/components/examples/error-service-unavailable"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "personalToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "dnt_pat_...",
        "description": "Secret key: chosen scopes, 30/90/365 days, shown once. For servers and bots; keep it secret."
      },
      "publishableKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "dnt_pk_...",
        "description": "Public key: profile:read, goals:read, stats:read; accepted only with an `Origin` header of the streamer's allowed sites. Visible to site visitors."
      }
    },
    "parameters": {
      "limit": {
        "name": "limit",
        "in": "query",
        "description": "How many records to return per page: 1 to 100, 20 by default.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      },
      "topLimit": {
        "name": "limit",
        "in": "query",
        "description": "How many donors to return: 1 to 100, 10 by default.",
        "example": 3,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 10
        }
      },
      "cursor": {
        "name": "cursor",
        "in": "query",
        "description": "`nextCursor` from the previous response; returns the next page.",
        "schema": {
          "type": "string"
        }
      },
      "since": {
        "name": "since",
        "in": "query",
        "description": "Only donations created at or after this moment, for example `2026-11-09T10:00:00Z`.",
        "schema": {
          "type": "string",
          "format": "date-time"
        }
      },
      "source": {
        "name": "source",
        "in": "query",
        "description": "Which sources to return, comma-separated. Without it, all sources.",
        "style": "form",
        "explode": false,
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "DONATTY",
              "DONATION_ALERTS"
            ]
          }
        }
      },
      "moderation": {
        "name": "moderation",
        "in": "query",
        "description": "Which moderation statuses to return, comma-separated. For showing on stream use `PASSED,NONE`. Without it you get every donation, rejected ones included.",
        "style": "form",
        "explode": false,
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "PENDING",
              "PASSED",
              "BLOCKED",
              "NONE"
            ]
          }
        }
      },
      "goalStatus": {
        "name": "status",
        "in": "query",
        "description": "`ACTIVE` — the goal is running, `CLOSED` — it is finished. Without it, all goals.",
        "schema": {
          "type": "string",
          "enum": [
            "ACTIVE",
            "CLOSED"
          ]
        }
      },
      "topPeriod": {
        "name": "period",
        "in": "query",
        "description": "`DAY` — today from 00:00, `WEEK` — this week from Monday, `MONTH` — this month, `YEAR` — this year, `ALL_TIME` — all time. Boundaries follow `timeZone`. `ALL_TIME` by default.",
        "example": "WEEK",
        "schema": {
          "type": "string",
          "enum": [
            "DAY",
            "WEEK",
            "MONTH",
            "YEAR",
            "ALL_TIME"
          ],
          "default": "ALL_TIME"
        }
      },
      "totalPeriod": {
        "name": "period",
        "in": "query",
        "description": "`DAY` — today from 00:00, `WEEK` — this week from Monday, `MONTH` — this month, `YEAR` — this year, `ALL_TIME` — all time. Boundaries follow `timeZone`. `ALL_TIME` by default.",
        "example": "DAY",
        "schema": {
          "type": "string",
          "enum": [
            "DAY",
            "WEEK",
            "MONTH",
            "YEAR",
            "ALL_TIME"
          ],
          "default": "ALL_TIME"
        }
      },
      "timeZone": {
        "name": "timeZone",
        "in": "query",
        "description": "The time zone used for period boundaries, for example `Asia/Novosibirsk`. `Europe/Moscow` by default.",
        "schema": {
          "type": "string",
          "default": "Europe/Moscow",
          "examples": [
            "Asia/Novosibirsk"
          ]
        }
      },
      "totalTimeZone": {
        "name": "timeZone",
        "in": "query",
        "description": "The time zone used for period boundaries, for example `Asia/Novosibirsk`. `Europe/Moscow` by default.",
        "example": "Asia/Novosibirsk",
        "schema": {
          "type": "string",
          "default": "Europe/Moscow",
          "examples": [
            "Asia/Novosibirsk"
          ]
        }
      }
    },
    "headers": {
      "RateLimit-Policy": {
        "description": "Active levels: `\"<level>\";q=<quota>;w=<window seconds>`.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimit": {
        "description": "Remaining per level: `\"<level>\";r=<remaining>;t=<seconds to reset>`.",
        "schema": {
          "type": "string"
        }
      },
      "Retry-After": {
        "description": "Seconds to wait.",
        "schema": {
          "type": "integer"
        }
      },
      "WWW-Authenticate": {
        "description": "`Bearer resource_metadata=\"...\"` on 401; `Bearer error=\"insufficient_scope\", scope=\"...\"` on 403.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "Money": {
        "type": "object",
        "required": [
          "value",
          "currency"
        ],
        "additionalProperties": false,
        "properties": {
          "value": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "description": "Decimal amount with two fraction digits.",
            "examples": [
              "500.00"
            ]
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "examples": [
              "RUB"
            ]
          }
        }
      },
      "Moderation": {
        "type": "object",
        "required": [
          "status",
          "deadline"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "PASSED",
              "BLOCKED",
              "NONE"
            ],
            "description": "`PENDING` — moderation in progress; `PASSED` — approved (including «Повторить на стриме» (Repeat on stream)); `BLOCKED` — rejected; `NONE` — no moderation (disabled, nobody online, Donation Alerts)."
          },
          "deadline": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Only for `PENDING`: when the default decision applies."
          }
        }
      },
      "Streamer": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "displayName",
          "avatarUrl",
          "donatePageUrl"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^str_[0-9a-f-]{36}$",
            "description": "Streamer identifier, `str_…`."
          },
          "slug": {
            "type": "string",
            "description": "Nickname: the last part of the donation page address."
          },
          "displayName": {
            "type": "string",
            "description": "The name donors see."
          },
          "avatarUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Avatar link; `null` when there is no avatar."
          },
          "donatePageUrl": {
            "type": "string",
            "format": "uri",
            "description": "Donation page link."
          }
        }
      },
      "Donation": {
        "type": "object",
        "required": [
          "id",
          "createdAt",
          "source",
          "donorName",
          "message",
          "amount",
          "feeCompensation",
          "paymentMethod",
          "goal",
          "moderation",
          "media"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^don_[0-9a-f-]{36}$",
            "description": "Donation identifier, `don_…`."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the donation was created; for a Donatty donation, when the payment was confirmed."
          },
          "source": {
            "type": "string",
            "enum": [
              "DONATTY",
              "DONATION_ALERTS"
            ],
            "description": "Where the donation came from: `DONATTY` or `DONATION_ALERTS`."
          },
          "donorName": {
            "type": "string",
            "description": "The name the donor entered. If they left it empty, a Donatty donation has `Anonymous`."
          },
          "message": {
            "type": "string",
            "description": "The donor's full message; an empty string if they wrote nothing. Widget filters are not applied."
          },
          "amount": {
            "$ref": "#/components/schemas/Money",
            "description": "The donation amount in its currency, without the donor's extra payment for the fee."
          },
          "feeCompensation": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Money"
              }
            ],
            "description": "The extra amount the donor paid to cover the service fee, in the currency of `amount`; the donor was charged `amount` plus `feeCompensation`. `null` when the donor did not pay it, and always for `DONATION_ALERTS`."
          },
          "paymentMethod": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "string",
                "enum": [
                  "CARD",
                  "SBP"
                ]
              }
            ],
            "description": "How the donor paid: `SBP` (Faster Payments System) or `CARD` — every other way, including Apple Pay and Google Pay and older donations with no recorded method. `null` for `DONATION_ALERTS`."
          },
          "goal": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "id",
                  "title"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "pattern": "^goal_[0-9a-f-]{36}$"
                  },
                  "title": {
                    "type": "string"
                  }
                }
              }
            ],
            "description": "The goal the donation went to: `id` and `title`. `null` when there is none."
          },
          "moderation": {
            "$ref": "#/components/schemas/Moderation",
            "description": "Moderation of the message: status and deadline."
          },
          "media": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "title",
                  "url",
                  "provider",
                  "durationSeconds",
                  "moderation"
                ],
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "provider": {
                    "type": "string",
                    "description": "YOUTUBE, VK, RUTUBE, TWITCH; new values may appear."
                  },
                  "durationSeconds": {
                    "type": "integer"
                  },
                  "moderation": {
                    "$ref": "#/components/schemas/Moderation"
                  }
                }
              }
            ],
            "description": "The video attached to the donation: `title`, `url`, `provider`, `durationSeconds` and its own `moderation`. `null` when there is none."
          }
        }
      },
      "DonationPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Donation"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as `cursor` to get the next page; `null` — last page."
          }
        }
      },
      "Goal": {
        "type": "object",
        "required": [
          "id",
          "title",
          "target",
          "raised",
          "status",
          "endsAt",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^goal_[0-9a-f-]{36}$",
            "description": "Goal identifier, `goal_…`."
          },
          "title": {
            "type": "string",
            "description": "Goal title."
          },
          "target": {
            "$ref": "#/components/schemas/Money",
            "description": "The amount to raise."
          },
          "raised": {
            "$ref": "#/components/schemas/Money",
            "description": "The amount raised: the amount you started the goal with (the «Начать сбор с» (Start collecting from) field) plus Donatty donations to this goal, including ones rejected by moderation."
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "CLOSED"
            ],
            "description": "`ACTIVE` — running, `CLOSED` — finished."
          },
          "endsAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the goal ends; `null` when no end is set."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the goal was created."
          }
        }
      },
      "GoalPage": {
        "type": "object",
        "required": [
          "items",
          "nextCursor"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Goal"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as `cursor` to get the next page; `null` — last page."
          }
        }
      },
      "Top": {
        "type": "object",
        "required": [
          "period",
          "from",
          "to",
          "items"
        ],
        "properties": {
          "period": {
            "type": "string",
            "enum": [
              "DAY",
              "WEEK",
              "MONTH",
              "YEAR",
              "ALL_TIME"
            ],
            "description": "The period from the request."
          },
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the period. For `ALL_TIME`, `1970-01-01T00:00:00Z`."
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the next period; that moment itself is not included. For `ALL_TIME`, the moment of the response."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "rank",
                "name",
                "total"
              ],
              "properties": {
                "rank": {
                  "type": "integer",
                  "minimum": 1,
                  "description": "Position in the top, starting from 1."
                },
                "name": {
                  "type": "string",
                  "description": "Donor name."
                },
                "total": {
                  "$ref": "#/components/schemas/Money",
                  "description": "The donor's total for the period, in rubles."
                }
              }
            }
          }
        }
      },
      "Total": {
        "type": "object",
        "required": [
          "period",
          "from",
          "to",
          "total"
        ],
        "properties": {
          "period": {
            "type": "string",
            "enum": [
              "DAY",
              "WEEK",
              "MONTH",
              "YEAR",
              "ALL_TIME"
            ],
            "description": "The period from the request."
          },
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the period. For `ALL_TIME`, `1970-01-01T00:00:00Z`."
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the next period; that moment itself is not included. For `ALL_TIME`, the moment of the response."
          },
          "total": {
            "$ref": "#/components/schemas/Money",
            "description": "The total donated for the period, in rubles."
          }
        }
      },
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "https://developers.donatty.com/errors/<code>"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "missing_token",
              "invalid_token",
              "token_expired",
              "token_in_query",
              "wrong_token_type",
              "insufficient_scope",
              "origin_not_allowed",
              "invalid_parameter",
              "not_found",
              "rate_limited",
              "internal_error",
              "service_unavailable"
            ]
          },
          "policy": {
            "type": "string",
            "enum": [
              "app-user",
              "app",
              "user",
              "publishable-ip"
            ],
            "description": "Only for `rate_limited`: the exhausted level."
          }
        }
      }
    },
    "examples": {
      "error-missing-token": {
        "value": {
          "type": "https://developers.donatty.com/errors/missing_token",
          "title": "Missing token",
          "status": 401,
          "detail": "Send the app token in the Authorization header: Bearer dnt_...",
          "code": "missing_token"
        }
      },
      "error-invalid-token": {
        "value": {
          "type": "https://developers.donatty.com/errors/invalid_token",
          "title": "Invalid token",
          "status": 401,
          "detail": "The token is unknown, deleted or malformed.",
          "code": "invalid_token"
        }
      },
      "error-token-expired": {
        "value": {
          "type": "https://developers.donatty.com/errors/token_expired",
          "title": "Token expired",
          "status": 401,
          "detail": "The token has expired. Issue a new one in the Donatty dashboard.",
          "code": "token_expired"
        }
      },
      "error-token-in-query": {
        "value": {
          "type": "https://developers.donatty.com/errors/token_in_query",
          "title": "Token in query",
          "status": 400,
          "detail": "Tokens are accepted only in the Authorization header. The token from the query string was not used.",
          "code": "token_in_query"
        }
      },
      "error-wrong-token-type": {
        "value": {
          "type": "https://developers.donatty.com/errors/wrong_token_type",
          "title": "Wrong token type",
          "status": 403,
          "detail": "Public API routes accept only Donatty app tokens (dnt_...); other routes never accept them.",
          "code": "wrong_token_type"
        }
      },
      "error-insufficient-scope": {
        "value": {
          "type": "https://developers.donatty.com/errors/insufficient_scope",
          "title": "Insufficient scope",
          "status": 403,
          "detail": "This route requires the donations:read scope.",
          "code": "insufficient_scope"
        }
      },
      "error-origin-not-allowed": {
        "value": {
          "type": "https://developers.donatty.com/errors/origin_not_allowed",
          "title": "Origin not allowed",
          "status": 403,
          "detail": "This publishable key accepts requests only from the origins allowed for its app.",
          "code": "origin_not_allowed"
        }
      },
      "error-invalid-parameter": {
        "value": {
          "type": "https://developers.donatty.com/errors/invalid_parameter",
          "title": "Invalid parameter",
          "status": 400,
          "detail": "The limit parameter must be an integer from 1 to 100.",
          "code": "invalid_parameter"
        }
      },
      "error-not-found": {
        "value": {
          "type": "https://developers.donatty.com/errors/not_found",
          "title": "Not found",
          "status": 404,
          "detail": "There is no such public API route.",
          "code": "not_found"
        }
      },
      "error-rate-limited": {
        "value": {
          "type": "https://developers.donatty.com/errors/rate_limited",
          "title": "Rate limited",
          "status": 429,
          "detail": "The app-user rate limit is exhausted.",
          "code": "rate_limited",
          "policy": "app-user"
        }
      },
      "error-internal-error": {
        "value": {
          "type": "https://developers.donatty.com/errors/internal_error",
          "title": "Internal error",
          "status": 500,
          "detail": "The request failed on the server. Try again later.",
          "code": "internal_error"
        }
      },
      "error-service-unavailable": {
        "value": {
          "type": "https://developers.donatty.com/errors/service_unavailable",
          "title": "Service unavailable",
          "status": 503,
          "detail": "The API is temporarily unavailable. Retry after the delay in Retry-After.",
          "code": "service_unavailable"
        }
      }
    }
  }
}
