openapi: 3.0.1
info:
  title: Cherre GraphQL API
  description: >-
    HTTP modeling of Cherre's single GraphQL API for connected real-estate data
    (property, tax assessor, recorder/deeds, mortgages/liens, owners, parcel
    boundaries, demographics, and connected datasets). GraphQL operations are
    issued as HTTP POST of a query document to the /graphql endpoint. Access is
    authorized with an OAuth 2.0 client-credentials bearer token obtained from
    the /oauth/token endpoint. This document is a representative model; the
    production schema is provisioned per customer via Cherre's Developer Portal.
  termsOfService: https://cherre.com/terms-of-service/
  contact:
    name: Cherre
    url: https://www.cherre.com
  version: '1.0'
servers:
  - url: https://api.cherre.com
    description: Cherre API (representative)
paths:
  /oauth/token:
    post:
      operationId: createAccessToken
      tags:
        - Auth
      summary: Obtain an OAuth 2.0 client-credentials access token.
      description: >-
        Exchange client credentials for a short-lived bearer access token used
        to authorize GraphQL requests.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid client credentials.
  /graphql:
    post:
      operationId: postGraphQL
      tags:
        - GraphQL
      summary: Execute a GraphQL query against Cherre's connected real-estate data.
      description: >-
        Submit a GraphQL document (query plus optional variables and operation
        name). Cherre joins, filters, and aggregates across the connected
        datasets the caller is licensed for and returns a JSON response. Supply
        a valid bearer token in the Authorization header.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            examples:
              taxAssessor:
                summary: Query tax assessor records by ZIP
                value:
                  query: >-
                    query($zip: String!) {
                      tax_assessor(where: { situs_zip_code: { _eq: $zip } }, limit: 25) {
                        tax_assessor_id
                        assessed_value_total
                        market_value_total
                        year_built
                      }
                    }
                  variables:
                    zip: '10001'
              recorderMortgages:
                summary: Recorder deeds with mortgages
                value:
                  query: >-
                    query {
                      recorder(where: { fips_code: { _eq: "06037" } }, limit: 50) {
                        recorder_id
                        document_type
                        document_recorded_date
                        document_amount
                        mortgages { lender_name mortgage_amount }
                      }
                    }
              spatialParcels:
                summary: Parcels within a custom boundary (PostGIS)
                value:
                  query: >-
                    query($area: geometry!) {
                      parcel_boundary(where: { geom: { _st_contains: $area } }, limit: 500) {
                        cherre_parcel_id
                        tax_assessor { assessed_value_total land_use_code }
                      }
                    }
                  variables:
                    area: 'SRID=4326;POLYGON((...))'
      responses:
        '200':
          description: >-
            GraphQL response envelope. A 200 may still carry an `errors` array
            per the GraphQL specification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '401':
          description: Missing or invalid bearer token.
        '429':
          description: Too Many Requests - rate or quota limit exceeded.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    TokenRequest:
      type: object
      required:
        - grant_type
        - client_id
        - client_secret
      properties:
        grant_type:
          type: string
          enum:
            - client_credentials
        client_id:
          type: string
        client_secret:
          type: string
        audience:
          type: string
          description: Optional API audience identifier.
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Token lifetime in seconds.
    GraphQLRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: The GraphQL query or mutation document.
        variables:
          type: object
          additionalProperties: true
          description: JSON map of GraphQL variables.
        operationName:
          type: string
          description: Name of the operation to run when the document defines several.
    GraphQLResponse:
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/GraphQLError'
    GraphQLError:
      type: object
      properties:
        message:
          type: string
        path:
          type: array
          items:
            type: string
        extensions:
          type: object
          additionalProperties: true
security:
  - bearerAuth: []