Service contract

Documentation for the
delivery layer.

Hivedeck serves tasteful ad tiles to publisher apps over plain HTTP. The integration model is intentionally small: identify the publisher, request a surface, render the tiles. The official Ruby gem pulls tiles on a cadence and serves them from a local cache with zero network calls on the render path.

View Endpoint → Ruby Gem Integration

01

Get a key

Provision a publisher key from the dashboard.

02

Pull & cache

Refresh tiles on a cadence into a local store.

03

Render tiles

Read from cache and display in your own UI.

Overview

Getting started

The current integration surface is intentionally narrow so consumer apps can adopt it quickly while the network evolves.

What Hivedeck returns

Hivedeck responds with a JSON array of ad tiles. Each tile carries the fields needed to render a small, tasteful unit: overline, headline, body, cta, image_url, target_url, and optional tracking beacons. Only headline and target_url are guaranteed. The host app keeps full control over layout and styling.

Security

Authentication

Publisher keys are the current request credential. Keep them in environment-driven configuration.

Publisher key

Your publisher key is available from the publisher dashboard. It should be treated as a secret and supplied with every request via the publisher_key query parameter.

requestHTTP

GET /api/v1/ad?publisher_key=YOUR_KEY&surface=site&slot=rail&count=3

Endpoint

Get ads

Retrieve ad tiles for a specific publisher surface and slot.

GET https://hivedeck.space/api/v1/ad

            ParameterTypeDescription
          

publisher_keyRequired string The publisher's API key.

surfaceRequired string One of site, brief, ticker.

slotOptional string One of rail, inline, top, mid, bottom. Omit for ticker, which returns a stack.

countOptional integer Number of tiles to return. Default 3.

200 OKJSON

[
  {
    "id": 6,
    "surface": "site",
    "slot": "rail",
    "kind": "house",
    "format": "standard",
    "mode": "single",
    "overline": "PROMOTED",
    "headline": "THE 50KFT BRIEF",
    "body": "Geopolitical intelligence, distilled.",
    "cta": "Subscribe free",
    "target_url": "/",
    "image_url": null,
    "beacons": { "impression_url": "...", "click_url": "..." }
  }
]

            FieldNotes
          

overline Small label above the headline. Defaults to "Sponsored".

kind One of sponsor, house, partner, internal.

format One of standard, feature, image, stack.

mode One of single, stack.

beacons Optional tracking pixels (impression_url, click_url).

401 UnauthorizedJSON

{
  "error": "Invalid publisher key"
}

422 UnprocessableJSON

{
  "error": "Unknown surface"
}

Implementation

Code examples

Call the endpoint directly with plain HTTP, or — recommended for Ruby apps — use the gem, which pulls and caches for you.

curlShell

curl "https://hivedeck.space/api/v1/ad?publisher_key=YOUR_KEY&surface=site&slot=rail&count=3"

client.jsJavaScript

const KEY = "your_publisher_key";

fetch(`https://hivedeck.space/api/v1/ad?publisher_key=${KEY}&surface=site&slot=rail&count=3`)
  .then(res => res.json())
  .then(tiles => {
    console.log(tiles);
  });

render.rbRuby

# Local-only read from the gem's cache — no network call.
tile = Hivedeck.cached(surface: :site, slot: :rail) || HOUSE
stack = Hivedeck.cached_all(surface: :ticker)

Integration

Ruby gem — pull and cache

The official hivedeck gem pulls tiles on a cadence into a local store and serves them with zero network calls on the render path. Fetching happens off the render path; rendering only reads the cache.

GemfileRuby

gem "hivedeck", git: "https://github.com/dmcycloid/hivedeck.git", tag: "v0.1.4"

config/initializers/hivedeck.rbRuby

Hivedeck.configure do |c|
  c.base_url      = "https://hivedeck.space"
  c.publisher_key = ENV["HIVEDECK_PUBLISHER_KEY"]
end

refresh + renderRuby

# Pull — off the render path (scheduler ~twice hourly + an admin button).
Hivedeck.refresh

# Render — local-only, reads the cache.
tile = Hivedeck.cached(surface: :site, slot: :rail) || HOUSE
stack = Hivedeck.cached_all(surface: :ticker)

Operations

Caching and support

Hivedeck uses a pull-and-cache model so the render path stays fast and resilient.

Pull and cache

Hivedeck.refresh populates a local store on a cadence. The render path reads only from that cache via Hivedeck.cached, so no network call happens while serving a page. When the cache is empty, fall back to a house tile.

Need support?

Manage publishers, surfaces, flights, and tiles from the dashboard. This page describes the delivery contract; operational controls live in the service.