animalchecklist-com Leaderboard API

openapi: 3.2.0
info:
  title: Animal Checklist Leaderboard API
  version: 1.0.0
  summary: Animal catalogue and account features.
  description: 'Search animals in eight languages and read licensed photos and summaries. Public catalogue reads need no account. Photo recognition and account data require a session. Sightings accept an anonymous sync code or an account session. Accounts use email magic links and passkeys. Versioning: URL path `/api/v1`; a breaking change ships as `/api/v2` and `/api/v1` then answers with Deprecation (RFC 9745) and Sunset (RFC 8594) headers for at least 180 days. Pagination: page and per query parameters, with total, page and per repeated in the answer. Batch: `GET /animals?ids=` reads up to 500 animals in one request. Errors: `{"error":{"code","message"}}`. Check each photo licence and source; summaries are Wikipedia CC BY-SA 4.0; names and counts come from iNaturalist and Wikidata.'
  termsOfService: https://animalchecklist.com/about
  contact:
    name: Animal Checklist
    url: https://animalchecklist.com/for-agents
    email: animalchecklist@arnekellmann.de
  license:
    name: CC BY-SA 4.0 (API description only)
    url: https://creativecommons.org/licenses/by-sa/4.0/
servers:
- url: https://animalchecklist.com/api/v1
  description: Production
security: []
tags:
- name: Leaderboard
paths:
  /leaderboard:
    get:
      operationId: getLeaderboard
      summary: Read the ranks of visible participants
      description: The viewer must sign in and enable leaderboard visibility. Score equals speciesCount plus quizPoints. Emails remain private. Species lists retain their existing visibility rules.
      security:
      - sessionCookie: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        description: Result page.
      - name: per
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 60
          default: 30
        description: Items per page.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 10000
        description: Read the ranked prefix instead of a page.
      responses:
        '200':
          description: Ranked participants. No-store.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - items
                    - total
                    - page
                    - per
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/LeaderboardEntry'
                      total:
                        type: integer
                      page:
                        type: integer
                      per:
                        type: integer
              example:
                data: {}
        '400':
          description: Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INVALID_INPUT
                  message: 'page: Number must be at least 1'
        '401':
          description: Sign-in required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: AUTH_REQUIRED
                  message: Sign in to your account
        '403':
          description: A same-origin request is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INVALID_ORIGIN
                  message: Use this site
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: Unknown animal
        '409':
          description: Account changed in another tab.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: ACCOUNT_SWITCH_REQUIRED
                  message: Refresh your account before changing data
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: RATE_LIMITED
                  message: Too many requests; try again later
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '500':
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INTERNAL
                  message: Unexpected error
      tags:
      - Leaderboard
