> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myabode.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# List deals

> Returns the deals the member the key belongs to can read, most recently updated first, in the standard list envelope. Every filter narrows within that fence and ANDs with the others; `id` returns the readable deals among up to 100 ids, and a `brokerage` the key cannot read matches nothing. Page by passing `next_cursor` back as `cursor`. Requires the `deals:read` scope.



## OpenAPI

````yaml https://api.myabode.ca/v1/openapi.json get /v1/deals
openapi: 3.1.1
info:
  title: myAbode Public API
  version: 1.0.0
  description: >-
    The `/v1` surface. Authenticate with `Authorization: Bearer mya_…`. A member
    key reads what its member reads; a service key reads its brokerage. Every
    failure is an RFC 9457 Problem Details body served as
    `application/problem+json`; branch on its `code`.
servers:
  - url: https://api.myabode.ca
security:
  - apiKey: []
paths:
  /v1/deals:
    get:
      summary: List deals
      description: >-
        Returns the deals the member the key belongs to can read, most recently
        updated first, in the standard list envelope. Every filter narrows
        within that fence and ANDs with the others; `id` returns the readable
        deals among up to 100 ids, and a `brokerage` the key cannot read matches
        nothing. Page by passing `next_cursor` back as `cursor`. Requires the
        `deals:read` scope.
      operationId: deals.list
      parameters:
        - name: id
          in: query
          schema:
            type: array
            maxItems: 100
            items:
              type: string
              minLength: 1
          style: form
          explode: true
          allowEmptyValue: true
          allowReserved: true
        - name: brokerage
          in: query
          schema:
            type: array
            maxItems: 100
            items:
              type: string
              minLength: 1
          style: form
          explode: true
          allowEmptyValue: true
          allowReserved: true
        - name: address
          in: query
          schema:
            type: string
            minLength: 2
            maxLength: 200
          allowEmptyValue: true
          allowReserved: true
        - name: mls_number
          in: query
          schema:
            type: string
            minLength: 1
            maxLength: 50
          allowEmptyValue: true
          allowReserved: true
        - name: status
          in: query
          schema:
            type: array
            maxItems: 100
            items:
              enum:
                - SUBMITTED
                - IN_PROGRESS
                - READY_FOR_PAYOUT
                - PAID_OUT
                - COMPLETED
                - FELL_THROUGH
              type: string
              description: >-
                Deal status. New values may be added; this is not a breaking
                change. Handle unknown values.
          style: form
          explode: true
          allowEmptyValue: true
          allowReserved: true
        - name: updated_since
          in: query
          schema:
            type: string
            format: date-time
          allowEmptyValue: true
          allowReserved: true
        - name: cursor
          in: query
          schema:
            type: string
            minLength: 1
            description: 'Opaque: send back a next_cursor unchanged.'
          allowEmptyValue: true
          allowReserved: true
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          allowEmptyValue: true
          allowReserved: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DealList'
        '400':
          description: >-
            A parameter failed validation — a filter, a paging value or the path
            id. `errors[]` names each rejected value with a JSON Pointer. A
            `cursor` this API cannot read, or one sent with a different `sort`,
            is `INVALID_CURSOR` and fails the same way on every retry: drop it
            and re-run the initial sync (on `/v1/events`, from `start=latest`,
            as for a 410).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: >-
            No `Authorization: Bearer mya_…` header (`API_KEY_REQUIRED`), or a
            credential this API will not accept (`API_KEY_INVALID`). Unknown,
            revoked and expired keys are one outcome.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: >-
            The key is valid but does not hold the scope this route requires
            (`INSUFFICIENT_SCOPE`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: >-
            No such resource, or none this key may read — the two answers are
            identical bar `request_id` (`NOT_FOUND`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: >-
            The key spent its per-minute request budget (`RATE_LIMITED`).
            `Retry-After` carries the seconds to wait.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    DealList:
      type: object
      properties:
        object:
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/DealListItem'
        has_more:
          type: boolean
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - object
        - data
        - has_more
        - next_cursor
      description: >-
        The `/v1` list envelope. `data` holds this page in `updated_at`
        descending order; `has_more` says whether another page exists, and when
        it does `next_cursor` is the opaque token to send back as `cursor` to
        fetch it. There is no total — count what you page through.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        detail:
          type: string
        code:
          type: string
        request_id:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              pointer:
                type: string
              code:
                type: string
              detail:
                type: string
              resource:
                type: string
            required:
              - pointer
              - code
              - detail
      required:
        - type
        - title
        - status
        - detail
        - code
        - request_id
      additionalProperties: false
      description: >-
        RFC 9457 Problem Details — the only error body the `/v1` surface emits,
        served as `application/problem+json` on every failure. Branch on `code`,
        not on `title` or `detail`; quote `request_id` (also the `Request-Id`
        response header) in a support request. `errors` is present only on a
        400, carrying one entry per rejected field.
    DealListItem:
      type: object
      properties:
        object:
          const: deal
        id:
          type: string
        brokerage:
          type: string
        office:
          anyOf:
            - type: string
            - type: 'null'
        status:
          enum:
            - SUBMITTED
            - IN_PROGRESS
            - READY_FOR_PAYOUT
            - PAID_OUT
            - COMPLETED
            - FELL_THROUGH
          type: string
          description: >-
            Deal status. New values may be added; this is not a breaking change.
            Handle unknown values.
        deal_type:
          anyOf:
            - type: string
            - type: 'null'
        title:
          anyOf:
            - type: string
            - type: 'null'
        mls_number:
          anyOf:
            - type: string
            - type: 'null'
        jurisdiction_code:
          anyOf:
            - type: string
            - type: 'null'
        address:
          type: object
          properties:
            line1:
              anyOf:
                - type: string
                - type: 'null'
            line2:
              anyOf:
                - type: string
                - type: 'null'
            city:
              anyOf:
                - type: string
                - type: 'null'
            province:
              anyOf:
                - type: string
                - type: 'null'
            postal_code:
              anyOf:
                - type: string
                - type: 'null'
          required:
            - line1
            - line2
            - city
            - province
            - postal_code
          additionalProperties: false
        list_price:
          anyOf:
            - type: string
              pattern: ^-?\d+\.\d{2}$
            - type: 'null'
        accepted_price:
          anyOf:
            - type: string
              pattern: ^-?\d+\.\d{2}$
            - type: 'null'
        sale_price:
          anyOf:
            - type: string
              pattern: ^-?\d+\.\d{2}$
            - type: 'null'
        monthly_rent:
          anyOf:
            - type: string
              pattern: ^-?\d+\.\d{2}$
            - type: 'null'
        lease_term_months:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        offer_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        accepted_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        firm_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        close_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        lease_start_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        listing_expiry_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
        is_exclusive_listing:
          anyOf:
            - type: boolean
            - type: 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        url:
          type: string
        agents:
          type: array
          items:
            type: object
            properties:
              user:
                type: object
                properties:
                  type:
                    const: user
                  id:
                    type: string
                  name:
                    anyOf:
                      - type: string
                      - type: 'null'
                required:
                  - type
                  - id
                  - name
                additionalProperties: false
              role:
                anyOf:
                  - enum:
                      - PRIMARY
                      - CO_AGENT
                      - ASSISTANT
                      - REFERRAL
                    type: string
                    description: >-
                      Agent role. New values may be added; this is not a
                      breaking change. Handle unknown values.
                  - type: 'null'
              side:
                anyOf:
                  - enum:
                      - LISTING
                      - COOP
                    type: string
                    description: >-
                      Deal side. New values may be added; this is not a breaking
                      change. Handle unknown values.
                  - type: 'null'
              is_primary:
                type: boolean
            required:
              - user
              - role
              - side
              - is_primary
            additionalProperties: false
      required:
        - object
        - id
        - brokerage
        - office
        - status
        - deal_type
        - title
        - mls_number
        - jurisdiction_code
        - address
        - list_price
        - accepted_price
        - sale_price
        - monthly_rent
        - lease_term_months
        - offer_date
        - accepted_date
        - firm_date
        - close_date
        - lease_start_date
        - listing_expiry_date
        - is_exclusive_listing
        - created_at
        - updated_at
        - url
        - agents
      additionalProperties: false
      description: >-
        A deal as a list row — every field of the deal except `parties`, which
        `GET /v1/deals/{id}` and `expand=deal` carry.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key of the form `mya_…`, sent as `Authorization: Bearer mya_…`.
        The secret is shown once, when the key is created.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.