Our Admin 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 Admin API that our entire
architecture relies upon.
OpenAPI Spec
This is the Fern-generated OpenAPI (v3) specification for the Admin 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.3971","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":{},"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":"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":"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":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"isAtlas":false,"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"admin-api/spec","slug":"/admin-api/spec","pageMetadata":{"title":"Specification","description":null,"href":"/admin-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 Admin 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 Admin API that our entire\narchitecture relies upon.`})}),_jsx(Card,{title:`OpenAPI Spec`,icon:`link`,href:`https://github.com/proficientai/js/blob/main/api/admin/openapi.yml`,children:_jsx(_components.p,{children:`This is the Fern-generated OpenAPI (v3) specification for the Admin 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":"/admin-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:50.098Z","originalFileLocation":"admin-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/admin-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=Admin+API\u0026amp;title=Specification\u0026amp;theme=e9955307109407130dbb3899\u0026amp;signature=cc9da703fae87287c91f670c8e4a4efd70988f130dd68caf93edf8361440b3a0\">\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=Admin+API\u0026amp;title=Specification\u0026amp;theme=e9955307109407130dbb3899\u0026amp;signature=cc9da703fae87287c91f670c8e4a4efd70988f130dd68caf93edf8361440b3a0\">\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/admin-api/spec\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/admin-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/admin-api/spec#webpage\",\"url\":\"https://docs.proficientai.com/admin-api/spec\",\"name\":\"Specification\",\"dateModified\":\"2026-01-06T22:48:50.098Z\",\"isPartOf\":{\"@id\":\"https://docs.proficientai.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.proficientai.com/admin-api/spec#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.proficientai.com/admin-api/spec#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Admin API\",\"item\":\"https://docs.proficientai.com/admin-api/intro\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Specification\",\"item\":\"https://docs.proficientai.com/admin-api/spec\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.proficientai.com/admin-api/spec#article\",\"headline\":\"Specification\",\"name\":\"Specification\",\"url\":\"https://docs.proficientai.com/admin-api/spec\",\"mainEntityOfPage\":{\"@id\":\"https://docs.proficientai.com/admin-api/spec#webpage\"},\"dateModified\":\"2026-01-06T22:48:50.098Z\",\"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","pages":[{"title":"Client API Reference","href":"/client-api/intro"}]},{"anchor":"Admin API Reference","icon":"rectangle-terminal","groups":[{"group":"Admin API","pages":[{"title":"Introduction","href":"/admin-api/intro"},{"title":"Authentication","description":"Use Bearer Authentication scheme","href":"/admin-api/auth"},{"title":"Specification","href":"/admin-api/spec"}]},{"group":"Agents","pages":[{"openapi":"admin-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":"/admin-api/agents/list"},{"openapi":"admin-openapi POST /agents","title":"Create an agent","href":"/admin-api/agents/create"},{"openapi":"admin-openapi GET /agents/{agent_id}","title":"Retrieve an agent","href":"/admin-api/agents/get"},{"openapi":"admin-openapi POST /agents/{agent_id}","title":"Update an agent","href":"/admin-api/agents/update"},{"openapi":"admin-openapi DELETE /agents/{agent_id}","title":"Delete an agent","href":"/admin-api/agents/delete"},{"openapi":"admin-openapi GET /agents/{agent_id}/config","title":"Retrieve agent configuration","href":"/admin-api/agents/get_config"},{"openapi":"admin-openapi POST /agents/{agent_id}/config","title":"Update agent configuration","href":"/admin-api/agents/update_config"},{"openapi":"admin-openapi POST /agents/{agent_id}/activate","title":"Activate an agent","href":"/admin-api/agents/activate"},{"openapi":"admin-openapi POST /agents/{agent_id}/deactivate","title":"Deactivate an agent","href":"/admin-api/agents/deactivate"}]},{"group":"Users","pages":[{"openapi":"admin-openapi GET /users","title":"List all users","href":"/admin-api/users/list"},{"openapi":"admin-openapi POST /users","title":"Create a user","href":"/admin-api/users/create"},{"openapi":"admin-openapi GET /users/{user_id}","title":"Retrieve a user","href":"/admin-api/users/get"},{"openapi":"admin-openapi POST /users/{user_id}","title":"Update a user","href":"/admin-api/users/update"},{"openapi":"admin-openapi DELETE /users/{user_id}","title":"Delete a user","href":"/admin-api/users/delete"}]}]},{"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_DFJrtvUi8HS5F9nkooKuDJsuD5BM","deploymentId":"dpl_DFJrtvUi8HS5F9nkooKuDJsuD5BM","dynamics":[],"chunks":[]}