openapi: 3.1.0
info:
  title: RescueGroups.org Animals API
  version: 5.0.0
  description: The RescueGroups.org REST API v5 provides access to adoptable pet data including animals, organizations, breeds, species, colors, and patterns. It supports advanced search with geodistance filtering, pagination, and relationship inclusion. API key authorization is used for public data access; bearer token authorization is used for private/write operations.
  contact:
    name: RescueGroups.org Developer Community
    url: https://groups.google.com/a/rescuegroups.org/g/apidev
  license:
    name: RescueGroups.org Terms
    url: https://rescuegroups.org/
servers:
- url: https://api.rescuegroups.org/v5
  description: Production API
- url: https://dev1-api.rescuegroups.org/v5
  description: Development/Test API
security:
- apiKeyAuth: []
tags:
- name: Animals
  description: Search and retrieve adoptable animal records.
paths:
  /public/animals:
    get:
      tags:
      - Animals
      summary: List Public Animals
      description: Retrieve a paginated list of public adoptable animals.
      operationId: listPublicAnimals
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/sortParam'
      - $ref: '#/components/parameters/fieldsParam'
      - $ref: '#/components/parameters/includeParam'
      responses:
        '200':
          description: A paginated list of animals.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/AnimalListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /public/animals/{animal_id}:
    get:
      tags:
      - Animals
      summary: Get Public Animal
      description: Retrieve a single public adoptable animal by ID.
      operationId: getPublicAnimal
      parameters:
      - name: animal_id
        in: path
        required: true
        schema:
          type: string
        description: The unique animal identifier.
      - $ref: '#/components/parameters/includeParam'
      responses:
        '200':
          description: A single animal record.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/AnimalSingleResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /public/animals/search/{view_name}:
    post:
      tags:
      - Animals
      summary: Search Public Animals
      description: 'Search public adoptable animals using filters, views, and geodistance. Predefined view names include: available, adopted, haspic, cats, dogs, rabbits, and species-specific variants.'
      operationId: searchPublicAnimals
      parameters:
      - name: view_name
        in: path
        required: true
        schema:
          type: string
        description: Predefined view name (e.g., available, adopted, haspic, cats, dogs).
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/sortParam'
      - $ref: '#/components/parameters/includeParam'
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Matching animals.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/AnimalListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    includeParam:
      name: include[]
      in: query
      schema:
        type: array
        items:
          type: string
      description: Related entities to include in the response.
    pageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number for paginated results.
    limitParam:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 250
        default: 25
      description: Number of records per page (max 250).
    sortParam:
      name: sort
      in: query
      schema:
        type: string
      description: Sort field with optional +/- prefix for direction.
    fieldsParam:
      name: fields[]
      in: query
      schema:
        type: array
        items:
          type: string
      description: Specific fields to return.
  schemas:
    RelationshipData:
      type: object
      properties:
        data:
          oneOf:
          - type: object
            properties:
              type:
                type: string
              id:
                type: string
          - type: array
            items:
              type: object
              properties:
                type:
                  type: string
                id:
                  type: string
    AnimalSingleResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Animal'
        included:
          type: array
          items:
            type: object
    SearchFilter:
      type: object
      required:
      - fieldName
      - operation
      properties:
        fieldName:
          type: string
          description: Field name to filter on.
        operation:
          type: string
          enum:
          - equal
          - notequal
          - lessthan
          - greaterthan
          - contains
          - notcontains
          - blank
          - notblank
          - startswith
          - endswith
          description: Filter operation.
        criteria:
          type: string
          description: Filter value or special criteria (e.g., rg:contactID, rg:today).
    GeoDistance:
      type: object
      properties:
        postalcode:
          type: string
          description: Postal code for distance search.
        lat:
          type: number
          description: Latitude for coordinate-based search.
        lon:
          type: number
          description: Longitude for coordinate-based search.
        miles:
          type: integer
          description: Search radius in miles.
        kilometers:
          type: integer
          description: Search radius in kilometers.
    Animal:
      type: object
      properties:
        id:
          type: string
          description: Unique animal identifier.
        type:
          type: string
          enum:
          - animals
        attributes:
          $ref: '#/components/schemas/AnimalAttributes'
        relationships:
          type: object
          properties:
            breeds:
              $ref: '#/components/schemas/RelationshipData'
            colors:
              $ref: '#/components/schemas/RelationshipData'
            patterns:
              $ref: '#/components/schemas/RelationshipData'
            species:
              $ref: '#/components/schemas/RelationshipData'
            orgs:
              $ref: '#/components/schemas/RelationshipData'
            pictures:
              $ref: '#/components/schemas/RelationshipData'
    AnimalListResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Animal'
        included:
          type: array
          items:
            type: object
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
              title:
                type: string
              detail:
                type: string
    AnimalAttributes:
      type: object
      properties:
        name:
          type: string
          description: Animal name.
        birthDate:
          type: string
          format: date
          description: Animal birth date.
        sex:
          type: string
          enum:
          - Male
          - Female
          - Unknown
          description: Animal sex.
        ageGroup:
          type: string
          enum:
          - Baby
          - Young
          - Adult
          - Senior
          description: Age group category.
        sizeGroup:
          type: string
          enum:
          - Small
          - Medium
          - Large
          - Extra Large
          description: Size group category.
        isAdoptionPending:
          type: boolean
          description: Whether adoption is pending.
        isAltered:
          type: boolean
          description: Whether the animal is spayed/neutered.
        pictureCount:
          type: integer
          description: Number of pictures available.
        videoCount:
          type: integer
          description: Number of videos available.
        adoptedDate:
          type: string
          format: date
          description: Date the animal was adopted.
        specialNeedsDetails:
          type: string
          description: Description of any special needs.
        descriptionText:
          type: string
          description: Plain text description of the animal.
        locationCitystate:
          type: string
          description: City and state where the animal is located.
        locationState:
          type: string
          description: State where the animal is located.
        locationDistance:
          type: number
          description: Distance from search location.
        rescueId:
          type: string
          description: External rescue ID.
        url:
          type: string
          format: uri
          description: URL of the animal profile page.
    ResponseMeta:
      type: object
      properties:
        count:
          type: integer
          description: Total number of matching records.
        pageCount:
          type: integer
          description: Total number of pages.
        transactionId:
          type: string
          description: Unique transaction identifier for support requests.
    SearchRequest:
      type: object
      properties:
        data:
          type: object
          properties:
            filters:
              type: array
              items:
                $ref: '#/components/schemas/SearchFilter'
            filterProcessing:
              type: string
              description: Boolean expression for filter combination.
            geodistance:
              $ref: '#/components/schemas/GeoDistance'
  responses:
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid authorization.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key authorization for public data access.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token for private/authenticated data access.