A Custral secret API key (sk_…), created in Settings → Applications. Sent as Authorization: Bearer sk_…. The X-Api-Key: sk_… header is also accepted and takes precedence. Never expose a secret key in a browser.
A per-request id (req_…). Quote it to support when reporting a problem.
Example:
"req_2a1f9c8e7b6d5"
Was this page helpful?
{"docsConfig":{"theme":"aspen","$schema":"https://mintlify.com/docs.json","name":"Custral Docs","colors":{"primary":"#5E7CFF","light":"#5E7CFF","dark":"#5E7CFF"},"logo":{"light":"https://mintcdn.com/custral/9h_119tROzHTKUiS/assets/logos/light.svg?fit=max\u0026auto=format\u0026n=9h_119tROzHTKUiS\u0026q=85\u0026s=50b063929ddff7335cc4db8352ae694a","dark":"https://mintcdn.com/custral/9h_119tROzHTKUiS/assets/logos/dark.svg?fit=max\u0026auto=format\u0026n=9h_119tROzHTKUiS\u0026q=85\u0026s=4025f09bcbe60697aef60a5bb3f849f0"},"favicon":"https://mintcdn.com/custral/NGCdls_pt-1YDx5S/favicon.svg?fit=max\u0026auto=format\u0026n=NGCdls_pt-1YDx5S\u0026q=85\u0026s=3a0ce3e846a625e7bc5e70aafe82cffa","navbar":{"links":[{"href":"https://custral.com","label":"Get Started"}],"primary":{"type":"button","label":"Dashboard","href":"https://app.custral.com"}},"footer":{"socials":{"linkedin":"https://www.linkedin.com/company/custral"},"links":[{"header":"Resources","items":[{"label":"Status Page","href":"https://status.custral.com"},{"label":"Blog","href":"https://blog.custral.com"}]},{"header":"Support","items":[{"label":"Get support","href":"/support"},{"label":"hello@custral.com","href":"mailto:hello@custral.com"}]}]},"search":{"prompt":"Search Custral docs..."},"seo":{"metatags":{"og:image":"/images/og-docs.png","og:image:width":"2400","og:image:height":"1260","twitter:card":"summary_large_image","twitter:image":"/images/og-docs.png"}},"banner":{"content":"New: Focus Mode sorts your inbox, records open in a peek, a rebuilt mobile app, and a daily brief. [See what's new](/product/updates)","dismissible":true},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"metadata":{"timestamp":false},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"custral","hasAudioNarration":false,"actualSubdomain":"custral","customDomains":["docs.custral.com"],"gitSource":{"type":"github","owner":"custral","repo":"custral-mono","deployBranch":"master","contentDirectory":"apps/docs","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6ade1ad5cc4d8fc7f4e59b84","collectionId":"a149e1a3-54d3-4769-89c2-5031be517fb3","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6ade1ad5cc4d8fc7f4e59b84"},"feedback":{"thumbs":true,"agentFeedback":true},"entitlements":{"AI_CHAT":{"status":"DISABLED"},"WEB_MCP":{"status":"DISABLED"},"NARRATION":{"status":"DISABLED"}},"buildId":"6ae601488b8badc2e429ed75","clientVersion":"0.0.4044","searchFilterCounts":[{"language":"default","tag":"Documentation","count":317},{"language":"default","tag":"Developer References","count":108},{"language":"default","tag":"Communications","count":66},{"language":"default","tag":"Data Structures","count":60},{"language":"default","tag":"API Reference","count":56},{"language":"default","tag":"Endpoints","count":49},{"language":"default","tag":"Blocks","count":46},{"language":"default","tag":"Properties","count":40},{"language":"default","tag":"Getting Started","count":37},{"language":"default","tag":"Embedded Components","count":35}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"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},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":".cxh{--brand:#5E7CFF;--brand-ink:#3f57e6;--brand-soft:#eef1ff;--g1:#5E7CFF;--g2:#8b5cf6;--g3:#ff5f7a;--bg:#ffffff;--bg2:#fbfbfe;--card:#ffffff;--panel:#f6f7fb;--border:#e8e9f3;--border-soft:#f0f1f8;--text:#191b26;--muted:#5b5e73;--faint:#9a9db2;--code-bg:#0f1119;--code-text:#e7e9f5;--a1:#5E7CFF;--a2:#8b5cf6;--a3:#ff5f7a;--a4:#10b981;--k:#c4b5fd;--s:#86efac;--f:#93c5fd;--c:#6b7089;--p:#f0a4b8;--shadow-sm:0 1px 2px rgba(20,22,50,.05),0 3px 10px rgba(20,22,50,.05);--shadow-lg:0 2px 6px rgba(20,22,50,.06),0 20px 50px rgba(30,34,80,.13);--dot:rgba(94,124,255,.14);--radius:14px;--mono:ui-monospace,SFMono-Regular,\"SF Mono\",Menlo,Consolas,monospace;color:var(--text)}:root[data-theme=dark] .cxh,html.dark .cxh,html[data-theme=dark] .cxh{--brand:#7d90ff;--brand-ink:#a6b2ff;--brand-soft:#191c2e;--bg:#0c0d14;--bg2:#0a0b11;--card:#14161f;--panel:#111219;--border:#242738;--border-soft:#1b1e29;--text:#e9eaf2;--muted:#a0a3b8;--faint:#6f7288;--code-bg:#0a0b12;--code-text:#e7e9f5;--shadow-sm:0 1px 2px rgba(0,0,0,.4),0 3px 10px rgba(0,0,0,.35);--shadow-lg:0 2px 6px rgba(0,0,0,.5),0 24px 60px rgba(0,0,0,.6);--dot:rgba(125,144,255,.14)}.cxh *{box-sizing:border-box}.cxh a{color:inherit;text-decoration:none}.cxh .wrap{max-width:1120px;margin:0 auto;padding-inline:28px}.cxh .fullbleed{width:100%}.cxh .hero{position:relative;overflow:hidden;border-bottom:1px solid var(--border-soft);background:var(--bg)}.cxh .hero-bg,.cxh .hero-dots{position:absolute;inset:0;z-index:0}.cxh .hero-bg{background:radial-gradient(680px 360px at 80% -10%,color-mix(in srgb,var(--brand) 22%,transparent),transparent 70%),radial-gradient(560px 300px at 6% 0%,color-mix(in srgb,var(--g2) 13%,transparent),transparent 70%)}.cxh .hero-dots{opacity:.9;background-image:radial-gradient(var(--dot) 1px,transparent 1.4px);background-size:22px 22px;mask-image:linear-gradient(180deg,#000,transparent 80%);-webkit-mask-image:linear-gradient(180deg,#000,transparent 80%)}.cxh .hero-in{position:relative;z-index:1;display:grid;grid-template-columns:1fr 1fr;gap:48px;align-items:center;padding:66px 0 60px}.cxh .eyebrow{font-size:12px;font-weight:700;letter-spacing:.14em;text-transform:uppercase;color:var(--brand-ink)}.cxh h1{font-size:46px;line-height:1.04;letter-spacing:-.03em;margin:14px 0 0;font-weight:750;text-wrap:balance;color:var(--text)}.cxh .lead{font-size:17.5px;line-height:1.55;color:var(--muted);margin:18px 0 0;max-width:34ch}.cxh .cta{display:flex;align-items:center;gap:12px;margin-top:28px;flex-wrap:wrap}.cxh .btn{display:inline-flex;align-items:center;gap:7px;height:40px;padding:0 18px;border-radius:9px;font-size:14px;font-weight:600;border:1px solid transparent;cursor:pointer}.cxh .btn.primary{background:var(--brand);color:#fff;box-shadow:0 1px 2px rgba(63,87,230,.35)}.cxh .btn.ghost{background:0 0;color:var(--text);border-color:var(--border)}.cxh .btn.ghost:hover{border-color:color-mix(in srgb,var(--brand) 45%,var(--border))}.cxh .cta .clink{font-size:14px;font-weight:600;color:var(--brand-ink);display:inline-flex;align-items:center;gap:6px}.cxh .herovis{position:relative;padding:6px 8px 26px 0}.cxh .appwin{position:relative;z-index:1;background:var(--card);border:1px solid var(--border);border-radius:14px;box-shadow:var(--shadow-lg);overflow:hidden;transform:rotate(-.6deg)}.cxh .winbar{display:flex;align-items:center;gap:7px;padding:9px 13px;border-bottom:1px solid var(--border-soft);background:var(--panel)}.cxh .tl{width:10px;height:10px;border-radius:50%}.cxh .tl.r{background:#ff5f57}.cxh .tl.y{background:#febc2e}.cxh .tl.g{background:#28c840}.cxh .winbar .wt{margin-left:8px;font-size:12px;font-weight:600;color:var(--muted)}.cxh .winbar .wpill{margin-left:auto;font-size:10.5px;color:var(--brand-ink);background:var(--brand-soft);border-radius:20px;padding:2px 8px;font-weight:600}.cxh .winbody{display:flex;min-height:214px}.cxh .side,.cxh .tcol ul{display:flex;flex-direction:column;gap:2px}.cxh .side{flex:0 0 120px;background:var(--bg2);border-right:1px solid var(--border-soft);padding:10px 8px}.cxh .snav{display:flex;align-items:center;gap:8px;font-size:12px;color:var(--muted);padding:6px 8px;border-radius:7px;font-weight:500}.cxh .snav .g{width:15px;text-align:center;opacity:.85}.cxh .snav.on{background:var(--brand-soft);color:var(--brand-ink);font-weight:600}.cxh .main{flex:1;padding:6px 4px}.cxh .conv{display:flex;align-items:center;gap:10px;padding:9px 12px;border-radius:9px}.cxh .conv+.conv{border-top:1px solid var(--border-soft)}.cxh .conv .av{flex:0 0 auto;width:28px;height:28px;border-radius:50%;display:grid;place-items:center;color:#fff;font-size:11px;font-weight:700}.cxh .conv .av.a1{background:var(--a1)}.cxh .conv .av.a2{background:var(--a2)}.cxh .conv .av.a3{background:var(--a3)}.cxh .conv .av.a4{background:var(--a4)}.cxh .conv .ct{min-width:0;flex:1}.cxh .conv .cn{font-size:12.5px;font-weight:600;display:flex;align-items:center;gap:6px;color:var(--text)}.cxh .conv .ch{font-size:9.5px;font-weight:700;letter-spacing:.04em;text-transform:uppercase;color:var(--faint);border:1px solid var(--border);border-radius:5px;padding:0 4px}.cxh .conv .cs{display:block;font-size:11.5px;color:var(--muted);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;margin-top:1px}.cxh .conv .cd{flex:0 0 auto;font-size:10.5px;color:var(--faint)}.cxh .conv .un{width:7px;height:7px;border-radius:50%;background:var(--brand);flex:0 0 auto}.cxh .codecard{position:absolute;z-index:2;right:-6px;bottom:-6px;width:290px;border-radius:12px;background:var(--code-bg);box-shadow:var(--shadow-lg);border:1px solid rgba(255,255,255,.07);overflow:hidden;transform:rotate(2.2deg)}.cxh .codebar{display:flex;align-items:center;gap:6px;padding:8px 11px;border-bottom:1px solid rgba(255,255,255,.07)}.cxh .codebar .tl{width:9px;height:9px}.cxh .codebar .name{margin-left:6px;font:11px/1 var(--mono);color:#8b8fa8}.cxh pre.code{margin:0;white-space:pre;text-align:left;padding:12px 13px 14px;font:11px/1.65 var(--mono);color:var(--code-text);overflow:hidden;background:0 0;border:0}.cxh .k{color:var(--k)}.cxh .s{color:var(--s)}.cxh .f{color:var(--f)}.cxh .c{color:var(--c)}.cxh .p{color:var(--p)}.cxh section{padding-block:56px}.cxh .pathsec{padding-block:48px 8px}.cxh .tasksec{padding-top:40px}.cxh .sechead{display:flex;align-items:baseline;justify-content:space-between;gap:16px;margin-bottom:26px}.cxh .path h4,.cxh h2{font-size:22px;letter-spacing:-.02em;font-weight:700;color:var(--text)}.cxh .path p,.cxh .sechead .sub{font-size:13.5px;color:var(--faint)}.cxh .paths{display:grid;grid-template-columns:1fr 1fr;gap:16px}.cxh .path{display:flex;gap:14px;align-items:flex-start;background:var(--card);border:1px solid var(--border);border-radius:var(--radius);padding:18px 20px;box-shadow:var(--shadow-sm)}.cxh .path:hover{border-color:color-mix(in srgb,var(--brand) 45%,var(--border))}.cxh .path .pic,.cxh .tcol h3 .ic{background:var(--brand-soft);display:grid;place-items:center}.cxh .path .pic{flex:0 0 auto;width:38px;height:38px;border-radius:10px;color:var(--brand-ink);font-size:17px}.cxh .path h4{margin:2px 0 4px;font-size:15.5px;font-weight:650;letter-spacing:-.01em}.cxh .path p{margin:0;color:var(--muted);line-height:1.5}.cxh .path .go{margin-top:10px;font-size:13px;font-weight:600;display:inline-flex;gap:6px}.cxh .tasks{display:grid;grid-template-columns:repeat(3,1fr);gap:34px}.cxh .tcol h3,.cxh .tcol li a{display:flex;align-items:center}.cxh .tcol h3{font-size:12.5px;font-weight:700;letter-spacing:.06em;text-transform:uppercase;color:var(--faint);margin:0 0 14px;gap:8px}.cxh .tcol h3 .ic{width:22px;height:22px;border-radius:6px;font-size:11px}.cxh .tcol ul{list-style:none;margin:0;padding:0}.cxh .tcol li,.cxh h2{margin:0}.cxh .tcol li a{gap:9px;padding:7px 9px;margin:0 -9px;border-radius:8px;font-size:14px;color:var(--text);font-weight:450}.cxh .dgroup h3 .chip,.cxh .path .go,.cxh .tcol h3 .ic,.cxh .tcol li a:hover{color:var(--brand-ink)}.cxh .tcol li a .arw{color:var(--faint);font-size:12px;margin-left:auto;opacity:0;transition:.15s}.cxh .tcol li a:hover .arw{opacity:1}.cxh .dirwrap{background:var(--bg2);border-top:1px solid var(--border-soft);border-bottom:1px solid var(--border-soft)}.cxh .dir{display:grid;grid-template-columns:repeat(2,1fr);gap:14px 40px}.cxh .dgroup{padding:4px 0}.cxh .dgroup h3{gap:10px;font-size:14px;font-weight:700;margin:0 0 12px;letter-spacing:-.01em}.cxh .dgroup h3 .chip{width:26px;height:26px;border-radius:8px;display:grid;place-items:center;font-size:13px;background:var(--brand-soft)}.cxh .drow{display:flex;gap:12px;padding:9px 10px;margin:0 -10px;border-radius:10px;align-items:flex-start}.cxh .drow:hover,.cxh .tcol li a:hover{background:var(--panel)}.cxh .drow .di,.cxh .helprow a{font-size:13px;color:var(--muted)}.cxh .drow .di{flex:0 0 auto;width:30px;height:30px;border-radius:8px;border:1px solid var(--border);background:var(--card);display:grid;place-items:center;margin-top:1px}.cxh .drow .dt{font-size:14px;font-weight:600;letter-spacing:-.01em;color:var(--text)}.cxh .drow .dd{font-size:12.5px;color:var(--muted);line-height:1.45;margin-top:1px}.cxh .dgroup h3,.cxh .helprow{display:flex;align-items:center}.cxh .helprow{flex-wrap:wrap;gap:14px 22px;padding:26px 0 8px}.cxh .helprow a{font-weight:500}.cxh .dgroup h3,.cxh .helprow a:hover{color:var(--text)}.cxh .helprow .sep{color:var(--faint)}.cxh .helprow .lead-in{font-size:13px;color:var(--faint);margin-right:6px}.cxh .supportband{background:var(--bg2);border-top:1px solid var(--border);border-bottom:1px solid var(--border);margin-top:40px}.cxh .supportrow{display:grid;grid-template-columns:1fr auto;gap:32px;align-items:center;padding:34px 0}.cxh .supportrow h3{font-size:19px;font-weight:650;letter-spacing:-.01em;margin:0 0 6px}.cxh .supportrow p{font-size:14px;color:var(--muted);margin:0 0 12px;max-width:44ch}.cxh .supportcontacts{display:flex;gap:10px;flex-wrap:wrap}.cxh .scontact{display:flex;align-items:center;gap:11px;padding:12px 16px;border:1px solid var(--border);border-radius:11px;background:var(--bg);min-width:236px;transition:border-color .15s ease}.cxh .scontact:hover{border-color:var(--brand)}.cxh .scontact .si{width:30px;height:30px;flex:none;display:flex;align-items:center;justify-content:center;border-radius:8px;background:var(--brand-soft);color:var(--brand-ink);font-size:14px}.cxh .scontact .sl{display:block;font-size:11.5px;color:var(--faint);letter-spacing:.01em}.cxh .scontact .sv{display:block;font-size:14px;font-weight:600;color:var(--text)}@media (max-width:920px){.cxh .hero-in{grid-template-columns:1fr;gap:44px;padding:48px 0 56px}.cxh .herovis{padding:0 8px 20px 0;max-width:520px}.cxh .tasks{gap:26px}.cxh .paths,.cxh .tasks{grid-template-columns:1fr}.cxh .dir,.cxh .supportrow{grid-template-columns:1fr;gap:8px 0}.cxh h1{font-size:36px}.cxh .supportrow{gap:22px}.cxh .scontact{min-width:0;flex:1 1 100%}}.nav-tag-pill-text[data-nav-tag=OBJECT]{color:rgb(82 82 91);background:rgb(113 113 122/.14);font-size:.5rem;white-space:nowrap}.dark .nav-tag-pill-text[data-nav-tag=OBJECT]{color:rgb(161 161 170);background:rgb(161 161 170/.16)}div:has(>.nav-tag-pill>[data-nav-tag=OBJECT]){order:-1;width:2rem;margin-right:6px;overflow:visible}.update-container>div:first-child>div.break-words{display:none}.card-group .card>img.object-cover{aspect-ratio:16/10;height:auto;object-position:top center}"}],"page":{"pagePath":"api-reference/conversations/create-a-conversation","slug":"/api-reference/conversations/create-a-conversation","pageMetadata":{"title":"Create a conversation","description":"Create a conversation, optionally attaching participants and importing an initial transcript. **Requires scope:** `conversations:write`.","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/conversations","href":"/api-reference/conversations/create-a-conversation","autogeneratedByOpenApi":true},"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 strong: \"strong\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"Create a conversation, optionally attaching participants and importing an initial transcript. \", _jsx(_components.strong, {\n children: \"Requires scope:\"\n }), \" \", _jsx(_components.code, {\n children: \"conversations:write\"\n }), \".\"]\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":"Create a conversation","description":"Create a conversation, optionally attaching participants and importing an initial transcript. **Requires scope:** `conversations:write`.","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/conversations","href":"/api-reference/conversations/create-a-conversation","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":["/_mintlify/custom/custral/17880bab12267dd5/index.js"],"openApiReferenceData":{"operation":{"operationId":"createConversation","tags":["Conversations"],"summary":"Create a conversation","description":"Create a conversation, optionally attaching participants and importing an initial transcript. **Requires scope:** `conversations:write`.","requestBody":"31aa273d-3ab0-4407-969c-a74e0e1647a0","responses":{"200":"4a5e4e9e-464f-4626-b664-aea690d9e557","401":"82143274-e00c-4118-ab6b-a0d75c4c27ef","403":"98d3c235-a23c-40fa-ac7f-783c6d3b5279"},"method":"post","type":"path","servers":["1973a696-1865-48ff-be0a-5b97a2fc45be"],"security":["969e856c-2093-48fd-9650-083e693332fa"],"path":"/v1/conversations","baseUrlOptions":["https://api.custral.com"],"title":"Create a conversation","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The body of a create-conversation request.","properties":{"title":{"type":"string","example":"Jane Doe","uniqueKey":"title","typeLabel":"string"},"sourceType":{"type":"string","description":"Free-form source label. Defaults to `api`.","example":"imessage","uniqueKey":"sourceType","typeLabel":"string"},"channelId":{"oneOf":[{"type":"string","description":"A channel (`chan_…`) to attach to.","uniqueKey":"channelId.oneOf.0","typeLabel":"string"},{"type":"null","description":"A channel (`chan_…`) to attach to.","uniqueKey":"channelId.oneOf.1","typeLabel":"null"}],"uniqueKey":"channelId","typeLabel":"string | null"},"status":{"type":"string","enum":["open","closed","completed"],"default":"open","uniqueKey":"status","typeLabel":"enum\u003cstring>"},"participants":{"type":"array","items":{"type":"object","description":"A participant to attach — a linked record, or a guest by name/email.","properties":{"recordId":{"type":"string","description":"Link an existing record (`rec_…`).","uniqueKey":"participants.items.[INDEX].recordId","typeLabel":"string"},"name":{"type":"string","description":"Guest display name.","uniqueKey":"participants.items.[INDEX].name","typeLabel":"string"},"email":{"type":"string","description":"Guest email.","uniqueKey":"participants.items.[INDEX].email","typeLabel":"string"}},"uniqueKey":"participants.items.[INDEX]","typeLabel":"object"},"uniqueKey":"participants","typeLabel":"object[]"},"messages":{"type":"array","items":{"type":"object","description":"One message to push into a conversation.","properties":{"text":{"type":"string","example":"On my way!","isRequired":true,"uniqueKey":"messages.items.[INDEX].text","typeLabel":"string"},"author":{"type":"string","description":"Display name of the sender.","uniqueKey":"messages.items.[INDEX].author","typeLabel":"string"},"authorId":{"type":"string","description":"Stable handle of the sender (phone, email, record id).","uniqueKey":"messages.items.[INDEX].authorId","typeLabel":"string"},"direction":{"type":"string","enum":["inbound","outbound"],"uniqueKey":"messages.items.[INDEX].direction","typeLabel":"enum\u003cstring>"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601. Defaults to now.","uniqueKey":"messages.items.[INDEX].timestamp","typeLabel":"string\u003cdate-time>"}},"required":["text"],"uniqueKey":"messages.items.[INDEX]","typeLabel":"object"},"uniqueKey":"messages","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"title":"Jane Doe","sourceType":"imessage","channelId":"\u003cstring>","status":"open","participants":[{"recordId":"\u003cstring>","name":"\u003cstring>","email":"\u003cstring>"}],"messages":[{"text":"On my way!","author":"\u003cstring>","authorId":"\u003cstring>","timestamp":"2023-11-07T05:31:56Z"}]}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"4a5e4e9e-464f-4626-b664-aea690d9e557":{"description":"The created conversation (detail shape).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"A conversation. `messages` + `participants` are present on retrieve/create and absent from list rows.","properties":{"id":{"type":"string","example":"conv_123","isRequired":true,"uniqueKey":"data.id","typeLabel":"string"},"title":{"oneOf":[{"type":"string","example":"Jane Doe","uniqueKey":"data.title.oneOf.0","typeLabel":"string"},{"type":"null","example":"Jane Doe","uniqueKey":"data.title.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.title","typeLabel":"string | null"},"status":{"oneOf":[{"type":"string","example":"open","uniqueKey":"data.status.oneOf.0","typeLabel":"string"},{"type":"null","example":"open","uniqueKey":"data.status.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.status","typeLabel":"string | null"},"outcome":{"oneOf":[{"type":"string","description":"A disposition key, or null.","example":"won","uniqueKey":"data.outcome.oneOf.0","typeLabel":"string"},{"type":"null","description":"A disposition key, or null.","example":"won","uniqueKey":"data.outcome.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.outcome","typeLabel":"string | null"},"summary":{"oneOf":[{"type":"string","uniqueKey":"data.summary.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"data.summary.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.summary","typeLabel":"string | null"},"sourceType":{"oneOf":[{"type":"string","example":"imessage","uniqueKey":"data.sourceType.oneOf.0","typeLabel":"string"},{"type":"null","example":"imessage","uniqueKey":"data.sourceType.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.sourceType","typeLabel":"string | null"},"channelId":{"oneOf":[{"type":"string","example":"chan_123","uniqueKey":"data.channelId.oneOf.0","typeLabel":"string"},{"type":"null","example":"chan_123","uniqueKey":"data.channelId.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.channelId","typeLabel":"string | null"},"startedAt":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"data.startedAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"data.startedAt.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.startedAt","typeLabel":"string\u003cdate-time> | null"},"endedAt":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"data.endedAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"data.endedAt.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.endedAt","typeLabel":"string\u003cdate-time> | null"},"createdAt":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"data.createdAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"data.createdAt.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.createdAt","typeLabel":"string\u003cdate-time> | null"},"updatedAt":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"data.updatedAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"data.updatedAt.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.updatedAt","typeLabel":"string\u003cdate-time> | null"},"messages":{"type":"array","items":{"type":"object","description":"A single transcript message.","properties":{"id":{"type":"string","example":"msg_123","isRequired":true,"uniqueKey":"data.messages.items.[INDEX].id","typeLabel":"string"},"text":{"type":"string","example":"On my way!","isRequired":true,"uniqueKey":"data.messages.items.[INDEX].text","typeLabel":"string"},"author":{"oneOf":[{"type":"string","description":"Display name of the sender.","example":"Jane Doe","uniqueKey":"data.messages.items.[INDEX].author.oneOf.0","typeLabel":"string"},{"type":"null","description":"Display name of the sender.","example":"Jane Doe","uniqueKey":"data.messages.items.[INDEX].author.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.messages.items.[INDEX].author","typeLabel":"string | null"},"authorId":{"oneOf":[{"type":"string","description":"Stable handle of the sender (phone, email, record id).","example":"+15551234567","uniqueKey":"data.messages.items.[INDEX].authorId.oneOf.0","typeLabel":"string"},{"type":"null","description":"Stable handle of the sender (phone, email, record id).","example":"+15551234567","uniqueKey":"data.messages.items.[INDEX].authorId.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.messages.items.[INDEX].authorId","typeLabel":"string | null"},"sourceType":{"oneOf":[{"type":"string","example":"imessage","uniqueKey":"data.messages.items.[INDEX].sourceType.oneOf.0","typeLabel":"string"},{"type":"null","example":"imessage","uniqueKey":"data.messages.items.[INDEX].sourceType.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.messages.items.[INDEX].sourceType","typeLabel":"string | null"},"direction":{"oneOf":[{"type":"string","enum":["inbound","outbound",null],"example":"inbound","uniqueKey":"data.messages.items.[INDEX].direction.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["inbound","outbound",null],"example":"inbound","uniqueKey":"data.messages.items.[INDEX].direction.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.messages.items.[INDEX].direction","typeLabel":"enum\u003cstring> | null"},"timestamp":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"data.messages.items.[INDEX].timestamp.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"data.messages.items.[INDEX].timestamp.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.messages.items.[INDEX].timestamp","typeLabel":"string\u003cdate-time> | null"}},"required":["id","text"],"uniqueKey":"data.messages.items.[INDEX]","typeLabel":"object"},"uniqueKey":"data.messages","typeLabel":"object[]"},"participants":{"type":"array","items":{"type":"object","description":"A conversation participant — a linked record or a guest.","properties":{"type":{"oneOf":[{"type":"string","enum":["record","guest","user",null],"example":"record","uniqueKey":"data.participants.items.[INDEX].type.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["record","guest","user",null],"example":"record","uniqueKey":"data.participants.items.[INDEX].type.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.participants.items.[INDEX].type","typeLabel":"enum\u003cstring> | null"},"name":{"oneOf":[{"type":"string","example":"Jane Doe","uniqueKey":"data.participants.items.[INDEX].name.oneOf.0","typeLabel":"string"},{"type":"null","example":"Jane Doe","uniqueKey":"data.participants.items.[INDEX].name.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.participants.items.[INDEX].name","typeLabel":"string | null"},"email":{"oneOf":[{"type":"string","example":"jane@acme.com","uniqueKey":"data.participants.items.[INDEX].email.oneOf.0","typeLabel":"string"},{"type":"null","example":"jane@acme.com","uniqueKey":"data.participants.items.[INDEX].email.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.participants.items.[INDEX].email","typeLabel":"string | null"},"recordId":{"oneOf":[{"type":"string","description":"Set only for a linked record.","example":"rec_123","uniqueKey":"data.participants.items.[INDEX].recordId.oneOf.0","typeLabel":"string"},{"type":"null","description":"Set only for a linked record.","example":"rec_123","uniqueKey":"data.participants.items.[INDEX].recordId.oneOf.1","typeLabel":"null"}],"uniqueKey":"data.participants.items.[INDEX].recordId","typeLabel":"string | null"}},"uniqueKey":"data.participants.items.[INDEX]","typeLabel":"object"},"uniqueKey":"data.participants","typeLabel":"object[]"}},"required":["id"],"uniqueKey":"data","typeLabel":"object"},"reqId":{"type":"string","description":"A per-request id (`req_…`). Quote it to support when reporting a problem.","example":"req_2a1f9c8e7b6d5","uniqueKey":"reqId","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"data":{"id":"conv_123","title":"Jane Doe","status":"open","outcome":"won","summary":"\u003cstring>","sourceType":"imessage","channelId":"chan_123","startedAt":"2023-11-07T05:31:56Z","endedAt":"2023-11-07T05:31:56Z","createdAt":"2023-11-07T05:31:56Z","updatedAt":"2023-11-07T05:31:56Z","messages":[{"id":"msg_123","text":"On my way!","author":"Jane Doe","authorId":"+15551234567","sourceType":"imessage","direction":"inbound","timestamp":"2023-11-07T05:31:56Z"}],"participants":[{"type":"record","name":"Jane Doe","email":"jane@acme.com","recordId":"rec_123"}]},"reqId":"req_2a1f9c8e7b6d5"}}},"exampleType":"generated"}},"exampleType":"generated"},"82143274-e00c-4118-ab6b-a0d75c4c27ef":{"description":"The API key is missing, unknown, inactive, or expired (`code: invalid_api_key`).","content":{"application/json":{"schema":{"type":"object","description":"The failure envelope. Every error carries a machine-readable `code` and the `reqId` of the failing request.","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"insufficient_scope","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"}},"required":["code"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"},"reqId":{"type":"string","description":"A per-request id (`req_…`). Quote it to support when reporting a problem.","example":"req_2a1f9c8e7b6d5","uniqueKey":"reqId","typeLabel":"string"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"invalid_api_key"},"reqId":"req_2a1f9c8e7b6d5"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_api_key"},"reqId":"req_2a1f9c8e7b6d5"}}},"exampleType":"examples"}},"exampleType":"examples"},"98d3c235-a23c-40fa-ac7f-783c6d3b5279":{"description":"The key lacks the scope this endpoint requires (`code: insufficient_scope`).","content":{"application/json":{"schema":{"type":"object","description":"The failure envelope. Every error carries a machine-readable `code` and the `reqId` of the failing request.","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"insufficient_scope","isRequired":true,"uniqueKey":"error.code","typeLabel":"string"}},"required":["code"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"},"reqId":{"type":"string","description":"A per-request id (`req_…`). Quote it to support when reporting a problem.","example":"req_2a1f9c8e7b6d5","uniqueKey":"reqId","typeLabel":"string"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"example":{"error":{"code":"insufficient_scope"},"reqId":"req_2a1f9c8e7b6d5"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"insufficient_scope"},"reqId":"req_2a1f9c8e7b6d5"}}},"exampleType":"examples"}},"exampleType":"examples"}},"security":{"969e856c-2093-48fd-9650-083e693332fa":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_...","description":"A Custral **secret** API key (`sk_…`), created in Settings → Applications. Sent as `Authorization: Bearer sk_…`. The `X-Api-Key: sk_…` header is also accepted and takes precedence. Never expose a secret key in a browser.","scopes":[],"schemeName":"ApiKey"}}},"servers":{"1973a696-1865-48ff-be0a-5b97a2fc45be":{"url":"https://api.custral.com","description":"Production"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","bearerFormat":"sk_...","description":"A Custral **secret** API key (`sk_…`), created in Settings → Applications. Sent as `Authorization: Bearer sk_…`. The `X-Api-Key: sk_…` header is also accepted and takes precedence. Never expose a secret key in a browser.","scopes":[],"schemeName":"ApiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"A Custral **secret** API key (`sk_…`), created in Settings → Applications. Sent as `Authorization: Bearer sk_…`. The `X-Api-Key: sk_…` header is also accepted and takes precedence. Never expose a secret key in a browser.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"ApiKey","name":"Authorization"}],"title":"ApiKey"}]},"originalFileLocation":"openapi-v1.json"},"subdomain":"custral","siteName":"Custral Docs","title":"Create a conversation - Custral Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-13T19:40:28.921Z","originalFileLocation":"api-reference/conversations/create-a-conversation.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=\"Create a conversation, optionally attaching participants and importing an initial transcript. Requires scope: conversations:write.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Custral Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/custral/zNw7VJKFFusEr-3b/_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/custral/zNw7VJKFFusEr-3b/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/custral/zNw7VJKFFusEr-3b/_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/custral/zNw7VJKFFusEr-3b/_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/custral/zNw7VJKFFusEr-3b/_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/custral/zNw7VJKFFusEr-3b/_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/custral/zNw7VJKFFusEr-3b/_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/custral/zNw7VJKFFusEr-3b/_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/custral/zNw7VJKFFusEr-3b/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create a conversation - Custral Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create a conversation, optionally attaching participants and importing an initial transcript. Requires scope: conversations:write.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Custral Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.custral.com/api-reference/conversations/create-a-conversation\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://custral.mintlify.app/images/og-docs.png\">\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=\"Create a conversation - Custral Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create a conversation, optionally attaching participants and importing an initial transcript. Requires scope: conversations:write.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://custral.mintlify.app/images/og-docs.png\">\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/custral/zNw7VJKFFusEr-3b/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Custral Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#5E7CFF\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.custral.com/api-reference/conversations/create-a-conversation\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/conversations/create-a-conversation.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.custral.com/#organization\",\"name\":\"Custral Docs\",\"url\":\"https://docs.custral.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/custral/9h_119tROzHTKUiS/assets/logos/light.svg?fit=max\u0026auto=format\u0026n=9h_119tROzHTKUiS\u0026q=85\u0026s=50b063929ddff7335cc4db8352ae694a\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.custral.com#website\",\"name\":\"Custral Docs\",\"url\":\"https://docs.custral.com\",\"publisher\":{\"@id\":\"https://docs.custral.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.custral.com/api-reference/conversations/create-a-conversation#webpage\",\"url\":\"https://docs.custral.com/api-reference/conversations/create-a-conversation\",\"name\":\"Create a conversation\",\"description\":\"Create a conversation, optionally attaching participants and importing an initial transcript. Requires scope: conversations:write.\",\"dateModified\":\"2026-10-13T19:40:28.921Z\",\"isPartOf\":{\"@id\":\"https://docs.custral.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.custral.com/api-reference/conversations/create-a-conversation#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.custral.com/api-reference/conversations/create-a-conversation#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://docs.custral.com/dev/api-reference/objects\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Widget identity\",\"item\":\"https://docs.custral.com/dev/api-reference/widget-identity\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Conversations\",\"item\":\"https://docs.custral.com/api-reference/conversations/list-conversations\"},{\"@type\":\"ListItem\",\"position\":4,\"name\":\"Create a conversation\",\"item\":\"https://docs.custral.com/api-reference/conversations/create-a-conversation\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.custral.com/api-reference/conversations/create-a-conversation#apireference\",\"headline\":\"Create a conversation\",\"name\":\"Create a conversation\",\"description\":\"Create a conversation, optionally attaching participants and importing an initial transcript. Requires scope: conversations:write.\",\"url\":\"https://docs.custral.com/api-reference/conversations/create-a-conversation\",\"mainEntityOfPage\":{\"@id\":\"https://docs.custral.com/api-reference/conversations/create-a-conversation#webpage\"},\"image\":\"https://docs.custral.com/images/og-docs.png\",\"dateModified\":\"2026-10-13T19:40:28.921Z\",\"publisher\":{\"@id\":\"https://docs.custral.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.custral.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Custral Docs\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Custral Docs","nav":{"global":null,"products":[{"product":"Documentation","icon":"book-open","pages":[{"title":"Documentation","href":"/start/introduction"}]},{"product":"Developer References","icon":"square-terminal","tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":"/dev/overview"}]},{"tab":"API Reference","groups":[{"group":"Introduction","pages":[{"title":"API Reference","sidebarTitle":"Introduction","icon":"code","href":"/dev/api-reference/overview"},{"title":"Authentication","sidebarTitle":"Authentication","icon":"key","href":"/dev/auth/overview"},{"title":"Requests \u0026 responses","sidebarTitle":"Requests \u0026 responses","icon":"right-left","href":"/dev/api-reference/requests"},{"title":"How the schema works","sidebarTitle":"How the schema works","icon":"sitemap","href":"/dev/api-reference/schema"},{"title":"Errors","sidebarTitle":"Errors","icon":"triangle-exclamation","href":"/dev/errors/overview"}]},{"group":"Endpoints","pages":[{"group":"Objects","pages":[{"title":"The Object object","sidebarTitle":"The Object object","tag":"OBJECT","href":"/dev/api-reference/objects"},{"title":"List objects","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/objects","href":"/api-reference/objects/list-objects"},{"title":"Retrieve an object","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/objects/{id}","href":"/api-reference/objects/retrieve-an-object"}]},{"group":"Records","pages":[{"title":"The Record object","sidebarTitle":"The Record object","tag":"OBJECT","href":"/dev/api-reference/records"},{"title":"List records","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/records/{object}","href":"/api-reference/records/list-records"},{"title":"Retrieve a record","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/records/{object}/{id}","href":"/api-reference/records/retrieve-a-record"},{"title":"Create a record","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/records/{object}","href":"/api-reference/records/create-a-record"},{"title":"Create or update a record","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/records/{object}/upsert","href":"/api-reference/records/create-or-update-a-record"},{"title":"Update a record","deprecated":null,"version":null,"openapi":"/openapi-v1.json patch /v1/records/{object}/{id}","href":"/api-reference/records/update-a-record"},{"title":"Run a record's AI auto-fills","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/records/{object}/{id}/enrich","href":"/api-reference/records/run-a-records-ai-auto-fills"}]},{"group":"Documents","pages":[{"title":"The Document object","sidebarTitle":"The Document object","tag":"OBJECT","href":"/dev/api-reference/documents"},{"title":"Retrieve a document","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/documents/{id}","href":"/api-reference/documents/retrieve-a-document"},{"title":"Update a document","deprecated":null,"version":null,"openapi":"/openapi-v1.json patch /v1/documents/{id}","href":"/api-reference/documents/update-a-document"}]},{"group":"Widget identity","pages":[{"title":"Widget visitor identity","sidebarTitle":"Widget identity","tag":"WIDGET","href":"/dev/api-reference/widget-identity"},{"group":"Identity","pages":[{"title":"Introspect the current key","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/me","href":"/api-reference/identity/introspect-the-current-key"}]},{"group":"Objects","pages":[{"title":"List objects","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/objects","href":"/api-reference/objects/list-objects"},{"title":"Retrieve an object","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/objects/{id}","href":"/api-reference/objects/retrieve-an-object"}]},{"group":"Records","pages":[{"title":"List records","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/records/{object}","href":"/api-reference/records/list-records"},{"title":"Create a record","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/records/{object}","href":"/api-reference/records/create-a-record"},{"title":"Create or update a record","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/records/{object}/upsert","href":"/api-reference/records/create-or-update-a-record"},{"title":"Retrieve a record","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/records/{object}/{id}","href":"/api-reference/records/retrieve-a-record"},{"title":"Update a record","deprecated":null,"version":null,"openapi":"/openapi-v1.json patch /v1/records/{object}/{id}","href":"/api-reference/records/update-a-record"},{"title":"Run a record's AI auto-fills","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/records/{object}/{id}/enrich","href":"/api-reference/records/run-a-records-ai-auto-fills"}]},{"group":"Conversations","pages":[{"title":"List conversations","description":"List conversations (offset pagination, newest first). List rows omit `messages` and `participants`. **Requires scope:** `conversations:read`.","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/conversations","href":"/api-reference/conversations/list-conversations"},{"title":"Create a conversation","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/conversations","href":"/api-reference/conversations/create-a-conversation"},{"title":"Retrieve a conversation","description":"Fetch one conversation with its transcript (`messages`) and `participants`. **Requires scope:** `conversations:read`.","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/conversations/{id}","href":"/api-reference/conversations/retrieve-a-conversation"},{"title":"Update status \u0026 outcome","deprecated":null,"version":null,"openapi":"/openapi-v1.json patch /v1/conversations/{id}","href":"/api-reference/conversations/update-status-\u0026-outcome"},{"title":"Append a message","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/conversations/{id}/messages","href":"/api-reference/conversations/append-a-message"},{"title":"List dispositions","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/dispositions","href":"/api-reference/conversations/list-dispositions"}]},{"group":"Property agents","pages":[{"title":"List auto-fill agents","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/property-agents","href":"/api-reference/property-agents/list-auto-fill-agents"},{"title":"Set up auto-fill on a property","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/property-agents","href":"/api-reference/property-agents/set-up-auto-fill-on-a-property"},{"title":"Retrieve an auto-fill agent","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/property-agents/{id}","href":"/api-reference/property-agents/retrieve-an-auto-fill-agent"},{"title":"Delete an auto-fill agent","deprecated":null,"version":null,"openapi":"/openapi-v1.json delete /v1/property-agents/{id}","href":"/api-reference/property-agents/delete-an-auto-fill-agent"},{"title":"Update an auto-fill agent","deprecated":null,"version":null,"openapi":"/openapi-v1.json patch /v1/property-agents/{id}","href":"/api-reference/property-agents/update-an-auto-fill-agent"}]},{"group":"MCP","pages":[{"title":"List MCP tools","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/mcp/tools","href":"/api-reference/mcp/list-mcp-tools"}]},{"group":"Documents","pages":[{"title":"Retrieve a document","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/documents/{id}","href":"/api-reference/documents/retrieve-a-document"},{"title":"Update a document","deprecated":null,"version":null,"openapi":"/openapi-v1.json patch /v1/documents/{id}","href":"/api-reference/documents/update-a-document"}]},{"group":"Usage modules","pages":[{"title":"List usage modules","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/usage-modules","href":"/api-reference/usage-modules/list-usage-modules"},{"title":"Create a usage module","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/usage-modules","href":"/api-reference/usage-modules/create-a-usage-module"},{"title":"Retrieve a usage module","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/usage-modules/{id}","href":"/api-reference/usage-modules/retrieve-a-usage-module"},{"title":"List unmatched usage","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/usage-modules/{id}/unmatched","href":"/api-reference/usage-modules/list-unmatched-usage"},{"title":"List usage events","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/usage-modules/{id}/events","href":"/api-reference/usage-modules/list-usage-events"},{"title":"Usage of a product, by customer","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/records/{object}/{id}/usage/by-customer","href":"/api-reference/usage-modules/usage-of-a-product-by-customer"},{"title":"Usage of a customer, by product","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/records/{object}/{id}/usage/by-product","href":"/api-reference/usage-modules/usage-of-a-customer-by-product"}]},{"group":"Connectors","pages":[{"title":"List connectors","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/connectors","href":"/api-reference/connectors/list-connectors"},{"title":"Add a custom connector","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/connectors","href":"/api-reference/connectors/add-a-custom-connector"},{"title":"Remove a custom connector","deprecated":null,"version":null,"openapi":"/openapi-v1.json delete /v1/connectors/{id}","href":"/api-reference/connectors/remove-a-custom-connector"}]}]},{"group":"Conversations","pages":[{"title":"The Conversation object","sidebarTitle":"The Conversation object","tag":"OBJECT","href":"/dev/api-reference/conversations"},{"title":"List conversations","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/conversations","href":"/api-reference/conversations/list-conversations"},{"title":"Retrieve a conversation","description":"Fetch one conversation with its transcript (`messages`) and `participants`. **Requires scope:** `conversations:read`.","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/conversations/{id}","href":"/api-reference/conversations/retrieve-a-conversation"},{"title":"Create a conversation","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/conversations","href":"/api-reference/conversations/create-a-conversation"},{"title":"Update status \u0026 outcome","description":"Set a conversation's `status` and/or `outcome` directly — the value you send is the value that sticks (no re-analysis). **Requires scope:** `conversations:write`.","deprecated":null,"version":null,"openapi":"/openapi-v1.json patch /v1/conversations/{id}","href":"/api-reference/conversations/update-status-\u0026-outcome"},{"title":"Append a message","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/conversations/{id}/messages","href":"/api-reference/conversations/append-a-message"},{"title":"List dispositions","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/dispositions","href":"/api-reference/conversations/list-dispositions"}]},{"group":"Property agents","pages":[{"title":"The Property Agent object","sidebarTitle":"The Property Agent object","tag":"OBJECT","href":"/dev/api-reference/property-agents"},{"title":"List auto-fill agents","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/property-agents","href":"/api-reference/property-agents/list-auto-fill-agents"},{"title":"Retrieve an auto-fill agent","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/property-agents/{id}","href":"/api-reference/property-agents/retrieve-an-auto-fill-agent"},{"title":"Set up auto-fill on a property","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/property-agents","href":"/api-reference/property-agents/set-up-auto-fill-on-a-property"},{"title":"Update an auto-fill agent","deprecated":null,"version":null,"openapi":"/openapi-v1.json patch /v1/property-agents/{id}","href":"/api-reference/property-agents/update-an-auto-fill-agent"},{"title":"Delete an auto-fill agent","deprecated":null,"version":null,"openapi":"/openapi-v1.json delete /v1/property-agents/{id}","href":"/api-reference/property-agents/delete-an-auto-fill-agent"}]},{"group":"Connectors","pages":[{"title":"The Connector object","sidebarTitle":"The Connector object","tag":"OBJECT","href":"/dev/api-reference/connectors"},{"title":"List connectors","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/connectors","href":"/api-reference/connectors/list-connectors"},{"title":"Add a custom connector","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/connectors","href":"/api-reference/connectors/add-a-custom-connector"},{"title":"Remove a custom connector","deprecated":null,"version":null,"openapi":"/openapi-v1.json delete /v1/connectors/{id}","href":"/api-reference/connectors/remove-a-custom-connector"}]},{"group":"Applications \u0026 keys","pages":[{"title":"Applications \u0026 keys","sidebarTitle":"Overview","icon":"key","href":"/dev/api-reference/applications"}]},{"group":"Identity \u0026 MCP","pages":[{"title":"Introspect the current key","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/me","href":"/api-reference/identity/introspect-the-current-key"},{"title":"List MCP tools","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/mcp/tools","href":"/api-reference/mcp/list-mcp-tools"}]},{"group":"Usage modules","pages":[{"title":"The Usage module object","sidebarTitle":"The Usage module object","tag":"USAGE MODULE","href":"/dev/api-reference/usage-modules"},{"title":"List usage modules","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/usage-modules","href":"/api-reference/usage-modules/list-usage-modules"},{"title":"Create a usage module","deprecated":null,"version":null,"openapi":"/openapi-v1.json post /v1/usage-modules","href":"/api-reference/usage-modules/create-a-usage-module"},{"title":"Retrieve a usage module","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/usage-modules/{id}","href":"/api-reference/usage-modules/retrieve-a-usage-module"},{"title":"List usage events","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/usage-modules/{id}/events","href":"/api-reference/usage-modules/list-usage-events"},{"title":"List unmatched usage","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/usage-modules/{id}/unmatched","href":"/api-reference/usage-modules/list-unmatched-usage"},{"title":"Usage of a product, by customer","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/records/{object}/{id}/usage/by-customer","href":"/api-reference/usage-modules/usage-of-a-product-by-customer"},{"title":"Usage of a customer, by product","deprecated":null,"version":null,"openapi":"/openapi-v1.json get /v1/records/{object}/{id}/usage/by-product","href":"/api-reference/usage-modules/usage-of-a-customer-by-product"}]},{"group":"Lists","pages":[{"title":"Lists","sidebarTitle":"Lists","tag":"LISTS","href":"/dev/api-reference/lists"}]},{"group":"Customer journeys","pages":[{"title":"Customer journeys","sidebarTitle":"Customer journeys","tag":"JOURNEY","href":"/dev/api-reference/journeys"}]},{"group":"Quotes","pages":[{"title":"The Quote object","sidebarTitle":"The Quote object","tag":"QUOTE","href":"/dev/api-reference/quotes"},{"title":"The Contract object","sidebarTitle":"The Contract object","tag":"CONTRACT","href":"/dev/api-reference/contracts"}]},{"group":"Billing","pages":[{"title":"Billing","sidebarTitle":"Billing","tag":"BILLING","href":"/dev/api-reference/billing"},{"title":"Products","sidebarTitle":"Products","tag":"BILLING","href":"/dev/api-reference/products"},{"title":"Plans","sidebarTitle":"Plans","tag":"BILLING","href":"/dev/api-reference/plans"}]}]},{"group":"Embeds \u0026 real-time","pages":[{"title":"Embed blocks","icon":"window-maximize","href":"/dev/embeds/overview"},{"title":"Real-time updates","sidebarTitle":"Real-time","icon":"bolt","href":"/dev/realtime/overview"}]}]},{"tab":"Webhooks","pages":[{"title":"Webhooks","href":"/dev/webhooks/overview"}]},{"tab":"SDKs \u0026 Tools","pages":[{"title":"SDKs \u0026 Tools","href":"/dev/sdks/overview"}]}]},{"product":"Product Updates","icon":"crystal-ball","pages":[{"title":"Product Updates","href":"/product/overview"}]},{"product":"Integrations","icon":"flask-gear","pages":[{"title":"Integrations","href":"/integrations/overview"}]}]},"basePath":"","title":"Create a conversation - Custral Docs","buildId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","deploymentId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","dynamics":["10e4515597","c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["BannerMarkdown-CX_qQQOL.js","dist-BTZUMDnx.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","clsx-xpJZXxdP.js","html-void-elements-mCSPHezU.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","OpenApiReferenceProvider-CS552b7R.js","utils-DDTCYAF2.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-De8ttokP.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-DrwRDvAh.js","snippetPresets-DtAN0nWx.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-D5rWArI6.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-O2i12wsz.js","shallow-DV8xABTt.js","getApiPlaygroundDisplay-DBZ0B5Jx.js","CodeSnippet-BVi0tPUX.js","CodeSnippets-CqASbIwY.js","Page-m07pfKpT.js","getPastedJson-DG9vsMS8.js","icon-CXzRSCr8.js","MethodPill-BdKVtEuX.js","DuplicateIcon-CZlmBrJI.js","createIcon-biFEUKPL.js","DynamicMarkdown-B54_zNBF.js","SectionHeading-DwwHK3Pt.js","axios-vUo_bRtp.js","Markdown-DfhCTwyA.js","AssistantPageLink-DqdKa2R4.js"]}