Every API here is available over the APIs.io API and to AI agents over MCP.
{"openapi":"3.0.1","info":{"title":"dotCMS REST API","version":"3"},"servers":[{"url":"/","description":"dotCMS Server"}],"tags":[{"name":"AI","description":"AI-powered content generation and analysis endpoints"},{"name":"dotAuth","description":"OAuth/OIDC and SAML authentication: per-site configuration (SYSTEM_HOST is the global default) and headless OIDC token exchange"},{"name":"JavaScript","description":"JavaScript execution and server-side scripting"},{"name":"Bundle","description":"Content bundle management and deployment"},{"name":"Content Delivery","description":"Content retrieval and manipulation endpoints"},{"name":"Data Integrity","description":"Data integrity checking and conflict resolution"},{"name":"Content Type","description":"Content type definitions and schema management"},{"name":"Tag (v1)","description":"Legacy tag management endpoints (deprecated - use v2 TagResource instead)"},{"name":"Accessibility Agent","description":"Streaming a11y-fix agent proxy"},{"name":"Accessibility Checker","description":"Endpoints that perform operations related to validating accessibility in content."},{"name":"Content Analytics","description":"Proxy endpoints that forward analytics requests to the dot-ca-event-manager service."},{"name":"Announcements","description":"System announcements and notifications"},{"name":"Apps","description":"Third-party application integration and configuration"},{"name":"Authentication","externalDocs":{"description":"Additional Authentication API information","url":"https://www.dotcms.com/docs/latest/rest-api-authentication"}},{"name":"Browser Tree","description":"File and folder browser tree operations"},{"name":"System Configuration","description":"System configuration and company settings"},{"name":"Containers","description":"Endpoints for managing Container objects and their content"},{"name":"Content","description":"Endpoints for managing content and contentlets - the core data objects in dotCMS"},{"name":"getPagesContentTypes","description":"Returns the content types valid for a page based on the container/types on the layout"},{"name":"Folders","description":"Endpoints for managing folder structure and organization"},{"name":"Forms","description":"Form management and processing"},{"name":"Health","description":"Health management and monitoring endpoints for administrative dashboards"},{"name":"Search Index","description":"Elasticsearch index management and operations"},{"name":"Job Queue","description":"Endpoints for managing background jobs and job queues"},{"name":"Language","description":"Language configuration and management"},{"name":"Maintenance","description":"System maintenance and administration operations"},{"name":"Navigation","description":"Site navigation tree endpoints"},{"name":"Page","description":"Page rendering, layout management, and content operations","externalDocs":{"description":"Additional Page API information","url":"https://www.dotcms.com/docs/latest/page-rest-api-layout-as-a-service-laas"}},{"name":"Publishing","description":"Push publishing job management endpoints"},{"name":"Relationships","description":"Content relationship management"},{"name":"Site","description":"Site management, lifecycle, and configuration endpoints"},{"name":"Cache Management","description":"Cache provider management and operations"},{"name":"System Logging","description":"System logging configuration and management"},{"name":"System Monitoring","description":"System monitoring and health checks"},{"name":"Temporary Files","description":"Temporary file upload and management for content creation"},{"name":"Template","description":"Template CRUD, publish, archive, and layout management endpoints"},{"name":"Theme","description":"Theme browsing and management"},{"name":"Usage","description":"Provides business intelligence metrics for dashboard usage"},{"name":"Variants","description":"Endpoints for managing content variants"},{"name":"Templates","description":"Template design and management"},{"name":"Content Type Field","description":"Content type field definitions and configuration"},{"name":"Tags","description":"Content tagging and labeling"},{"name":"Administration","description":"System administration and management tools"},{"name":"API Token","description":"API token management and authentication","externalDocs":{"description":"Additional API token information","url":"https://www.dotcms.com/docs/latest/rest-api-authentication#APIToken"}},{"name":"Categories","description":"Content categorization and taxonomy"},{"name":"Cluster Management","description":"Cluster nodes and distributed system management"},{"name":"Content Report","description":"Content reporting and analytics"},{"name":"Environment","description":"Publishing environment management and configuration"},{"name":"Experiments","description":"A/B testing and experimentation management"},{"name":"File Assets","description":"File asset management and download operations"},{"name":"Internationalization","description":"Language management and localization"},{"name":"License","description":"License management and validation"},{"name":"Notifications","description":"User notifications and alerts management"},{"name":"OSGi Plugins","description":"OSGi plugin management and dynamic deployment"},{"name":"Permissions","description":"Permission management and access control"},{"name":"Personas","description":"Content persona management and targeting"},{"name":"Personalization","description":"Content personalization and persona management"},{"name":"Portlets","description":"Portlet management and administration"},{"name":"Push Publishing","description":"Remote content publishing and synchronization"},{"name":"Roles","description":"User role and permission management"},{"name":"Rules Engine","description":"Business rules and conditional logic management"},{"name":"SAML Authentication","description":"SAML SSO authentication and integration"},{"name":"Search","description":"Content search and query operations"},{"name":"Sites","description":"Multi-site management and configuration"},{"name":"System","description":"System-level operations and Redis management"},{"name":"System Storage","description":"Storage providers and data replication management"},{"name":"TailLog","description":"Server log file monitoring and real-time viewing"},{"name":"Testing","description":"Testing utilities and development endpoints"},{"name":"Themes","description":"Theme design and management"},{"name":"Tool Groups","description":"Administrative tool group management"},{"name":"Users","description":"User account management and administration"},{"name":"Versionables","description":"Version control and content archiving"},{"name":"VTL","description":"Velocity Template Language execution and rendering"},{"name":"Web Assets","description":"Web asset management and operations"},{"name":"Widgets","description":"Widget development and rendering"},{"name":"Workflow","description":"Endpoints that perform operations related to workflows.","externalDocs":{"description":"Additional Workflow API information","url":"https://www.dotcms.com/docs/latest/workflow-rest-api"}},{"name":"Elasticsearch Content Search","description":"Backend Elasticsearch search endpoints for portlet context"}],"paths":{"/api/v1/ai/providers":{"get":{"tags":["AI"],"summary":"List dotAI provider configuration metadata","description":"Returns, for every registered dotAI provider, the capabilities it supports (chat/embeddings/image) and the providerConfig fields each supported capability requires or accepts.","operationId":"listAiProviders","responses":{"200":{"description":"Provider metadata retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEntityAiProviderListView"}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{}}}}}},"/api/v1/ai/providers/test/{capability}":{"post":{"tags":["AI"],"summary":"Test a dotAI provider connection","description":"Builds the provider client for the given capability from the posted configuration and issues one minimal real request against the provider (a short chat reply, a one-line embedding, or a single test image). Masked credential fields (\"*****\") in the posted config are resolved against the real value already stored for siteId before testing. Returns success=false with a message on any validation or provider error rather than an HTTP error status, so the caller can always render the result.","operationId":"testAiProviderConnection","parameters":[{"name":"capability","in":"path","required":true,"schema":{"type":"string"}},{"name":"siteId","in":"query","schema":{"type":"string"}}],"requestBody":{"description":"Provider config section to test","content":{"application/json":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Test executed — check the success field for the outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEntityAiTestConnectionView"}}}},"400":{"description":"Unknown capability or malformed request body","content":{"application/json":{}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{}}},"403":{"description":"Forbidden - requires CMS admin, or access denied to site","content":{"application/json":{}}}}}},"/api/v1/ai/completions/config":{"get":{"tags":["AI"],"summary":"Get AI service configuration","description":"Retrieves the current AI service configuration. Accepts an optional siteId query parameter (site identifier / UUID, or the literal SYSTEM_HOST). Hostname values are not supported — use the site identifier. When siteId is omitted or cannot be resolved, falls back to the site derived from the HTTP Host header.","operationId":"getAiConfig","parameters":[{"name":"siteId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Configuration retrieved successfully","content":{"application/json":{"schema":{"type":"string"}}}},"401":{"description":"Unauthorized - User not authenticated"},"403":{"description":"Forbidden - User lacks permission for the requested site"},"500":{"description":"Internal server error"}}},"put":{"tags":["AI"],"summary":"Save AI provider configuration","description":"Saves the providerConfig JSON for the target site. Accepts an optional siteId query parameter (site identifier / UUID, or the literal SYSTEM_HOST). Hostname values are not supported — use the site identifier. When siteId is omitted, saves to the site derived from the HTTP Host header. An unresolvable siteId returns 400. Credential fields set to \"*****\" are preserved from the existing stored configuration. Requires CMS admin.","operationId":"saveAiConfig","parameters":[{"name":"siteId","in":"query","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Configuration saved successfully"},"400":{"description":"Missing or invalid request body, or site not found"},"403":{"description":"Forbidden - requires CMS admin or access denied to site"},"500":{"description":"Internal server error"}}}},"/api/v1/ai/completions/rawPrompt":{"post":{"tags":["AI"],"summary":"Generate AI completions from raw prompt","description":"Processes raw prompts directly through the AI service without content preprocessing. Supports both streaming and non-streaming responses.","operationId":"rawPrompt","requestBody":{"description":"Completion form with raw prompt and configuration","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CompletionsForm"}}}},"responses":{"200":{"description":"Raw completion generated successfully","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request - Missing or invalid prompt"},"401":{"description":"Unauthorized - User not authenticated"},"500":{"description":"Internal server error"}}}},"/api/v1/ai/completions":{"post":{"tags":["AI"],"summary":"Generate AI completions from content","description":"Creates AI-powered content summaries and completions based on provided prompts. Supports both streaming and non-streaming responses.","operationId":"summarizeFromContent","requestBody":{"description":"Completion form with prompt and configuration","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CompletionsForm"}}}},"responses":{"200":{"description":"Completion generated successfully","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request - Missing or invalid prompt"},"401":{"description":"Unauthorized - User not authenticated"},"500":{"description":"Internal server error"}}}},"/api/v1/ai/embeddings/count":{"get":{"tags":["AI"],"operationId":"count_1","parameters":[{"name":"site","in":"query","schema":{"type":"string"}},{"name":"contentType","in":"query","schema":{"type":"string"}},{"name":"indexName","in":"query","schema":{"type":"string"}},{"name":"language","in":"query","schema":{"type":"string"}},{"name":"identifier","in":"query","schema":{"type":"string"}},{"name":"inode","in":"query","schema":{"type":"string"}},{"name":"fieldVar","in":"query","schema":{"type":"string"}}],"responses":{"default":{"description":"default response","content":{"application/json":{}}}}},"post":{"tags":["AI"],"operationId":"count","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/CompletionsForm"}}}},"responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/ai/embeddings":{"post":{"tags":["AI"],"operationId":"embed","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/EmbeddingsForm"}}}},"responses":{"default":{"description":"default response","content":{"application/json":{}}}}},"delete":{"tags":["AI"],"operationId":"delete","requestBody":{"content":{"*/*":{"schema":{"type":"object","properties":{"asMap":{"type":"object","additionalProperties":{"type":"object"}},"empty":{"type":"boolean"}},"additionalProperties":{"type":"object"}}}}},"responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/ai/embeddings/db":{"delete":{"tags":["AI"],"operationId":"dropAndRecreateTables","requestBody":{"content":{"*/*":{"schema":{"type":"object","properties":{"asMap":{"type":"object","additionalProperties":{"type":"object"}},"empty":{"type":"boolean"}},"additionalProperties":{"type":"object"}}}}},"responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/ai/embeddings/indexCount":{"get":{"tags":["AI"],"operationId":"indexCount","responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/ai/embeddings/test":{"get":{"tags":["AI"],"operationId":"textResource","responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/ai/image/generate":{"get":{"tags":["AI"],"operationId":"indexByInode_1","parameters":[{"name":"prompt","in":"query","schema":{"type":"string"}}],"responses":{"default":{"description":"default response","content":{"application/json":{}}}}},"post":{"tags":["AI"],"operationId":"handleImageRequest","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/AIImageRequestDTO"}}}},"responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/ai/image/test":{"get":{"tags":["AI"],"operationId":"indexByInode","responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/ai/search/related":{"get":{"tags":["AI"],"operationId":"relatedByGet","parameters":[{"name":"language","in":"query","schema":{"type":"integer","format":"int64"}},{"name":"identifier","in":"query","schema":{"type":"string"}},{"name":"inode","in":"query","schema":{"type":"string"}},{"name":"indexName","in":"query","schema":{"type":"string"}},{"name":"fieldVar","in":"query","schema":{"type":"string"}}],"responses":{"default":{"description":"default response","content":{"application/json":{}}}}},"post":{"tags":["AI"],"operationId":"relatedByPost","requestBody":{"content":{"*/*":{"schema":{"type":"object","properties":{"asMap":{"type":"object","additionalProperties":{"type":"object"}},"empty":{"type":"boolean"}},"additionalProperties":{"type":"object"}}}}},"responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/ai/search":{"get":{"tags":["AI"],"operationId":"searchByGet","parameters":[{"name":"query","in":"query","schema":{"type":"string"}},{"name":"searchLimit","in":"query","schema":{"type":"integer","format":"int32","default":1000}},{"name":"searchOffset","in":"query","schema":{"type":"integer","format":"int32","default":0}},{"name":"site","in":"query","schema":{"type":"string"}},{"name":"contentType","in":"query","schema":{"type":"string"}},{"name":"indexName","in":"query","schema":{"type":"string","default":"default"}},{"name":"threshold","in":"query","schema":{"type":"number","format":"float","default":0.25}},{"name":"stream","in":"query","schema":{"type":"boolean","default":false}},{"name":"responseLength","in":"query","schema":{"type":"integer","format":"int32","default":1024}},{"name":"operator","in":"query","schema":{"type":"string","default":"<=>"}},{"name":"language","in":"query","schema":{"type":"string"}}],"responses":{"default":{"description":"default response","content":{"application/octet-stream":{},"application/json":{}}}}},"post":{"tags":["AI"],"operationId":"searchByPost","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/CompletionsForm"}}}},"responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/ai/search/test":{"get":{"tags":["AI"],"operationId":"testResponse","responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/ai/text/generate":{"get":{"tags":["AI"],"operationId":"doGet","parameters":[{"name":"prompt","in":"query","schema":{"type":"string"}}],"responses":{"default":{"description":"default response","content":{"application/json":{}}}}},"post":{"tags":["AI"],"operationId":"doPost","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/CompletionsForm"}}}},"responses":{"default":{"description":"default response","content":{"application/json":{}}}}}},"/api/v1/dotauth/oauth/exchange":{"post":{"tags":["dotAuth"],"summary":"Exchange an OIDC id_token for a dotAuth session-ref","description":"Validates the caller-supplied id_token against the configured OIDC provider's JWKS (signature, iss, aud == our client_id, exp, nonce), resolves or JIT-provisions the matching dotCMS user, and returns an opaque session-ref bound to that user.","operationId":"exchange","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthExchangeForm"}}}},"responses":{"200":{"description":"Token exchange succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEntityOAuthExchangeView"}}}},"400":{"description":"Malformed payload or non-OIDC provider configured"},"401":{"description":"id_token failed validation (signature, iss, aud, exp, or nonce)"},"403":{"description":"Resolved dotCMS user exists but is not active"},"404":{"description":"Exchange endpoint not found"},"503":{"description":"OAuth is not configured for this site"}}},"options":{"tags":["dotAuth"],"operationId":"exchangePreflight","responses":{"default":{"description":"default response","content":{"*/*":{}}}}}},"/api/v1/dotauth/sites/{hostId}":{"get":{"tags":["dotAuth"],"summary":"Get the dotAuth configuration for a site","description":"Returns the protocol-specific configuration stored for the given hostId. Use the sentinel \"SYSTEM_HOST\" for the global default. When the host has no row of its own and the system default is configured, the response carries inherited=true and values holds the system defaults. Hidden secrets (e.g. clientSecret, privateKey) are masked as \"****\".","operationId":"getDotAuthConfig","parameters":[{"name":"hostId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Configuration retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEntityDotAuthConfigView"}}}},"401":{"description":"Authentication required"},"403":{"description":"User does not have permission to read this site"},"404":{"description":"Site not found"},"500":{"description":"Internal server error"}}},"put":{"tags":["dotAuth"],"summary":"Save (upsert) the dotAuth configuration for a site","description":"Writes the chosen protocol's secrets for the given hostId and deletes the other protocol's row for that host (mutual exclusion). Posting \"****\" on a hidden field preserves the stored value.","operationId":"saveDotAuthConfig","parameters":[{"name":"hostId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DotAuthConfigForm"}}}},"responses":{"200":{"description":"Configuration saved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEntityStringView"}}}},"400":{"description":"Invalid form payload"},"401":{"description":"Authentication required"},"403":{"description":"User does not have permission to edit this site"},"404":{"description":"Site not found"},"500":{"description":"Internal server error"}}},"delete":{"tags":["dotAuth"],"summary":"Clear the dotAuth configuration for a site","description":"Deletes both OAuth and SAML secret rows for the given hostId. On SYSTEM_HOST this removes the global default; non-system hosts fall back to inheriting from SYSTEM_HOST afterward.","operationId":"clearDotAuthConfig","parameters":[{"name":"hostId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Configuration cleared successfully"},"401":{"description":"Authentication required"},"403":{"description":"User does not have permission to edit this site"},"404":{"description":"Site not found"},"500":{"description":"Internal server error"}}}},"/api/v1/dotauth/headless":{"put":{"tags":["dotAuth"],"summary":"Save the system-level headless token-exchange configuration","description":"Writes headless config to SYSTEM_HOST. Headless config is system-wide (not per-site). SSO saves/deletes never affect it.","operationId":"saveDotAuthHeadlessConfig","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object"}}}}},"responses":{"200":{"description":"Headless config saved"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"},"500":{"description":"Internal server error"}}},"delete":{"tags":["dotAuth"],"summary":"Clear the system-level headless token-exchange configuration","description":"Deletes the headless config. SSO config is not affected.","operationId":"clearDotAuthHeadlessConfig","responses":{"204":{"description":"Headless config cleared"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permissions"},"500":{"description":"Internal server error"}}}},"/api/v1/dotauth/discover/oidc":{"post":{"tags":["dotAuth"],"summary":"Fetch and parse an OIDC discovery document","description":"Thin authenticated proxy used by the dotAuth portlet to populate issuer, endpoint, JWKS, and supported algorithm fields from a .well-known/openid-configuration URL.","operationId":"discoverDotAuthOidc","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object"}}}}},"responses":{"200":{"description":"Discovery document parsed successfully","content":{"application/json":{"schema":{"type":"object","description":"Parsed OIDC discovery fields: issuer, endpoints, JWKS URI, and signing algorithms"}}}},"400":{"description":"Missing or invalid discovery URL"},"401":{"description":"Authentication required"},"500":{"description":"Internal server error"}}}},"/api/v1/dotauth/export":{"post":{"tags":["dotAuth"],"summary":"Export all dotAuth AppSecrets","description":"Exports OAuth/OIDC, SAML, and headless dotAuth AppSecrets into one encrypted Apps export file.","operationId":"exportDotAuthAppSecrets","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object"}}}}},"responses":{"200":{"description":"Encrypted export file","content":{"application/octet-stream":{}}},"400":{"description":"Invalid password or no secrets configured"},"401":{"description":"Authentication required"},"403":{"description":"Admin access required"},"500":{"description":"Internal server error"}}}},"/api/v1/dotauth/fetch/saml-metadata":{"post":{"tags":["dotAuth"],"summary":"Fetch SAML IdP metadata XML from a URL","description":"Authenticated proxy that fetches SAML metadata XML from an IdP's metadata endpoint URL. Returns the raw XML as a string so the admin can review it before saving.","operationId":"fetchSamlMetadata","requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object"}}}}},"responses":{"200":{"description":"Metadata fetched successfully","content":{"application/json":{"schema":{"type":"object","description":"Object with a single 'xml' field containing the raw metadata XML"}}}},"400":{"description":"Missing or invalid metadata URL"},"401":{"description":"Authentication required"},"500":{"description":"Internal server error"}}}},"/api/v1/dotauth/saml/metadata/{hostId}":{"get":{"tags":["dotAuth"],"summary":"Download SAML SP metadata XML for a site","description":"Generates SAML Service Provider metadata XML for the given site. For inherited configs the certificate comes from the SYSTEM_HOST row, but the entity ID and ACS URL use the target site's hostname so the IdP can distinguish per-site requests.","operationId":"getSamlSpMetadata","parameters":[{"name":"hostId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SP metadata XML","content":{"application/xml":{}}},"401":{"description":"Authentication required"},"404":{"description":"No SAML configuration found for this site"},"500":{"description":"Internal server error"}}}},"/api/v1/dotauth/import":{"post":{"tags":["dotAuth"],"summary":"Import dotAuth AppSecrets","description":"Imports an encrypted Apps export file containing only OAuth/OIDC, SAML, and headless dotAuth AppSecrets.","operationId":"importDotAuthAppSecrets","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/FormDataMultiPart"}}}},"responses":{"200":{"description":"Import succeeded","content":{"application/json":{"schema":{"type":"object","description":"Import result with count of imported secrets"}}}},"400":{"description":"Invalid password, empty file, or non-dotAuth secrets in file"},"401":{"description":"Authentication required"},"403":{"description":"Admin access required"},"500":{"description":"Internal server error"}}}},"/api/v1/dotauth/sites":{"get":{"tags":["dotAuth"],"summary":"List all sites with their dotAuth status","description":"Returns the SYSTEM_HOST (global default) status plus a per-site list indicating whether each site has its own OAuth/SAML configuration, inherits from the system default, or is unconfigured.","operationId":"listDotAuthSites","responses":{"200":{"description":"Sites retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEntityDotAuthSitesView"}}}},"401":{"description":"Authentication required"},"403":{"description":"User does not have permission to access dotAuth"},"500":{"description":"Internal server error"}}}},"/api/v1/dotauth/sessionrefs/revoke":{"post":{"tags":["dotAuth"],"summary":"Revoke all dotAuth sessionRefs","description":"Flushes the dotAuth sessionRef cache. Existing browser sessions are not affected.","operationId":"revokeDotAuthSessionRefs","responses":{"200":{"description":"All session-refs revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEntityStringView"}}}},"401":{"description":"Authentication required"},"403":{"description":"Admin access required"},"500":{"description":"Internal server error"}}}},"/api/v1/dotauth/oauth/session":{"delete":{"tags":["dotAuth"],"summary":"Invalidate the caller's dotAuth session-ref","description":"Removes the session referenced by the Authorization: Bearer header from the in-memory session cache. Always returns 204 — unknown or missing refs are silently ignored so this is safe to call unconditionally on sign-out.","operationId":"logout","responses":{"204":{"description":"Session invalidated (or was unknown)"}}}},"/api/v1/dotsaml/login/{idpConfigId}":{"get":{"tags":["SAML Authentication"],"summary":"Initiate SAML login","description":"Initiates a SAML authentication request by redirecting the user to the Identity Provider (IDP) login screen. Requires IDP metadata to determine the SSO login endpoint.","operationId":"doLogin","parameters":[{"name":"idpConfigId","in":"path","description":"Identity Provider configuration ID (typically host ID)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SAML authentication request initiated successfully (no body)"},"400":{"description":"Bad request - invalid IDP configuration ID","content":{"application/json":{}}},"404":{"description":"IDP configuration not found or not enabled","content":{"application/json":{}}},"500":{"description":"Internal server error during SAML authentication initiation","content":{"application/json":{}}}}},"post":{"tags":["SAML Authentication"],"summary":"Process SAML login callback","description":"Handles the callback from the Identity Provider after successful authentication. Extracts user information from the SAML assertion and creates/logs in the user to dotCMS.","operationId":"processLogin","parameters":[{"name":"idpConfigId","in":"path","description":"Identity Provider configuration ID (typically host ID)","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"SAML assertion data from Identity Provider","content":{"application/xml":{},"application/x-www-form-urlencoded":{}},"required":true},"responses":{"200":{"description":"SAML login processed successfully - user logged in","content":{"text/html":{}}},"400":{"description":"Bad request - invalid SAML assertion or missing data","content":{"text/html":{}}},"401":{"description":"Unauthorized - SAML assertion validation failed","content":{"text/html":{}}},"404":{"description":"IDP configuration not found or not enabled","content":{"text/html":{}}},"500":{"description":"Internal server error during SAML login processing","content":{"text/html":{}}}}}},"/api/v1/dotsaml/logout/{idpConfigId}":{"get":{"tags":["SAML Authentication"],"summary":"Process SAML logout (GET)","description":"Processes a SAML logout request via GET method. Initiates logout flow and redirects to the configured logout endpoint or builds a logout URL based on the request.","operationId":"logoutGet","parameters":[{"name":"idpConfigId","in":"path","description":"Identity Provider configuration ID (typically host ID)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SAML logout processed successfully","content":{"text/html":{}}},"404":{"description":"IDP configuration not found or not enabled","content":{"text/html":{}}},"500":{"description":"Internal server error during logout processing","content":{"text/html":{}}}}},"post":{"tags":["SAML Authentication"],"summary":"Process SAML logout (POST)","description":"Processes a SAML logout request via POST method. Handles logout callbacks from the Identity Provider and redirects to the configured logout endpoint.","operationId":"logoutPost","parameters":[{"name":"idpConfigId","in":"path","description":"Identity Provider configuration ID (typically host ID)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SAML logout processed successfully","content":{"text/html":{}}},"404":{"description":"IDP configuration not found or not enabled","content":{"text/html":{}}},"500":{"description":"Internal server error during logout processing","content":{"text/html":{}}}}}},"/api/v1/dotsaml/metadata/{idpConfigId}":{"get":{"tags":["SAML Authentication"],"summary":"Get SAML metadata","description":"Renders the XML metadata for the SAML Service Provider configuration. This endpoint is only accessible by administrators and provides the metadata required for IDP configuration.","operationId":"metadata","parameters":[{"name":"idpConfigId","in":"path","description":"Identity Provider configuration ID (typically host ID)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"descript
# --- truncated at 32 KB (1020 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dotcms/refs/heads/main/openapi/dotcms-rest-api-openapi.json