Publish a time series

Use this workflow for a series whose observations are stored by QuickLookup in ClickHouse. The same definition can be private to your account or shared under a published access policy.

Before you start

You need:

• an editor grant to create drafts and a publisher grant to publish;
• an owner, source, publisher, and publication entity;
• a unit, at least one metric, and any dimensions used by the rows;
• a series group; and
• a source binding with Mode = Stored.

Search for these records before creating them. See Catalogue definitions.

Create the definition in the admin

1. Open Provision → Time-series families. Reuse the matching family, or create and publish one when the measurement meaning is genuinely new.
2. Use Add compatible variant on the family. QuickLookup pre-fills the common subject, metrics, dimensions, units, category, time semantics, and family contract.
3. In Definition, enter the variant label, stable key, canonical URL, granularity, value type, and completeness.
4. Choose the sharing policy in Access. Local keeps the service private to the active account. Choose a broader value only when it matches the intended grant model.
5. Select the source, publisher, publication, and stored source binding.
6. Confirm the inherited metrics and dimensions. The response key on each assignment is the key clients will query.
7. Save, clear every Ready to publish? blocker, and use Preview to switch among the authorized variants.
8. Publish and wait for the ClickHouse publication to become delivered.

The signed-in account is assigned by the session. There is no account-routing field to enter or override.

Create the definition through the API

Creating definitions through the API needs the catalogue editor role, so these operations are not in the public reference; the admin does the same work. For a key that holds the role, GET https://quicklookup.com/api/v1/authoring returns the step-by-step guide.

Execute GET /v1/authoring with a bearer token. Its quickStart contains matched UUIDv5 identities and request bodies for the supporting definitions, stored binding, series, publication, and first observation. Use those values as a working baseline; replace the labels, canonical URLs, contract fields, and access policy with your own.

The write sequence is:

supporting definitions → stored binding → PUT series group → POST series-group publish
→ PUT concrete time-series variant → POST variant publish

Publish the family again after changing its source preferences; this activates the new ranking without republishing its variants: POST /v1/provision/series-groups/{familyGid}/publish. Every update and publish includes the current expectedDraftVersion. A stale version returns 409.

Add observations

Only a delivered series with a stored binding accepts ingestion.

POST https://quicklookup.com/api/v1/series/{seriesGid}/observations
Authorization: Bearer <your API key>
Content-Type: application/json

{
  "items": [
    {
      "entityGid": "the observed entity GID",
      "timestamp": "2030-01-01T00:00:00Z",
      "metrics": {"value": 1},
      "dimensions": {}
    }
  ]
}

QuickLookup supplies the service identity, accepted revision, provenance, access policy, and account routing from the published definition and token. The request supplies only observation data.

The endpoint rejects undeclared keys, wrong value types, non-finite metrics, missing required dimensions, oversized batches, unpublished series, and non-stored bindings before writing to ClickHouse. A successful response reports the accepted row count.

Verify the service

1. Find it once with GET /v1/catalog/series-families.
2. Follow variantsUrl, or accept recommendedVariant. Explicit source, publication, quality, resolution, from, and to selectors are hard constraints.
3. Inspect the chosen concrete variant and send the example to its queryUrl.
4. For shared access, repeat discovery with an entitled consumer token and a token that has no grant. The second request must not disclose the service.

Use the integrated query workbench for these checks.