animalchecklist-com Diagnostics API

openapi: 3.2.0
info:
  title: Animal Checklist Diagnostics 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: Diagnostics
  description: Client error reports.
paths:
  /animals/{id}/photo-report:
    post:
      operationId: reportPhoto
      summary: Report a bad species photo
      description: 'Flags the photo of one species for review: dead animal, poor photo, wrong species, drawing or other, with an optional note. Answers 204 with no body. Limit: 200 requests per IP per day.'
      tags:
      - Diagnostics
      parameters:
      - name: id
        in: path
        required: true
        description: Species id (slug).
        schema:
          type: string
        example: red-fox
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  enum:
                  - dead
                  - poor-quality
                  - unclear
                  - wrong-species
                  - drawing
                  - other
                  default: other
                  description: 'poor-quality: blurry, low quality or the animal is hard to see. unclear is the legacy value.'
                note:
                  type: string
                  maxLength: 500
                  description: Optional free text for the review.
            example:
              reason: poor-quality
              note: The fox is a tiny blur.
      responses:
        '204':
          description: Accepted. No body.
        '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'
        '404':
          description: Unknown species.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: Unknown animal
        '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
  /client-error:
    post:
      operationId: reportClientError
      summary: Report a browser error
      description: 'Forwards one unhandled browser error to the operator. Answers 204 with no body. Limit: 30 requests per IP per hour. Agents do not need this endpoint.'
      tags:
      - Diagnostics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - message
              properties:
                message:
                  type: string
                  maxLength: 1000
                stack:
                  type: string
                  maxLength: 4000
                url:
                  type: string
                  maxLength: 500
            example:
              message: 'TypeError: x is not a function'
              url: https://animalchecklist.com/
      responses:
        '204':
          description: Accepted. No body.
        '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'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: Unknown animal
        '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
components:
  schemas:
    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.
  headers:
    RateLimit-Policy:
      schema:
        type: string
      description: Quota policy of a metered endpoint, for example "accounts";q=20;w=3600.
  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.'