Errors return a non-2xx status with a message and often a code. See Errors.
Versioning
The version is in the path (/v1). Within a version we only make changes that do not break your integration, such as adding an endpoint or a response field. Ignore fields you do not recognise so those additions never break you. A breaking change is released as a new version, and announced in the changelog first.
Each endpoint page has a playground. Enter your key under Authorization, fill in the parameters and send a request.
The playground sends real requests with your key. Prefer a key that is limited to the scopes you are testing.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Cerium","colors":{"primary":"#4F46E5","light":"#818CF8","dark":"#4338CA"},"logo":{"light":"/images/logo-light.svg","dark":"/images/logo-dark.svg"},"favicon":"/images/favicon.svg","appearance":{"default":"system"},"navbar":{"links":[{"href":"mailto:support@usecerium.com","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://app.usecerium.com"}},"footer":{"socials":{}},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"hasAudioNarration":false,"customDomains":[],"gitSource":{"type":"github","owner":"local","repo":"local","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":"local","isBase":true},"buildId":"local","clientVersion":"0.0.4271"},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[],"googleFontsInlined":false,"isLoggedInCli":false},"customCss":[{"filePath":"style.css","content":"#content-area,.prose{font-size:0.9375rem;line-height:1.6}#content-area p,#content-area li{line-height:1.6}#page-title,h1#page-title{font-size:1.75rem;line-height:2.1rem;letter-spacing:-0.02em}#content-area h2{font-size:1.25rem;line-height:1.75rem;letter-spacing:-0.01em}#content-area h3{font-size:1.0625rem;line-height:1.5rem}#content-area h4{font-size:0.9375rem}#content-area .mt-2.text-lg,#page-description{font-size:1rem;line-height:1.5rem}#content-area code{font-size:0.85em}#content-area pre,#content-area pre code{font-size:0.8125rem;line-height:1.55}#content-area .callout,#content-area [data-component-part=\"callout\"]{font-size:0.875rem}#content-area a.card,#content-area .card{font-size:0.875rem}#sidebar,#table-of-contents{font-size:0.8125rem}#content-area table{font-size:0.875rem}"}]}
{"page":{"pagePath":"api-reference/introduction","slug":"/api-reference/introduction","pageMetadata":{"title":"API reference","description":"Base URL, authentication, versioning and conventions for every endpoint.","href":"/api-reference/introduction"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Base URL, authentication, versioning and conventions for every endpoint.\"\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,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`2`,id:`base-url`,children:`Base URL`}),`\n`,_jsx(CodeBlock,{numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`https://api.usecerium.com/v1`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[`All requests use HTTPS. Request and response bodies are JSON. Set `,_jsx(_components.code,{children:`Content-Type: application/json`}),` on requests with a body.`]}),`\n`,_jsx(Heading,{level:`2`,id:`authentication`,children:`Authentication`}),`\n`,_jsx(CodeBlock,{numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`Authorization: Bearer \u003cyour API key>`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[`See `,_jsx(_components.a,{href:`/authentication`,children:`Authentication`}),` for scopes. Each endpoint page names the scope it needs.`]}),`\n`,_jsx(Heading,{level:`2`,id:`endpoints`,children:`Endpoints`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Resource`}),_jsx(_components.th,{children:`Endpoints`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Customers`})}),_jsx(_components.td,{children:`Create or get, list, get, update, erase`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Conversations`})}),_jsx(_components.td,{children:`Start, list, get, close or reopen`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Messages`})}),_jsx(_components.td,{children:`List, send`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`responses`,children:`Responses`}),`\n`,_jsx(CodeBlock,{numberOfLines:`6`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`6`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Conversations retrieved successfully.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"status\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"success\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"data\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: [],`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"meta\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {}`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Errors return a non-2xx status with a `,_jsx(_components.code,{children:`message`}),` and often a `,_jsx(_components.code,{children:`code`}),`. See `,_jsx(_components.a,{href:`/guides/errors`,children:`Errors`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`versioning`,children:`Versioning`}),`\n`,_jsxs(_components.p,{children:[`The version is in the path (`,_jsx(_components.code,{children:`/v1`}),`). Within a version we only make changes that do not break your integration, such as adding an endpoint or a response field. `,_jsx(_components.strong,{children:`Ignore fields you do not recognise`}),` so those additions never break you. A breaking change is released as a new version, and announced in the `,_jsx(_components.a,{href:`/changelog`,children:`changelog`}),` first.`]}),`\n`,_jsx(Heading,{level:`2`,id:`conventions`,children:`Conventions`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Timestamps are ISO 8601 in UTC.`}),`\n`,_jsx(_components.li,{children:`Ids are opaque strings.`}),`\n`,_jsxs(_components.li,{children:[`Empty values are `,_jsx(_components.code,{children:`null`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Lists are newest first. See `,_jsx(_components.a,{href:`/guides/pagination`,children:`Pagination`}),`.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`try-it`,children:`Try it`}),`\n`,_jsxs(_components.p,{children:[`Each endpoint page has a playground. Enter your key under `,_jsx(_components.strong,{children:`Authorization`}),`, fill in the parameters and send a request.`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`The playground sends `,_jsx(_components.strong,{children:`real requests`}),` with your key. Prefer a key that is limited to the scopes you are testing.`]})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"API reference","description":"Base URL, authentication, versioning and conventions for every endpoint.","href":"/api-reference/introduction"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Base URL","slug":"base-url","depth":2,"children":[]},{"title":"Authentication","slug":"authentication","depth":2,"children":[]},{"title":"Endpoints","slug":"endpoints","depth":2,"children":[]},{"title":"Responses","slug":"responses","depth":2,"children":[]},{"title":"Versioning","slug":"versioning","depth":2,"children":[]},{"title":"Conventions","slug":"conventions","depth":2,"children":[]},{"title":"Try it","slug":"try-it","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"docs.usecerium.com","siteName":"Cerium","title":"API reference - Cerium","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"originalFileLocation":"api-reference/introduction.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=\"Base URL, authentication, versioning and conventions for every endpoint.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Cerium\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/favicons/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/favicons/favicon-32x32.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/favicons/favicon-16x16.png\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/favicons/favicon.ico\">\u003cmeta data-mint-head property=\"og:title\" content=\"API reference - Cerium\">\u003cmeta data-mint-head property=\"og:description\" content=\"Base URL, authentication, versioning and conventions for every endpoint.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Cerium\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://local./api-reference/introduction\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"http://docs.usecerium.com/_mintlify/og/api-reference/introduction.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=\"API reference - Cerium\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Base URL, authentication, versioning and conventions for every endpoint.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"http://docs.usecerium.com/_mintlify/og/api-reference/introduction.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=\"/favicons/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Cerium\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#4F46E5\">\u003clink data-mint-head rel=\"canonical\" href=\"https://local./api-reference/introduction\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/introduction.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Cerium\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Cerium\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/introduction.md","siteName":"Cerium","nav":{"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API reference","groups":[{"group":"Overview","pages":[{"title":"API reference","href":"/api-reference/introduction"}]},{"group":"Customers","pages":[{"title":"Create or get a customer","description":"Creates the customer, or returns the one you already sent, unchanged (`200`).\nThe same `externalId`, or the same `email`, is the same customer.\n\nA request whose `externalId` and `email` belong to two different customers is refused (`409`).\nA `device` sent with it is added; to change details use [Update a customer](/api-reference/customers/update-a-customer).\n\nRequired scope: `customers:write`.\n","openapi":"/openapi.yaml post /customers","href":"/api-reference/customers/create-or-get-a-customer"},{"title":"List customers","openapi":"/openapi.yaml get /customers","href":"/api-reference/customers/list-customers"},{"title":"Get a customer","openapi":"/openapi.yaml get /customers/{customerId}","href":"/api-reference/customers/get-a-customer"},{"title":"Update a customer","openapi":"/openapi.yaml patch /customers/{customerId}","href":"/api-reference/customers/update-a-customer"},{"title":"Erase a customer","openapi":"/openapi.yaml delete /customers/{customerId}","href":"/api-reference/customers/erase-a-customer"}]},{"group":"Conversations","pages":[{"title":"Start a conversation","openapi":"/openapi.yaml post /conversations","href":"/api-reference/conversations/start-a-conversation"},{"title":"List conversations","openapi":"/openapi.yaml get /conversations","href":"/api-reference/conversations/list-conversations"},{"title":"Get a conversation","openapi":"/openapi.yaml get /conversations/{conversationId}","href":"/api-reference/conversations/get-a-conversation"},{"title":"Close or reopen a conversation","openapi":"/openapi.yaml patch /conversations/{conversationId}","href":"/api-reference/conversations/close-or-reopen-a-conversation"}]},{"group":"Messages","pages":[{"title":"List messages in a conversation","openapi":"/openapi.yaml get /conversations/{conversationId}/messages","href":"/api-reference/messages/list-messages-in-a-conversation"},{"title":"Send a message","openapi":"/openapi.yaml post /conversations/{conversationId}/messages","href":"/api-reference/messages/send-a-message"}]}]}]},"basePath":"","title":"API reference - Cerium","buildId":"997e403e4737","dynamics":[],"chunks":[]}