Skip to main content

Catalog

Discover available signals, deliverable types, serializer formats, and connector types from the delivery registry. Use the catalog to build valid bindings.

The catalog endpoints expose the four delivery registries. Use them to discover which event types, deliverable resolvers, serializer formats, and connectors are available before creating bindings.

Walk the catalog top-down to build valid binding configurations: start with signals to pick an event type, then check which deliverables are compatible with that signal, which serializers support the deliverable shape, and which connectors accept the serializer format. This ensures every combination passes the compatibility triangle.

The catalog is a read-only snapshot of the four in-process registries — the same objects the delivery engine consults at runtime, so what the catalog reports is by construction what a binding create will accept. Entries carry human-readable label and description fields intended for configuration UIs; the type and format identifiers are the values you actually pass when creating a binding.

Because the registries are code-defined rather than tenant-configured, the catalog is identical for every workspace and changes only with platform releases. It is safe to cache per process lifetime; re-fetch when a binding create starts rejecting a combination that used to validate, which indicates the platform registry changed underneath you.

All four catalog routes require only the read scope, take no parameters, and are cheap — they read in-memory registries, not the database. Wire them into your binding-configuration UI as live dropdowns rather than hardcoding event types or serializer formats.
GET/v1/delivery/catalog/signals

curl

curl -s https://api.talonic.com/v1/delivery/catalog/signals \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

typesarrayArray of all known event type strings.
itemsarrayArray of signal objects with label and description.
items[].typestringEvent type identifier (e.g. `document.extracted`).
items[].labelstringHuman-readable label for the event type.
items[].descriptionstringDescription of when this event fires.

Response

{
  "types": ["document.extracted", "run.dataspace.completed", "record.approved"],
  "items": [
    { "type": "document.extracted", "label": "Document extracted", "description": "Fired when document extraction finishes." },
    { "type": "run.dataspace.completed", "label": "Dataspace run completed", "description": "Fired when a structuring run completes." },
    { "type": "record.approved", "label": "Record approved", "description": "Fired when a record passes review." }
  ]
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.
GET/v1/delivery/catalog/deliverables

Response

Response fields

[].typestringDeliverable resolver identifier (e.g. `document_capture`).
[].compatible_signalsarrayEvent types that can route to this resolver.
[].shapeobjectDeliverable shape descriptor with `kind` (`record`, `blob`, `graph`, `envelope`).
[].labelstringHuman-readable label.
[].descriptionstringDescription of what this deliverable resolves.

Response

[
  {
    "type": "document_capture",
    "compatible_signals": ["document.extracted"],
    "shape": { "kind": "record", "is_collection": false, "columns": [] },
    "label": "Document capture",
    "description": "Raw extracted fields for a single document."
  },
  {
    "type": "run_outcomes",
    "compatible_signals": ["run.dataspace.completed"],
    "shape": { "kind": "record", "is_collection": true, "columns": [] },
    "label": "Run outcomes",
    "description": "All structured rows from a completed run."
  }
]

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.
GET/v1/delivery/catalog/serializers

Response

Response fields

[].formatstringSerializer format identifier (e.g. `json`, `csv`, `xlsx`).
[].supports_kindsarrayArray of `DeliverableShape.kind` values this serializer can handle (`record`, `blob`, `graph`, `envelope`).

Response

[
  { "format": "json", "supports_kinds": ["record", "envelope"] },
  { "format": "csv", "supports_kinds": ["record"] },
  { "format": "xlsx", "supports_kinds": ["record"] },
  { "format": "raw", "supports_kinds": ["blob"] }
]

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.
GET/v1/delivery/catalog/connectors

Response

Response fields

[].typestringConnector type (e.g. `webhook`, `s3`, `google_drive`).
[].capabilitiesobjectConnector capabilities object.
[].capabilities.supported_serializersarraySerializer formats this connector accepts.
[].capabilities.supported_deliverable_kindsarrayDeliverable shape kinds supported.
[].capabilities.auth_typesarraySupported authentication types.
[].capabilities.delivery_semanticsstring`record` (per-event) or `file` (file-drop).
[].capabilities.requires_oauthbooleanWhether this connector requires OAuth authorization.

Response

[
  {
    "type": "webhook",
    "capabilities": {
      "supported_serializers": ["json", "ndjson", "raw"],
      "supported_deliverable_kinds": ["envelope", "record", "blob"],
      "auth_types": ["none", "bearer", "basic", "api_key"],
      "delivery_semantics": "record"
    }
  },
  {
    "type": "s3",
    "capabilities": {
      "supported_serializers": ["json", "ndjson", "csv_file", "xlsx", "md", "txt", "raw"],
      "supported_deliverable_kinds": ["record", "blob", "envelope"],
      "auth_types": ["access_key"],
      "delivery_semantics": "file"
    }
  },
  {
    "type": "google_drive",
    "capabilities": {
      "supported_serializers": ["json", "ndjson", "csv_file", "xlsx", "md", "txt", "raw"],
      "supported_deliverable_kinds": ["record", "blob", "envelope"],
      "auth_types": ["oauth_google"],
      "delivery_semantics": "file"
    }
  }
]

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

How do I know which combinations are valid for a binding?+
Use the catalog endpoints to check compatibility. A valid binding requires: the signal event_type exists, the deliverable type lists that signal in compatible_signals, the serializer supports the deliverable shape, and the connector supports the serializer format.
What is the difference between record and file delivery semantics?+
Record semantics (webhook) deliver one event per HTTP request. File semantics (S3, SFTP, Azure Blob, Google Drive, OneDrive) write each delivery as a separate file/object, using a configurable filename template with tokens like {event_id} and {timestamp_iso}.
Are all catalog entries available for use?+
Most entries are live. A deliverable registered with an empty compatible_signals array is a stub — it appears in the catalog but cannot be used in bindings until its resolver is implemented. Everything else the catalog lists is accepted by binding creation.
Does the catalog differ per workspace or API key?+
No. The registries are code-defined, so every workspace sees the same catalog. It changes only with platform releases, which makes it safe to cache for the lifetime of your process.

Related

Create Binding
List Destinations