openapi: 3.1.0
info:
  title: Displays
  version: 1.1.0
  description: |
    The Displays API is the self-service surface for out-of-home display faces: build and measure your own asset library, search the public inventory, and render display data as vector tiles in any TileJSON-compatible map (MapLibre GL, Mapbox GL JS, deck.gl).

    Three surfaces share one base path, `https://api2.mworks.com/v2/displays/*`:

    - **Assets** — a pay-as-you-go library of your display faces. Each asset moves from `draft` to `draft_measured` to `final_measured`, and a `final_measured` asset can be published into the public inventory. Measurement purchases and the measurement poll live alongside under the Viewcast API (`/v2/viewcast/measurements/*`).
    - **Display Search** — find public display faces, or your own assets, with a closed set of filters, and count the values left for a set of filters. 1 credit per request.
    - **Maptiles** — Mapbox Vector Tile delivery for the inventory face points and the modeled exposure layers. Mint a grant scoped to your web origins, hand the TileJSON URL to your map library, and it fetches tiles for you. Grant management is free; tile traffic is metered at **1 credit per 1,000 tiles served**.

    Authenticate with an org-scoped API key (`X-API-Key: mw_…`) or a signed-in session (`Authorization: Bearer <jwt>`). The prose guides — lifecycle recipes, purchase flow, search filters — are at [Displays](https://www.mworks.com/docs/displays/).
  contact:
    name: Motionworks AI
    url: https://mworks.com
    email: api@mworks.com
servers:
  - url: https://api2.mworks.com/v2
    description: Production
security:
  - apiKey: []
tags:
  - name: Tile Discovery
    description: |
      The public tile catalog: every layer Displays publishes, with its title, zoom range and field schema. No authentication, no charge.
  - name: Tile Grants
    description: |
      Mint, list, read and revoke tile-delivery grants. A grant belongs to your organization and names the web origins allowed to fetch tiles. Free.
  - name: Tile TileJSON
    description: |
      The TileJSON manifest for a grant — the URL you hand to your map library. It carries a short-lived tile token, so it needs no separate auth header.
  - name: Tile Data
    description: |
      The tile bytes themselves (Mapbox Vector Tile, binary). Your map library requests these with the token from the TileJSON manifest; you will not normally call this endpoint yourself.
  - name: Assets
    description: |
      Your organization's library of display faces. Create a draft asset, refine it, read it back, list and summarize the library, and archive what you no longer need. Assets progress from `draft` to `draft_measured` to `final_measured`. Measurement purchases, the measurement poll, and profile retrieval are under the Viewcast API (`/v2/viewcast/*`).
  - name: Display Search
    description: |
      Search public out-of-home display faces — or, with `publication: private`, your own assets — using a closed set of filters and, on the public inventory, a ranked free-text `q`. Authenticated callers only. 1 credit per request. Cursor pagination: 50 results per page by default, 200 at most, up to 10,000 results per query (no limit with `q`).
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        A signed-in user session (`Authorization: Bearer <jwt>`), as used by the Motionworks console and account flows to manage tile grants for your organization.
    tileTokenAuth:
      type: apiKey
      in: query
      name: token
      description: |
        Opaque per-grant tile-token (24-hour TTL) minted by `GET /v2/displays/tiles/grants/{id}/tilejson`. Accepted ONLY as the `?token=` query parameter — header form is rejected. Treat as a short-lived bearer credential.
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            status:
              type: integer
            request_id:
              type: string
            docs_url:
              type: string
          description: 'The error: a stable `code`, a human-readable `message`, and optional `context` with the specifics.'
    TileMeta:
      type: object
      x-motionworks-status: production
      properties:
        request_id:
          type: string
          description: Unique id for this request.
        credits_used:
          type: integer
          enum:
            - 0
          description: Always 0 — grant management is free; tile traffic is metered separately at 1 credit per 1,000 tiles.
        product:
          type: string
          enum:
            - displays
            - viewcast
          description: '`displays` for the `faces` layer; `viewcast` for the modeled exposure layers.'
    TilesetCatalogLayer:
      type: object
      x-motionworks-status: production
      description: |
        TileJSON 3.0.0 `vector_layers[]` entry — one per MVT layer emitted by the upstream tileset.
      required:
        - id
        - fields
      properties:
        id:
          type: string
          description: |
            Layer id inside the tile bytes (the MVT `source-layer`). Often `default` for single-layer tilesets — not the URL slug.
        description:
          type: string
          description: What the layer contains.
        minzoom:
          type: integer
          minimum: 0
          description: Lowest zoom level the layer serves.
        maxzoom:
          type: integer
          minimum: 0
          description: Highest zoom level the layer serves.
        fields:
          type: object
          description: Map of MVT feature property → TileJSON field type (`String` | `Number` | `Boolean`).
          additionalProperties:
            type: string
            enum:
              - String
              - Number
              - Boolean
    TilesetCatalogEntry:
      type: object
      x-motionworks-status: production
      required:
        - slug
        - title
        - minzoom
        - maxzoom
        - bounds
        - layers
      properties:
        slug:
          type: string
          description: Customer-facing layer slug. Matches the `{layer}` URL path segment used in `GET /v2/displays/tiles/{layer}/{z}/{x}/{y}.mvt` and the values accepted in `TileGrantCreateRequest.tilesets`.
        title:
          type: string
          description: Human-readable display title for this tileset.
        minzoom:
          type: integer
          minimum: 0
          description: Lowest zoom level the tileset serves.
        maxzoom:
          type: integer
          minimum: 0
          description: Highest zoom level the tileset serves.
        bounds:
          type: array
          description: TileJSON `bounds` — `[west, south, east, north]`, WGS84.
          items:
            type: number
          minItems: 4
          maxItems: 4
        layers:
          type: array
          items:
            $ref: '#/components/schemas/TilesetCatalogLayer'
          description: The MVT layers inside the tiles, with their field schemas.
    TilesetCatalogResponse:
      type: object
      x-motionworks-status: production
      required:
        - tilesets
      properties:
        tilesets:
          type: array
          items:
            $ref: '#/components/schemas/TilesetCatalogEntry'
          description: Every tileset Displays publishes.
    TileGrantCreateRequest:
      type: object
      x-motionworks-status: production
      required:
        - name
        - tilesets
        - allowed_origins
        - expires_at
      properties:
        name:
          type: string
          maxLength: 120
          description: Human-readable label for this grant (shown in the developer dashboard).
        tilesets:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - faces
              - viewsheds
              - paths_vehicle
              - paths_pedestrian
              - gates_vehicle
              - gates_pedestrian
          description: |
            Tileset slugs to include. `faces` (OOH inventory face points, z 0–14) and the modeled exposure layers (z 11–17): `viewsheds`, `paths_vehicle`, `paths_pedestrian`, `gates_vehicle`, `gates_pedestrian`. Any other slug returns 403 `TILE_LAYER_NOT_LICENSED`.
        allowed_origins:
          type: array
          items:
            type: string
          description: |
            Browser `Origin` allowlist for the TileJSON and tile requests made with this grant. Requests must carry an `Origin` header that matches one entry. To test from curl or a native app, include the literal string `null` in `allowed_origins`. A request without an `Origin` header is otherwise refused (403 `ORIGIN_NOT_ALLOWED`, `error.context.reason: origin_required`). Wildcards are not supported — list each origin literally.
        expires_at:
          type: string
          format: date-time
          description: |
            ISO 8601 timestamp at which this grant expires. The tile-token JWT minted by `/tilejson` independently expires 24h after each mint — re-fetch TileJSON before then.
    TileGrant:
      type: object
      x-motionworks-status: production
      description: |
        Server representation of a Displays tile-delivery grant. The `grant_id` is a Crockford-base32 ULID and is itself a bearer credential — anyone who knows the ULID can fetch the TileJSON capability URL from an allowed origin.
      properties:
        grant_id:
          type: string
          description: Opaque ULID. Treat as a secret.
        org_id:
          type: string
          format: uuid
          description: The organization that owns the grant.
        product:
          type: string
          enum:
            - displays
            - viewcast
          description: |
            `displays` for grants scoped to the `faces` layer; `viewcast` for grants scoped to the modeled exposure layers.
        name:
          type: string
          description: The label you gave the grant.
        tilesets:
          type: array
          items:
            type: string
            enum:
              - faces
              - viewsheds
              - paths_vehicle
              - paths_pedestrian
              - gates_vehicle
              - gates_pedestrian
          description: Tileset slugs the grant covers.
        allowed_origins:
          type: array
          items:
            type: string
          description: Browser origins allowed to fetch TileJSON and tiles with this grant.
        expires_at:
          type: string
          format: date-time
          description: When the grant expires (ISO 8601).
        revoked_at:
          type: string
          format: date-time
          nullable: true
          description: When the grant was revoked, or null while it is active.
        created_at:
          type: string
          format: date-time
          description: When the grant was created (ISO 8601).
        created_by:
          type: string
          format: uuid
          nullable: true
          description: |
            The user who created the grant. For a grant minted with an API key, this is the user who created that key.
        usage_30d:
          type: integer
          description: 30-day tile fetch count. Reported as 0 today; usage aggregation is coming.
    TileGrantCreateResponse:
      type: object
      x-motionworks-status: production
      properties:
        grant_id:
          type: string
          description: Opaque ULID. Treat as a secret.
        tile_json_url:
          type: string
          format: uri
          description: |
            Capability URL — drop this into MapLibre as the `url` for a vector source. The opaque `grant_id` segment IS the credential, so treat the URL like an AWS S3 presigned URL.
        tilesets:
          type: array
          items:
            type: string
          description: Tileset slugs the grant covers.
        allowed_origins:
          type: array
          items:
            type: string
          description: Browser origins allowed to fetch TileJSON and tiles with this grant.
        expires_at:
          type: string
          format: date-time
          description: When the grant expires (ISO 8601).
        created_at:
          type: string
          format: date-time
          description: When the grant was created (ISO 8601).
    TileJsonManifest:
      type: object
      x-motionworks-status: production
      description: |
        TileJSON 3.0.0 manifest with a freshly-minted 24-hour tile-token embedded in `tiles[]`. Standard TileJSON consumers (MapLibre, Mapbox GL JS, deck.gl `MVTLayer`) handle the rest transparently.
      properties:
        tilejson:
          type: string
          example: 3.0.0
          description: TileJSON specification version (`3.0.0`).
        name:
          type: string
          description: Name of the tileset.
        tiles:
          type: array
          items:
            type: string
            format: uri
          description: Tile URL templates with the tile token already embedded. Your map library substitutes `{z}/{x}/{y}`.
        minzoom:
          type: integer
          description: Lowest zoom level served.
        maxzoom:
          type: integer
          description: Highest zoom level served.
        bounds:
          type: array
          items:
            type: number
          minItems: 4
          maxItems: 4
          description: Geographic extent `[west, south, east, north]` in WGS84.
        attribution:
          type: string
          description: Attribution text to show on the map.
        vector_layers:
          type: array
          items:
            type: object
          description: The MVT layers in the tiles and their field schemas.
        x-mw:
          type: object
          description: Motionworks-specific tile-token refresh metadata.
          properties:
            grant_id:
              type: string
            product:
              type: string
              enum:
                - displays
                - viewcast
              description: '`displays` for the `faces` layer; `viewcast` for the five modeled-exposure layers.'
            tilesets:
              type: array
              items:
                type: string
            token_expires_at:
              type: string
              format: date-time
            refresh_after:
              type: integer
              description: Seconds-since-mint after which clients should re-fetch this TileJSON. Set to 82,800 (23h, one hour before the tile-token JWT expires).
    Pagination:
      type: object
      properties:
        cursor:
          type: string
          nullable: true
          description: Opaque cursor for the next page. Pass it back as `cursor` to continue; absent on the last page.
        has_more:
          type: boolean
          description: Whether another page follows.
        total:
          type: integer
          description: Total matching results, when the endpoint reports one.
    ViewcastAssetAnchor:
      type: object
      required:
        - lat
        - lon
      properties:
        lat:
          type: number
          minimum: -90
          maximum: 90
          description: Latitude of the face (WGS84 degrees).
        lon:
          type: number
          minimum: -180
          maximum: 180
          description: Longitude of the face (WGS84 degrees).
    ViewcastPartySpot:
      type: object
      additionalProperties: false
      description: |
        A spot as defined by one related party. `spot_id` is that party's own identifier and may be null. Per party, `spots[]` holds at most 24 entries, non-null `spot_id` values are unique, and `share_of_voice` values sum to at most 1.
      properties:
        spot_id:
          type: string
          maxLength: 256
          nullable: true
          description: Party-assigned spot identifier; null when no id is assigned.
        spot_length:
          type: integer
          minimum: 0
          maximum: 3600
          nullable: true
          description: Spot duration in seconds.
        share_of_voice:
          type: number
          minimum: 0
          maximum: 1
          nullable: true
          description: Share of voice (0-1). Null/omitted treated as 0 in the per-party sum.
        status_type:
          type: string
          maxLength: 64
          nullable: true
          description: The party's own status vocabulary; free-form.
        full_motion:
          type: boolean
          nullable: true
          description: Per-spot capability override.
        partial_motion:
          type: boolean
          nullable: true
          description: Per-spot capability override.
        interactive:
          type: boolean
          nullable: true
          description: Per-spot capability override.
        audio:
          type: boolean
          nullable: true
          description: Per-spot capability override.
    ViewcastRelatedParty:
      type: object
      additionalProperties: false
      description: |
        A party related to the display — owner, manager, reseller and so on — as returned on read. `source_id` and `observed_at` are stamped by Motionworks and cannot be supplied in requests (use the request form, which omits them). Per party: `spots[]` holds at most 24 entries, non-null `spot_id` values are unique, the `share_of_voice` values across `spots[]` sum to at most 1, and `other_ids` holds at most 8 keys. The roles `registry` and `measurement_provider` are reserved for Motionworks and are rejected in requests. Any party, including the owner, may carry its own `media_name`. An owner whose `party_display_id` is already registered to another of your assets returns 409.
      required:
        - party_name
        - role
        - source_id
        - observed_at
      properties:
        party_id:
          type: string
          description: Reserved for the Motionworks party registry; optional today.
        party_name:
          type: string
          minLength: 1
          maxLength: 256
          description: The organization (e.g. "Great Outdoor"). Required.
        division:
          type: string
          maxLength: 256
          nullable: true
          description: Sub-entity (e.g. "GREAT OUTDOOR - LOS ANGELES").
        role:
          type: string
          enum:
            - owner
            - operator
            - manager
            - reseller
            - agency
            - platform
            - venue
            - registry
            - measurement_provider
          description: |
            The party's role on this display. `registry` and `measurement_provider` are reserved for Motionworks and rejected in requests.
        party_display_id:
          type: string
          maxLength: 256
          description: The party's own identifier for this display. On owner entries it drives the duplicate guard.
        other_ids:
          type: object
          description: |
            Additional party identifiers (keys: frame, face, layout, ...). Capped at 8 keys; each key max 64 chars, each value max 256 chars.
          additionalProperties:
            type: string
        media_name:
          type: string
          maxLength: 256
          nullable: true
          description: Party-authored media label. Allowed on any role, including the owner.
        status_type:
          type: string
          maxLength: 64
          nullable: true
          description: The party's own status vocabulary; free-form.
        spots:
          type: array
          maxItems: 24
          description: Party-scoped spot definitions (max 24).
          items:
            $ref: '#/components/schemas/ViewcastPartySpot'
        source_id:
          type: string
          description: |
            Stamped by Motionworks: the source that asserted this entry. Present on read; not accepted in requests.
        observed_at:
          type: string
          description: 'Stamped by Motionworks: when this entry was observed. Present on read; not accepted in requests.'
    ViewcastRelatedPartyInput:
      type: object
      additionalProperties: false
      description: |
        A related party as supplied in create and refine requests: the same shape as the read form without `source_id` and `observed_at`, which Motionworks stamps (supplying either returns 400). Per party: `spots[]` holds at most 24 entries, non-null `spot_id` values are unique, the `share_of_voice` values across `spots[]` sum to at most 1, and `other_ids` holds at most 8 keys. The roles `registry` and `measurement_provider` are reserved for Motionworks and are rejected in requests. Any party, including the owner, may carry its own `media_name`. An owner whose `party_display_id` is already registered to another of your assets returns 409.
      required:
        - party_name
        - role
      properties:
        party_id:
          type: string
          description: Reserved for the Motionworks party registry; optional today.
        party_name:
          type: string
          minLength: 1
          maxLength: 256
          description: The organization (e.g. "Great Outdoor"). Required.
        division:
          type: string
          maxLength: 256
          nullable: true
          description: Sub-entity (e.g. "GREAT OUTDOOR - LOS ANGELES").
        role:
          type: string
          enum:
            - owner
            - operator
            - manager
            - reseller
            - agency
            - platform
            - venue
            - registry
            - measurement_provider
          description: |
            The party's role on this display. `registry` and `measurement_provider` are reserved for Motionworks and rejected in requests.
        party_display_id:
          type: string
          maxLength: 256
          description: The party's own identifier for this display. On owner entries it drives the duplicate guard.
        other_ids:
          type: object
          description: |
            Additional party identifiers (keys: frame, face, layout, ...). Capped at 8 keys; each key max 64 chars, each value max 256 chars.
          additionalProperties:
            type: string
        media_name:
          type: string
          maxLength: 256
          nullable: true
          description: Party-authored media label. Allowed on any role, including the owner.
        status_type:
          type: string
          maxLength: 64
          nullable: true
          description: The party's own status vocabulary; free-form.
        spots:
          type: array
          maxItems: 24
          description: Party-scoped spot definitions (max 24).
          items:
            $ref: '#/components/schemas/ViewcastPartySpot'
    ViewcastAsset:
      type: object
      description: |
        A display asset in your organization's library. `asset_id` is assigned at creation and never changes; `display_id` is assigned by Motionworks when the asset reaches `final_measured`. Lifecycle: `draft` → `draft_measured` → `final_measured`. `publication` (`private` or `public`) can be changed on `final_measured` assets only, and only public `final_measured` assets appear in the tile layers. A 12-month measurement subscription starts with the 300-credit purchase, whether by direct-add or by the final measurement, clocked from the purchase date.
      required:
        - asset_id
        - org_id
        - state
        - classification
        - anchor
        - related_parties
        - row_version
        - created_at
        - updated_at
      properties:
        asset_id:
          type: string
          description: |
            Identifier assigned when the asset was created. Stable for the life of the asset; every asset endpoint keys off it.
        org_id:
          type: string
          description: The organization that owns the asset.
        state:
          type: string
          enum:
            - draft
            - draft_measured
            - final_measured
          description: |
            Lifecycle state: `draft` (created, not yet measured), `draft_measured` (draft measurement complete) or `final_measured` (final measurement complete; publishable).
        classification:
          type: string
          enum:
            - Roadside
            - Place-Based
          description: '`Roadside` or `Place-Based`. Set at creation and immutable.'
        anchor:
          $ref: '#/components/schemas/ViewcastAssetAnchor'
        related_parties:
          type: array
          maxItems: 16
          description: The parties related to this display (up to 16), each stamped with `source_id` and `observed_at`.
          items:
            $ref: '#/components/schemas/ViewcastRelatedParty'
        display_id:
          type: string
          description: Present only once the asset reaches final_measured.
        display:
          $ref: '#/components/schemas/ViewcastDisplay'
        user_reference:
          type: string
          nullable: true
          description: Your own free-text reference, echoed back unchanged.
        enrichment:
          type: object
          nullable: true
          description: |
            The resolved measurement detail: `attributes` (the resolved display descriptor), `audience` (the per-face and per-spot measurement block), and the widened measurement context: `viewshed_id`, `viewshed_geography` and `location` (GeoJSON), the `market` record, and the measurement period (`period_start` / `period_end` / `period_days`). Present on the detail response only, not in lists.
        enriched_at:
          type: string
          format: date-time
          nullable: true
          description: When the measurement detail was produced.
        publication:
          type: string
          enum:
            - private
            - public
          default: private
          description: |
            Publication flag. Only `final_measured` assets can be `public`; setting it on a `draft` or `draft_measured` asset returns 400. Only public `final_measured` assets appear in the tile layers, which show the public inventory. Publication can be revoked: new direct-adds stop, and existing subscribers keep access through their own subscription.
        subscription_started_at:
          type: string
          format: date-time
          nullable: true
          description: |
            Start of the 12-month measurement subscription window, set on either 300-cr purchase path (direct-add or final transition). Null before any purchase.
        subscription_expires_at:
          type: string
          format: date-time
          nullable: true
          description: |
            Expiry of the 12-month measurement subscription window. At expiry GET /v2/viewcast/profiles/{display_id} fails closed until repurchase. Null before any purchase.
        row_version:
          type: integer
          description: |
            Optimistic-concurrency version, incremented on every change. Send it back as `expected_row_version` when you PATCH; a stale value returns 409.
        created_at:
          type: string
          format: date-time
          description: When the asset was created (ISO 8601).
        updated_at:
          type: string
          format: date-time
          description: When the asset last changed (ISO 8601).
    ViewcastAssetCreateRequest:
      type: object
      additionalProperties: false
      required:
        - classification
        - anchor
      properties:
        classification:
          type: string
          enum:
            - Roadside
            - Place-Based
          description: '`Roadside` or `Place-Based`. Immutable after creation.'
        anchor:
          $ref: '#/components/schemas/ViewcastAssetAnchor'
        related_parties:
          type: array
          maxItems: 16
          description: |
            The parties related to this display (up to 16). Do not include `source_id` or `observed_at` — Motionworks stamps them. Per party: `spots[]` holds at most 24 entries, non-null `spot_id` values are unique, the `share_of_voice` values across `spots[]` sum to at most 1, and `other_ids` holds at most 8 keys. The roles `registry` and `measurement_provider` are reserved for Motionworks and are rejected in requests. Any party, including the owner, may carry its own `media_name`.
          items:
            $ref: '#/components/schemas/ViewcastRelatedPartyInput'
        display:
          $ref: '#/components/schemas/ViewcastDisplay'
        user_reference:
          type: string
          nullable: true
          description: Your own free-text reference, echoed back unchanged.
    ViewcastAssetRefineRequest:
      type: object
      additionalProperties: false
      description: |
        Partial refine, a party edit, or a publication toggle. classification is immutable and intentionally absent; the anchor may move at most 100 m (400 on violation). publication carries the final_measured-only publication toggle and MUST NOT be combined with any refine field in one request (400). On a `final_measured` asset the only accepted body is `related_parties` alone (the administrative party-edit lane: accepted, never re-queues measurement, never touches the catalog-sourced definition fields); every other non-publication body on `final_measured` returns 409.
      properties:
        anchor:
          $ref: '#/components/schemas/ViewcastAssetAnchor'
        related_parties:
          type: array
          maxItems: 16
          description: |
            Replaces the whole party roster (up to 16); partial edits are not supported. Same rules as on create: no `source_id` or `observed_at`, reserved roles rejected, any party may carry a `media_name`. On a `final_measured` asset this is the ONE accepted body (the administrative party-edit lane): accepted alone, never re-queues measurement, never touches the catalog-sourced definition fields.
          items:
            $ref: '#/components/schemas/ViewcastRelatedPartyInput'
        display:
          $ref: '#/components/schemas/ViewcastDisplayRefine'
        user_reference:
          type: string
          nullable: true
          description: Your own free-text reference; `null` clears it.
        auto_progress_final:
          type: boolean
          description: |
            Deprecated and inert. The platform never purchases a final measurement automatically: a completed draft measurement leaves the asset at `draft_measured` and the final is only ever purchased explicitly. The final purchase endpoint itself is stubbed (501 NOT_YET_AVAILABLE) until the measurement provider's viewshed function is wired. This flag is retained for backward compatibility; it is read by nothing and has no effect in either position. Boolean; any other value returns 400. Setting it on a `final_measured` asset counts as a refine and returns 409.
        publication:
          type: string
          enum:
            - private
            - public
          description: |
            final_measured-only toggle. Carrying it together with any refine field in one request is a 400.
    ViewcastDisplay:
      type: object
      additionalProperties: false
      description: |
        The display descriptor. Sparse and strict: every field is optional and unknown keys are rejected. Field names follow the Motionworks display schema with explicit units (`height_in`, `width_in`). On create, sending an explicit `null` for a field is the same as omitting it, and the stored descriptor never contains null values. Responses never carry null display values.
      properties:
        height_in:
          type: number
          description: Face height in inches.
        width_in:
          type: number
          description: Face width in inches.
        media_type_name:
          type: string
          enum:
            - Bulletin
            - Display
            - Junior Poster
            - Murals
            - Panel
            - Poster
          description: 'Media type of the face: `Bulletin`, `Poster`, `Junior Poster`, `Panel`, `Display` or `Murals`. The server enforces this list; off-list values return 400 `display.media_type_name is not an allowed value.`'
        construction_type_name:
          type: string
          enum:
            - Ceiling
            - Column
            - Elevator
            - Exterior Vehicle
            - Exterior Wall
            - Floor
            - Freestanding
            - Furniture
            - Furniture - Top
            - Interior Vehicle
            - Interior Wall
            - Rooftop
            - Stairs
            - Tablet
          description: |
            How the display is mounted or built (for example `Freestanding`, `Exterior Wall`, `Rooftop`, `Interior Vehicle`). The server enforces this list; off-list values return 400 `display.construction_type_name is not an allowed value.`
        illumination_type_name:
          type: string
          enum:
            - Artificial Ambient
            - Backlit
            - Frontlit
            - Sunlit Ambient
          description: 'How the face is lit: `Frontlit`, `Backlit`, `Sunlit Ambient` or `Artificial Ambient`. The server enforces this list; off-list values return 400 `display.illumination_type_name is not an allowed value.`'
        digital:
          type: boolean
          description: Whether the face is digital (`true`) or static (`false`).
        orientation:
          type: number
          minimum: 0
          maximum: 360
          description: Compass direction the face points toward, in degrees clockwise from north (0 = north, 180 = south).
        elevation:
          type: number
          description: Height of the face above ground, when known.
        placement_type_name:
          type: string
          description: Placement type of the face, using the Motionworks display taxonomy.
        urbanicity:
          type: string
          description: The setting around the face (for example `Urban`, `Suburban`, `Rural`).
        place_id:
          type: string
          description: Your place reference; meaningful for Place-Based assets.
        rotating:
          type: boolean
          description: Whether the face rotates.
        full_motion:
          type: boolean
          description: Whether the face plays full-motion video.
        partial_motion:
          type: boolean
          description: Whether the face plays partial-motion video.
        interactive:
          type: boolean
          description: Whether the face supports interactive content.
        audio:
          type: boolean
          description: Whether the face plays audio.
    ViewcastDisplayRefine:
      type: object
      additionalProperties: false
      properties:
        height_in:
          type: number
          nullable: true
          description: Face height in inches.
        width_in:
          type: number
          nullable: true
          description: Face width in inches.
        media_type_name:
          type: string
          nullable: true
          enum:
            - Bulletin
            - Display
            - Junior Poster
            - Murals
            - Panel
            - Poster
          description: 'Media type of the face: `Bulletin`, `Poster`, `Junior Poster`, `Panel`, `Display` or `Murals`. The server enforces this list; off-list values return 400 `display.media_type_name is not an allowed value.`'
        construction_type_name:
          type: string
          nullable: true
          enum:
            - Ceiling
            - Column
            - Elevator
            - Exterior Vehicle
            - Exterior Wall
            - Floor
            - Freestanding
            - Furniture
            - Furniture - Top
            - Interior Vehicle
            - Interior Wall
            - Rooftop
            - Stairs
            - Tablet
          description: |
            How the display is mounted or built (for example `Freestanding`, `Exterior Wall`, `Rooftop`, `Interior Vehicle`). The server enforces this list; off-list values return 400 `display.construction_type_name is not an allowed value.`
        illumination_type_name:
          type: string
          nullable: true
          enum:
            - Artificial Ambient
            - Backlit
            - Frontlit
            - Sunlit Ambient
          description: 'How the face is lit: `Frontlit`, `Backlit`, `Sunlit Ambient` or `Artificial Ambient`. The server enforces this list; off-list values return 400 `display.illumination_type_name is not an allowed value.`'
        digital:
          type: boolean
          nullable: true
          description: Whether the face is digital (`true`) or static (`false`).
        orientation:
          type: number
          nullable: true
          minimum: 0
          maximum: 360
          description: Compass direction the face points toward, in degrees clockwise from north (0 = north, 180 = south).
        elevation:
          type: number
          nullable: true
          description: Height of the face above ground, when known.
        placement_type_name:
          type: string
          nullable: true
          description: Placement type of the face, using the Motionworks display taxonomy.
        urbanicity:
          type: string
          nullable: true
          description: The setting around the face (for example `Urban`, `Suburban`, `Rural`).
        place_id:
          type: string
          nullable: true
          description: Your place reference; meaningful for Place-Based assets.
        rotating:
          type: boolean
          nullable: true
          description: Whether the face rotates.
        full_motion:
          type: boolean
          nullable: true
          description: Whether the face plays full-motion video.
        partial_motion:
          type: boolean
          nullable: true
          description: Whether the face plays partial-motion video.
        interactive:
          type: boolean
          nullable: true
          description: Whether the face supports interactive content.
        audio:
          type: boolean
          nullable: true
          description: Whether the face plays audio.
      description: |
        The display descriptor as accepted by `PATCH /v2/displays/assets/{asset_id}`: the same strict key set as the create form, but every field also accepts an explicit `null`. The object merges per key (JSON Merge Patch, RFC 7386): a key with a value overwrites the stored value, a key with `null` deletes it, and an absent key is left alone. `display: {}` is a valid no-op. The merged result is validated against the strict schema, so unknown keys are still a 400. On create, an explicit `null` is the same as omitting the key.
    ViewcastAssetSummary:
      type: object
      required:
        - by_state
        - by_classification
        - total
      properties:
        by_state:
          type: object
          required:
            - draft
            - draft_measured
            - final_measured
          properties:
            draft:
              type: integer
              minimum: 0
            draft_measured:
              type: integer
              minimum: 0
            final_measured:
              type: integer
              minimum: 0
          description: Asset counts keyed by lifecycle state.
        by_classification:
          type: object
          required:
            - Roadside
            - Place-Based
          properties:
            Roadside:
              type: integer
              minimum: 0
            Place-Based:
              type: integer
              minimum: 0
          description: Asset counts keyed by classification.
        total:
          type: integer
          minimum: 0
          description: Total assets in your library (archived assets excluded).
    Provenance:
      type: object
      if:
        required:
          - is_focused
          - measurement_method
      then:
        oneOf:
          - properties:
              is_focused:
                const: true
              measurement_method:
                const: direct
          - properties:
              is_focused:
                const: false
              measurement_method:
                const: estimated
      properties:
        source:
          type: string
          description: The Motionworks dataset or model the result came from.
        source_doc:
          type: string
          format: uri
          description: Link to the methodology or dataset documentation for this result.
        methodology_version:
          type: string
          description: Version of the methodology that produced the result.
        data_vintage:
          type: string
          format: date
          description: The date the underlying data represents.
        data_freshness:
          type: string
          description: Refresh cadence of the underlying data.
        data_latency_days:
          type: integer
          description: Lag, in days, between the data vintage and its availability.
        data_maturity:
          type: string
          enum:
            - production
            - research-preview
            - synthetic-only
            - roadmap
          description: |
            Maturity of the data behind the result: `production` (supported and stable), `research-preview` (available, subject to change), `synthetic-only` or `roadmap` (not yet backed by production data).
        is_focused:
          type: boolean
          description: |
            Whether the place is directly measured (`true`) rather than estimated from its peer group (`false`). When present alongside `measurement_method`, the two agree.
        measurement_method:
          type: string
          enum:
            - direct
            - estimated
          description: |
            `direct` when the place is measured directly; `estimated` when its statistics come from peer-group inference. When present alongside `is_focused`, the two agree (`true` ↔ `direct`).
    Meta:
      type: object
      properties:
        request_id:
          type: string
          description: Unique id for this request. Quote it when contacting support.
        credits_used:
          type: integer
          description: Credits charged for this call.
        credits_remaining:
          type: integer
          description: Credits remaining on your account after this call.
        product:
          type: string
          description: The Motionworks product that served the call.
        version:
          type: string
          description: API version that served the call.
        provenance:
          $ref: '#/components/schemas/Provenance'
    DisplaySearchRequest:
      type: object
      description: |
        Filters for `POST /v2/displays/search`, named for the canonical display fields. All filters are optional, but a JSON body is required: `{}` returns the first page of the merged walk, and a request with no body returns 400. Unknown keys return 400, including the retired filters (`media_type`, `classification_type`, `construction`, `illumination`, `place_type`, `place_name`, `party`, `party_scoped_identifiers`, `geography.resolved_ids`) and `query`, `dsl`, `catalog_status`. Free text goes in `q` (public inventory only).

        Every filter key is named for a canonical display field (for example `media_type_name` mirrors `DisplaySearchResult.media_type_name`), so values read out of a response feed straight back into a filter. The exception set is `state`, `direct`, `publication`, `geography.bbox`, `geography.dma_id`, `limit`, `cursor`, plus `status_type`, which appears on results but has no matching filter. `state` is the sharp exception: the `state` field on a result is geographic (for example `IL`), while the `state` filter is the asset lifecycle (`draft`, `draft_measured`, `final_measured`); the two are unrelated homonyms, and a row's lifecycle state never appears on results (it is carried by `status_type`).

        **Corpus routing (`publication`).** Omitted = fan-out over both corpora merged: your organization's own assets first, to exhaustion, then the public inventory continues the walk (one request, one credit; results are deduplicated across corpora, with your own assets preferred). `private` scopes to your organization's own assets. `public` scopes to the public inventory.

        **Per-leg behavior.** Most filters are honored on both legs. Two are per-leg: `state` is honored on the private leg and honored-as-constant on the public leg (public inventory rows are all `final_measured`; a request asking only for non-final states on the public leg is truthfully an empty result, not an error). `direct` is honored on the private leg and rejected with a 400 on the public leg (direct-add provenance is not exposed on the public corpus). A small set of private-only party keys (`related_parties[].media_name`, `related_parties[].status_type`, unknown `related_parties[].other_ids` keys) and the `urbanicity`/`elevation` filters are likewise rejected with a 400 on the public leg, which does not carry those fields.
      additionalProperties: false
      properties:
        q:
          type: string
          minLength: 1
          maxLength: 200
          example: coffee shop
          description: |
            Free-text search over the public inventory, ranked. Leading and trailing spaces are trimmed, and the 1–200 character limits apply to the trimmed text. Case doesn't matter. Results come in this order:
            1. an exact match on a Geopath id (frame, face or spot id, operator frame id, place id) or on a whole name (venue, owner, division, venue type, media name). A `display_id` is not searchable;
            2. names that start with your words in order (`peach` finds "Peachtree Hill");
            3. results containing every word;
            4. results where every word starts a word;
            5. results containing every word within a typo (`krogr` finds Kroger);
            6. results containing some of the words, then some words within a typo.

            Within each step, closer matches come first. Matched fields: venue name, owner and division, venue type, DMA, CBSA and county names, primary artery. Filters narrow the matched set and never change the order.

            With `q`, results are ordered by relevance, then by frame id, and there is no 10,000-result limit on paging. Public inventory only: send `publication: public` with it; with your own assets in scope (`publication: private` or omitted) it returns a 400.
        media_type_name:
          oneOf:
            - type: string
              enum:
                - Display
                - Panel
                - Junior Poster
                - Poster
                - Bulletin
                - Mural
            - type: array
              minItems: 1
              items:
                type: string
                enum:
                  - Display
                  - Panel
                  - Junior Poster
                  - Poster
                  - Bulletin
                  - Mural
          description: 'Canon media type, one value or several (surface canon: `Display`, `Panel`, `Junior Poster`, `Poster`, `Bulletin`, `Mural`).'
        classification_type_name:
          oneOf:
            - type: string
              enum:
                - Roadside
                - Place-Based
            - type: array
              minItems: 1
              items:
                type: string
                enum:
                  - Roadside
                  - Place-Based
          description: '`Roadside` or `Place-Based`, one or both.'
        construction_type_name:
          oneOf:
            - type: string
            - type: array
              minItems: 1
              items:
                type: string
          description: Canon construction type (14-value closed set), one value or several (for example `Freestanding`, `Exterior Wall`, `Rooftop`).
        illumination_type_name:
          oneOf:
            - type: string
              enum:
                - Frontlit
                - Sunlit Ambient
                - Backlit
                - Artificial Ambient
            - type: array
              minItems: 1
              items:
                type: string
                enum:
                  - Frontlit
                  - Sunlit Ambient
                  - Backlit
                  - Artificial Ambient
          description: |
            Illumination type, one value or several: `Frontlit`, `Backlit`, `Sunlit Ambient`, `Artificial Ambient`.
        digital:
          type: boolean
          description: '`true` for digital faces only, `false` for static only. Omit for both.'
        placement_type_name:
          oneOf:
            - type: string
              minLength: 1
            - type: array
              minItems: 1
              items:
                type: string
                minLength: 1
          description: 'Placement type, one value or several. Free string: the caller''s own vocabulary on the private corpus, the Geopath vocabulary on the public corpus; the adapter does not map between them.'
        urbanicity:
          oneOf:
            - type: string
              minLength: 1
            - type: array
              minItems: 1
              items:
                type: string
                minLength: 1
          description: Urbanicity around the face, one value or several. Private corpus only; the public corpus carries no urbanicity field and rejects this filter with a 400.
        place_id:
          oneOf:
            - type: string
              minLength: 1
            - type: array
              minItems: 1
              items:
                type: string
                minLength: 1
          description: Place id, one value or several. Exact id equality on both corpora.
        rotating:
          type: boolean
          description: Whether the display rotates between multiple creatives.
        full_motion:
          type: boolean
          description: Whether the display supports full-motion video.
        partial_motion:
          type: boolean
          description: Whether the display supports partial motion (animated stills).
        interactive:
          type: boolean
          description: Whether the display is interactive.
        audio:
          type: boolean
          description: Whether the display plays audio.
        height_in:
          type: object
          additionalProperties: false
          properties:
            min:
              type: number
            max:
              type: number
          description: Face height range in inches, as { min, max }; at least one bound required.
        width_in:
          type: object
          additionalProperties: false
          properties:
            min:
              type: number
            max:
              type: number
          description: Face width range in inches, as { min, max }; at least one bound required.
        elevation:
          type: object
          additionalProperties: false
          properties:
            min:
              type: number
            max:
              type: number
          description: Elevation range, as { min, max }; at least one bound required. Private corpus only; the public corpus carries no elevation field and rejects this filter with a 400.
        orientation:
          type: object
          additionalProperties: false
          properties:
            min:
              type: number
              minimum: 0
              maximum: 360
            max:
              type: number
              minimum: 0
              maximum: 360
          description: Facing orientation range in degrees clockwise from north, as { min, max }; at least one bound required. Each bound must be within 0-360; out-of-range values return 400 (bounds outside 0-360 are rejected, not clamped).
        related_parties:
          type: array
          minItems: 1
          items:
            type: object
            additionalProperties: false
            properties:
              party_name:
                oneOf:
                  - type: string
                    maxLength: 256
                  - type: array
                    minItems: 1
                    items:
                      type: string
                      maxLength: 256
                description: 'Party name to match. Matching is exact and case-sensitive: the value must equal the stored party name character for character, with no case folding, trimming, or partial matching.'
              division:
                oneOf:
                  - type: string
                    maxLength: 256
                  - type: array
                    minItems: 1
                    items:
                      type: string
                      maxLength: 256
              role:
                oneOf:
                  - type: string
                  - type: array
                    minItems: 1
                    items:
                      type: string
              party_display_id:
                type: array
                minItems: 1
                items:
                  type: string
                  maxLength: 256
              other_ids:
                type: object
                description: Generic party identifier lookup. The public corpus honors the known keys `frame`, `face`, `layout` (numeric id strings) and rejects unknown keys with a 400; the private corpus honors any key.
                additionalProperties:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    maxLength: 256
              spot_id:
                type: array
                minItems: 1
                items:
                  type: string
                  maxLength: 256
                description: 'Party-scoped spot ids; integer values are coerced to strings. Honored on both corpora. The public corpus matches the nested `layouts.faces.spots.id`, which carries numeric ids only: a non-numeric value (some operator-native spot ids are non-numeric) is rejected with a 400 on an explicit `publication: public` request. On an omitted-publication (merged) request the 400 fires once the walk reaches the public leg, so a merged first page filled by the private corpus can return 200 and surface the reject on a later page.'
              media_name:
                oneOf:
                  - type: string
                    maxLength: 256
                  - type: array
                    minItems: 1
                    items:
                      type: string
                      maxLength: 256
                description: Party-authored media label. Private corpus only; the public corpus rejects it with a 400.
              status_type:
                oneOf:
                  - type: string
                    maxLength: 64
                  - type: array
                    minItems: 1
                    items:
                      type: string
                      maxLength: 64
                description: Party vocabulary status. Private corpus only; the public corpus rejects it with a 400.
            description: |
              One party constraint element. Keys within ONE element must hold on the SAME party (AND); multiple elements are a disjunction (OR); an array value inside a key is an OR over values, still within the same party.
          description: 'Party constraints: an array of elements. AND within an element (same party), OR across elements, OR inside a key''s values. Every element must carry at least one constraint key; an empty `{}` element is rejected with a 400 naming `related_parties` (it would vacuously match every party).'
        publication:
          type: string
          enum:
            - private
            - public
          description: |
            Which corpus to search. Omitted = fan-out over both corpora merged: the caller's own org assets are walked first, to exhaustion, then the public inventory continues the same walk (one request, one credit). `private` scopes to the caller's own org assets across every lifecycle state, expired subscriptions included. `public` scopes to the public inventory.
        state:
          oneOf:
            - type: string
              enum:
                - draft
                - draft_measured
                - final_measured
            - type: array
              minItems: 1
              items:
                type: string
                enum:
                  - draft
                  - draft_measured
                  - final_measured
          description: |
            Lifecycle-state filter. Honored with all three values on the private corpus. On the public corpus it is honored as a constant: public inventory rows are all `final_measured`, so a request whose state set includes `final_measured` serves the normal page and a draft-only request is truthfully an empty 200 result, not a 400. This filter is the asset lifecycle and is unrelated to the geographic `state` field on results (for example `IL`).
        direct:
          type: boolean
          description: 'Direct-add copies only. Honored on the private corpus; sending it whenever the public leg is in scope (an explicit `publication: public`, or an omitted publication) returns a 400 naming it, rejected at validation before any backend query. Filters are honored or rejected, never silently ignored. `direct: true` returns only your organization''s direct-add copies (any lifecycle state). `direct: false` returns the rest of your organization''s corpus: canonical assets and your drafts and draft-measured assets, which are not direct-add copies. Draft and draft-measured rows carry their `vca`-prefixed asset id in the `display_id` field until a canonical display id is minted at `final_measured`.'
        geography:
          type: object
          additionalProperties: false
          properties:
            dma_id:
              oneOf:
                - type: string
                  minLength: 1
                  maxLength: 16
                - type: array
                  minItems: 1
                  maxItems: 250
                  items:
                    type: string
                    minLength: 1
                    maxLength: 16
              example: '524'
              description: 'Geopath DMA id, as returned in `dma_id` on public results (for example `"524"` for Atlanta). An array matches any of the DMAs. Public corpus only: private assets carry no DMA, so sending it whenever the private corpus is in scope (`publication: private`, or an omitted publication) returns a 400 naming `geography.dma_id`. Send `publication: public` to filter by DMA.'
            bbox:
              type: object
              additionalProperties: false
              required:
                - north
                - south
                - east
                - west
              properties:
                north:
                  type: number
                  minimum: -90
                  maximum: 90
                south:
                  type: number
                  minimum: -90
                  maximum: 90
                east:
                  type: number
                  minimum: -180
                  maximum: 180
                west:
                  type: number
                  minimum: -180
                  maximum: 180
              description: Bounding box; `north` must be >= `south` and `east` must be >= `west`. An inverted box (north < south, or east < west) is rejected with a 400 naming `geography.bbox`. Antimeridian-spanning boxes are not supported.
          description: 'Geography filter: `bbox` and/or `dma_id`; when both are sent they AND. Other geo attributes on results (county, CBSA, postal code) are not searchable.'
        limit:
          type: integer
          minimum: 1
          maximum: 200
          description: Page size. Default 50, max 200.
        cursor:
          type: string
          description: Opaque pagination cursor from the previous response's `meta.pagination.next_cursor`. Cursors are versioned, bound to the request's filter set, and signed for tamper-evidence. Replaying a cursor with different filters, an edited or tampered cursor, or a cursor minted before the current binding (one without a filter-hash and signature) returns a 400 asking you to restart pagination without it.
    DisplaySearchResult:
      type: object
      description: |
        One display face as a canonical display row. Contains only the canonical display fields; face dimensions are in inches. Rows from both corpora take this same canonical form, with structural differences by corpus: private-corpus rows omit the following 13 public-row fields because the private corpus does not carry them (the geo-enrichment block plus the venue-taxonomy key `openooh_venue_id`): `cbsa_code`, `cbsa_name`, `county_id`, `county_name`, `dma_id`, `dma_name`, `location_description`, `openooh_venue_id`, `place_name`, `place_type_name`, `postal_code`, `primary_artery`, `state`. Public-corpus rows omit `last_modified` and `sources[].observed_at` because the public corpus carries no usable record vintage (see those fields).
      additionalProperties: false
      required:
        - display_id
        - publication
        - status_type
        - lat
        - lon
        - related_parties
      properties:
        display_id:
          type: string
          description: |
            Stable Motionworks display identifier: the same `display_id` used across Displays and Viewcast. For a face not yet mapped, the upstream source face id is returned until the mapping catches up (within about an hour). The registry's own identifier appears in `related_parties[].party_display_id` under the `registry` role. On the private corpus, the projection coalesces `display_id`, then `source_display_id`, then `asset_id`, so a private draft row with neither a mapped nor a source display id returns the vca-prefixed asset id in this field.
        publication:
          type: string
          enum:
            - private
            - public
          description: |
            The corpus this row came from: `public` for published inventory, `private` for your organization's own assets. Both `public` and `private` rows are emitted.
        status_type:
          type: string
          description: The face's status in its source inventory.
        height_in:
          type: number
          description: Face height in inches.
        width_in:
          type: number
          description: Face width in inches.
        media_type_name:
          type: string
          description: Media type of the face (for example `Bulletin`, `Poster`, `Panel`).
        construction_type_name:
          type: string
          description: How the display is mounted or built.
        illumination_type_name:
          type: string
          enum:
            - Frontlit
            - Sunlit Ambient
            - Backlit
            - Artificial Ambient
          description: How the face is lit.
        classification_type_name:
          type: string
          description: Canon classification type (e.g. "Place-Based", "Roadside").
        digital:
          type: boolean
          description: Whether the face is digital.
        orientation:
          type: number
          description: Compass direction the face points toward, in degrees clockwise from north.
        elevation:
          type: number
          description: Height of the face above ground, when known.
        placement_type_name:
          type: string
          description: Placement type of the face, using the Motionworks display taxonomy.
        urbanicity:
          type: string
          description: The setting around the face (for example `Urban`, `Suburban`, `Rural`).
        place_id:
          type: string
          description: Identifier of the place the face is in, for place-based inventory.
        rotating:
          type: boolean
          nullable: true
          description: Whether the face rotates between multiple creatives.
        full_motion:
          type: boolean
          nullable: true
          description: Whether the face supports full-motion video.
        partial_motion:
          type: boolean
          nullable: true
          description: Whether the face supports partial motion (animated stills).
        interactive:
          type: boolean
          nullable: true
          description: Whether the face is interactive.
        audio:
          type: boolean
          nullable: true
          description: Whether the face plays audio.
        place_name:
          type: string
          description: Name of the place the face is in.
        place_type_name:
          type: string
          description: 'Geopath place type of the face. It depends on the classification: Roadside faces carry an area type (Urban, Suburban, Rural, Urban Business, Central Business District), Place-Based faces a venue type (Grocery Store, Bar, Transit Station and so on). Faces whose classification is Fleet Exterior - Scheduled, which is neither filter value, carry Bus Garage. Filter on `classification_type_name: Place-Based` to see venue types only; that excludes the fleet faces too.'
        openooh_venue_id:
          type: string
          nullable: true
          description: Venue taxonomy id, when known.
        lat:
          type: number
          description: Latitude of the face (WGS84 degrees). Public rows are rounded to 3 decimals (about 110 m); private rows are exact. Rounding is applied after filtering, so a public row may lie up to 0.0005° outside the requested bbox.
        lon:
          type: number
          description: Longitude of the face (WGS84 degrees). Public rows are rounded to 3 decimals (about 110 m); private rows are exact. Rounding is applied after filtering, so a public row may lie up to 0.0005° outside the requested bbox.
        location_description:
          type: string
          nullable: true
          description: Free-text description of the location, as recorded in the source inventory.
        primary_artery:
          type: string
          nullable: true
          description: The main road the face is read from.
        postal_code:
          type: string
          description: Postal code of the face location.
        state:
          type: string
          description: State of the face location (geographic, for example `IL`). Unrelated to the lifecycle `state` request filter; the row's lifecycle status is carried by `status_type`.
        county_id:
          type: string
          description: County identifier.
        county_name:
          type: string
          description: County name.
        cbsa_code:
          type: string
          description: Core-based statistical area (metro) code.
        cbsa_name:
          type: string
          description: Core-based statistical area (metro) name.
        dma_id:
          type: string
          description: Designated market area (DMA) id.
        dma_name:
          type: string
          description: Designated market area (DMA) name.
        sources:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - source_id
            properties:
              source_id:
                type: string
              observed_at:
                type: string
          description: |
            The inventories this row was assembled from. `observed_at` is present on private-corpus rows (the asset record vintage); omitted on public-corpus rows because the public corpus carries no usable vintage.
        last_modified:
          type: string
          description: |
            Present on private-corpus rows (the asset record vintage); omitted on public-corpus rows because the public corpus carries no usable vintage. Previously public rows stamped the request time here, which was misleading.
        related_parties:
          type: array
          items:
            type: object
          description: |
            The parties related to this face (owner, manager, reseller, registry), each with its own identifiers.
    DisplaySearchResponse:
      type: object
      description: |
        Response envelope for `POST /v2/displays/search`: `{ data, meta }` with cursor pagination and provenance in `meta`. Carries `cursor` and `has_more`; there is no total count.
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DisplaySearchResult'
          description: The matching display faces for this page.
        meta:
          type: object
          additionalProperties: false
          required:
            - pagination
            - provenance
            - request_id
            - credits_used
          properties:
            pagination:
              type: object
              additionalProperties: false
              required:
                - has_more
                - count
              properties:
                next_cursor:
                  type: string
                has_more:
                  type: boolean
                count:
                  type: integer
                truncated:
                  type: boolean
                  description: 'Present and true when the walk stopped at a result cap rather than exhausting the matches: the 10,000-result ceiling on the public corpus, or the private-corpus candidate-examination cap on a sparse `related_parties` walk. `has_more` may still be true and `next_cursor` resumes the walk.'
            provenance:
              $ref: '#/components/schemas/Provenance'
            request_id:
              type: string
            credits_used:
              type: number
          description: 'Request metadata: pagination cursor, `has_more`, credits and provenance.'
    DisplayFacetKey:
      type: string
      enum:
        - related_parties.party_name
        - media_type_name
        - classification_type_name
        - construction_type_name
        - illumination_type_name
        - placement_type_name
        - digital
        - dma_id
        - county_id
        - cbsa_code
        - place_name
        - place_type_name
      description: |
        A field to count values of. Each key names a display result field (`related_parties.party_name` names the party field). `dma_id`, `county_id` and `cbsa_code` are public-corpus only: private assets carry no resolved geography, so private rows count under `missing` for them. `place_name` (the venue name) and `place_type_name` (the venue type) group free-text results; most roadside displays have no venue name (counted as `missing`), a brand can appear under several names ("Kroger", "Kroger - Atlanta"), and venue type also holds environment values such as Urban and Suburban.
    DisplayFacetsRequest:
      type: object
      description: |
        Body for `POST /v2/displays/facets`: the same filters as `POST /v2/displays/search` (same keys, same rules, same 400 messages), plus `facets` and `size`. `limit` and `cursor` are not accepted, since facets return no rows.
      additionalProperties: false
      required:
        - facets
      properties:
        q:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/q'
        media_type_name:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/media_type_name'
        classification_type_name:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/classification_type_name'
        construction_type_name:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/construction_type_name'
        illumination_type_name:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/illumination_type_name'
        digital:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/digital'
        placement_type_name:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/placement_type_name'
        urbanicity:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/urbanicity'
        place_id:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/place_id'
        rotating:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/rotating'
        full_motion:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/full_motion'
        partial_motion:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/partial_motion'
        interactive:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/interactive'
        audio:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/audio'
        height_in:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/height_in'
        width_in:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/width_in'
        elevation:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/elevation'
        orientation:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/orientation'
        related_parties:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/related_parties'
        publication:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/publication'
        state:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/state'
        direct:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/direct'
        geography:
          $ref: '#/components/schemas/DisplaySearchRequest/properties/geography'
        facets:
          type: array
          minItems: 1
          maxItems: 10
          uniqueItems: true
          items:
            $ref: '#/components/schemas/DisplayFacetKey'
          description: The fields to count, 1 to 10 keys, no repeats.
        size:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
          description: Most values returned per facet. Values past the top `size` are summed into `other`.
    DisplayFacetValue:
      type: object
      additionalProperties: false
      required:
        - value
        - count
      properties:
        value:
          oneOf:
            - type: string
            - type: boolean
          description: The field value, exactly as search results carry it, so it can be sent back as a filter unchanged.
        count:
          type: integer
          minimum: 0
          description: Display faces (result rows) with this value in the filtered slice.
        label:
          type: string
          description: Human-readable name for an id value, for example the DMA name for a `dma_id`.
        leg:
          type: string
          enum:
            - private
            - public
          description: Set only on `placement_type_name`, whose vocabulary differs between your assets and the public inventory, so its values are reported per corpus rather than merged.
    DisplayFacetCounts:
      type: object
      additionalProperties: false
      required:
        - values
        - other
        - missing
      properties:
        values:
          type: array
          items:
            $ref: '#/components/schemas/DisplayFacetValue'
          description: Values sorted by count, highest first, then by value. At most `size` entries.
        other:
          type: integer
          minimum: 0
          description: Faces whose value is outside the top `size`.
        missing:
          type: integer
          minimum: 0
          description: Faces with no value for this field.
      description: |
        Counts for one facet. For a single-valued field, the counts in `values` plus `other` plus `missing` equal `total`. `related_parties.party_name` is multi-valued: a face with two parties counts under both, so its sum can exceed `total`.
    DisplayFacetsResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          type: object
          additionalProperties: false
          required:
            - total
            - facets
            - legs
          properties:
            total:
              type: integer
              minimum: 0
              description: Display faces in the filtered slice, across the corpora in scope. This is the whole slice, not one page.
            facets:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/DisplayFacetCounts'
              description: Counts per requested facet key.
            legs:
              type: object
              additionalProperties: false
              properties:
                private:
                  type: integer
                  minimum: 0
                public:
                  type: integer
                  minimum: 0
              description: Faces per corpus. A corpus outside the request's `publication` scope is omitted.
            truncated:
              type: boolean
              description: Present and true when your private assets exceeded the counting cap (10,000 matching assets, or 50,000 assets examined), so the private counts cover only part of them.
        meta:
          type: object
          additionalProperties: false
          required:
            - provenance
            - request_id
            - credits_used
          properties:
            provenance:
              $ref: '#/components/schemas/Provenance'
            request_id:
              type: string
            credits_used:
              type: number
paths:
  /displays/search:
    post:
      tags:
        - Display Search
      operationId: searchDisplays
      summary: Search OOH displays (public inventory + your organization's assets)
      description: |
        Search out-of-home display inventory: the public Geopath corpus and your organization's own assets. Each result is one advertising face, described with the canonical Motionworks display fields: classification, media type, dimensions in inches, illumination, and the related parties with their own identifiers.

        - **Filters, plus free text on the public inventory.** The body is a closed set of filters; a JSON body is required (an explicit `{}` returns the first page of the merged walk; a request with no body returns 400). Unknown keys, including `query`, `dsl` and `catalog_status`, return 400. `q` searches the public inventory by text and ranks the results (see `q` below); it needs `publication: public`.
        - **Both corpora, one request.** Omit `publication` to fan out: your organization's own assets are walked first, to exhaustion, then the public inventory continues the same walk, deduplicated, for one credit. Set `publication` to `private` or `public` to scope to one corpus.
        - **Pagination.** Cursor-based: 50 results per page by default, 200 at most, up to 10,000 results per query without `q` (no limit with `q`). The response reports `has_more` rather than a total count. Cursors are versioned; a cursor minted before the current grammar returns a 400 asking you to restart pagination without it.

        ### Combining filters: AND, OR, NOT

        - **AND across top-level filters.** Every top-level filter you send must hold on the same result. For example, `media_type_name` AND `digital` AND `geography.bbox` returns only faces that satisfy all three:

          ```json
          {
            "media_type_name": "Bulletin",
            "digital": false,
            "geography": { "bbox": { "north": 41, "south": 40.5, "east": -73.5, "west": -74.5 } }
          }
          ```

        - **OR across array values.** A filter sent as an array is a disjunction over its values: `"media_type_name": ["Bulletin", "Poster"]` matches faces of either media type.
        - **AND within one `related_parties` element.** Every key inside ONE element must hold on the SAME party. For example, this matches displays where one party is both the owner AND named Clear Channel:

          ```json
          { "related_parties": [ { "role": "owner", "party_name": "Clear Channel" } ] }
          ```

        - **OR across `related_parties` elements.** Multiple array elements are a disjunction: two elements match displays where party A satisfies the first element OR party B satisfies the second (the same party need not satisfy both). An array value inside one key is also an OR over values, still within that one party.
        - **NOT is not supported.** There is no negation operator anywhere in the grammar. For closed-enum filters (`media_type_name`, `classification_type_name`, `illumination_type_name`, `state`) express complements by omission: instead of "NOT Bulletin", send every media type except `Bulletin` (the enum is closed, so the complement is exactly enumerable). Open-vocabulary fields cannot be complemented.
        - **Access and cost.** Requires an API key or a signed-in session: a request with no credentials receives 401, and an anonymous trial session receives 403 (`FEATURE_NOT_LICENSED`). 1 credit per request. Responses are never cached (`Cache-Control: private, no-store`).
      x-credit-cost: 1
      x-motionworks-status: production
      security:
        - apiKey: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisplaySearchRequest'
      responses:
        '200':
          description: Search results.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
            Vary:
              schema:
                type: string
                enum:
                  - X-API-Key, Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplaySearchResponse'
        '400':
          description: |
            Invalid request: a request with no JSON body, an unknown key (including `query`, `dsl` or `catalog_status`), `limit` outside 1–200, or `q` with your own assets in scope (send `publication: public`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: |
            `FEATURE_NOT_LICENSED` — authenticated but not licensed for Display Search (anonymous sessions are not licensed). `error.context` carries `feature_key` and `user_class`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /displays/facets:
    post:
      tags:
        - Display Search
      operationId: facetDisplays
      summary: Count display values for a set of filters
      description: |
        For the same filters as `POST /v2/displays/search`, returns how many display faces carry each value of the fields you name, so you can show the choices left (and their sizes) before fetching rows. For example, with `geography.dma_id: "524"` and `facets: ["related_parties.party_name"]` you get every owner in the Atlanta DMA with its face count.

        - **Same slice as search.** The body takes every search filter, with the same rules and the same 400 messages. Counts are in faces, the row unit search returns, and cover the whole filtered slice, not one page: if 2,000 of 9,000 matching faces belong to one owner, its count is 2,000 whatever page size you search with.
        - **Both corpora.** Omit `publication` to count your organization's assets and the public inventory together, summed by value; `data.legs` gives each corpus's total. A display you also hold privately counts once in each corpus. Set `publication` to `private` or `public` to count one corpus.
        - **Exact values.** Values come back exactly as results carry them, so you can send one straight back as a filter. Matching is exact and case-sensitive, as in search. `place_name` and `place_type_name` have no matching filter: to narrow to one of their values, send it as `q`.
        - **Categories for a text search.** Send the same `q` (with `publication: public`) to count what a text search found, for example `facets: ["place_type_name", "place_name"]` for "coffee shop" returns venue types and venue names with their counts. `place_type_name` holds area types (Urban, Suburban, Rural and so on) for Roadside faces and venue types for Place-Based faces, so add `classification_type_name: Place-Based` to count venue types alone.
        - **Status.** The public inventory counts `Published - Measured` displays only, the same set search returns.
        - **Access and cost.** Requires an API key or a signed-in session; anonymous sessions receive 403 (`FEATURE_NOT_LICENSED`). 1 credit per request. Responses are never cached.
      x-credit-cost: 1
      x-motionworks-status: production
      security:
        - apiKey: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisplayFacetsRequest'
            example:
              publication: public
              geography:
                dma_id: '524'
              classification_type_name: Roadside
              facets:
                - related_parties.party_name
                - media_type_name
                - digital
              size: 50
      responses:
        '200':
          description: Value counts for the filtered slice.
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                  - private, no-store
            Vary:
              schema:
                type: string
                enum:
                  - X-API-Key, Authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayFacetsResponse'
        '400':
          description: |
            Invalid request: no JSON body, an unknown key (including `limit` and `cursor`), an unknown or repeated facet key, more than 10 facets, `size` outside 1–200, or a filter the corpus in scope cannot serve (for example `geography.dma_id` with the private corpus in scope).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: |
            `FEATURE_NOT_LICENSED` — authenticated but not licensed for Display Search (anonymous sessions are not licensed). `error.context` carries `feature_key` and `user_class`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /displays/tiles/tilesets:
    get:
      tags:
        - Tile Discovery
      operationId: listDisplaysTilesets
      summary: List the tilesets Displays publishes
      description: |
        Returns the public tile catalog for Displays: every layer slug with its title, zoom range, geographic bounds and TileJSON `vector_layers[]` field schema. Use it to choose the `tilesets[]` for a grant, or to build a layer picker without hardcoding the catalog.

        No authentication required and no charge. Responses are not cached (`Cache-Control: private, no-store`).
      x-credit-cost: 0
      x-motionworks-status: production
      security: []
      responses:
        '200':
          description: Tile catalog.
          headers:
            Cache-Control:
              schema:
                type: string
                example: private, no-store
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TilesetCatalogResponse'
                  meta:
                    $ref: '#/components/schemas/TileMeta'
  /displays/tiles/grants:
    post:
      tags:
        - Tile Grants
      operationId: createDisplaysTileGrant
      summary: Mint a Displays vector-tile grant
      description: |
        Creates a tile-delivery grant for your organization and returns its capability `tile_json_url`. Hand that URL to MapLibre, Mapbox GL JS or any TileJSON-aware client and it starts rendering. Free — grant management costs 0 credits; only tile traffic is metered.

        Authenticate with an org-scoped API key (`X-API-Key: mw_…`) or a signed-in session (`Authorization: Bearer <jwt>`); anonymous callers cannot mint grants. Your organization must be licensed for Displays tiles; the license is included for signed-in and pay-as-you-go accounts. Tile traffic is charged to your organization at 1 credit per 1,000 tiles served. If your organization's billing setup cannot carry tile traffic you receive `403 TILE_GRANTS_REQUIRE_METERED`; contact sales to enable tile delivery.
      x-credit-cost: 0
      x-motionworks-status: production
      security:
        - bearerAuth: []
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TileGrantCreateRequest'
      responses:
        '201':
          description: Grant created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TileGrantCreateResponse'
                  meta:
                    $ref: '#/components/schemas/TileMeta'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: |
            Common cases:
              * `FEATURE_NOT_LICENSED` — your organization is not licensed for Displays vector tiles. Contact sales.
              * `TILE_GRANTS_REQUIRE_METERED` — tile delivery for your organization requires pay-as-you-go (metered) billing, which is not enabled. Contact sales to enable tile delivery.
              * `TILE_LAYER_NOT_LICENSED` — one or more `tilesets[]` entries name a layer Displays does not publish.
              * `API_KEY_NO_AUDIT_USER` — the API key is not tied to a user. Mint with a signed-in session, or with a key created by a user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      tags:
        - Tile Grants
      operationId: listDisplaysTileGrants
      summary: List your organization's grants
      description: Returns your organization's tile grants, most recent first. Free.
      x-credit-cost: 0
      x-motionworks-status: production
      security:
        - bearerAuth: []
        - apiKey: []
      responses:
        '200':
          description: Grant list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TileGrant'
                  meta:
                    $ref: '#/components/schemas/TileMeta'
        '401':
          description: Missing or invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /displays/tiles/grants/{id}:
    get:
      tags:
        - Tile Grants
      operationId: getDisplaysTileGrant
      summary: Read one grant
      description: Returns one grant by id, scoped to your organization. Free.
      x-credit-cost: 0
      x-motionworks-status: production
      security:
        - bearerAuth: []
        - apiKey: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Grant ULID returned by `POST /v2/displays/tiles/grants`.
      responses:
        '200':
          description: Grant.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TileGrant'
                  meta:
                    $ref: '#/components/schemas/TileMeta'
        '401':
          description: Missing or invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: |
            No grant with this id in your organization. Expired and revoked grants are still returned so you can inspect them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /displays/tiles/grants/{id}/revoke:
    post:
      tags:
        - Tile Grants
      operationId: revokeDisplaysTileGrant
      summary: Revoke a grant immediately
      description: |
        Revokes the grant immediately: the grant's TileJSON URL stops working (404), and tile requests using tokens already minted from it return 401 `UNAUTHORIZED` with `error.context.reason: grant_revoked`. Revoking a grant that is already revoked returns it unchanged. Free.
      x-credit-cost: 0
      x-motionworks-status: production
      security:
        - bearerAuth: []
        - apiKey: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Grant revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TileGrant'
                  meta:
                    $ref: '#/components/schemas/TileMeta'
        '401':
          description: Missing or invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No grant with this id in your organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /displays/tiles/grants/{id}/tilejson:
    get:
      tags:
        - Tile TileJSON
      operationId: getDisplaysTileJson
      summary: Get the TileJSON manifest for a grant (capability URL, no auth header)
      description: |
        Returns a TileJSON 3.0.0 manifest with a freshly minted 24-hour tile token embedded in `tiles[]`. This is the URL you hand to MapLibre, Mapbox GL JS or any TileJSON-aware client.

        **This URL is a capability — treat it like a secret.** It carries the credential needed to fetch tiles inside the URL itself, like a presigned object-storage URL: anyone who has it can render your map until the grant expires or is revoked. That is by design — your front-end code can pass it straight to the map library without a separate auth header. Two safety nets are built in: the grant's `allowed_origins` pins which sites can fetch tiles, and `POST /v2/displays/tiles/grants/{id}/revoke` ends the grant.

        Free — the tile bytes themselves are metered on `GET .../{layer}/{z}/{x}/{y}.mvt`.
      x-credit-cost: 0
      x-motionworks-status: production
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Grant ULID. Opaque bearer credential — treat as secret.
      responses:
        '200':
          description: TileJSON 3.0.0 manifest.
          headers:
            Cache-Control:
              schema:
                type: string
                example: private, max-age=3600, must-revalidate
            Vary:
              schema:
                type: string
                example: Origin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TileJsonManifest'
        '403':
          description: |
            `error.code` tells you which:
              * `ORIGIN_NOT_ALLOWED` — the request `Origin` is not in the grant's `allowed_origins` (`error.context.reason: origin_not_allowed`), or the request carried no `Origin` header at all (`origin_required`). Requests must carry an `Origin` header that matches one entry. To test from curl or a native app, include the literal string `null` in `allowed_origins`.
              * `FEATURE_NOT_LICENSED` — your organization is not licensed for Displays vector tiles. Contact sales.
              * `TILE_GRANTS_REQUIRE_METERED` — tile delivery for your organization requires pay-as-you-go (metered) billing, which is not enabled. Contact sales to enable tile delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Grant not found, expired, or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /displays/tiles/{layer}/{z}/{x}/{y}.mvt:
    get:
      tags:
        - Tile Data
      operationId: getDisplaysTileMvt
      summary: Fetch a single Displays vector tile (binary MVT)
      description: |
        **Your map library calls this for you.** MapLibre, Mapbox GL JS and deck.gl's `MVTLayer` read the `?token=` from the TileJSON manifest and append it to every tile request.

        Returns a Mapbox Vector Tile (binary protobuf). The only accepted credential is the `?token=` query parameter — header-based auth is rejected by design, so the TileJSON URL alone is enough for a browser to render. Metered at **1 credit per 1,000 tiles served**. Responses may be gzip-encoded; honor `Content-Encoding`. A tile with no features returns HTTP 204.

        Zoom ranges differ by layer: `faces` serves z 0–14; the modeled exposure layers (`viewsheds`, `paths_vehicle`, `paths_pedestrian`, `gates_vehicle`, `gates_pedestrian`) serve z 11–17. The `X-MW-Snapshot` response header names the data snapshot for dated layers and reads `static` for layers that always serve the latest published release.
      x-credit-cost: 1
      x-motionworks-status: production
      x-motionworks-source-doc: https://docs.mworks.com/docs/displays-tiles
      security:
        - tileTokenAuth: []
      externalDocs:
        description: MapLibre vector source spec — explains how MapLibre fetches this endpoint for you.
        url: https://maplibre.org/maplibre-style-spec/sources/#vector
      parameters:
        - name: layer
          in: path
          required: true
          schema:
            type: string
            enum:
              - faces
              - viewsheds
              - paths_vehicle
              - paths_pedestrian
              - gates_vehicle
              - gates_pedestrian
          description: |
            Tileset slug: `faces` (OOH inventory face points, z 0–14) or one of the modeled exposure layers (z 11–17): `viewsheds`, `paths_vehicle`, `paths_pedestrian`, `gates_vehicle`, `gates_pedestrian`. A slug the token does not cover returns 401 `layer_not_in_tilesets`.
        - name: z
          in: path
          required: true
          schema:
            type: integer
            minimum: 0
            maximum: 17
          description: |
            Tile zoom level. `faces` serves z 0–14; the modeled exposure layers serve z 11–17. A zoom outside the layer's range returns 400 `INVALID_REQUEST`.
        - name: x
          in: path
          required: true
          schema:
            type: integer
            minimum: 0
          description: Tile column.
        - name: 'y'
          in: path
          required: true
          schema:
            type: integer
            minimum: 0
          description: Tile row.
        - name: token
          in: query
          required: true
          schema:
            type: string
          description: Opaque tile-token JWT extracted from TileJSON. Treat as secret.
      responses:
        '200':
          description: Vector tile bytes.
          headers:
            Cache-Control:
              schema:
                type: string
                example: private, max-age=300
            Content-Encoding:
              schema:
                type: string
                example: gzip
              description: Present when upstream returned gzip-encoded bytes. Clients MUST honor.
            Vary:
              schema:
                type: string
                example: Accept-Encoding, Origin
            X-MW-Tileset:
              schema:
                type: string
              description: Resolved upstream tileset id (e.g. `displays.faces`).
            X-MW-Snapshot:
              schema:
                type: string
                format: date
              description: |
                Data snapshot the tile came from. For `faces` this is the snapshot date (for example `2026-01-15`). The five modeled-exposure layers always serve the latest published release and carry the literal `static`.
          content:
            application/vnd.mapbox-vector-tile:
              schema:
                type: string
                format: binary
        '204':
          description: Empty tile — no features intersect this z/x/y. No body, no `Content-Encoding`.
        '400':
          description: '`error.code: INVALID_REQUEST` — zoom outside the layer''s range, or non-integer `x`/`y`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: |
            `error.code: UNAUTHORIZED`. Disambiguated by `error.context.reason`:
              * (no reason) — `?token=` missing.
              * `expired` / `malformed` / `signature_mismatch` — the token is invalid or expired; fetch the TileJSON again.
              * `layer_not_in_tilesets` — the token does not authorize the requested layer.
              * `grant_revoked` — the backing grant has been revoked.
              * `tile_grant_exhausted` — your organization's credits are exhausted (a billing signal, not an auth failure).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: |
            `error.code: ORIGIN_NOT_ALLOWED` — the request `Origin` is not in the grant's `allowed_origins` (`error.context.reason: origin_not_allowed`), or the request carried no `Origin` header (`origin_required`). Map libraries send `Origin` automatically; to test from curl or a native app, include the literal string `null` in the grant's `allowed_origins`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: |
            The grant behind the token no longer exists, or the layer is no longer published. (A slug the token does not cover returns 401, not 404.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /displays/assets:
    post:
      tags:
        - Assets
      operationId: createDisplaysAsset
      summary: Create a draft asset
      description: |
        Creates a draft asset from its classification, its anchor point and the parties related to it, and returns the asset record in state `draft`. This call is synchronous and costs 1 credit; it does not start a measurement.

        To measure the asset, purchase a draft measurement with `POST /v2/viewcast/measurements/purchase/draft` (150 credits) and poll `GET /v2/viewcast/measurements/{asset_id}` — polling is free (0 credits). Draft submissions aggregate for up to 2 minutes before pipeline dispatch (one file per <=100 queued items). A draft measurement completes within three hours of purchase; if it cannot complete, the purchase is refunded automatically and the asset returns to `draft`, ready to purchase again.

        Retrying a create request creates a second asset — there is no idempotency key. The one guard is the duplicate check: if any owner entry's `party_display_id` is already registered to another asset your organization owns, the request returns 409.
      x-credit-cost: 1
      x-motionworks-status: production
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ViewcastAssetCreateRequest'
      responses:
        '200':
          description: Draft asset created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ViewcastAsset'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          description: Invalid payload (classification enum, anchor bounds).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient credits for the draft purchase.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: |
            Duplicate: an owner entry's `party_display_id` in this request is already registered to another asset your organization owns.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      tags:
        - Assets
      operationId: listDisplaysAssets
      summary: List your asset library
      description: |
        Lists the assets your organization owns, optionally filtered by lifecycle state and classification. Paginated by cursor.
      x-credit-cost: 1
      x-motionworks-status: production
      parameters:
        - name: state
          in: query
          schema:
            type: string
            enum:
              - draft
              - draft_measured
              - final_measured
          description: Only assets in this lifecycle state (`draft`, `draft_measured` or `final_measured`).
        - name: classification
          in: query
          schema:
            type: string
            enum:
              - Roadside
              - Place-Based
          description: Only assets with this classification (`Roadside` or `Place-Based`).
        - name: cursor
          in: query
          schema:
            type: string
          description: Opaque cursor from the previous page's `meta`.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Page size.
      responses:
        '200':
          description: Paginated asset list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ViewcastAsset'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '503':
          description: Upstream read failure (DATA_UNAVAILABLE).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /displays/assets/summary:
    get:
      tags:
        - Assets
      operationId: getDisplaysAssetsSummary
      summary: Count your assets by state and classification
      description: Returns counts of your organization's assets by lifecycle state and by classification.
      x-credit-cost: 1
      x-motionworks-status: production
      responses:
        '200':
          description: Library summary counts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ViewcastAssetSummary'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '503':
          description: Upstream read failure (DATA_UNAVAILABLE).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /displays/assets/{asset_id}:
    get:
      tags:
        - Assets
      operationId: getDisplaysAsset
      summary: Read one asset
      description: |
        Returns one asset by its `asset_id`. The detail response carries `enrichment` (the measurement detail) when one is available; list responses omit it.
      x-credit-cost: 1
      x-motionworks-status: production
      parameters:
        - name: asset_id
          in: path
          required: true
          schema:
            type: string
          description: The asset identifier returned when the asset was created.
      responses:
        '200':
          description: The asset.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ViewcastAsset'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '404':
          description: Unknown asset_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - Assets
      operationId: refineDisplaysAsset
      summary: Refine an asset, or publish a measured one
      description: |
        Refines the fields you supplied on a `draft` or `draft_measured` asset, or toggles `publication` on a `final_measured` asset.

        - **Guardrails.** The anchor may move at most 100 m from its current position. `classification` is immutable and is not part of the request. A `final_measured` asset cannot be refined — clone it into a new draft instead.
        - **Display descriptor merges per key** (JSON Merge Patch, RFC 7386): a key present in `display` overwrites the stored value, an explicit `null` deletes that key, and an absent key is left alone. `display: {}` is a valid no-op. The merged result is validated against the strict display schema, so unknown keys are still a 400. Every other field replaces its stored value wholesale (`related_parties` replaces the whole roster).
        - **Measurement-input refines always succeed.** Refining `anchor`, `display`, or basis-entry `spots` on a `draft_measured` asset succeeds even while a measurement run is queued or in flight: the platform supersedes the prior run and re-queues a fresh measurement against the new inputs at no additional charge (the 1-cr refine base still applies). When a re-queue fires, the 200 response carries an optional `data.measurement_requeued_at` timestamp; poll `GET /v2/viewcast/measurements/{asset_id}` for the run itself. Re-queues are throttled per asset (default 10/hour); on throttle the refine still succeeds and only the re-queue is skipped.
        - **Response codes.** `final_measured` + `publication` only → 200. `final_measured` + any refine field → 409. `draft` / `draft_measured` + `publication` → 400 (publication is for measured assets). Refine fields and `publication` in one request → 400 in any state. Archived → 404, indistinguishable from an unknown asset.
      x-credit-cost: 1
      x-motionworks-status: production
      parameters:
        - name: asset_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ViewcastAssetRefineRequest'
      responses:
        '200':
          description: The refined asset. When the refine touched measurement inputs on a `draft_measured` asset, `data` additionally carries the optional `measurement_requeued_at` timestamp.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    allOf:
                      - $ref: '#/components/schemas/ViewcastAsset'
                      - type: object
                        properties:
                          measurement_requeued_at:
                            type: string
                            format: date-time
                            description: Present when this refine triggered a free measurement re-queue. Absent on non-measurement-input refines, on `draft` assets, and when the per-asset re-queue throttle skipped the re-queue.
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          description: 'Guardrail violation: anchor moved more than 100 m; `publication` on a `draft`/`draft_measured` asset (publication is final_measured-only); or refine fields combined with `publication` in one request.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown asset_id (archived is indistinguishable from unknown).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: |
            State conflict: a refine was attempted on a `final_measured` asset, or a concurrent change won the race (`row_version` is stale — read the asset and retry).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Assets
      operationId: archiveDisplaysAsset
      summary: Archive an asset
      description: Archives (soft-deletes) an asset. Archived assets no longer appear in list or summary responses.
      x-credit-cost: 1
      x-motionworks-status: production
      parameters:
        - name: asset_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Archived.
        '404':
          description: Unknown asset_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
x-tagGroups:
  - name: Asset library
    tags:
      - Assets
  - name: Search
    tags:
      - Display Search
  - name: Maptiles
    tags:
      - Tile Discovery
      - Tile Grants
      - Tile TileJSON
      - Tile Data
x-customer-voice: true