components:
  headers:
    Sunset:
      schema:
        type: string
        format: http-date
      description: RFC 8594. Date the deprecated version stops answering.
    RateLimit-Policy:
      schema:
        type: string
      description: Quota policy of a metered endpoint, for example "accounts";q=20;w=3600.
    Deprecation:
      schema:
        type: string
      description: RFC 9745. Present on every answer of a deprecated version.
  schemas:
    LeaderboardEntry:
      type: object
      required:
      - rank
      - accountId
      - username
      - speciesCount
      - quizPoints
      - score
      properties:
        rank:
          type: integer
          minimum: 1
        accountId:
          type: string
          format: uuid
        username:
          type: string
        speciesCount:
          type: integer
          minimum: 0
        quizPoints:
          type: integer
          minimum: 0
        score:
          type: integer
          minimum: 0
    Error:
      type: object
      title: Error
      description: Every failure answers this shape. The status matches `error.code`.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - INVALID_INPUT
              - INVALID_JSON
              - UNKNOWN_CODE
              - UNKNOWN_ANIMAL
              - CANDIDATE_UNAVAILABLE
              - CANDIDATE_IMAGE_UNAVAILABLE
              - AUTH_REQUIRED
              - INVALID_ORIGIN
              - INVALID_BODY
              - INVALID_EMAIL
              - EMAIL_UNAVAILABLE
              - INVALID_LINK
              - INVALID_PASSKEY
              - INVALID_CHALLENGE
              - PASSKEY_LIMIT
              - PASSKEY_UNAVAILABLE
              - PASSKEY_NOT_FOUND
              - ACCOUNT_SWITCH_REQUIRED
              - ACCOUNT_LINKED
              - QUIZ_UNAVAILABLE
              - QUIZ_NOT_FOUND
              - QUIZ_EXPIRED
              - QUIZ_INCOMPLETE
              - QUIZ_ALREADY_SAVED
              - INVALID_ANSWER
              - QUIZ_ORDER
              - QUIZ_ANSWERED
              - MCP_KEY_LIMIT
              - NOT_FOUND
              - TOO_LARGE
              - RATE_LIMITED
              - INTERNAL
              description: Machine-readable reason.
            message:
              type: string
              description: One sentence for a human.
  securitySchemes:
    syncCode:
      type: http
      scheme: bearer
      bearerFormat: AC-XXXX-XXXX-XXXX-XXXX
      description: The person's anonymous sync code. It grants read and write access to that one checklist and nothing else. An agent uses a code only when the person supplied it.
    quizRound:
      type: http
      scheme: bearer
      bearerFormat: 43-character opaque round secret
      description: Keep this secret in local storage. Completed guest rounds remain claimable until deletion.
    sessionCookie:
      type: apiKey
      in: cookie
      name: ac_session
      description: HttpOnly session set after a magic link or passkey sign-in.
externalDocs:
  description: Agent guide
  url: https://animalchecklist.com/for-agents
x-authentication:
  scheme: public reads; sync code or session for sightings; session for recognition and account data
  description: Catalogue reads need no key or account. Sightings accept a sync code or the person's session cookie. Recognition, account and passkey management require a session cookie.
  docs: https://animalchecklist.com/for-agents
x-versioning-policy:
  scheme: url-path
  current: v1
  deprecation: A breaking change ships as a new path version. The old version answers with a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) at least 180 days before removal.
  headers:
  - Deprecation
  - Sunset
  noticePeriodDays: 180
  docs: https://animalchecklist.com/for-agents
x-pagination:
  style: page
  description: Send `page` from 1 and `per` up to 120 for animals or 100 for registry endpoints. Default per is 60. Stop when page * per >= total.
  requestParameters:
  - page
  - per
  responseFields:
  - total
  - page
  - per
  endpoints:
  - /animals
  - /taxa
  - /breeds
x-batch-endpoints:
- path: /animals
  method: get
  operationId: getAnimalsByIds
  itemsField: ids
  maxItems: 500
  description: Reads up to 500 animals in one request with a comma separated `ids` list.
- path: /sightings
  method: put
  operationId: putSightings
  itemsField: sightings
  maxItems: 2000
  description: Merges up to 2000 sightings in one request.
x-rate-limit:
  description: Public catalogue reads use edge caching. POST /accounts allows 20 requests per IP per hour. POST /recognitions allows 10 per IP per hour, 20 per account per day, and 200 total per day. POST /client-error allows 30 per IP per hour.
  headers:
  - RateLimit-Policy
  - Retry-After
  accountsPerHour: 20
  clientErrorPerHour: 30
x-llms-txt: https://animalchecklist.com/llms.txt
x-agents-md: https://animalchecklist.com/agents.md
x-api-catalog: https://animalchecklist.com/.well-known/api-catalog
x-licence:
  scope: The info.license covers this API description. Response content keeps its source rights.
  terms: https://animalchecklist.com/licences
  photos: CC0, Public domain, Pexels License or Pixabay Content License; see each image record
  texts: Wikipedia excerpts, CC BY-SA 4.0. Keep attribution, licence link, changes and supplied notices. Check article exceptions.
  data: 'Structured Wikidata: CC0. iNaturalist taxonomy archive: no explicit licence supplied. Breed standards: source-specific rights.'