Our Client API specification is defined in Fern, which is
a more powerful alternative to OpenAPI.
Fern definition allows us to produce fully type-safe code and brings a higher level of
reliability to our systems. We also have an OpenAPI spec, which is generated by Fern.
Fern Definition
This is where we define the interface of the Client API that our entire
architecture relies upon.
OpenAPI Spec
This is the Fern-generated OpenAPI (v3) specification for the Client API.
{"docsConfig":{"$schema":"https://mintlify.com/docs.json","theme":"mint","name":"Proficient AI Documentation","colors":{"primary":"#8535f0","light":"#5659f0","dark":"#5659f0"},"favicon":"/favicon.png","logo":{"light":"https://mintcdn.com/proficientai/FLSho9m8n9aeXKxf/logo/light.png?fit=max\u0026auto=format\u0026n=FLSho9m8n9aeXKxf\u0026q=85\u0026s=6689e8fc19bf2b816777d3c19dd24acc","dark":"https://mintcdn.com/proficientai/FLSho9m8n9aeXKxf/logo/dark.png?fit=max\u0026auto=format\u0026n=FLSho9m8n9aeXKxf\u0026q=85\u0026s=612c2a3f66e74b1825dde3f1097c771e","href":"https://proficientai.com"},"api":{"openapi":["admin-openapi.yml","client-openapi.yml"],"playground":{"display":"interactive"},"mdx":{"server":"https://api.proficientai.com","auth":{"method":"key","name":null}}},"background":{"image":"https://mintlify.s3.us-west-1.amazonaws.com/proficientai/images/bg.png","decoration":null,"color":{"light":"#f9f7fc","dark":"#14111C"}},"navbar":{"links":[{"label":"GitHub","href":"https://github.com/proficientai/js"}],"primary":{"type":"button","label":"Request Access","href":"https://proficientai.com/access"}},"footer":{"socials":{"discord":"https://discord.gg/DVbwTM8erb","github":"https://github.com/proficientai","twitter":"https://twitter.com/proficientai","linkedin":"https://linkedin.com/company/proficientai"}},"integrations":{"posthog":{"apiKey":"phc_9KnDgBFBrOLG4Sp9dbn6nVpighZAkNDbimz0CGib5Uo"}},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"proficientai","hasAudioNarration":false,"actualSubdomain":"proficientai","customDomains":["docs.proficientai.com"],"gitSource":{"type":"github","owner":"proficientai","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6a20c35512ef21155ee551bc","collectionId":"8b5d8ba7-4b73-472a-9401-c4dac5099a89","schemaVersion":"v2"},"entitlements":{},"buildId":"6a20c35512ef21155ee551bc:success","clientVersion":"0.0.3939","searchFilterCounts":[{"language":"default","tag":"Admin API Reference","count":17},{"language":"default","tag":"Client API Reference","count":16},{"language":"default","tag":"Agents","count":11},{"language":"default","tag":"Documentation","count":9},{"language":"default","tag":"Users","count":7},{"language":"default","tag":"Interactions","count":5},{"language":"default","tag":"Messages","count":4},{"language":"default","tag":"SDKs","count":4},{"language":"default","tag":"Admin API","count":3},{"language":"default","tag":"Client API","count":3}]},"assistantConfig":{},"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":"editor-v7-file-tree","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":"pause-universal-search-reconcile","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":"per-site-search-delta","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":"editor-private-page-search","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":"editor-nav-generations","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":"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":"editor-agent-model-picker","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":"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}],"isAtlas":false,"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"client-api/spec","slug":"/client-api/spec","pageMetadata":{"title":"Specification","description":null,"href":"/client-api/spec"},"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`,p:`p`,..._provideComponents(),...props.components},{Card,CardGroup}=_components;if(!Card)_missingMdxReference(`Card`,true);if(!CardGroup)_missingMdxReference(`CardGroup`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Our Client API specification is defined in `,_jsx(_components.a,{href:`https://buildwithfern.com`,children:`Fern`}),`, which is\n`,_jsx(_components.a,{href:`https://buildwithfern.com/docs/comparison-with-openapi`,children:`a more powerful alternative`}),` to OpenAPI.\nFern definition allows us to produce fully type-safe code and brings a higher level of\nreliability to our systems. We also have an OpenAPI spec, which is generated by Fern.`]}),`\n`,_jsxs(CardGroup,{cols:2,children:[_jsx(Card,{title:`Fern Definition`,icon:`link`,href:`https://github.com/proficientai/js/tree/main/fern/api/definition`,children:_jsx(_components.p,{children:`This is where we define the interface of the Client API that our entire\narchitecture relies upon.`})}),_jsx(Card,{title:`OpenAPI Spec`,icon:`link`,href:`https://github.com/proficientai/js/blob/main/api/client/openapi.yml`,children:_jsx(_components.p,{children:`This is the Fern-generated OpenAPI (v3) specification for the Client API.`})})]})]})}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":"Specification","description":null,"href":"/client-api/spec"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"subdomain":"proficientai","siteName":"Proficient AI Documentation","title":"Specification - Proficient AI Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-01-06T22:48:51.179Z","originalFileLocation":"client-api/spec.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=\"application-name\" content=\"Proficient AI Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/proficientai/UWEmv4sUfmm3I8jG/_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/proficientai/UWEmv4sUfmm3I8jG/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/proficientai/UWEmv4sUfmm3I8jG/_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/proficientai/UWEmv4sUfmm3I8jG/_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/proficientai/UWEmv4sUfmm3I8jG/_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/proficientai/UWEmv4sUfmm3I8jG/_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/proficientai/UWEmv4sUfmm3I8jG/_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/proficientai/UWEmv4sUfmm3I8jG/_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/proficientai/UWEmv4sUfmm3I8jG/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Specification - Proficient AI Documentation\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Proficient AI Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.proficientai.com/client-api/spec\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://proficientai.mintlify.app/_mintlify/api/og/v2?division=Client+API\u0026amp;title=Specification\u0026amp;theme=a3cd34458aa6cd48b49538c1\u0026amp;signature=932d017b44cf9d0511945ecc47951df6f702af8691362eedb0f326ba41c78d34\">\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=\"Specification - Proficient AI Documentation\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://proficientai.mintlify.app/_mintlify/api/og/v2?division=Client+API\u0026amp;title=Specification\u0026amp;theme=a3cd34458aa6cd48b49538c1\u0026amp;signature=932d017b44cf9d0511945ecc47951df6f702af8691362eedb0f326ba41c78d34\">\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/proficientai/UWEmv4sUfmm3I8jG/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Proficient AI Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#8535f0\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.proficientai.com/client-api/spec\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/client-api/spec.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.proficientai.com/#organization\",\"name\":\"Proficient AI Documentation\",\"url\":\"https://docs.proficientai.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/proficientai/FLSho9m8n9aeXKxf/logo/light.png?fit=max\u0026auto=format\u0026n=FLSho9m8n9aeXKxf\u0026q=85\u0026s=6689e8fc19bf2b816777d3c19dd24acc\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.proficientai.com#website\",\"name\":\"Proficient AI Documentation\",\"url\":\"https://docs.proficientai.com\",\"publisher\":{\"@id\":\"https://docs.proficientai.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.proficientai.com/client-api/spec#webpage\",\"url\":\"https://docs.proficientai.com/client-api/spec\",\"name\":\"Specification\",\"dateModified\":\"2026-01-06T22:48:51.179Z\",\"isPartOf\":{\"@id\":\"https://docs.proficientai.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.proficientai.com/client-api/spec#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.proficientai.com/client-api/spec#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Client API\",\"item\":\"https://docs.proficientai.com/client-api/intro\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Specification\",\"item\":\"https://docs.proficientai.com/client-api/spec\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.proficientai.com/client-api/spec#article\",\"headline\":\"Specification\",\"name\":\"Specification\",\"url\":\"https://docs.proficientai.com/client-api/spec\",\"mainEntityOfPage\":{\"@id\":\"https://docs.proficientai.com/client-api/spec#webpage\"},\"dateModified\":\"2026-01-06T22:48:51.179Z\",\"publisher\":{\"@id\":\"https://docs.proficientai.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.proficientai.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Proficient AI Documentation\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Proficient AI Documentation","nav":{"global":null,"anchors":[{"anchor":"Documentation","icon":"book-open","pages":[{"title":"Documentation","href":"/intro"}]},{"anchor":"Client API Reference","icon":"rectangle-terminal","groups":[{"group":"Client API","pages":[{"title":"Introduction","href":"/client-api/intro"},{"title":"Authentication","description":"Use request headers for authentication","href":"/client-api/auth"},{"title":"Specification","href":"/client-api/spec"}]},{"group":"Agents","pages":[{"openapi":"client-openapi GET /agents","title":"List all agents","description":"Returns a list of agents that belong to the current project. The agents are returned sorted by creation date, with the most recently created agents appearing first.","href":"/client-api/agents/list"},{"openapi":"client-openapi GET /agents/{agent_id}","title":"Retrieve an agent","href":"/client-api/agents/get"}]},{"group":"Interactions","pages":[{"openapi":"client-openapi GET /interactions","title":"List all interactions","href":"/client-api/interactions/list"},{"openapi":"client-openapi POST /interactions","title":"Create an interaction","href":"/client-api/interactions/create"},{"openapi":"client-openapi GET /interactions/{interaction_id}","title":"Retrieve an interaction","href":"/client-api/interactions/get"},{"openapi":"client-openapi POST /interactions/{interaction_id}","title":"Update an interaction","href":"/client-api/interactions/update"},{"openapi":"client-openapi DELETE /interactions/{interaction_id}","title":"Delete an interaction","href":"/client-api/interactions/delete"}]},{"group":"Messages","pages":[{"openapi":"client-openapi GET /messages","title":"List all messages in an interaction","href":"/client-api/messages/list"},{"openapi":"client-openapi POST /messages","title":"Create a message in an interaction","href":"/client-api/messages/create"},{"openapi":"client-openapi GET /messages/{message_id}","title":"Retrieve a message","href":"/client-api/messages/get"},{"openapi":"client-openapi POST /messages/{message_id}/ask","title":"Ask for a reply to a message","href":"/client-api/messages/ask"}]},{"group":"Users","pages":[{"openapi":"client-openapi GET /users/{user_id}","title":"Retrieve a user","href":"/client-api/users/get"},{"openapi":"client-openapi POST /users/{user_id}","title":"Update a user","href":"/client-api/users/update"}]}]},{"anchor":"Admin API Reference","icon":"rectangle-terminal","pages":[{"title":"Admin API Reference","href":"/admin-api/intro"}]},{"anchor":"Community \u0026 Support","href":"https://discord.gg/DVbwTM8erb","icon":"discord"},{"anchor":"GitHub","href":"https://github.com/proficientai/js","icon":"github"}]},"title":"Specification - Proficient AI Documentation","buildId":"dpl_5UDDZ9hnigTkoV7QtvQ39eUp84nu","deploymentId":"dpl_5UDDZ9hnigTkoV7QtvQ39eUp84nu","dynamics":[],"chunks":[]}