Ingest typed events from a custom connector. kind is either a
first-party kind (email, calendar, conversation_message, page, issue, …)
or any evidence type from GET /v1/knowledge/evidence-types (order, deal,
contact, company, product, …), whose payload is validated against that
type’s schema. A payload for a type whose update contract names one
identity field that its schema leaves optional (file, asset, video,
calendar_event) may omit it: the item’s external id becomes the identity (a
fresh id when there is none); an explicitly empty value, a missing required
identity, or a missing field of a multi-field identity, is refused with a
422. Use
conversation_message for chat messages and message exports (iMessage,
WhatsApp, assistant conversations, …). message is deprecated: it is
Slack-shaped and stores your data as Slack messages. Each item’s
timestamp is the record’s own time and dates the evidence; it defaults
to payload.timestamp, then the record’s created_at, then the ingest
clock. Connector- and per-item metadata are merged and attached to each
event under event.metadata (item wins on key conflict).
Re-process items even when their content is byte-identical to what was previously ingested for the same external_id. Without this, unchanged re-pushes are acknowledged but skipped (reported in unchanged).
external_id of each accepted item whose content was byte-identical to the previously ingested version and was therefore not re-processed. Pass force=true to override.
Payload fields the item's kind does not define, by external_id. They are kept in the stored raw copy but do not reach typed evidence or search. Empty when every field was used. For kind 'email' the evidence catalogue's names body_text and body_excerpt are accepted as body and body_snippet.
Show child attributes
Example:
{ "ext-123": ["priority_hint"] }
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Adapter","colors":{"primary":"#8765F0","light":"#8765F0","dark":"#8765F0"},"logo":{"light":"https://mintcdn.com/adapter/J3Ydy4fSe61BUDTE/logo/light.svg?fit=max\u0026auto=format\u0026n=J3Ydy4fSe61BUDTE\u0026q=85\u0026s=459bd6410eb825d264414176cd7eba07","dark":"https://mintcdn.com/adapter/J3Ydy4fSe61BUDTE/logo/dark.svg?fit=max\u0026auto=format\u0026n=J3Ydy4fSe61BUDTE\u0026q=85\u0026s=0bed0f3d3311b99106ba98e43a63d5e2"},"favicon":"https://mintcdn.com/adapter/J3Ydy4fSe61BUDTE/favicon.svg?fit=max\u0026auto=format\u0026n=J3Ydy4fSe61BUDTE\u0026q=85\u0026s=83406b22c16edb6994e5b28b146a7446","api":{"openapi":"api-reference/openapi.json","playground":{}},"background":{"color":{"light":"#F2F2F0","dark":"#171717"}},"navbar":{"links":[{"href":"mailto:support@adapter.com","label":"Support"}],"primary":{"type":"button","label":"Sign In","href":"https://mind.adapter.com"}},"footer":{"socials":{"x":"https://x.com/adapter"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"adapter","hasAudioNarration":false,"actualSubdomain":"adapter","customDomains":["docs.beta.adapter.com"],"gitSource":{"type":"github","owner":"adapter-group","repo":"adapter-platform","deployBranch":"main","contentDirectory":"apps/docs","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ae23bb95db1d64f77da812c","collectionId":"3e863929-e534-43f8-bffd-cc13d5f5a900","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ae23bb95db1d64f77da812c"},"feedback":{"thumbs":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6ae23bb95db1d64f77da812c","clientVersion":"0.0.4043","searchFilterCounts":[{"language":"default","tag":"API Reference","count":40},{"language":"default","tag":"Documentation","count":13},{"language":"default","tag":"Knowledge","count":11},{"language":"default","tag":"Triggers","count":10},{"language":"default","tag":"Core Concepts","count":7},{"language":"default","tag":"Ingestion","count":6},{"language":"default","tag":"Custom Connectors","count":5},{"language":"default","tag":"Getting Started","count":4},{"language":"default","tag":"Connectors","count":3},{"language":"default","tag":"Data","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/ingestion/ingest-typed","slug":"/api-reference/ingestion/ingest-typed","pageMetadata":{"title":"Ingest typed first-party events","openapi":"POST /v1/custom-connectors/{connector_id}/ingest/typed","description":"Ingest typed events from a custom connector. `kind` is either a\nfirst-party kind (email, calendar, conversation_message, page, issue, ...)\nor any evidence type from `GET /v1/knowledge/evidence-types` (order, deal,\ncontact, company, product, ...), whose payload is validated against that\ntype's schema. A payload for a type whose update contract names one\nidentity field that its schema leaves optional (file, asset, video,\ncalendar_event) may omit it: the item's external id becomes the identity (a\nfresh id when there is none); an explicitly empty value, a missing required\nidentity, or a missing field of a multi-field identity, is refused with a\n422. Use\n`conversation_message` for chat messages and message exports (iMessage,\nWhatsApp, assistant conversations, ...). `message` is deprecated: it is\nSlack-shaped and stores your data as Slack messages. Each item's\n`timestamp` is the record's own time and dates the evidence; it defaults\nto `payload.timestamp`, then the record's `created_at`, then the ingest\nclock. Connector- and per-item metadata are merged and attached to each\nevent under `event.metadata` (item wins on key conflict).","href":"/api-reference/ingestion/ingest-typed"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"Ingest typed events from a custom connector. \", _jsx(_components.code, {\n children: \"kind\"\n }), \" is either a\\nfirst-party kind (email, calendar, conversation_message, page, issue, …)\\nor any evidence type from \", _jsx(_components.code, {\n children: \"GET /v1/knowledge/evidence-types\"\n }), \" (order, deal,\\ncontact, company, product, …), whose payload is validated against that\\ntype’s schema. A payload for a type whose update contract names one\\nidentity field that its schema leaves optional (file, asset, video,\\ncalendar_event) may omit it: the item’s external id becomes the identity (a\\nfresh id when there is none); an explicitly empty value, a missing required\\nidentity, or a missing field of a multi-field identity, is refused with a\\n422. Use\\n\", _jsx(_components.code, {\n children: \"conversation_message\"\n }), \" for chat messages and message exports (iMessage,\\nWhatsApp, assistant conversations, …). \", _jsx(_components.code, {\n children: \"message\"\n }), \" is deprecated: it is\\nSlack-shaped and stores your data as Slack messages. Each item’s\\n\", _jsx(_components.code, {\n children: \"timestamp\"\n }), \" is the record’s own time and dates the evidence; it defaults\\nto \", _jsx(_components.code, {\n children: \"payload.timestamp\"\n }), \", then the record’s \", _jsx(_components.code, {\n children: \"created_at\"\n }), \", then the ingest\\nclock. Connector- and per-item metadata are merged and attached to each\\nevent under \", _jsx(_components.code, {\n children: \"event.metadata\"\n }), \" (item wins on key conflict).\"]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Ingest typed first-party events","openapi":"POST /v1/custom-connectors/{connector_id}/ingest/typed","description":"Ingest typed events from a custom connector. `kind` is either a\nfirst-party kind (email, calendar, conversation_message, page, issue, ...)\nor any evidence type from `GET /v1/knowledge/evidence-types` (order, deal,\ncontact, company, product, ...), whose payload is validated against that\ntype's schema. A payload for a type whose update contract names one\nidentity field that its schema leaves optional (file, asset, video,\ncalendar_event) may omit it: the item's external id becomes the identity (a\nfresh id when there is none); an explicitly empty value, a missing required\nidentity, or a missing field of a multi-field identity, is refused with a\n422. Use\n`conversation_message` for chat messages and message exports (iMessage,\nWhatsApp, assistant conversations, ...). `message` is deprecated: it is\nSlack-shaped and stores your data as Slack messages. Each item's\n`timestamp` is the record's own time and dates the evidence; it defaults\nto `payload.timestamp`, then the record's `created_at`, then the ingest\nclock. Connector- and per-item metadata are merged and attached to each\nevent under `event.metadata` (item wins on key conflict).","href":"/api-reference/ingestion/ingest-typed"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["ingestion"],"summary":"Ingest typed first-party events","description":"Ingest typed events from a custom connector. `kind` is either a\nfirst-party kind (email, calendar, conversation_message, page, issue, ...)\nor any evidence type from `GET /v1/knowledge/evidence-types` (order, deal,\ncontact, company, product, ...), whose payload is validated against that\ntype's schema. A payload for a type whose update contract names one\nidentity field that its schema leaves optional (file, asset, video,\ncalendar_event) may omit it: the item's external id becomes the identity (a\nfresh id when there is none); an explicitly empty value, a missing required\nidentity, or a missing field of a multi-field identity, is refused with a\n422. Use\n`conversation_message` for chat messages and message exports (iMessage,\nWhatsApp, assistant conversations, ...). `message` is deprecated: it is\nSlack-shaped and stores your data as Slack messages. Each item's\n`timestamp` is the record's own time and dates the evidence; it defaults\nto `payload.timestamp`, then the record's `created_at`, then the ingest\nclock. Connector- and per-item metadata are merged and attached to each\nevent under `event.metadata` (item wins on key conflict).","operationId":"ingest_typed","parameters":["aaec06bd-0a21-4a68-a9a2-4dfc37b4bd7e"],"requestBody":"861dc949-2a15-484a-aa43-6b7e9db99b14","responses":{"200":"d87008ac-23fb-4cc5-8791-305249e2bb29","402":"962d2142-ee75-4479-84d5-8e4fb3f0148f","422":"4d875151-c2fc-434d-a25b-7bbe772371bb","429":"05a100f5-a7f4-451c-a8ef-dfc1313fcbdc"},"method":"post","type":"path","servers":["b45a6dfc-eec4-42ae-a72a-9361a1098054"],"security":[],"path":"/v1/custom-connectors/{connector_id}/ingest/typed","baseUrlOptions":["http://localhost:8080"],"title":"Ingest typed first-party events","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"aaec06bd-0a21-4a68-a9a2-4dfc37b4bd7e":{"name":"connector_id","in":"path","required":true,"schema":{"type":"string","title":"Connector Id","isRequired":true,"uniqueKey":"","typeLabel":"string"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"kind":{"oneOf":[{"type":"string","title":"Kind","description":"What this item is: a first-party kind (`email`, `page`, `conversation_message`, ...) or any evidence type from `GET /v1/knowledge/evidence-types` (`order`, `deal`, `contact`, ...). Evidence-type payloads are validated against that type's schema; types with an identity in their update contract are stored under the id derived from those payload fields, which the response reports in `external_ids`.","enum":["email","calendar","message","conversation_message","page","issue","custom","asset","video"],"example":"email","isRequired":true,"uniqueKey":"\\items.items.[INDEX].kind.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"string","title":"Kind","description":"What this item is: a first-party kind (`email`, `page`, `conversation_message`, ...) or any evidence type from `GET /v1/knowledge/evidence-types` (`order`, `deal`, `contact`, ...). Evidence-type payloads are validated against that type's schema; types with an identity in their update contract are stored under the id derived from those payload fields, which the response reports in `external_ids`.","example":"email","isRequired":true,"uniqueKey":"\\items.items.[INDEX].kind.oneOf.1","typeLabel":"string"}],"isRequired":true,"uniqueKey":"\\items.items.[INDEX].kind","typeLabel":"enum\u003cstring> | string"},"external_id":{"oneOf":[{"type":"string","title":"External Id","description":"Stable external identifier. Auto-generated if omitted.","example":"ext-123","uniqueKey":"\\items.items.[INDEX].external_id.oneOf.0","typeLabel":"string"},{"type":"null","title":"External Id","description":"Stable external identifier. Auto-generated if omitted.","example":"ext-123","uniqueKey":"\\items.items.[INDEX].external_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].external_id","typeLabel":"string | null"},"timestamp":{"oneOf":[{"type":"string","title":"Timestamp","description":"Event timestamp. Defaults to now if omitted.","format":"date-time","uniqueKey":"\\items.items.[INDEX].timestamp.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","title":"Timestamp","description":"Event timestamp. Defaults to now if omitted.","uniqueKey":"\\items.items.[INDEX].timestamp.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].timestamp","typeLabel":"string\u003cdate-time> | null"},"payload":{"additionalProperties":true,"type":"object","title":"Payload","description":"Fields matching the first-party type (e.g. sender/subject for kind='email').","uniqueKey":"\\items.items.[INDEX].payload","typeLabel":"Payload · object"},"metadata":{"oneOf":[{"type":"object","title":"Metadata","description":"Per-item key/value metadata merged with the connector's metadata (item wins on key conflict). String values only. Lands on `event.metadata` and is visible to downstream subscribers and triggers.","example":{"batch":"2026-06-01","env":"staging"},"additionalProperties":{"type":"string","uniqueKey":"\\items.items.[INDEX].metadata.oneOf.0.additionalProperties","typeLabel":"string"},"uniqueKey":"\\items.items.[INDEX].metadata.oneOf.0","typeLabel":"Metadata · object"},{"type":"null","title":"Metadata","description":"Per-item key/value metadata merged with the connector's metadata (item wins on key conflict). String values only. Lands on `event.metadata` and is visible to downstream subscribers and triggers.","example":{"batch":"2026-06-01","env":"staging"},"uniqueKey":"\\items.items.[INDEX].metadata.oneOf.1","typeLabel":"null"}],"uniqueKey":"\\items.items.[INDEX].metadata","typeLabel":"Metadata · object | null"}},"type":"object","required":["kind"],"title":"TypedIngestItem","uniqueKey":"\\items.items.[INDEX]","typeLabel":"TypedIngestItem · object"},"type":"array","maxItems":500,"minItems":1,"title":"Items","description":"Events to ingest, at most 500 per request. Chunk larger loads into multiple requests.","isRequired":true,"uniqueKey":"\\items","typeLabel":"TypedIngestItem · object[]"},"force":{"type":"boolean","title":"Force","description":"Re-process items even when their content is byte-identical to what was previously ingested for the same external_id. Without this, unchanged re-pushes are acknowledged but skipped (reported in `unchanged`).","default":false,"uniqueKey":"force","typeLabel":"boolean"}},"type":"object","required":["items"],"title":"TypedIngestRequest","uniqueKey":"","typeLabel":"TypedIngestRequest · object"},"examples":{"Example":{"title":"Example","value":{"items":[{"kind":"email","external_id":"ext-123","timestamp":"2023-11-07T05:31:56Z","payload":{},"metadata":{"batch":"2026-06-01","env":"staging"}}],"force":false}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"d87008ac-23fb-4cc5-8791-305249e2bb29":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","title":"Status","description":"Always 'accepted' (a fully-rejected ingest returns 402).","examples":["accepted"],"isRequired":true,"uniqueKey":"status","typeLabel":"string"},"events":{"type":"integer","title":"Events","description":"Number of events accepted.","examples":[1],"isRequired":true,"uniqueKey":"events","typeLabel":"integer"},"external_ids":{"items":{"type":"string","uniqueKey":"external_ids.items.[INDEX]","typeLabel":"string"},"type":"array","title":"External Ids","description":"external_id of each accepted event, in submission order. Useful for callers that want to look up the resulting canonical doc.","examples":[["ext-123"]],"uniqueKey":"external_ids","typeLabel":"string[]"},"rejected":{"items":{"properties":{"external_id":{"type":"string","title":"External Id","description":"external_id of the rejected item.","examples":["ext-123"],"isRequired":true,"uniqueKey":"rejected.items.[INDEX].external_id","typeLabel":"string"},"resource":{"type":"string","title":"Resource","description":"Which cap was hit: 'documents' (the object limit) or 'doc_size'.","examples":["documents"],"isRequired":true,"uniqueKey":"rejected.items.[INDEX].resource","typeLabel":"string"},"reason":{"type":"string","title":"Reason","description":"Machine-readable rejection reason.","default":"quota_exceeded","examples":["quota_exceeded"],"uniqueKey":"rejected.items.[INDEX].reason","typeLabel":"string"}},"type":"object","required":["external_id","resource"],"title":"RejectedItem","description":"An item refused at ingest admission because a tier quota was exceeded — appears\nin a partial-accept batch response (some items admitted, some over the cap). A\n*fully* rejected ingest instead returns 402 (see QuotaExceededError). Only\npopulated when quota enforcement is on (monitor mode admits everything).","uniqueKey":"rejected.items.[INDEX]","typeLabel":"RejectedItem · object"},"type":"array","title":"Rejected","description":"Items refused at admission on a partial-accept (some over a tier quota). Empty on full accept; a fully-rejected ingest returns 402 instead.","uniqueKey":"rejected","typeLabel":"RejectedItem · object[]"},"unchanged":{"items":{"type":"string","uniqueKey":"unchanged.items.[INDEX]","typeLabel":"string"},"type":"array","title":"Unchanged","description":"external_id of each accepted item whose content was byte-identical to the previously ingested version and was therefore not re-processed. Pass force=true to override.","uniqueKey":"unchanged","typeLabel":"string[]"},"ignored_fields":{"additionalProperties":{"items":{"type":"string","uniqueKey":"ignored_fields.additionalProperties.items.[INDEX]","typeLabel":"string"},"type":"array","uniqueKey":"ignored_fields.additionalProperties","typeLabel":"string[]"},"type":"object","title":"Ignored Fields","description":"Payload fields the item's kind does not define, by external_id. They are kept in the stored raw copy but do not reach typed evidence or search. Empty when every field was used. For kind 'email' the evidence catalogue's names body_text and body_excerpt are accepted as body and body_snippet.","examples":[{"ext-123":["priority_hint"]}],"uniqueKey":"ignored_fields","typeLabel":"Ignored Fields · object"}},"type":"object","required":["status","events"],"title":"TypedIngestResponse","uniqueKey":"","typeLabel":"TypedIngestResponse · object"},"examples":{"Example":{"title":"Example","value":{"status":"accepted","events":1,"external_ids":["ext-123"],"rejected":[{"external_id":"ext-123","resource":"documents","reason":"quota_exceeded"}],"unchanged":["\u003cstring>"],"ignored_fields":{"ext-123":["priority_hint"]}}}},"exampleType":"generated"}},"exampleType":"generated"},"962d2142-ee75-4479-84d5-8e4fb3f0148f":{"description":"Ingest fully rejected — the workspace is over a tier quota (the object limit or the per-document size). Partial batches instead return 200 with a `rejected` list. Not transient, and deleting data doesn't give back object headroom; upgrade rather than retry.","content":{"application/json":{"schema":{"properties":{"error_code":{"type":"string","const":"quota_exceeded","title":"Error Code","default":"quota_exceeded","uniqueKey":"error_code","typeLabel":"string"},"message":{"type":"string","title":"Message","default":"Ingest rejected: this workspace is over its plan quota.","uniqueKey":"message","typeLabel":"string"},"details":{"oneOf":[{"type":"object","title":"Details","description":"Carries `rejected`: the refused items as `{external_id, resource, reason}` (resource ∈ documents/doc_size).","additionalProperties":true,"uniqueKey":"details.oneOf.0","typeLabel":"Details · object"},{"type":"null","title":"Details","description":"Carries `rejected`: the refused items as `{external_id, resource, reason}` (resource ∈ documents/doc_size).","uniqueKey":"details.oneOf.1","typeLabel":"null"}],"uniqueKey":"details","typeLabel":"Details · object | null"}},"type":"object","title":"QuotaExceededErrorModel","uniqueKey":"","typeLabel":"QuotaExceededErrorModel · object"},"examples":{"Example":{"title":"Example","value":{"error_code":"quota_exceeded","message":"Ingest rejected: this workspace is over its plan quota.","details":{}}}},"exampleType":"generated"}},"exampleType":"generated"},"4d875151-c2fc-434d-a25b-7bbe772371bb":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"oneOf":[{"type":"string","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.0","typeLabel":"string"},{"type":"integer","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.1","typeLabel":"integer"}],"uniqueKey":"detail.items.[INDEX].loc.items.[INDEX]","typeLabel":"string | integer"},"type":"array","title":"Location","isRequired":true,"uniqueKey":"detail.items.[INDEX].loc","typeLabel":"(string | integer)[]"},"msg":{"type":"string","title":"Message","isRequired":true,"uniqueKey":"detail.items.[INDEX].msg","typeLabel":"string"},"type":{"type":"string","title":"Error Type","isRequired":true,"uniqueKey":"detail.items.[INDEX].type","typeLabel":"string"},"input":{"oneOf":[{"title":"Input"}],"uniqueKey":"detail.items.[INDEX].input","typeLabel":"any"},"ctx":{"type":"object","title":"Context","uniqueKey":"detail.items.[INDEX].ctx","typeLabel":"Context · object"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError","uniqueKey":"detail.items.[INDEX]","typeLabel":"ValidationError · object"},"type":"array","title":"Detail","uniqueKey":"detail","typeLabel":"ValidationError · object[]"}},"type":"object","title":"HTTPValidationError","uniqueKey":"","typeLabel":"HTTPValidationError · object"},"examples":{"Example":{"title":"Example","value":{"detail":[{"loc":["\u003cstring>"],"msg":"\u003cstring>","type":"\u003cstring>","input":"\u003cunknown>","ctx":{}}]}}},"exampleType":"generated"}},"exampleType":"generated"},"05a100f5-a7f4-451c-a8ef-dfc1313fcbdc":{"description":"Rate limit exceeded for the caller's tier. RFC 9457 problem+json body; IETF RateLimit-* headers and Retry-After are set.","headers":{"Retry-After":{"description":"Seconds to wait before retrying (RFC 9110).","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Delta-seconds until the window resets.","schema":{"type":"integer"}},"RateLimit-Policy":{"description":"Active policy, e.g. '5;w=60'.","schema":{"type":"string"}}},"content":{"application/problem+json":{"schema":{"properties":{"type":{"type":"string","title":"Type","description":"Stable problem-type URI, e.g. '{api_base_url}/errors/rate_limit_exceeded'.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"detail":{"type":"string","title":"Detail","description":"Human-readable explanation, including the retry hint.","isRequired":true,"uniqueKey":"detail","typeLabel":"string"},"endpoint":{"type":"string","title":"Endpoint","description":"Logical endpoint the limit applies to (e.g. 'ask', 'search').","isRequired":true,"uniqueKey":"endpoint","typeLabel":"string"},"tier":{"type":"string","title":"Tier","description":"The caller's billing tier (e.g. 'flex').","isRequired":true,"uniqueKey":"tier","typeLabel":"string"},"limit":{"type":"integer","title":"Limit","description":"Requests allowed per window for this tier + endpoint.","isRequired":true,"uniqueKey":"limit","typeLabel":"integer"},"remaining":{"type":"integer","title":"Remaining","description":"Requests remaining in the current window (0 when blocked).","isRequired":true,"uniqueKey":"remaining","typeLabel":"integer"},"window_seconds":{"type":"integer","title":"Window Seconds","description":"Length of the fixed rate-limit window, in seconds.","isRequired":true,"uniqueKey":"window_seconds","typeLabel":"integer"},"retry_after":{"type":"integer","title":"Retry After","description":"Seconds to wait before retrying (mirrors the Retry-After header).","isRequired":true,"uniqueKey":"retry_after","typeLabel":"integer"},"title":{"type":"string","const":"Too Many Requests","title":"Title","default":"Too Many Requests","uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","const":429,"title":"Status","default":429,"uniqueKey":"status","typeLabel":"integer"},"error_code":{"type":"string","const":"rate_limit_exceeded","title":"Error Code","default":"rate_limit_exceeded","uniqueKey":"error_code","typeLabel":"string"},"instance":{"oneOf":[{"type":"string","title":"Instance","description":"The request path that was limited.","uniqueKey":"instance.oneOf.0","typeLabel":"string"},{"type":"null","title":"Instance","description":"The request path that was limited.","uniqueKey":"instance.oneOf.1","typeLabel":"null"}],"uniqueKey":"instance","typeLabel":"string | null"}},"type":"object","required":["type","detail","endpoint","tier","limit","remaining","window_seconds","retry_after"],"title":"RateLimitProblemDetail","description":"The 429 response body, exactly as ``RateLimitError.problem_detail`` renders it —\nRFC 9457 Problem Details, served as ``application/problem+json`` alongside the IETF\n``RateLimit-*`` headers and ``Retry-After``. (Distinct from the legacy\n``RateLimitErrorModel`` shape, which does not match what the handler emits.)","uniqueKey":"","typeLabel":"RateLimitProblemDetail · object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","detail":"\u003cstring>","endpoint":"\u003cstring>","tier":"\u003cstring>","limit":123,"remaining":123,"window_seconds":123,"retry_after":123,"title":"Too Many Requests","status":429,"error_code":"rate_limit_exceeded","instance":"\u003cstring>"}}},"exampleType":"generated"},"application/json":{"schema":{"properties":{"type":{"type":"string","title":"Type","description":"Stable problem-type URI, e.g. '{api_base_url}/errors/rate_limit_exceeded'.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"detail":{"type":"string","title":"Detail","description":"Human-readable explanation, including the retry hint.","isRequired":true,"uniqueKey":"detail","typeLabel":"string"},"endpoint":{"type":"string","title":"Endpoint","description":"Logical endpoint the limit applies to (e.g. 'ask', 'search').","isRequired":true,"uniqueKey":"endpoint","typeLabel":"string"},"tier":{"type":"string","title":"Tier","description":"The caller's billing tier (e.g. 'flex').","isRequired":true,"uniqueKey":"tier","typeLabel":"string"},"limit":{"type":"integer","title":"Limit","description":"Requests allowed per window for this tier + endpoint.","isRequired":true,"uniqueKey":"limit","typeLabel":"integer"},"remaining":{"type":"integer","title":"Remaining","description":"Requests remaining in the current window (0 when blocked).","isRequired":true,"uniqueKey":"remaining","typeLabel":"integer"},"window_seconds":{"type":"integer","title":"Window Seconds","description":"Length of the fixed rate-limit window, in seconds.","isRequired":true,"uniqueKey":"window_seconds","typeLabel":"integer"},"retry_after":{"type":"integer","title":"Retry After","description":"Seconds to wait before retrying (mirrors the Retry-After header).","isRequired":true,"uniqueKey":"retry_after","typeLabel":"integer"},"title":{"type":"string","const":"Too Many Requests","title":"Title","default":"Too Many Requests","uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","const":429,"title":"Status","default":429,"uniqueKey":"status","typeLabel":"integer"},"error_code":{"type":"string","const":"rate_limit_exceeded","title":"Error Code","default":"rate_limit_exceeded","uniqueKey":"error_code","typeLabel":"string"},"instance":{"oneOf":[{"type":"string","title":"Instance","description":"The request path that was limited.","uniqueKey":"instance.oneOf.0","typeLabel":"string"},{"type":"null","title":"Instance","description":"The request path that was limited.","uniqueKey":"instance.oneOf.1","typeLabel":"null"}],"uniqueKey":"instance","typeLabel":"string | null"}},"type":"object","required":["type","detail","endpoint","tier","limit","remaining","window_seconds","retry_after"],"title":"RateLimitProblemDetail","description":"The 429 response body, exactly as ``RateLimitError.problem_detail`` renders it —\nRFC 9457 Problem Details, served as ``application/problem+json`` alongside the IETF\n``RateLimit-*`` headers and ``Retry-After``. (Distinct from the legacy\n``RateLimitErrorModel`` shape, which does not match what the handler emits.)","uniqueKey":"","typeLabel":"RateLimitProblemDetail · object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","detail":"\u003cstring>","endpoint":"\u003cstring>","tier":"\u003cstring>","limit":123,"remaining":123,"window_seconds":123,"retry_after":123,"title":"Too Many Requests","status":429,"error_code":"rate_limit_exceeded","instance":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{},"servers":{"b45a6dfc-eec4-42ae-a72a-9361a1098054":{"url":"http://localhost:8080"}}},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"adapter","siteName":"Adapter","title":"Ingest typed first-party events - Adapter","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-15T21:39:25.936Z","originalFileLocation":"api-reference/ingestion/ingest-typed.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Ingest typed events from a custom connector. kind is either a first-party kind (email, calendar, conversation_message, page, issue, ...) or any evidence type from GET /v1/knowledge/evidence-types (order, deal, contact, company, product, ...), whose payload is validated against that type\u0026#x27;s schema. A payload for a type whose update contract names one identity field that its schema leaves optional (file, asset, video, calendar_event) may omit it: the item\u0026#x27;s external id becomes the identity (a fresh id when there is none); an explicitly empty value, a missing required identity, or a missing field of a multi-field identity, is refused with a 422. Use conversation_message for chat messages and message exports (iMessage, WhatsApp, assistant conversations, ...). message is deprecated: it is Slack-shaped and stores your data as Slack messages. Each item\u0026#x27;s timestamp is the record\u0026#x27;s own time and dates the evidence; it defaults to payload.timestamp, then the record\u0026#x27;s created_at, then the ingest clock. Connector- and per-item metadata are merged and attached to each event under event.metadata (item wins on key conflict).\">\u003cmeta data-mint-head name=\"application-name\" content=\"Adapter\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/adapter/QFVp-gltrPnIPgdk/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/adapter/QFVp-gltrPnIPgdk/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/adapter/QFVp-gltrPnIPgdk/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/adapter/QFVp-gltrPnIPgdk/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/adapter/QFVp-gltrPnIPgdk/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/adapter/QFVp-gltrPnIPgdk/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/adapter/QFVp-gltrPnIPgdk/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/adapter/QFVp-gltrPnIPgdk/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/adapter/QFVp-gltrPnIPgdk/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Ingest typed first-party events - Adapter\">\u003cmeta data-mint-head property=\"og:description\" content=\"Ingest typed events from a custom connector. kind is either a first-party kind (email, calendar, conversation_message, page, issue, ...) or any evidence type from GET /v1/knowledge/evidence-types (order, deal, contact, company, product, ...), whose payload is validated against that type\u0026#x27;s schema. A payload for a type whose update contract names one identity field that its schema leaves optional (file, asset, video, calendar_event) may omit it: the item\u0026#x27;s external id becomes the identity (a fresh id when there is none); an explicitly empty value, a missing required identity, or a missing field of a multi-field identity, is refused with a 422. Use conversation_message for chat messages and message exports (iMessage, WhatsApp, assistant conversations, ...). message is deprecated: it is Slack-shaped and stores your data as Slack messages. Each item\u0026#x27;s timestamp is the record\u0026#x27;s own time and dates the evidence; it defaults to payload.timestamp, then the record\u0026#x27;s created_at, then the ingest clock. Connector- and per-item metadata are merged and attached to each event under event.metadata (item wins on key conflict).\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Adapter\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-typed\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://adapter.mintlify.app/_mintlify/api/og/v2?division=Ingestion\u0026amp;title=Ingest+typed+first-party+events\u0026amp;description=Ingest+typed+events+from+a+custom+connector.+%60kind%60+is+either+a%0Afirst-party+kind+%28email%2C+calendar%2C+conversation_message%2C+page%2C+issue%2C+...%29%0Aor+any+evidence+type+\u0026amp;theme=172df802757f1536c21dc595\u0026amp;signature=eb74e35275a842a4d10160e311c5b1b12058320749117cbd1e0862f53671aa42\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Ingest typed first-party events - Adapter\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Ingest typed events from a custom connector. kind is either a first-party kind (email, calendar, conversation_message, page, issue, ...) or any evidence type from GET /v1/knowledge/evidence-types (order, deal, contact, company, product, ...), whose payload is validated against that type\u0026#x27;s schema. A payload for a type whose update contract names one identity field that its schema leaves optional (file, asset, video, calendar_event) may omit it: the item\u0026#x27;s external id becomes the identity (a fresh id when there is none); an explicitly empty value, a missing required identity, or a missing field of a multi-field identity, is refused with a 422. Use conversation_message for chat messages and message exports (iMessage, WhatsApp, assistant conversations, ...). message is deprecated: it is Slack-shaped and stores your data as Slack messages. Each item\u0026#x27;s timestamp is the record\u0026#x27;s own time and dates the evidence; it defaults to payload.timestamp, then the record\u0026#x27;s created_at, then the ingest clock. Connector- and per-item metadata are merged and attached to each event under event.metadata (item wins on key conflict).\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://adapter.mintlify.app/_mintlify/api/og/v2?division=Ingestion\u0026amp;title=Ingest+typed+first-party+events\u0026amp;description=Ingest+typed+events+from+a+custom+connector.+%60kind%60+is+either+a%0Afirst-party+kind+%28email%2C+calendar%2C+conversation_message%2C+page%2C+issue%2C+...%29%0Aor+any+evidence+type+\u0026amp;theme=172df802757f1536c21dc595\u0026amp;signature=eb74e35275a842a4d10160e311c5b1b12058320749117cbd1e0862f53671aa42\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/adapter/QFVp-gltrPnIPgdk/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Adapter\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#8765F0\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-typed\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/ingestion/ingest-typed.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.beta.adapter.com/#organization\",\"name\":\"Adapter\",\"url\":\"https://docs.beta.adapter.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/adapter/J3Ydy4fSe61BUDTE/logo/light.svg?fit=max\u0026auto=format\u0026n=J3Ydy4fSe61BUDTE\u0026q=85\u0026s=459bd6410eb825d264414176cd7eba07\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.beta.adapter.com#website\",\"name\":\"Adapter\",\"url\":\"https://docs.beta.adapter.com\",\"publisher\":{\"@id\":\"https://docs.beta.adapter.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-typed#webpage\",\"url\":\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-typed\",\"name\":\"Ingest typed first-party events\",\"description\":\"Ingest typed events from a custom connector. kind is either a first-party kind (email, calendar, conversation_message, page, issue, ...) or any evidence type from GET /v1/knowledge/evidence-types (order, deal, contact, company, product, ...), whose payload is validated against that type's schema. A payload for a type whose update contract names one identity field that its schema leaves optional (file, asset, video, calendar_event) may omit it: the item's external id becomes the identity (a fresh id when there is none); an explicitly empty value, a missing required identity, or a missing field of a multi-field identity, is refused with a 422. Use conversation_message for chat messages and message exports (iMessage, WhatsApp, assistant conversations, ...). message is deprecated: it is Slack-shaped and stores your data as Slack messages. Each item's timestamp is the record's own time and dates the evidence; it defaults to payload.timestamp, then the record's created_at, then the ingest clock. Connector- and per-item metadata are merged and attached to each event under event.metadata (item wins on key conflict).\",\"dateModified\":\"2026-10-15T21:39:25.936Z\",\"isPartOf\":{\"@id\":\"https://docs.beta.adapter.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-typed#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-typed#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Ingestion\",\"item\":\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-custom\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Ingest typed first-party events\",\"item\":\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-typed\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-typed#apireference\",\"headline\":\"Ingest typed first-party events\",\"name\":\"Ingest typed first-party events\",\"description\":\"Ingest typed events from a custom connector. kind is either a first-party kind (email, calendar, conversation_message, page, issue, ...) or any evidence type from GET /v1/knowledge/evidence-types (order, deal, contact, company, product, ...), whose payload is validated against that type's schema. A payload for a type whose update contract names one identity field that its schema leaves optional (file, asset, video, calendar_event) may omit it: the item's external id becomes the identity (a fresh id when there is none); an explicitly empty value, a missing required identity, or a missing field of a multi-field identity, is refused with a 422. Use conversation_message for chat messages and message exports (iMessage, WhatsApp, assistant conversations, ...). message is deprecated: it is Slack-shaped and stores your data as Slack messages. Each item's timestamp is the record's own time and dates the evidence; it defaults to payload.timestamp, then the record's created_at, then the ingest clock. Connector- and per-item metadata are merged and attached to each event under event.metadata (item wins on key conflict).\",\"url\":\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-typed\",\"mainEntityOfPage\":{\"@id\":\"https://docs.beta.adapter.com/api-reference/ingestion/ingest-typed#webpage\"},\"dateModified\":\"2026-10-15T21:39:25.936Z\",\"publisher\":{\"@id\":\"https://docs.beta.adapter.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.beta.adapter.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Adapter\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Adapter","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/getting-started/introduction"}]},{"tab":"MCP","pages":[{"title":"MCP","href":"/getting-started/mcp"}]},{"tab":"API Reference","groups":[{"group":"Overview","pages":[{"title":"Overview","href":"/api-reference/introduction"}]},{"group":"Connectors","expanded":false,"pages":[{"title":"List Connections","openapi":"GET /v1/connections","href":"/api-reference/connectors/list-connections"},{"title":"Get Connection","openapi":"GET /v1/connections/{connection_id}","href":"/api-reference/connectors/get-connection"},{"title":"List Resource Facets","openapi":"GET /v1/connections/{connection_id}/resources/{resource}/facets/{facet_name}","href":"/api-reference/connectors/list-resource-facets"}]},{"group":"Custom Connectors","expanded":false,"pages":[{"title":"List custom connectors","openapi":"GET /v1/custom-connectors","href":"/api-reference/custom-connectors/list-custom-connectors"},{"title":"Create a custom connector","openapi":"POST /v1/custom-connectors","href":"/api-reference/custom-connectors/create-custom-connector"},{"title":"Get a custom connector","openapi":"GET /v1/custom-connectors/{connector_id}","href":"/api-reference/custom-connectors/get-custom-connector"},{"title":"Update a custom connector","openapi":"PATCH /v1/custom-connectors/{connector_id}","href":"/api-reference/custom-connectors/update-custom-connector"},{"title":"Deactivate a custom connector","openapi":"DELETE /v1/custom-connectors/{connector_id}","href":"/api-reference/custom-connectors/delete-custom-connector"}]},{"group":"Data","expanded":false,"pages":[{"title":"Download Document Raw","openapi":"GET /v1/data/{connection_id}/{resource}/raw/{external_id}","href":"/api-reference/data/download-document-raw"},{"title":"Get Document Detail","openapi":"GET /v1/data/{connection_id}/{resource}/{external_id}","href":"/api-reference/data/get-document-detail"}]},{"group":"Documents","expanded":false,"pages":[{"title":"Get Document By Urn","openapi":"GET /v1/documents/{urn}","href":"/api-reference/documents/get-document-by-urn"},{"title":"Download Document By Urn","openapi":"GET /v1/documents/{urn}/raw","href":"/api-reference/documents/download-document-by-urn"}]},{"group":"Ingestion","expanded":false,"pages":[{"title":"Ingest generic JSON events","openapi":"POST /v1/custom-connectors/{connector_id}/ingest","href":"/api-reference/ingestion/ingest-custom"},{"title":"Upload a binary as a generic event","openapi":"POST /v1/custom-connectors/{connector_id}/ingest/upload","href":"/api-reference/ingestion/ingest-custom-upload"},{"title":"Start a presigned video upload","openapi":"POST /v1/custom-connectors/{connector_id}/ingest/video/upload-url","href":"/api-reference/ingestion/ingest-video-upload-url"},{"title":"Finalize a presigned video upload","openapi":"POST /v1/custom-connectors/{connector_id}/ingest/video/complete","description":"Finalize the multipart upload, verify the object (true size ≤150MB and\nreal MP4/MOV magic bytes — never trust the declared values), then publish\na typed `video` event (VideoRawData contract) that routes the file to\nmedia enrichment. An optional `hint` rides on event.metadata as\n`enrichment_hint` and is folded into the analysis prompt.","href":"/api-reference/ingestion/ingest-video-complete"},{"title":"Ingest typed first-party events","openapi":"POST /v1/custom-connectors/{connector_id}/ingest/typed","href":"/api-reference/ingestion/ingest-typed"},{"title":"Upload a binary as a typed event","openapi":"POST /v1/custom-connectors/{connector_id}/ingest/typed/upload","description":"Upload a binary file as a typed first-party event (e.g. a PDF as a\n`page`, a screenshot as an `asset`, an mp4 as a `video`). When `kind` is\nomitted, image/video mimes route to `asset`/`video` and everything else to\n`page`. The payload is validated before any byte is stored, so a rejected\nupload stores nothing. Bytes are stored at an address of their content and\nthe event carries `raw_object_s3_key` so the LLM enricher analyzes the\ncontent; a later upload under the same external id never overwrites them.\n\nThis is how a connector delivers a file's bytes: with `kind=file` the\npublished `file` record names the stored object (`storage_uri`,\n`size_bytes`, a server-computed SHA-256 `file_hash`) and Adapter extracts\nthe text from it. The JSON evidence route carries file metadata only.","href":"/api-reference/ingestion/ingest-typed-upload"}]},{"group":"Knowledge","expanded":false,"pages":[{"title":"Search","openapi":"POST /v1/knowledge/search","href":"/api-reference/knowledge/search"},{"title":"Ask","openapi":"POST /v1/knowledge/ask","href":"/api-reference/knowledge/ask"},{"title":"Ask Stream","openapi":"POST /v1/knowledge/ask/stream","href":"/api-reference/knowledge/ask-stream"},{"title":"List Ask Jobs","openapi":"GET /v1/knowledge/ask/jobs","href":"/api-reference/knowledge/list-ask-jobs"},{"title":"Create Ask Job","openapi":"POST /v1/knowledge/ask/jobs","href":"/api-reference/knowledge/create-ask-job"},{"title":"Get Ask Job","openapi":"GET /v1/knowledge/ask/jobs/{job_id}","href":"/api-reference/knowledge/get-ask-job"},{"title":"Get Entity","openapi":"GET /v1/knowledge/entities/{entity_id}","href":"/api-reference/knowledge/get-entity"},{"title":"Refresh Context","openapi":"POST /v1/knowledge/refresh","href":"/api-reference/knowledge/refresh-context"},{"title":"Context Status","openapi":"GET /v1/knowledge/status","href":"/api-reference/knowledge/context-status"},{"title":"Get Knowledge Settings","openapi":"GET /v1/knowledge/settings","href":"/api-reference/knowledge/get-knowledge-settings"},{"title":"Update Knowledge Settings","openapi":"PATCH /v1/knowledge/settings","href":"/api-reference/knowledge/update-knowledge-settings"}]},{"group":"Triggers","expanded":false,"pages":[{"title":"List triggers","openapi":"GET /v1/triggers","href":"/api-reference/Triggers/list-triggers"},{"title":"Create trigger","openapi":"POST /v1/triggers","href":"/api-reference/Triggers/create-trigger"},{"title":"List trigger registry","openapi":"GET /v1/triggers/kinds","href":"/api-reference/Triggers/list-trigger-kinds"},{"title":"Get delivery counts","openapi":"GET /v1/triggers/deliveries/summary","href":"/api-reference/Triggers/get-trigger-delivery-summary"},{"title":"Get trigger details","openapi":"GET /v1/triggers/{trigger_id}","href":"/api-reference/Triggers/get-trigger"},{"title":"Update trigger","openapi":"PATCH /v1/triggers/{trigger_id}","href":"/api-reference/Triggers/update-trigger"},{"title":"Delete trigger","openapi":"DELETE /v1/triggers/{trigger_id}","href":"/api-reference/Triggers/delete-trigger"},{"title":"List deliveries","openapi":"GET /v1/triggers/{trigger_id}/deliveries","href":"/api-reference/Triggers/list-trigger-deliveries"}]},{"group":"Writeback","expanded":false,"pages":[{"title":"Write agent output back into the workspace","openapi":"POST /v1/writeback","href":"/api-reference/writeback/write-back"},{"title":"Recently written-back items","openapi":"GET /v1/writeback/recent","href":"/api-reference/writeback/recent-writebacks"}]}]}]},"basePath":"","title":"Ingest typed first-party events - Adapter","buildId":"dpl_G9nrg4qeJSZtah1Ziwbc2n6WkLch","deploymentId":"dpl_G9nrg4qeJSZtah1Ziwbc2n6WkLch","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-B7XKH4J3.js","utils-lOYzL7z-.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-DF6jUUIM.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-Dpsj5f7C.js","snippetPresets-CYeiDe8v.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-CUFz1YZ_.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-D8H_iLS4.js","shallow-DdluZBHX.js","getApiPlaygroundDisplay-B9922vev.js","CodeSnippet-CMoRNGYs.js","CodeSnippets-DwyrPHuw.js","Page-DSVu9Ucl.js","getPastedJson-G-zIvlHh.js","icon-B03fnEy0.js","MethodPill-CW7teklc.js","DuplicateIcon-CtO8eekd.js","createIcon-DZTKdM_A.js","DynamicMarkdown-D5M2At0B.js","SectionHeading-C_2NaA2U.js","axios-vUo_bRtp.js","Markdown-D7QRHV3m.js","clsx-D1Z-ELXV.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-lvhuD9Du.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-CKfC4ywL.js"]}