placestack-com Monitor API

openapi: 3.2.0
info:
  title: Placestack Monitor API
  summary: The Placestack API.
  description: 'The Placestack API: US parcels, zoning and jurisdictions.


    ## Paths


    Paths are singular nouns, such as `/v1/parcel` and `/v1/parcel/{parcel_id}`.


    ## Pagination


    Lists return a page at a time. Send a page''s `next_cursor` as `cursor` to get the next one, and `size`

    to set the page size. Where an endpoint takes `sort`, `sort=field` sorts ascending and `sort=-field`

    descending.


    ## Errors


    Errors are RFC 9457 problem details (`application/problem+json`) with `type`, `title`, `status`,

    `detail`, `code` and `field`. Handle errors by `code`.


    ## Updates


    Updates accept an `If-Match` header with the `ETag` from your last read. A stale `ETag` is refused

    with `409 version_conflict`.


    ## Credits


    A lookup costs one credit: a parcel by address, number, point or id, or the zoning at a place. A search

    costs 1 credit per 20 results, and one zoning classification, permit or case costs one credit. The

    same lookup is free again for 24 hours. Requests that return nothing are free, as are jurisdictions,

    suggestions and account endpoints. `GET /v1/me` returns the credit balance.


    ## GeoJSON


    `/v1/parcel`, `/v1/zoning` and `/v1/jurisdiction` return GeoJSON with `format=geojson` or

    `Accept: application/geo+json`: a `FeatureCollection` for a list, a `Feature` for one object. The

    boundary is the geometry and the object is the properties. `include=geometry` adds the boundary to

    the JSON response instead.


    ## Webhooks


    Deliveries are signed with Standard Webhooks headers (`webhook-id`, `webhook-timestamp`,

    `webhook-signature`), so any Standard Webhooks library can verify them. An event can be delivered

    more than once: deduplicate on `webhook-id`. `GET /event_type` lists the event types.


    A `permit.created` or `case.created` event''s `data` holds the record''s `id` and `href`, and the

    `monitor` and `list_item` ids it matched. Retrieve the record at `href`, which costs a credit.'
  version: 0.0.0
servers:
- url: http://localhost:3030
  description: Development.
tags:
- name: Monitor
  description: Monitors on lists, which produce events about the places on a list.
