{"openapi":"3.1.0","info":{"title":"Telltale Public API","description":"Ingest orders and customers from any custom or headless platform. Auth: Authorization: Bearer tk_live_… (ingest key from Resources → API Docs). Docs: https://app.telltale.pro/help/api","version":"v0"},"servers":[{"url":"https://api.telltale.pro"}],"paths":{"/pixel/collect":{"post":{"tags":["pixel"],"summary":"Collect","description":"Ingest a batch of on-site events. Returns 204 on accept (or quiet\naccept-and-drop under load); 4xx on auth/validation failure. Runs in the\nthreadpool (sync def) so the sync key lookup + buffer push don't block the\nloop. The body is validated by FastAPI against the strict `PixelCollectRequest`\nschema (closed event_type enum, extra='forbid') BEFORE this body runs.","operationId":"collect_pixel_collect_post","parameters":[{"name":"origin","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PixelCollectRequest"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/webhooks/custom-api":{"post":{"tags":["custom-api"],"summary":"Custom Api Webhook","operationId":"custom_api_webhook_webhooks_custom_api_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Custom Api Webhook Webhooks Custom Api Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":""}},"/ingest/health":{"get":{"tags":["ingest"],"summary":"Ingest Health","description":"Verify an ingest key. Returns the resolved account + connected providers\nso a client can confirm setup before pushing data.","operationId":"ingest_health_ingest_health_get","parameters":[{"name":"account_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-telltale-account-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Telltale-Account-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ingest Health Ingest Health Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ingestKey":[]}]}},"/ingest/orders":{"post":{"tags":["ingest"],"summary":"Ingest Orders","description":"Batch upsert orders (and the customer identity carried on each order).","operationId":"ingest_orders_ingest_orders_post","parameters":[{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","description":"Validate only — report per-row errors, write nothing.","default":false,"title":"Dry Run"},"description":"Validate only — report per-row errors, write nothing."},{"name":"account_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-telltale-account-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Telltale-Account-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrdersBatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ingest Orders Ingest Orders Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ingestKey":[]}]}},"/ingest/customers":{"post":{"tags":["ingest"],"summary":"Ingest Customers","description":"Batch upsert customer identity / consent / address (no order).","operationId":"ingest_customers_ingest_customers_post","parameters":[{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","description":"Validate only — report per-row errors, write nothing.","default":false,"title":"Dry Run"},"description":"Validate only — report per-row errors, write nothing."},{"name":"account_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-telltale-account-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Telltale-Account-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomersBatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ingest Customers Ingest Customers Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ingestKey":[]}]}},"/ingest/account":{"patch":{"tags":["ingest"],"summary":"Ingest Account Settings","description":"Account-level settings a custom client owns — today just\n``store_timezone`` (IANA name).","operationId":"ingest_account_settings_ingest_account_patch","parameters":[{"name":"account_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-telltale-account-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Telltale-Account-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSettingsIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ingest Account Settings Ingest Account Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ingestKey":[]}]}},"/ingest/sync":{"post":{"tags":["ingest"],"summary":"Ingest Sync","description":"Recompute analytics after a bulk load.","operationId":"ingest_sync_ingest_sync_post","parameters":[{"name":"account_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-telltale-account-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Telltale-Account-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ingest Sync Ingest Sync Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ingestKey":[]}]}},"/ingest/sync/{task_id}":{"get":{"tags":["ingest"],"summary":"Ingest Sync Status","description":"Status of a recompute queued by POST /ingest/sync (this account only).","operationId":"ingest_sync_status_ingest_sync__task_id__get","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}},{"name":"account_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-telltale-account-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Telltale-Account-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ingest Sync Status Ingest Sync  Task Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ingestKey":[]}]}},"/ingest/batches":{"get":{"tags":["ingest"],"summary":"Ingest Batches","description":"Recent ingest activity for this account (counts + error codes, no PII).","operationId":"ingest_batches_ingest_batches_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"account_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Account Id"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"deprecated":true,"description":"Legacy tile-token auth only. Ingest keys must be sent as Authorization: Bearer."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-telltale-account-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Telltale-Account-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Ingest Batches Ingest Batches Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ingestKey":[]}]}},"/webhooks/zero-party":{"post":{"tags":["zero-party"],"summary":"Zero Party Webhook","operationId":"zero_party_webhook_webhooks_zero_party_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Zero Party Webhook Webhooks Zero Party Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":""}}},"components":{"schemas":{"AccountSettingsIn":{"properties":{"store_timezone":{"type":"string","minLength":1,"title":"Store Timezone","description":"IANA timezone of the store (e.g. 'America/Chicago'). Used as the local-clock fallback for customers whose ZIP can't place them."}},"type":"object","required":["store_timezone"],"title":"AccountSettingsIn","description":"Account-level settings a custom client owns."},"AddressIn":{"properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Street"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"},"zip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zip"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"}},"type":"object","title":"AddressIn"},"ConsentIn":{"properties":{"marketing_email":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Marketing Email"},"sms":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Sms"},"suppressed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Suppressed"},"bounced":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Bounced"}},"type":"object","title":"ConsentIn"},"CustomerIn":{"properties":{"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"address":{"anyOf":[{"$ref":"#/components/schemas/AddressIn"},{"type":"null"}]},"consent":{"anyOf":[{"$ref":"#/components/schemas/ConsentIn"},{"type":"null"}]},"source_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Label"},"subscription_status":{"anyOf":[{"type":"string","enum":["active","paused","cancelled"]},{"type":"null"}],"title":"Subscription Status","description":"active | paused | cancelled. Omit for customers who never subscribed."},"subscription_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Started At","description":"ISO-8601 (with offset) when their first subscription started."}},"additionalProperties":true,"type":"object","title":"CustomerIn"},"CustomersBatch":{"properties":{"customers":{"items":{"$ref":"#/components/schemas/CustomerIn"},"type":"array","title":"Customers"}},"type":"object","title":"CustomersBatch"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"OrderIn":{"properties":{"order_id":{"type":"string","minLength":1,"title":"Order Id","description":"Your unique order id."},"customer_id":{"type":"string","minLength":1,"title":"Customer Id","description":"Your unique customer id."},"order_date":{"type":"string","title":"Order Date","description":"ISO-8601 timestamp of the order."},"order_amount":{"type":"number","title":"Order Amount","description":"Order total in major units (e.g. dollars)."},"product_name":{"type":"string","minLength":1,"title":"Product Name","description":"Primary product on the order."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"customer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Customer Name"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Acquisition/channel label."},"order_channel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Channel","description":"e.g. 'email', 'web', 'pos'."},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"ISO-4217; defaults USD."},"shipping_city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipping City"},"shipping_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipping State"},"shipping_zip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipping Zip"},"refunded_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Refunded Amount"},"discount_total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Discount Total"},"discount_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Discount Pct"},"discount_codes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Discount Codes"},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancelled At"}},"additionalProperties":true,"type":"object","required":["order_id","customer_id","order_date","order_amount","product_name"],"title":"OrderIn"},"OrdersBatch":{"properties":{"orders":{"items":{"$ref":"#/components/schemas/OrderIn"},"type":"array","title":"Orders"}},"type":"object","title":"OrdersBatch"},"PixelCollectRequest":{"properties":{"key":{"type":"string","maxLength":128,"minLength":3,"title":"Key"},"events":{"items":{"$ref":"#/components/schemas/PixelEvent"},"type":"array","maxItems":50,"minItems":1,"title":"Events"}},"additionalProperties":false,"type":"object","required":["key","events"],"title":"PixelCollectRequest"},"PixelEvent":{"properties":{"event_id":{"type":"string","format":"uuid","title":"Event Id"},"event_type":{"$ref":"#/components/schemas/WebEventType"},"occurred_at":{"type":"string","format":"date-time","title":"Occurred At"},"anonymous_id":{"type":"string","maxLength":128,"minLength":1,"title":"Anonymous Id"},"session_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Session Id"},"url_path":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Url Path"},"page_title":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Page Title"},"referrer_host":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Referrer Host"},"product_external_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Product External Id"},"collection":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Collection"},"search":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Search"},"price_cents":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Price Cents"},"dwell_ms":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Dwell Ms"},"consent_state":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Consent State"},"raw_props":{"additionalProperties":true,"type":"object","title":"Raw Props"}},"additionalProperties":false,"type":"object","required":["event_id","event_type","occurred_at","anonymous_id"],"title":"PixelEvent","description":"One on-site event. Strict: unknown fields are rejected (no smuggling)."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebEventType":{"type":"string","enum":["page_view","product_view","search","add_to_cart","checkout_started"],"title":"WebEventType"}},"securitySchemes":{"ingestKey":{"type":"http","scheme":"bearer","bearerFormat":"tk_live_…","description":"Ingest key minted under Resources → API Docs (owner/admin)."}}}}