placestack-com Event API

openapi: 3.2.0
info:
  title: Placestack Event 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: Event
  description: Permits and cases filed on monitored places, as events. Each is also sent to webhooks subscribed to its type.
paths:
  /v1/event:
    get:
      tags:
      - Event
      summary: List events
      description: 'Lists events, newest first: permits and cases filed on monitored places.


        Events are listed whether or not a webhook takes them. Retrieve the record at `data.href`, which

        costs a credit.'
      operationId: list_event
      security:
      - HTTPBearer: []
      parameters:
      - name: type
        in: query
        required: false
        schema:
          type: array
          items:
            enum:
            - permit.created
            - case.created
            type: string
          description: Only events of these types. Repeat for several.
          default: []
          title: Type
        description: Only events of these types. Repeat for several.
      - name: min_created
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Only events created at or after this time, in ISO 8601.
          title: Min Created
        description: Only events created at or after this time, in ISO 8601.
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'A cursor for pagination: the `next_cursor` from the previous page.'
          title: Cursor
        description: 'A cursor for pagination: the `next_cursor` from the previous page.'
      - name: size
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 200
            minimum: 1
          - type: 'null'
          description: Number of results per page, between 1 and 200. Defaults to 20.
          title: Size
        description: Number of results per page, between 1 and 200. Defaults to 20.
      responses:
        '200':
          description: A page of events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection_Event_'
        '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'
      x-credits: Free.
  /v1/event/{event_id}:
    get:
      tags:
      - Event
      summary: Retrieve an event
      description: Retrieves an event with its type and payload.
      operationId: get_event
      security:
      - HTTPBearer: []
      parameters:
      - name: event_id
        in: path
        required: true
        schema:
          type: string
          description: The event's id, `evt_...`.
          title: Event Id
        description: The event's id, `evt_...`.
      responses:
        '200':
          description: The event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '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:
    Event:
      properties:
        object:
          type: string
          const: event
          title: Object
          description: The object's type. Always `event`.
          default: event
        id:
          type: string
          pattern: ^evt_[0-7][0-9a-hjkmnp-tv-z]{25}$
          title: Id
          description: Unique identifier for the object.
          examples:
          - evt_01h455vb4pex5vsknk084sn02q
        type:
          type: string
          enum:
          - permit.created
          - case.created
          title: Type
          description: The event's type. One of `permit.created` or `case.created`.
        data:
          additionalProperties: true
          type: object
          title: Data
          description: 'The event''s payload, as webhooks receive it: the record''s `id` and `href`, and the `monitor` and `list_item` it matched.'
          examples:
          - href: /v1/permit/pmt_01h455vb4pex5vsknk084sn02q
            id: pmt_01h455vb4pex5vsknk084sn02q
            list_item: lsi_01h455vb4pex5vsknk084sn02q
            monitor: mon_01h455vb4pex5vsknk084sn02q
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Time at which the object was created.
        href:
          type: string
          title: Href
          description: The object's path in the API.
          examples:
          - /v1/event/evt_01h455vb4pex5vsknk084sn02q
      type: object
      required:
      - object
      - id
      - type
      - data
      - created_at
      - href
      title: Event
    Collection_Event_:
      properties:
        object:
          type: string
          const: list
          title: Object
          description: The object's type. Always `list`.
          default: list
        data:
          items:
            $ref: '#/components/schemas/Event'
          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[Event]
    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
    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`).
  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