openapi: '3.1.0' info: title: Motionworks API - OOH Displays (Vector Tile Delivery) version: 1.0.0 description: > OOH Displays vector-tile delivery surface for Motionworks Displays data (ADR-027 PR-T1.8) — Mapbox Vector Tile (`.mvt`) delivery for the Motionworks OOH inventory face POINT layer. Drop the face point layer directly into MapLibre, Mapbox GL JS, or any TileJSON-compatible map. Mint a grant scoped to your origins, fetch the TileJSON capability URL, and point your map at it; tiles render in seconds. Tile traffic is metered at **1 credit per 1,000 tiles served** (op id `displays_tiles_fetch`). The grant + TileJSON control-plane endpoints are free. The feature key `oohdisplays.displays.face_point_tiles` is matrix-licensed (authenticated + PAYG default-allow; anon default-deny), so signed-in + PAYG callers can mint grants without an explicit `org_feature_grants` row. Credit-pack-only orgs receive `403 TILE_GRANTS_REQUIRE_METERED` until the metered Stripe rail is enabled. ### Workflow 1. **Mint a grant** (`POST /v2/displays/tiles/grants`) — server-side, authenticated with your Supabase JWT or `X-API-Key`. Specify `allowed_origins` for the browser sites that will render the map. 2. **Use the returned TileJSON URL** (`GET /v2/displays/tiles/grants/{id}/tilejson`) — this is a **capability URL**: the opaque `grant_id` in the path IS the credential. Drop it straight into MapLibre's vector source. 3. **MapLibre fetches the tiles for you** (`GET /v2/displays/tiles/{layer}/{z}/{x}/{y}.mvt?token=…`) — extracts the `?token=` JWT from TileJSON and appends it on every tile request. You will not call the `.mvt` endpoint directly. One layer ships today (static, zoom 0..14): `faces` (OOH inventory face points). Designed per [ADR-027 — Vector Tile Endpoints](https://github.com/InterMx/api-mworks-com/blob/main/docs/architecture/27-vector-tile-endpoints.md). contact: name: Motionworks AI url: https://mworks.com email: api@mworks.com servers: - url: https://api.mworks.com/v2 description: Production security: - apiKey: [] tags: - name: Tile Discovery description: Public capability catalog — list the tilesets the Displays product publishes (slugs, titles, zoom ranges, layer schemas). No auth required; free. - name: Tile Grants description: Mint, list, read, and revoke Displays vector-tile delivery grants. JWT or X-API-Key authenticated. - name: Tile TileJSON description: TileJSON capability URL — the discovery endpoint MapLibre calls to learn where to fetch tiles. - name: Tile Data description: Binary Mapbox Vector Tile bytes. Called by MapLibre/Mapbox GL on your behalf; you will not call this directly in normal use. components: securitySchemes: apiKey: type: apiKey name: X-API-Key in: header bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Supabase user JWT (`Authorization: Bearer `). Used by portal/account flows that mint and manage tile grants for a logged-in user's 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 TileMeta: type: object x-motionworks-status: production properties: request_id: type: string credits_used: type: integer enum: [0] product: type: string enum: [displays] 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: MVT-side layer id (matches the layer name CARTO emits inside the tile bytes — often `default` for single-layer tilesets, NOT the URL slug). description: type: string minzoom: type: integer minimum: 0 maxzoom: type: integer minimum: 0 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 maxzoom: type: integer minimum: 0 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' TilesetCatalogResponse: type: object x-motionworks-status: production required: [tilesets] properties: tilesets: type: array items: $ref: '#/components/schemas/TilesetCatalogEntry' 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] description: > Tileset slugs to include in this grant. Displays publishes one layer today, gated by the bundled `oohdisplays.displays.face_point_tiles` entitlement: `faces` (OOH inventory face points). Any other slug is rejected with 403 `TILE_LAYER_NOT_LICENSED`. allowed_origins: type: array items: type: string description: > Browser `Origin` allowlist for `/tilejson` and `.mvt` fetches. Use the explicit string `"null"` to allow requests that omit `Origin` (e.g. `curl`, server-side rendering). 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 product: type: string enum: [displays] name: type: string tilesets: type: array items: type: string enum: [faces] allowed_origins: type: array items: type: string expires_at: type: string format: date-time revoked_at: type: string format: date-time nullable: true created_at: type: string format: date-time created_by: type: string format: uuid nullable: true usage_30d: type: integer description: 30-day tile fetch count (placeholder — outbox aggregate lands in a follow-up; reported as 0 today). 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 allowed_origins: type: array items: type: string expires_at: type: string format: date-time created_at: type: string format: date-time 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 name: type: string tiles: type: array items: type: string format: uri minzoom: type: integer maxzoom: type: integer bounds: type: array items: type: number minItems: 4 maxItems: 4 attribution: type: string vector_layers: type: array items: type: object x-mw: type: object description: Motionworks-specific tile-token refresh metadata. properties: grant_id: type: string product: type: string enum: [displays] 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). paths: # ─── Tile Discovery (public capability catalog) ────────────────────── /displays/tiles/tilesets: get: tags: [Tile Discovery] operationId: listDisplaysTilesets summary: List the tilesets Displays publishes description: > Returns the customer-facing tile catalog for the Displays product — every layer slug, human-readable title, zoom range, geographic bounds, and TileJSON `vector_layers[]` schema. Use this to pick a `tilesets[]` slug before minting a grant via `POST /v2/displays/tiles/grants`, or to render a "supported layers" UI without hardcoding the catalog client-side. Public — no auth header required. Free — 0 credits. Response carries `Cache-Control: private, no-store` (matches the router's global egress policy on `api2.mworks.com`, which overwrites upstream cache headers — same posture as `/v2/places/autocomplete`). 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 new tile-delivery grant scoped to the caller's org and returns a capability `tile_json_url`. Drop the URL into MapLibre or Mapbox GL JS to start rendering. Free — control-plane endpoint, 0 credits. Auth: Supabase JWT (`Authorization: Bearer `) OR org-scoped API key (`X-API-Key: mw_…`). Anonymous callers cannot mint grants. The caller's organization must be metered AND licensed for Displays vector tiles (`oohdisplays.displays.face_point_tiles` — matrix-licensed for authenticated + PAYG callers). Credit-pack-only orgs receive `403 TILE_GRANTS_REQUIRE_METERED`. 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: > One of three cases: * `FEATURE_NOT_LICENSED` — caller's org is not licensed for `oohdisplays.displays.face_point_tiles`. Contact sales for an explicit grant. * `TILE_GRANTS_REQUIRE_METERED` — caller's org has no metered Stripe billing rail (credit-pack only). Contact sales to enable Displays vector-tile delivery. * `TILE_LAYER_NOT_LICENSED` — one or more `tilesets[]` entries name a layer Displays does not publish. content: application/json: schema: $ref: '#/components/schemas/Error' get: tags: [Tile Grants] operationId: listDisplaysTileGrants summary: List active grants for the caller's org description: > Returns the caller-org's Displays tile grants, most recent first. Free — control-plane endpoint, 0 credits. 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 a single grant by ULID, scoped to the caller's org. Free — control-plane endpoint, 0 credits. 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: Grant not found, expired, or belongs to a different org. 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: > Marks the grant revoked. The 24-hour tile-token JWTs already minted by `/tilejson` will continue to validate until they expire; for an instant cutoff in production, rotate `MW_VECTOR_TILE_JWT_KEY` (operator runbook). Free — 0 credits. 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: Grant not found. content: application/json: schema: $ref: '#/components/schemas/Error' /displays/tiles/grants/{id}/tilejson: get: tags: [Tile TileJSON] operationId: getDisplaysTileJson summary: 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 The TileJSON URL returned by `POST /v2/displays/tiles/grants` is a **capability URL** — it carries the credentials needed to fetch tiles embedded in the URL itself. Treat it like an AWS S3 presigned URL: anyone who has the URL can render your map until the underlying grant expires or is revoked. This is by design — your front-end JavaScript can pass it straight to MapLibre without a separate auth header. Two safety nets are built in: the grant's `allowed_origins` list pins which sites can fetch tiles (Origin-enforced), and `POST /v2/displays/tiles/grants/{id}/revoke` kills the grant. Free — control-plane endpoint, 0 credits. 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: > Origin not in the grant's `allowed_origins`, or the org is not licensed/metered for Displays vector tiles (`FEATURE_NOT_LICENSED` / `TILE_GRANTS_REQUIRE_METERED` / `ORIGIN_NOT_ALLOWED`). 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: > **You will not call this endpoint directly in normal use.** MapLibre, Mapbox GL JS, and deck.gl's `MVTLayer` extract the `?token=` JWT from the TileJSON manifest above and append it to every tile request on your behalf. Returns a Mapbox Vector Tile (binary protobuf). Auth is the `?token=` query parameter ONLY — header form is rejected by design (capability semantics). Metered at **1 credit per 1,000 tiles served** (op id `displays_tiles_fetch`, meter divisor 1000). Response may be gzip-encoded — clients MUST honor `Content-Encoding`. Empty tiles (z/x/y with no features) return HTTP 204. See [ADR-027](https://github.com/InterMx/api-mworks-com/blob/main/docs/architecture/27-vector-tile-endpoints.md) for the full tile-delivery contract. 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] description: > Tileset slug. Displays publishes one layer: `faces` (OOH inventory face points). - name: z in: path required: true schema: type: integer minimum: 0 maximum: 14 description: Tile zoom level. Displays layers are valid for z in [0, 14]. - 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: Tileset snapshot date. 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 out of range (z must be in [0, 14] for Displays layers) 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) — missing, invalid, or expired `?token=` tile-token JWT. * `layer_not_in_tilesets` — token does not authorize the requested layer. * `grant_revoked` — the backing grant has been revoked. * `tile_grant_exhausted` — the org's credit wallet is exhausted (billing signal, not auth). content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Request `Origin` is not in the grant's `allowed_origins` (`error.code: ORIGIN_NOT_ALLOWED`). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Unknown layer slug, or the backing grant was not found. content: application/json: schema: $ref: '#/components/schemas/Error'