openapi: 3.0.3
info:
  title: MLS Grid RESO Web API
  description: |
    The MLS Grid RESO Web API is a normalized, RESO Data Dictionary–compliant OData v4 Web API for replicating
    Multiple Listing Service (MLS) data across the dozens of participating boards on the MLS Grid network. The
    API is optimized for incremental replication using `ModificationTimestamp`, supports `$select`, `$filter`,
    and `$expand` for related resources (Media, Rooms, UnitTypes), and applies a single license agreement across
    all participating MLSs.

    Authentication uses long-lived OAuth 2.0 bearer tokens issued through the MLS Grid web application.
  version: 2.0.0
  contact:
    name: MLS Grid Support
    email: support@mlsgrid.com
    url: https://www.mlsgrid.com
  license:
    name: MLS Grid Master Data License Agreement
    url: https://www.mlsgrid.com
  x-logo:
    url: https://www.mlsgrid.com
servers:
- url: https://api.mlsgrid.com/v2
  description: MLS Grid Web API v2 (production)
tags:
- name: Property
  description: Property listings (RESO Data Dictionary Property resource).
- name: Member
  description: Real estate agents (RESO Data Dictionary Member resource).
- name: Office
  description: Brokerage offices (RESO Data Dictionary Office resource).
- name: OpenHouse
  description: Open house events (RESO Data Dictionary OpenHouse resource).
- name: Media
  description: Listing media (photos, virtual tours) expanded from Property.
- name: Lookup
  description: Enumerated lookup values per originating MLS.
- name: Metadata
  description: OData service and EDMX metadata.