paths:
  /v1/monitor:
    get:
      tags:
      - Monitor
      summary: List monitors
      description: 'Lists monitors, most recently created first.


        Not paginated: `has_more` is always `false`.'
      operationId: list_monitor
      responses:
        '200':
          description: A page of monitors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection_Monitor_'
        '401':
          description: '`credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: '`scope_missing`, `person_required`, `api_key_not_accepted` or `entitlement_missing`. The credential or plan does not allow this request. `detail` names the reason.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '422':
          description: '`parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '429':
          description: '`rate_limited`. Too many requests. Retry after the `Retry-After` interval. Nothing is charged.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      security:
      - HTTPBearer: []
      x-credits: Free.
    post:
      tags:
      - Monitor
      summary: Create a monitor
      description: 'Creates a monitor that watches a list.


        Permits and cases filed on the list''s places become `permit.created` and `case.created` events

        within a day of being published. Each is listed by `GET /v1/event` and sent to every webhook

        subscribed to its type. A place added to the list

        later is watched from when it is added. An item''s `filter` applies to the parcels each permit or

        case is about. A list that already has a monitor returns it with `200`.'
      operationId: post_monitor
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorBody'
        required: true
      responses:
        '201':
          description: The monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '401':
          description: '`credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: '`scope_missing`, `person_required`, `api_key_not_accepted` or `entitlement_missing`. The credential or plan does not allow this request. `detail` names the reason.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '422':
          description: '`parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '429':
          description: '`rate_limited`. Too many requests. Retry after the `Retry-After` interval. Nothing is charged.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '200':
          description: The list's existing monitor, unchanged.
      security:
      - HTTPBearer: []
      x-credits: Free.
  /v1/monitor/{monitor_id}:
    get:
      tags:
      - Monitor
      summary: Retrieve a monitor
      description: Retrieves a monitor with the list it watches and whether it is active.
      operationId: get_monitor
      security:
      - HTTPBearer: []
      parameters:
      - name: monitor_id
        in: path
        required: true
        schema:
          type: string
          description: The monitor's id, `mon_...`.
          title: Monitor Id
        description: The monitor's id, `mon_...`.
      responses:
        '200':
          description: The monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '401':
          description: '`credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: '`scope_missing`, `person_required`, `api_key_not_accepted` or `entitlement_missing`. The credential or plan does not allow this request. `detail` names the reason.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: '`no_such_resource`. No object has that id.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '422':
          description: '`parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '429':
          description: '`rate_limited`. Too many requests. Retry after the `Retry-After` interval. Nothing is charged.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      x-credits: Free.
    patch:
      tags:
      - Monitor
      summary: Update a monitor
      description: 'Pauses or resumes a monitor, or changes what it reports and who receives its daily email.


        A paused monitor produces no events, and nothing that happened while it was paused is sent when

        it resumes.'
      operationId: patch_monitor
      security:
      - HTTPBearer: []
      parameters:
      - name: monitor_id
        in: path
        required: true
        schema:
          type: string
          description: The monitor's id, `mon_...`.
          title: Monitor Id
        description: The monitor's id, `mon_...`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorPatch'
      responses:
        '200':
          description: The monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '401':
          description: '`credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: '`scope_missing`, `person_required`, `api_key_not_accepted` or `entitlement_missing`. The credential or plan does not allow this request. `detail` names the reason.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: '`no_such_resource`. No object has that id.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '422':
          description: '`parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '429':
          description: '`rate_limited`. Too many requests. Retry after the `Retry-After` interval. Nothing is charged.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      x-credits: Free.
    delete:
      tags:
      - Monitor
      summary: Delete a monitor
      description: 'Deletes a monitor. The list is unchanged, and events already queued for webhooks are still

        delivered. This cannot be undone.'
      operationId: delete_monitor
      security:
      - HTTPBearer: []
      parameters:
      - name: monitor_id
        in: path
        required: true
        schema:
          type: string
          description: The monitor's id, `mon_...`.
          title: Monitor Id
        description: The monitor's id, `mon_...`.
      responses:
        '204':
          description: No content.
        '401':
          description: '`credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '403':
          description: '`scope_missing`, `person_required`, `api_key_not_accepted` or `entitlement_missing`. The credential or plan does not allow this request. `detail` names the reason.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '404':
          description: '`no_such_resource`. No object has that id.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '422':
          description: '`parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
        '429':
          description: '`rate_limited`. Too many requests. Retry after the `Retry-After` interval. Nothing is charged.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
      x-credits: Free.
