Displays Search is an authenticated-only endpoint that lets callers find display assets by a closed filter set. It returns a flat list of matching assets without overlay geometry, idempotency guarantees, or pagination cursors. Every call costs 1 credit (displays_search).

The endpoint is on the v2 base https://api2.mworks.com under the /v2/displays/* path. For the full endpoint reference, see Displays API reference.

Endpoint

POST /v2/displays/search

• Auth: required (Supabase JWT or org-scoped API key). Anonymous callers get 401.
• Feature gate: oohdisplays.displays.search must be enabled on your organization. Unlicensed orgs get 403 FEATURE_NOT_LICENSED.
• Cost: 1 credit per call (displays_search), flat. No overlay, no idempotency.

Request body

The request body is a strict object. Only the following fields are accepted; unknown fields return 400.

All fields are optional; an empty body returns results up to the default limit.

Rejected fields (strict schema)

The following are NOT accepted and return 400 if present in the request body:

• Free-text q parameter (no full-text search).
• catalog_status filter.
• Raw query / dsl (no query-DSL pass-through).

The schema is closed: any field not listed above returns 400. There is no way to inject a raw query or override the filter set.

Example request

curl -X POST https://api2.mworks.com/v2/displays/search \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "classification_type": "Roadside",
    "digital": true,
    "limit": 50
  }'

Example response (schema-derived, pending live E2E verification)

The response shape below is derived from the OpenAPI schema. It has not yet been exercised against the live API in an E2E test. Treat field names and nesting as provisional until verified.

{
  "data": {
    "results": [
      {
        "asset_id": "vcaJDVDYWSSMHAXVEFYW1DVD2PPFD",
        "state": "final_measured",
        "classification": "Roadside",
        "display": {
          "digital": true,
          "media_type": "Billboard"
        },
        "anchor": { "lat": 34.0901, "lon": -118.3839 },
        "display_id": "dspABCD1234EFGH5678"
      }
    ],
    "total": 1
  },
  "meta": {
    "request_id": "req_e8281bd0f5a1",
    "credits_used": 1,
    "product": "displays"
  }
}

Pending live E2E verification: the exact response field names, the total field, and whether display_id appears on every result or only on final_measured assets have not yet been confirmed against the live API. This page will be updated once an E2E test exercises the endpoint.

What to read next

• Displays On Demand - overview and endpoint map.
• Asset lifecycle - create, list, refine, archive recipes.
• Purchase flow and credits - the credit model.
• Displays API reference - auto-built endpoint documentation.