paths:
  /$metadata:
    get:
      tags:
      - Metadata
      summary: Get Service Metadata
      description: Returns the OData v4 EDMX metadata document describing all entity types, properties, navigation properties, and enumerations exposed by the MLS Grid Web API.
      operationId: getMetadata
      responses:
        '200':
          description: EDMX metadata document.
          content:
            application/xml:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /Property:
    get:
      tags:
      - Property
      summary: List Properties
      description: Replicate Property listings filtered by `OriginatingSystemName` and `ModificationTimestamp`. Use `$expand=Media,Rooms,UnitTypes` to include nested resources and `@odata.nextLink` for pagination.
      operationId: listProperties
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Expand'
      - $ref: '#/components/parameters/Top'
      - $ref: '#/components/parameters/Count'
      responses:
        '200':
          description: Collection of Property records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /Property('{ListingKey}'):
    get:
      tags:
      - Property
      summary: Get Property by Key
      description: Retrieve a single Property record by its prefixed `ListingKey` (e.g. `actris-1234567`).
      operationId: getProperty
      parameters:
      - name: ListingKey
        in: path
        required: true
        schema:
          type: string
        description: Prefixed MLS Grid listing key.
      - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: A single Property record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Property'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Property not found.
  /Member:
    get:
      tags:
      - Member
      summary: List Members
      description: Replicate Member (agent) records filtered by `OriginatingSystemName` and `ModificationTimestamp`.
      operationId: listMembers
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Top'
      - $ref: '#/components/parameters/Count'
      responses:
        '200':
          description: Collection of Member records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /Office:
    get:
      tags:
      - Office
      summary: List Offices
      description: Replicate Office (brokerage) records filtered by `OriginatingSystemName` and `ModificationTimestamp`.
      operationId: listOffices
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Top'
      - $ref: '#/components/parameters/Count'
      responses:
        '200':
          description: Collection of Office records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfficeCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /OpenHouse:
    get:
      tags:
      - OpenHouse
      summary: List Open Houses
      description: Replicate OpenHouse events filtered by `OriginatingSystemName` and `ModificationTimestamp`.
      operationId: listOpenHouses
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Top'
      responses:
        '200':
          description: Collection of OpenHouse records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenHouseCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /Media:
    get:
      tags:
      - Media
      summary: List Media
      description: Replicate Media records as a standalone resource where supported by the originating MLS. Use `MediaModificationTimestamp` for incremental replication.
      operationId: listMedia
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Top'
      responses:
        '200':
          description: Collection of Media records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /Lookup:
    get:
      tags:
      - Lookup
      summary: List Lookup Values
      description: Retrieve enumerated lookup values per originating MLS. Filter by `OriginatingSystemName` and `LookupName`.
      operationId: listLookups
      parameters:
      - $ref: '#/components/parameters/Filter'
      - $ref: '#/components/parameters/Select'
      - $ref: '#/components/parameters/Top'
      responses:
        '200':
          description: Collection of Lookup records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2
      description: Long-lived OAuth 2.0 bearer token issued via the MLS Grid web application token tab.
  parameters:
    Filter:
      name: $filter
      in: query
      description: |
        OData `$filter` expression. Required pattern uses `OriginatingSystemName eq '<system>'` combined with
        `ModificationTimestamp gt <UTC datetime>` for incremental replication. Replication queries are
        restricted to a limited set of searchable fields documented per resource.
      schema:
        type: string
      example: OriginatingSystemName eq 'actris' and ModificationTimestamp gt 2026-01-01T00:00:00Z
    Select:
      name: $select
      in: query
      description: Comma-separated list of fields to return. Reduces payload size.
      schema:
        type: string
      example: ListingKey,StandardStatus,ListPrice,ModificationTimestamp
    Expand:
      name: $expand
      in: query
      description: Comma-separated list of related resources to expand inline. Common values for Property are `Media`, `Rooms`, and `UnitTypes`.
      schema:
        type: string
      example: Media,Rooms,UnitTypes
    Top:
      name: $top
      in: query
      description: Maximum number of records to return per page.
      schema:
        type: integer
        maximum: 1000
    Count:
      name: $count
      in: query
      description: When `true`, includes `@odata.count` in the response.
      schema:
        type: boolean
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
    RateLimited:
      description: Rate limit exceeded. The MLS Grid Web API enforces 2 RPS, 7,200 requests/hour, 40,000 requests/24h, and 4 GB/hour download caps. Repeated violations may suspend the token.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the client may retry.
  schemas:
    Property:
      type: object
      description: RESO Data Dictionary Property resource. Only fields present in the originating MLS are populated.
      properties:
        ListingKey:
          type: string
          description: Prefixed MLS Grid listing key (e.g. `actris-1234567`).
        OriginatingSystemName:
          type: string
          description: Source MLS identifier (e.g. `actris`, `mred`, `nwmls`).
        StandardStatus:
          type: string
          description: RESO StandardStatus enumeration.
          enum:
          - Active
          - ActiveUnderContract
          - Pending
          - Hold
          - Withdrawn
          - Expired
          - Closed
          - Canceled
          - ComingSoon
          - Delete
          - Incomplete
        PropertyType:
          type: string
          description: RESO PropertyType enumeration.
          enum:
          - Residential
          - ResidentialIncome
          - ResidentialLease
          - CommercialSale
          - CommercialLease
          - BusinessOpportunity
          - Farm
          - Land
          - ManufacturedInPark
        ListPrice:
          type: number
        ModificationTimestamp:
          type: string
          format: date-time
        PhotosChangeTimestamp:
          type: string
          format: date-time
        MlgCanView:
          type: boolean
          description: Indicates whether the listing may currently be viewed under license terms.
        MlgCanUse:
          type: array
          description: Allowed use cases for the listing (e.g. `IDX`, `VOW`, `BO`, `PT`).
          items:
            type: string
        Media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        Rooms:
          type: array
          items:
            $ref: '#/components/schemas/Room'
        UnitTypes:
          type: array
          items:
            $ref: '#/components/schemas/UnitType'
    PropertyCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Property'
    Member:
      type: object
      properties:
        MemberKey:
          type: string
        OriginatingSystemName:
          type: string
        MemberFirstName:
          type: string
        MemberLastName:
          type: string
        MemberEmail:
          type: string
        MemberMlsId:
          type: string
        ModificationTimestamp:
          type: string
          format: date-time
        MlgCanView:
          type: boolean
    MemberCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Member'
    Office:
      type: object
      properties:
        OfficeKey:
          type: string
        OriginatingSystemName:
          type: string
        OfficeName:
          type: string
        OfficeMlsId:
          type: string
        ModificationTimestamp:
          type: string
          format: date-time
        MlgCanView:
          type: boolean
    OfficeCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Office'
    OpenHouse:
      type: object
      properties:
        OpenHouseKey:
          type: string
        ListingKey:
          type: string
        OriginatingSystemName:
          type: string
        OpenHouseStartTime:
          type: string
          format: date-time
        OpenHouseEndTime:
          type: string
          format: date-time
        ModificationTimestamp:
          type: string
          format: date-time
    OpenHouseCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/OpenHouse'
    Media:
      type: object
      properties:
        MediaKey:
          type: string
        ResourceRecordKey:
          type: string
          description: Foreign key back to Property (or other resource).
        OriginatingSystemName:
          type: string
        MediaURL:
          type: string
          description: URL for downloading a local copy. Direct hot-linking is not permitted.
        MediaCategory:
          type: string
        Order:
          type: integer
        MediaModificationTimestamp:
          type: string
          format: date-time
    MediaCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Media'
    Room:
      type: object
      properties:
        RoomKey:
          type: string
        RoomType:
          type: string
        RoomLevel:
          type: string
        RoomLength:
          type: number
        RoomWidth:
          type: number
    UnitType:
      type: object
      properties:
        UnitTypeKey:
          type: string
        UnitTypeType:
          type: string
        UnitTypeBedsTotal:
          type: integer
        UnitTypeBathsTotal:
          type: number
    Lookup:
      type: object
      properties:
        LookupKey:
          type: string
        OriginatingSystemName:
          type: string
        LookupName:
          type: string
        LookupValue:
          type: string
        StandardLookupValue:
          type: string
        ModificationTimestamp:
          type: string
          format: date-time
    LookupCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Lookup'
security:
- bearerAuth: []