components:
  schemas:
    Monitor:
      properties:
        object:
          type: string
          const: monitor
          title: Object
          description: The object's type. Always `monitor`.
          default: monitor
        id:
          type: string
          pattern: ^mon_[0-7][0-9a-hjkmnp-tv-z]{25}$
          title: Id
          description: Unique identifier for the object.
          examples:
          - mon_01h455vb4pex5vsknk084sn02q
        list:
          type: string
          pattern: ^lst_[0-7][0-9a-hjkmnp-tv-z]{25}$
          title: List
          description: The id of the list watched.
          examples:
          - lst_01h455vb4pex5vsknk084sn02q
        active:
          type: boolean
          title: Active
          description: Whether the monitor produces events.
        event_type:
          items:
            type: string
            enum:
            - permit.created
            - case.created
          type: array
          title: Event Type
          description: The event types the monitor reports. Any of `permit.created` and `case.created`.
        email_recipient:
          items:
            type: string
          type: array
          title: Email Recipient
          description: Email addresses of the members who receive a daily summary of the monitor's events. Empty when no one does.
          examples:
          - - jordan@example.com
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Time at which the object was created.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Time at which the object was last updated.
        href:
          type: string
          title: Href
          description: The object's path in the API.
          examples:
          - /v1/monitor/mon_01h455vb4pex5vsknk084sn02q
      type: object
      required:
      - object
      - id
      - list
      - active
      - event_type
      - email_recipient
      - created_at
      - updated_at
      - href
      title: Monitor
    Collection_Monitor_:
      properties:
        object:
          type: string
          const: list
          title: Object
          description: The object's type. Always `list`.
          default: list
        data:
          items:
            $ref: '#/components/schemas/Monitor'
          type: array
          title: Data
          description: The results on this page.
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more results after this page.
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: The cursor for the next page. Send it as `cursor`. Null on the last page.
          examples:
          - eyJrIjoiMjAyNi0xMC0wMSIsInQiOjQyfQ
        suppressed:
          type: integer
          title: Suppressed
          description: The number of matching results withheld because the plan does not include them.
          default: 0
        total:
          anyOf:
          - $ref: '#/components/schemas/Total'
          - type: 'null'
          description: The number of matching results. Only on the first page, when `total=true` is sent. Null otherwise.
      type: object
      required:
      - object
      - data
      - has_more
      - next_cursor
      - suppressed
      - total
      title: Collection[Monitor]
    Total:
      properties:
        value:
          type: integer
          title: Value
          description: The number of matching results.
        relation:
          type: string
          enum:
          - eq
          - gte
          title: Relation
          description: One of `eq` (exact) or `gte` (at least `value`). Counts above 10,000 are `gte`.
      type: object
      required:
      - value
      - relation
      title: Total
      description: The number of matching results.
    ProblemFieldError:
      properties:
        field:
          anyOf:
          - type: string
          - type: 'null'
          title: Field
          description: The invalid parameter.
        detail:
          type: string
          title: Detail
          description: What is wrong with it.
      type: object
      required:
      - detail
      title: ProblemFieldError
    MonitorPatch:
      properties:
        active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Active
          description: Whether the monitor produces events.
        event_type:
          anyOf:
          - items:
              type: string
              enum:
              - permit.created
              - case.created
            type: array
            minItems: 1
          - type: 'null'
          title: Event Type
          description: The event types to report. Replaces the current set.
        email_recipient:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 50
          - type: 'null'
          title: Email Recipient
          description: Email addresses of members to send a daily summary to. Replaces the current set. `[]` sends none.
      type: object
      title: MonitorPatch
      description: A partial update. Omitted fields are unchanged.
    ProblemDetail:
      properties:
        type:
          type: string
          title: Type
          description: 'A link to the error code''s documentation: `https://placestack.com/docs/api/error#<code>`.'
        title:
          type: string
          title: Title
          description: A short, fixed name for the error code.
        status:
          type: integer
          title: Status
          description: The HTTP status.
        detail:
          type: string
          title: Detail
          description: A message about this occurrence, and how to resolve it.
        code:
          type: string
          title: Code
          description: The error code. Handle errors by this value.
        field:
          anyOf:
          - type: string
          - type: 'null'
          title: Field
          description: The parameter that caused the error. Null when none did.
        errors:
          anyOf:
          - items:
              $ref: '#/components/schemas/ProblemFieldError'
            type: array
          - type: 'null'
          title: Errors
          description: Every invalid parameter. Only with `parameter_invalid`.
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
          description: The request's id, also sent as the `request-id` response header. Include it when contacting support about a request.
      type: object
      required:
      - type
      - title
      - status
      - detail
      - code
      title: ProblemDetail
      description: An error, as RFC 9457 problem details (`application/problem+json`).
    MonitorBody:
      properties:
        list:
          type: string
          pattern: ^lst_[0-7][0-9a-hjkmnp-tv-z]{25}$
          title: List
          description: The id of the list to watch.
          examples:
          - lst_01h455vb4pex5vsknk084sn02q
        active:
          type: boolean
          title: Active
          description: Whether the monitor produces events. Defaults to `true`.
          default: true
        event_type:
          items:
            type: string
            enum:
            - permit.created
            - case.created
          type: array
          minItems: 1
          title: Event Type
          description: The event types to report. Defaults to all of them.
        email_recipient:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 50
          - type: 'null'
          title: Email Recipient
          description: Email addresses of members to send a daily summary to. Defaults to the caller's own address when a person creates the monitor, and to none for an API key.
      type: object
      required:
      - list
      title: MonitorBody
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-tagGroups:
- name: Parcels
  tags:
  - parcel
  - suggestion
- name: Zoning
  tags:
  - zoning
- name: Permits and cases
  tags:
  - permit
  - case
- name: Jurisdictions
  tags:
  - jurisdiction
- name: Lists
  tags:
  - list
- name: Monitoring
  tags:
  - monitor
  - event
- name: Webhooks
  tags:
  - webhook
- name: Account
  tags:
  - account
  - usage