Binding manifest

Every key of a binding.yaml, block by block, and which keys it shares with a process adapter's manifest, generated from spec/binding-schema.json

Every key spec/binding-schema.json allows in a binding.yaml, block by block, with the keys it shares with a process adapter's manifest.json (spec/schemas/manifest.schema.json). A dotted key sits inside the key before the dot, and an upper-case part such as FIELD stands for a name you choose.

A tier-1 adapter: a YAML document the runner's generic HTTP engine interprets deterministically (SPEC.md §10a, ADR-022). Validate after decoding the YAML to JSON. Deliberately ~8 primitives; the moment a binding needs logic it graduates to a process adapter — no expression language may ever grow in here. Templating (ADR-057, M31): a leaf is a Liquid object in gtme's one bounded dialect over 'record.<field>', 'config.<key>', 'variables.<name>' and 'session' — objects only, no block tags, the fixed filter allowlist (SPEC.md §10 item 10; 'default' is the fallback: '{{ record.linkedin_url | default: record.linkedin_internal_url }}'). A leaf that is exactly one placeholder substitutes the typed value; leaves resolving to empty/null are omitted from the request (omitempty). The retired '{{a|b}}' alternatives fail verify naming the rewrite. In a deliver body, an object may carry the key '$variables': true — the resolved variables: mapping (minus any variable referenced individually elsewhere in the body) is spliced into that object. The engine pre-fills config defaults declared in config_schema.

Manifest surface

The keys that say what the binding is. Process manifest says whether a process adapter's manifest has the same key; where the binding schema gives no description, the process manifest's is shown.

Process manifest keys a binding does not take

Auth

The auth block, optional.

Request

The request block, required. Templating draws only from step config, the record's canonical fields, resolved variables, and the session id — no expressions, no computation.

Pagination

The pagination block, optional.

Extract

The extract block, optional.

Errors

The errors block, optional. HTTP status (or status class like '4xx') -> one rule, or an ordered list of rules (SPEC.md §10a Error verdicts, ADR-065). The first rule whose match occurs in the response body, or that has no match, applies; a rule after one with no match can never apply and is refused. A status with no applicable rule follows the engine's default classification (SPEC.md §8 exit-code classes). fail_run stops the step; fail_record and retry fail the record; skip counts it skipped.

Cost

The cost block, optional.

Retry

The retry block, optional.

Session

The session block, optional. Optional pagination-consistency session: a UUID minted per run and passed through on every request.

Example

From spec/bindings/apollo-search/binding.yaml:

# apollo/search — THE apollo/search adapter (built into gtme until ADR-059),
# rewritten for the masked API surface (ADR-043). Apollo withdrew value
# fields from API search 2026-08-30: `mixed_people/search` 422s for API
# callers, and its replacement `mixed_people/api_search` returns masked rows
# (no email, no linkedin, `has_*` booleans, obfuscated last name). This
# binding is honest about that: it provides the masked surface at $0, and
# the revealed person is apollo/enrich's job — the canonical composition
# filters on these free fields first and reveals only past the filter.
#
# Identity (§4): a masked row carries no email, no linkedin and no company
# domain, so identity derives from the name-hash tier — which needs a first
# AND last name. `last_name` therefore carries Apollo's own obfuscated form
# (e.g. "D.") rather than being dropped: it keys the record, `gtme plan`
# notes the weak tier, and apollo/enrich supersedes it with the real value
# on reveal. Distinct people who share a first name and an obfuscated
# initial in one pull would collide on this tier — reveal early if that
# matters.
#
# Endpoint: POST https://api.apollo.io/api/v1/mixed_people/api_search
# Auth:     X-Api-Key header
# Docs:     https://docs.apollo.io/reference/people-api-search

id: apollo/search
version: 2
role: source
entity_type: person

provides:
  type: object
  additionalProperties: false
  properties:
    first_name: { type: string }
    last_name: { type: string }
    title: { type: string }
    company_name: { type: string }
    apollo.id: { type: string }
    apollo.has_email: { type: boolean }

config_schema:
  type: object
  additionalProperties: false
  anyOf:
    - required: [query]
    - required: [titles]
    - required: [seniorities]
    - required: [locations]
    - required: [domains]
  properties:
    query:
      type: string
      description: Free-text search, such as "vp marketing, saas, 50-200 employees"
    limit:
      type: integer
      minimum: 1
      description: Stop after this many people
    titles:
      type: array
      items: { type: string }
      description: person_titles
    seniorities:
      type: array
      items: { type: string }
      description: person_seniorities
    locations:
      type: array
      items: { type: string }
      description: organization_locations
    employee_ranges:
      type: array
      items: { type: string }
      description: organization_num_employees_ranges, such as "50,200"
    domains:
      type: array
      items: { type: string }
      description: q_organization_domains
    per_page:
      type: integer
      minimum: 1
      maximum: 100
      default: 25
    base_url:
      type: string
      default: "https://api.apollo.io"
      description: Override the API host (testing)

credentials: [APOLLO_API_KEY]
cost_estimate_usd: 0

auth:
  type: header
  name: X-Api-Key
  env: APOLLO_API_KEY

request:
  method: POST
  url: "{{config.base_url}}/api/v1/mixed_people/api_search"
  headers:
    Cache-Control: no-cache
  body:
    q_keywords: "{{config.query}}"
    person_titles: "{{config.titles}}"
    person_seniorities: "{{config.seniorities}}"
    organization_locations: "{{config.locations}}"
    organization_num_employees_ranges: "{{config.employee_ranges}}"
    q_organization_domains_list: "{{config.domains}}"

pagination:
  strategy: page
  param: page
  in: body
  size_param: per_page
  page_size: "{{config.per_page}}"
  termination:
    empty_records: true
    short_page: true

extract:
  records: people
  fields:
    apollo.id: id
    first_name: first_name
    last_name: last_name_obfuscated
    title: title
    company_name: organization.name
    apollo.has_email: has_email

cost:
  per: record
  amount_usd: 0

See also

• Adapter catalog
• Wire protocol
• Conformance kit and fixtures
• gtme adapters

Used in

• Add a vendor: Every key a binding.yaml can declare, including the transform rules
• Two adapter tiers: Every key a binding.yaml can declare