placestack-com Account API

openapi: 3.2.0
info:
  title: Placestack Account 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: Account
  description: The credential making the request, its scopes and its credit balance.
paths:
  /v1/me:
    get:
      tags:
      - Account
      summary: Retrieve the current credential
      description: 'Returns the organization, plan, scopes and credit balance of the API key or token making the

        request.'
      operationId: whoami
      responses:
        '200':
          description: The credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '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.
components:
  schemas:
    Credential:
      properties:
        object:
          type: string
          const: credential
          title: Object
          description: The object's type. Always `credential`.
          default: credential
        organization:
          type: string
          title: Organization
          description: The organization's id.
          examples:
          - 0192f3a4-5b6c-7d8e-9f01-23456789abcd
        organization_name:
          type: string
          title: Organization Name
          description: The organization's name.
          examples:
          - Acme Realty
        plan:
          type: string
          title: Plan
          description: The organization's plan, such as `free`.
          examples:
          - build
        kind:
          type: string
          title: Kind
          description: Whether the credential belongs to a person or a machine. One of `user` or `machine`.
          examples:
          - machine
        subject:
          type: string
          title: Subject
          description: The id of the API key, user or OAuth client the credential belongs to.
          examples:
          - 0192f3a4-7d8e-7f90-b123-456789abcdef
        method:
          type: string
          title: Method
          description: How the request was authenticated. One of `session`, `api_key`, `oauth` or `mcp`.
          examples:
          - api_key
        name:
          type: string
          title: Name
          description: The API key's name or the user's email address, for display.
          examples:
          - Production
        scope:
          items:
            type: string
          type: array
          title: Scope
          description: The credential's scopes, such as `record:read` and `webhook:manage`. A console session also has its role's `*:manage` scopes.
          examples:
          - - record:read
        credit_balance:
          type: integer
          title: Credit Balance
          description: The current credit balance.
        user:
          anyOf:
          - type: string
          - type: 'null'
          title: User
          description: The user's id. Null for a machine credential.
          examples:
          - 0192f3a4-6c7d-7e8f-a012-3456789abcde
      type: object
      required:
      - object
      - organization
      - organization_name
      - plan
      - kind
      - subject
      - method
      - name
      - scope
      - credit_balance
      - user
      title: Credential
      description: A credential, its scopes and its organization's credit balance.
    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`).
    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
  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