Theneo User Guide

Theneo Quickstart Guide - discover how Theneo can generate Stripe-like API docs

## Sections
• [Quickstart](https://app.theneo.io/theneo/quickstart/theneo-quickstart-guide/introduction.md): Get started with Theneo and publish your first API docs in minutes. Creating intuitive, detailed, and easy-to-navigate API documentation has never been easier. Theneo streamlines every step of the process, ensuring that your documentation is not only comprehensive but also interactive and user-friendly. Here's how you can quickly set up your project in Theneo. Getting Started To create and publish documentation in Theneo, you first need to create a Theneo account. If you don’t have an account yet, you can sign up for free . Create Your First Doc When you log into Theneo, start by adding a new project from the homepage. Your project could be an API reference, a developer guide, or any type of documentation you need. Give your project a title, select the appropriate workspace, and you're on your way. Uploading Your API Specification Theneo accommodates a wide array of API specifications, making it easy to get started regardless of whether you have an existing spec or not. If you're equipped with Swagger, OpenAPI, GraphQL, or another format, the upload process is designed to be straightforward and efficient. In case you don't have a spec ready, Theneo offers tools to help you create one from scratch. Use our intuitive interface to define your API endpoints directly within the platform. For additional guidance on creating or importing your spec and ensuring format compatibility, check out our guide. If you do not have a spec, do not worry you can define that in Theneo as well. Learn how to create a spec in Theneo. Selecting Your AI Co-Pilot Once your API specification is uploaded, you can harness the power of Theneo's AI Co-pilot to enrich your content. Decide whether you want the AI to fully generate the content, enhance what you've already created, or if you prefer to proceed without AI assistance. If you're looking to streamline the setup, simply click on "Quick Start" to bypass the customization and move directly to publishing. Setting Permissions and Fine-Tuning Your Project Set your project’s visibility and invite collaborators according to your workflow needs. With Theneo, you can start with a private project and go public when you're ready, seamlessly inviting others to contribute. Manage these settings at any time to fit your project’s development lifecycle. You can change project level permission and even set up advanced access management later in the project settings. Publish Utilize Theneo's editing suite for final adjustments before publishing. Preview to ensure everything is perfect and publish to make your documentation available to users. It’s documentation made simple, yet powerful and comprehensive Optional steps Edit the project Easily update and refine your project content in real-time. Preview changes See how your project will look before going live. Automate the flow Streamline your workflow with powerful automation tools. AI search Find answers instantly with intelligent AI-powered search.
• [API Import](https://app.theneo.io/theneo/quickstart/theneo-quickstart-guide/api-import.md): Theneo provides a robust and versatile solution for managing your API documentation. Whether you're starting from scratch or updating existing documentation, our platform supports a wide range of API formats and import methods to streamline your workflow. Supported API Formats & Collections Theneo supports the following API formats and specification types: REST SOAP GraphQL Async APIs We also support various API specification collections, ensuring smooth migration and integration with your existing tooling. Importing Your API Documentation 1. Getting Started with Importing If you do not have existing documentation in Theneo, you can begin by importing your API spec: From the Theneo Dashboard Using Theneo CLI (for local environment or automation) You can easily migrate and unify your API documentation into Theneo using either method. 2. Updating Existing Projects in the Editor If you already have a project in Theneo and want to update the API spec , you can do this directly from the Theneo Editor : Steps: Open the Editor and navigate to the Endpoints tab (above the left-side menu). Click "Import Collection" . Choose your preferred import method . Import Options Explained: Option Description Import Endpoints Only Imports only the endpoints from the uploaded file, without affecting your content. Append Sections Adds new content and endpoints from the uploaded file while keeping existing ones untouched. Merge Sections Combines new and existing documentation. You’ll choose how to handle conflicts: Keep old or new section descriptions Keep old or new parameter descriptions Overwrite Sections Replaces existing content and endpoints with those from the uploaded file. Use with caution. You can upload your spec via: File Link Postman Collection Raw Text Once confirmed, the changes will be reflected directly in the Editor. Automating Imports: CLI & GitHub Actions For developers preferring automation and CI/CD workflows, Theneo supports imports via: A. GitHub Actions Integration Automate documentation updates with GitHub: Setup: Create a workflow file named Theneo.yml in your repository under .github/workflows/ . Example: Theneo.yml YAML name: Update Documentation on: pull_request: branches: - main jobs: update-doc: name: Update Theneo Documentation runs-on: ubuntu-latest steps: - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event." - name: Checkout uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: "18" - name: Update Documentation on Theneo uses: Theneo-Inc/api-documentation@1.8.0 with: FILE_PATH: doc/api.yml PROJECT_SLUG: <project_slug> VERSION_SLUG: <version_slug> WORKSPACE_SLUG: <workspace_slug> SECRET: ${{secrets.SECRET}} AUTO_PUBLISH: true IMPORT_OPTION: merge_v2 PARAMETER_DESCRIPTION_MERGE_STRATEGY: keep_new SECTION_DESCRIPTION_MERGE_STRATEGY: keep_old INCLUDE_GITHUB_METADATA: true For more guidance, visit here . B. Theneo CLI Integration Use Theneo CLI for advanced import control. Basic Command theneo project import [options] Options: Option Description --project Specify the project slug --file or --link Import via file path or URL --postman-api-key / --postman-collection Import via Postman API --import-type Choose from: endpoints , overwrite , append , or merge_v2 --publish Auto-publish after import --workspace Workspace slug --projectVersion Version slug --keepOldParameterDescription Keep old parameter descriptions during merge --keepOldSectionDescription Keep old section descriptions during merge Example Command Bash Usage: theneo project import [options] Import updated documentation into Theneo using file, link or postman collection Note: Published document link has this pattern: https://app.theneo.io/<workspace-slug>/<project-slug>/<version-slug> Options: --project <project-slug> Specify the project slug to import updated documentation in -f, --file <file> API file path to import (eg: docs/openapi.yml) --link <link> API file URL to create project using it --postman-api-key <postman-api-key> Postman API Key (env: THENEO_POSTMAN_API_KEY) --postman-collection <postman-collection> Postman collection id, you can use multiple times --import-type <import-type> Indicates how should the new api spec be imported (choices: "endpoints", "overwrite", "append", "merge_v2") --publish Automatically publish the project (default: false) --workspace <workspace-slug> Workspace slug, where the project is located --projectVersion <version-slug> Project version slug to import to, if not provided then default version will be used --keepOldParameterDescription Additional flag during merging import option, it will keep old parameter descriptions --keepOldSectionDescription Additional flag during merging import option, it will keep old section descriptions --profile <string> Use a specific profile from your config file. -h, --help display help for command For more guidance, visit here . Theneo offers flexible import options for all types of users—from product managers updating documentation manually to developers automating the process with GitHub or CLI. Whether you're starting from scratch or maintaining existing documentation, Theneo makes it easy to import, manage, and publish your API specs with confidence.
• [Other Docs & User Guides](https://app.theneo.io/theneo/quickstart/theneo-quickstart-guide/other-docs-and-user-guides.md): Theneo isn't just for API documentation—it also empowers teams to create non-API documents , such as technical guides, onboarding docs, tutorials, help centers, product manuals, and more. Getting Started from the Theneo Dashboard Login to Theneo Dashboard Go to Theneo Dashboard and sign in with your workspace credentials. Create a New Project Click on "Create Project" from the dashboard. Select “Other Docs” On the project creation page, choose the "Other Docs" option instead of an API format. Pick Your Sections You’ll be prompted to choose section templates like: Introduction/Overview Prerequisites & Installation Sample Code & Tutorials Supported Libraries Usage & Integration Troubleshooting & Support You can customize, rename, and reorder these sections later. Editing Your Docs in Theneo Once the project is created, you have two ways to start working on your documentation: A. Use the Theneo Editor Enjoy a Notion- and Figma-like editing experience with: Rich text formatting Drag & drop content blocks Real-time editing and live preview Easy collaboration with teammates Everything you need to build modern documentation without writing a single line of code. B. Import Markdown Using Theneo CLI Prefer to write in Markdown and keep content locally? You can import Markdown files into Theneo using the CLI. CLI Usage theneo import [options] Options Option Description --project <project-slug> The slug of the project you want to update --workspace <workspace-slug> The workspace slug to use (defaults to your primary workspace) --dir <directory> Path to the directory containing your generated Markdown --publish Auto-publish the imported content (optional) --projectVersion <version-slug> The version slug of the project (optional) --profile <string> Use a specific CLI profile if configured -h , --help Show help and usage information Example Bash Usage: theneo import [options] Update theneo project from generated markdown directory Options: --project <project-slug> project slug --workspace <workspace-slug> Enter workspace slug where the project should be created in, if not present uses default workspace --dir <directory> Generated theneo project directory --publish Automatically publish the project (default: false) --projectVersion <version-slug> Version slug --profile <string> Use a specific profile from your config file. -h, --help display help for command For more information on setting up Theneo CLI, visit here Recommended Layout: Single Page Template For guides and other non-API docs , such as: Tutorials Onboarding walkthroughs Step-by-step how-tos We highly recommend using the Single Page Template. Why Choose the Single Page Template? Feature Benefit Modular Layout Each section appears on its own page for cleaner, more intuitive navigation. Improved Performance Only the requested page loads, speeding up performance — great for large docs. Clear Navigation & URLs Each section gets a unique URL, perfect for deep linking and sharing. Optimized for Guides Best suited for linear content such as step-by-step instructions or tutorials. Better Readability Reduces scrolling fatigue and offers a more focused, distraction-free experience. To learn more about this layout and how to activate it for your project, visit here
• [Themes & Templates](https://app.theneo.io/theneo/quickstart/theneo-quickstart-guide/themes.md): In Theneo, you can fully customize the appearance of your docs to align with your company’s branding—no coding required. To make styling easy and consistent, Theneo provides a set of predefined themes you can apply instantly. These themes control elements like: Fonts & typography Colors (text, background, buttons) Header and sidebar styles Accent colors and UI highlights Branding Customization Options You can further tailor your documentation by adjusting: Primary & secondary colors Logo & favicon Font styles Code block styling Custom CSS/JS (Advanced) Choosing a Documentation Template Theneo supports two layout templates for structuring your documentation: Single Page Template and Continuous Scrolling . You can choose the one that best fits your content and user experience goals. Single Page Template (Recommended for Guides & Tutorials) This layout breaks your documentation into modular sections. Best for: Step-by-step guides Tutorials Onboarding walkthroughs Help center-style docs Benefits: Cleaner navigation Improved performance (loads one section at a time) Unique URLs for deep linking Better readability and user focus 💡 Ideal for users creating non-API docs and guides. Footer Configuration To customize the footer in the Single Page Template , follow these steps: Navigate to Branding Settings from your Theneo dashboard. Go to the General Settings tab. Open the Footer Links section. Add, edit, or remove footer content — including: Social links Corporate URLs Custom web links relevant to your documentation This allows you to align your doc’s footer with your brand and link out to key resources for your users. Continuous Scrolling Template This is the traditional doc style where all content flows on one long page. Best for: Reference documentation Technical specs API overviews and lists Benefits : Seamless vertical reading Great for quick searching via browser Simpler document flow for smaller projects Switching Templates You can change the template at any time in your Project Settings : Go to Project Settings > Features Turn the Single Page Template toggle on or off There are a variety of themes and templates to choose from — giving you full control over how your docs look and feel. Solid Roboto Bloom Single Page Template Continues Scrolling
• [Migration](https://app.theneo.io/theneo/quickstart/theneo-quickstart-guide/migration.md): Migrating to Theneo is fast, simple, and fully supported. Whether you're coming from platforms like Swagger , Postman , ReadMe , Docusaurus , or any other API/documentation tool — Theneo makes it easy to bring your content over and elevate it with our powerful features. Easy Migration Process From Swagger Postman Readme Docusaurus You can migrate: API specs (OpenAPI, Swagger, Postman Collections, etc.) Markdown content (guides, tutorials, onboarding flows) Full documentation projects from other platforms Migration Assistance & Best Practices As part of our Annual Growth Package , the Theneo team offers: End-to-end migration assistance Personalized suggestions to improve your docs using Theneo’s smart tools Optimization support for readability, structure, and performance Need Help Migrating? For custom migration cases or platform-specific needs, contact us at hello@theneo.io — we’ll evaluate your current setup and provide tailored migration assistance.
• [Markdown support](https://app.theneo.io/theneo/quickstart/theneo-quickstart-guide/markdown-support.md): Theneo provides robust markdown support both within the editor and through CLI-based markdown imports, enabling flexible documentation creation and management workflows. In-Editor Markdown Support Standard Markdown Formatting Theneo's editor supports all standard markdown formatting including: Headers (H1-H6) Bold and italic text Inline code and code blocks with syntax highlighting Lists (ordered and unordered) Links and images Tables Blockquotes Horizontal rules Theneo Custom Widgets Beyond standard markdown, Theneo provides custom widgets that enhance API documentation with interactive elements. These widgets enable rich content presentation directly within your markdown files. Code Blocks with Enhanced Features Markdown <CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"bash","label":"Bash"}'> <CodeLine>npm install -g @theneo/cli@latest</CodeLine> </CodeBlock> Interactive Accordions Plain text <Accordion attributes='{"style":{"width":"100%"}}'> <AccordionItem title="Authentication" iconUrl=""> <p>Your authentication content here</p> </AccordionItem> </Accordion> Callout Blocks Plain text <Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%"}}'> Important information for your users </Callout> These widgets can be combined with standard markdown to create comprehensive, interactive API documentation that enhances developer experience. Importing Markdown Folders Theneo CLI provides powerful capabilities for managing documentation through markdown files, enabling version control and collaborative workflows. Installation Plain text npm install -g @theneo/cli@latest Project Structure Requirements To import markdown folders into Theneo, your project must follow a specific structure: Plain text your-documentation/ ├── theneo.json ├── introduction/ │ ├── index.md │ └── section.json ├── getting-started/ │ ├── index.md │ └── section.json ├── api-reference/ │ ├── index.md │ ├── section.json │ └── endpoints/ │ ├── create-customer/ │ │ ├── index.md │ │ └── section.json │ └── get-customer/ │ ├── index.md │ └── section.json Configuration Files theneo.json - Project Structure Definition The theneo.json file defines the overall structure and hierarchy of your documentation: Plain text { "name": "Your API Documentation", "baseUrl": "https://api.yourdomain.com", "sections": [ { "name": "Introduction", "slug": "introduction", "icon": "6", "isHeader": false }, { "name": "Getting Started", "slug": "getting-started", "isHeader": true, "children": [ { "name": "Authentication", "slug": "getting-started/authentication", "icon": "5" } ] }, { "name": "API Reference", "slug": "api-reference", "isHeader": true, "children": [ { "name": "Customer Management", "slug": "api-reference/customer-management", "children": [ { "name": "Create Customer", "slug": "api-reference/customer-management/create-customer" } ] } ] } ] } section.json - API Endpoint Definition For sections containing API endpoints, the section.json file defines request and response specifications: Plain text { "endpoints": { "method": "POST", "path": "/customers" }, "request": { "contentType": "application/json", "body": [ { "name": "given_name", "description": "The first name of the customer", "isRequired": true, "valueType": "string", "value": "John" }, { "name": "email_address", "description": "The email address of the customer", "isRequired": true, "valueType": "string", "value": "john@example.com" } ], "header": [ { "name": "Authorization", "description": "Bearer token for authentication", "isRequired": true, "valueType": "string", "value": "Bearer <access_token>" } ] }, "responses": [ { "statusCode": 200, "description": "Successful response", "contentType": "application/json", "body": [ { "name": "customer", "description": "The created customer object", "valueType": "object" } ] } ] } For sections without API endpoints (like introductory content), section.json can be an empty object {} . CLI Commands for Markdown Management Creating a New Project from Markdown Plain text theneo create --dir ./your-documentation --name "API Documentation" --workspace your-workspace Importing/Updating Existing Project Plain text theneo import --dir ./your-documentation --project your-project-slug --workspace your-workspace Exporting Project as Markdown Plain text theneo export --project your-project-slug --dir ./exported-docs Best Practices Version Control : Keep your markdown documentation in Git for version tracking and collaboration Consistent Structure : Maintain the required folder structure for seamless imports Modular Organization : Organize endpoints logically within nested folders Descriptive Names : Use clear, kebab-case slugs for sections and endpoints Complete Metadata : Ensure all section.json files contain complete API specifications Regular Sync : Use CI/CD pipelines to automatically sync documentation updates Example Workflow mkdir api-docs && cd api-docstouch theneo.json mkdir -p api-reference/customersecho "# Customer Management API" > api-reference/customers/index.mdecho '{}' > api-reference/customers/section.json theneo login --token your-api-keytheneo create --dir . --name "My API Docs" --publish # Make changes to your markdown filestheneo import --dir . --project your-project-slug --publish Advanced Features AI-Powered Description Generation When importing documentation, leverage AI to automatically generate or enhance descriptions: Plain text theneo project create --file ./openapi.json --generate-description fill Options: fill : Add descriptions where missing overwrite : Replace all existing descriptions no_generation : Skip AI generation (default) Multi-Environment Support - Only for Enterprise accounts Use profiles for different environments: Plain text theneo login --profile production --token prod-api-key theneo import --dir . --project api-docs --profile production Working with Complex API Structures For complex APIs with nested resources, organize your folder structure to mirror your API architecture: Plain text api-reference/ ├── customers/ │ ├── index.md │ ├── section.json │ ├── create/ │ │ ├── index.md │ │ └── section.json │ ├── retrieve/ │ │ ├── index.md │ │ └── section.json │ └── orders/ │ ├── index.md │ ├── section.json │ └── list/ │ ├── index.md │ └── section.json This structure translates to: /customers - Create Customer /customers/{id} - Retrieve Customer /customers/{id}/orders - List Customer Orders Troubleshooting Common Issues and Solutions Import fails with structure error : Verify theneo.json exists in root directory Ensure all section slugs match folder names exactly Check that each section folder contains index.md and section.json API endpoints not appearing : Confirm section.json contains valid endpoint configuration Validate JSON syntax in all configuration files Ensure method and path are correctly specified Markdown rendering issues : Use proper escaping for special characters Verify custom widget syntax matches documentation Test widgets individually before combining Authentication errors : Confirm API key is valid: theneo login --token your-api-key Check workspace permissions Verify profile configuration if using multiple environments Migration Guide From Static Markdown to Theneo If you have existing markdown documentation, follow these steps to migrate: Analyze current structure : Map your existing documentation to Theneo's section hierarchy Create theneo.json : Define your documentation structure Reorganize files : Move markdown files into the required folder structure Add section.json files : Define API endpoints where applicable Test import locally : Use theneo create --dir . --name "Test Import" Iterate and refine : Adjust structure based on import results From Other Documentation Platforms When migrating from platforms like Swagger UI, Redoc, or Postman: Export OpenAPI/Swagger spec if available Use Theneo's import feature : theneo project create --file openapi.json Export as markdown : theneo export --project your-project --dir ./markdown Customize markdown files with additional content Re-import with enhancements : theneo import --dir ./markdown --project your-project Integration with CI/CD GitHub Actions Example Plain text name: Deploy Documentation on: push: branches: [main] paths: - 'docs/**' jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Setup Node.js uses: actions/setup-node@v2 with: node-version: '16' - name: Install Theneo CLI run: npm install -g @theneo/cli@latest - name: Deploy to Theneo env: THENEO_API_KEY: ${{ secrets.THENEO_API_KEY }} run: | theneo import \ --dir ./docs \ --project ${{ vars.THENEO_PROJECT }} \ --workspace ${{ vars.THENEO_WORKSPACE }} \ --publish GitLab CI Example Plain text deploy-docs: stage: deploy image: node:16 script: - npm install -g @theneo/cli@latest - theneo login --token $THENEO_API_KEY - theneo import --dir ./docs --project $THENEO_PROJECT --publish only: - main when: manual Conclusion Theneo's markdown support provides a flexible, developer-friendly approach to API documentation. Whether you prefer working directly in the editor with custom widgets or managing documentation as code through the CLI, Theneo adapts to your workflow while maintaining professional, interactive documentation. For more information and updates, visit: Theneo CLI GitHub Repository NPM Package
• [API Specs & Supported Formats](https://app.theneo.io/theneo/quickstart/api-reference/supported-apis.md): Theneo provides a robust and versatile range of API formats and collection types to cater to a wide array of integration and development needs. Our platform supports various API formats, including REST, SOAP, GraphQL, and Async APIs, each tailored to different use cases and requirements. Additionally, we offer compatibility with multiple API specification collections, ensuring seamless integration and a streamlined development process. Below is an overview of the supported formats and collections. REST API REST (Representational State Transfer) APIs are widely used due to their simplicity and statelessness. SOAP API SOAP (Simple Object Access Protocol) APIs are a protocol standard for web services that enable the exchange of structured information. GraphQL GraphQL is a powerful data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data. Postman Collection Theneo offers seamless integration with Postman, making it possible to import your Postman collections into Theneo. Custom SDK The Custom SDK Import feature in Theneo allows users to integrate their own SDKs for use within the platform. Theneo Custom Metadata Theneo allows you to import extra configurations from OpenAPI using the `x-theneo-metadata` attribute.
  • [REST API](https://app.theneo.io/theneo/quickstart/api-reference/supported-apis/rest-api.md): REST (Representational State Transfer) APIs are widely used due to their simplicity and statelessness. Theneo supports REST APIs through various collection formats, ensuring compatibility and ease of integration. Supported Collections for REST APIs OpenAPI 3.0 and 3.1: These specifications enable the definition of a REST API, including endpoints, methods, responses, and more, providing a comprehensive and standardized approach to RESTful services. ⬇️ Download a sample file Swagger 2: A predecessor to OpenAPI, Swagger 2 allows for detailed API definitions and includes tools for auto-generating documentation, client SDKs, and more. 💾 Download a sample file Postman Collections: Widely used for API testing, Postman collections allow you to define requests, tests, and scripts for API endpoints. ⬇️ Download a sample file Insomnia Collections: Similar to Postman, Insomnia offers a platform for API design and testing, with an emphasis on simplicity and a clean interface. ⬇️ Download a sample file On the right side, you can see what an example REST API looks like. and below you should see how we automatically render the request and response descriptions. While these are automatically rendered you can also turn them off → see article Below and right API request examples and responses are all fake, just for demo purposes
  • [SOAP API](https://app.theneo.io/theneo/quickstart/api-reference/supported-apis/soap-api.md): SOAP (Simple Object Access Protocol) APIs are a protocol standard for web services that enable the exchange of structured information. Theneo supports SOAP APIs through a variety of collection formats, which ensures comprehensive interoperability and integration capabilities. Supported Collections for SOAP APIs HAR (HTTP Archive format): This file format records the web requests and responses that your SOAP API makes. It's incredibly useful for reproducing and debugging issues. ⬇️ Download a sample file WSDL (Web Services Description Language): WSDL is an XML-based protocol for information exchange in decentralized and distributed environments. Theneo fully supports WSDL for defining network services as sets of endpoints operating on messages. ⬇️ Download a sample file On the right side, you can see an example SOAP request and the corresponding WSDL file structure. Below you can see how we automatically render the SOAP envelope and its headers, including the action and body content. You can also toggle to view the raw XML.
  • [GraphQL](https://app.theneo.io/theneo/quickstart/api-reference/supported-apis/graphql.md): GraphQL is a powerful data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data. Theneo's GraphQL API support allows clients to request exactly what they need and nothing more, making it easier to evolve APIs over time. Simply import a .graphql spec and let Theneo parse the entire doc. ⬇️ Download a sample file Sample GraphQL doc How we parse and output the GraphQL spec Theneo's GraphQL API support provides a structured way to define and interact with your data. The schema you see is automatically parsed by Theneo to facilitate clear and efficient data retrieval and manipulation. Here's an in-depth look at the key components of a GraphQL schema and their importance: Query Definition: A Query is a read-only fetch operation to request data from your GraphQL server. It's akin to performing a GET request in a REST API. Theneo's Parsing: Theneo interprets the Query type definitions to allow clients to make requests for specific data. The weeklyAdventure query is automatically grouped under the Query category in the API reference documentation, showcasing its available parameters and return type. Mutation Definition: Mutations are how you create, update, or delete data. This is similar to POST , PUT , PATCH , or DELETE in REST. Theneo's Parsing: Although not explicitly shown in the provided schema, any defined mutations would be parsed and displayed under this section, detailing how clients can modify data. Subscription Definition: Subscriptions maintain a steady connection to the server, allowing clients to receive real-time updates. Theneo's Parsing: Theneo would parse and categorize any subscriptions in the schema, explaining how clients can establish a persistent connection to listen for specific events. Objects Definition: GraphQL objects represent a list of named fields, each of which can return a specific type. They can be thought of as the building blocks of your GraphQL API. Theneo's Parsing: The schema's objects like WeeklyAdventure , TheneoHighlights , and HeroHighlight are parsed and displayed with their fields and respective types, indicating the shape of the data that clients can expect to receive. Scalars Definition: Scalars are primitive data types (e.g., Int , Float , String , Boolean ) that resolve to a single scalar object, and they are the leaves of the query. Theneo's Parsing: Theneo highlights these fundamental types in the schema, showcasing where they are used within object fields to define the type of data they represent. Directives Definition: Directives provide a way to dynamically alter the execution of a query or mutation. Theneo's Parsing: If any directives are used in the schema, Theneo would explain their use cases, such as conditionally including or skipping fields. Enums Definition: Enums are a special kind of scalar that is restricted to a particular set of allowed values. They validate that any arguments of that type are one of the allowed values. Theneo's Parsing: The Mood enum in the schema is parsed and documented, indicating the fixed set of options that can be used for fields of this type. Unions Definition: Unions are similar to interfaces but they can't specify any common fields between the types. Theneo's Parsing: If there were unions in the schema, Theneo would parse these and illustrate how they can be used to return an object that could be one of several types. Theneo GraphQL schema parsing feature automatically structures and documents these elements for developers to easily understand and interact with the API. Each component plays a crucial role in defining the capabilities and constraints of the API, ensuring a robust and flexible interface for interacting with data.
  • [Postman Collection](https://app.theneo.io/theneo/quickstart/api-reference/supported-apis/postman-collection.md): Theneo offers seamless integration with Postman, making it possible to import your Postman collections into Theneo for enhanced API documentation. Below is a straightforward guide to establishing this integration. Connecting Postman with Theneo You can integrate your Postman collections with Theneo during two key phases: When creating a new project When editing an existing project A Creating a new project with Postman integration Start a New Project: Navigate to the Theneo dashboard and click on "Create Project." Connect to Postman: Select "Connect to Postman" from the project setup options. Provide Your Postman API Key: Enter your Postman API key in the designated field. Generating a Postman API Key: Log into your Postman account. Go to "Profile" > "Settings." Access the "API Keys" section. Click on "Generate API Key," name it, and hit generate. Copy the newly created API key. Import Collections: Once the API key is validated, your Postman collections will be listed. Select the collections you want to import or choose "Select All." Click on "Import." Create the Project: With collections imported, click "Create Project" to finalize. B Adding Postman Collections to an Existing Project Edit Your Project: From the Theneo dashboard, open your existing project and choose "Edit." Navigate to Endpoints: In the project editor, go to the "Endpoints" section where your current API endpoints are listed. Initiate Import: Click on the import icon and select "Connect to Postman." Enter Postman API Key: Provide your Postman API key when prompted. Import Collections: After authentication, your Postman collections will be displayed. Select the desired collections or "Select All," then click "Import." By following these steps, your Postman collections will be integrated into Theneo, streamlining your API documentation workflow.
  • [Importing Custom SDK](https://app.theneo.io/theneo/quickstart/api-reference/supported-apis/importing-custom-sdk.md): The Custom SDK Import feature in Theneo allows users to integrate their own SDKs for use within the platform. This feature currently supports OpenAPI specifications. By adding the x-theneo-endpoint-metadata property to your OpenAPI spec, Theneo will be able to import and utilize your custom SDK in the platform's interface. Steps for Importing Custom SDK 1 Prepare Your OpenAPI Specification: Ensure your OpenAPI spec is up to date and reflects the endpoints you wish to use with the Theneo platform. 2 Add Custom SDK Metadata: Within your OpenAPI spec, add the x-theneo-endpoint-metadata field to the endpoints where you want to use your custom SDK. Include code examples for supported languages under the examples Example of Custom SDK Metadata: or check out this ful l sample spec YAML "x-theneo-endpoint-metadata": { "examples": [ { "title": "Create a Pet", "request": { "python": "from swagger_petstore_sdk import PetstoreClient\n\n# Python\nclient = PetstoreClient()\nnew_pet = {'name': 'NewPet', 'tag': 'Tag123'}\nresponse = client.create_pet(new_pet)\nprint(response.status_code)", "javascript": "import { PetstoreClient } from 'swagger-petstore-sdk';\n\n// JavaScript\nconst client = new PetstoreClient();\nconst newPet = { name: 'NewPet', tag: 'Tag123' };\nconst response = await client.createPet(newPet);\nconsole.log(response.status)" } } ] } 3 Import the OpenAPI Spec to Theneo: After updating your OpenAPI spec, import it into Theneo. Theneo will read the x-theneo-endpoint-metadata and populate the SDK selection dropdown with your custom SDK options. Supported Languages Currently, Theneo supports importing SDK examples written in the following languages: cURL Python Javascript Go Java Csharp PHP Ruby GraphQL Upcoming Language Support Theneo plans to expand support to additional languages in the future. Keep an eye on the platform updates for when these become available. Technical Requirements and Limitations OpenAPI Specification: Your API must have an OpenAPI specification to use this feature. Endpoint Metadata: The x-theneo-endpoint-metadata field is necessary for Theneo to recognize and import the SDK properly. Editor Limitation: Currently, modifications to the x-theneo-endpoint-metadata for the purpose of custom SDK integration cannot be made directly within the Theneo editor. These changes must be made to the OpenAPI spec file before importing it into Theneo. By adhering to these guidelines, you can effectively document and import your custom SDKs into Theneo, providing a seamless experience for users to interact with your API through the platform.
  • [Theneo Custom Metadata](https://app.theneo.io/theneo/quickstart/api-reference/supported-apis/theneo-custom-metadata.md): Theneo allows you to import additional configuration options directly from your OpenAPI specification using the x-theneo-metadata attribute. This custom extension provides more flexibility, allowing you to define a complex structure and additional settings for how your API documentation is organized and displayed, offering much more configuration than what’s possible with a traditional OpenAPI spec. What does x-theneo-metadata do? The x-theneo-metadata attribute gives you the ability to add sections, sub-sections, and other properties that control how your API documentation is structured. This lets you create a more detailed and customized hierarchy, offering more complex configuration options beyond the standard OpenAPI capabilities. Key Features of x-theneo-metadata: • menu : This array lets you organize your documentation into sections, which can include: • name : The title of the section that will appear in the menu. • description : A brief explanation of the section’s content. • icon : (Optional) A visual icon that represents the section. • openDefault : (Optional) Determines if the section should be expanded by default when the documentation is first loaded. • isHeader : (Optional) Specifies whether the section is just a header with no further details or endpoints under it. • isPrivate : (Optional) Allows you to mark sections as private, restricting them to specific users. • viewers : (Optional) An array of email addresses for users who are permitted to view private sections. • operationId : (Optional) Links a section or sub-section to a specific API operation (endpoint) using the operationId from your OpenAPI spec. • subSections : Lets you create nested sections within a larger section, allowing for a more detailed breakdown. Example: JSON x-theneo-metadata: menu: - name: Pet endpoints description: "A section for managing pet-related API operations." icon: https://theneo-prod-public.s3.us-east-1.amazonaws.com/theneo/make/api-explorer.png subSections: - name: List Pets operationId: listPets - name: Get Pet information using ID operationId: showPetById subSections: - name: Add new pet operationId: createPets - name: Header Section openDefault: true isHeader: true subSections: - name: Private Section isPrivate: true viewers: - test@theneo.io description: "Details that only certain users can see." Why is this useful for you? By using x-theneo-metadata in your OpenAPI spec, you can define a much more complex and customizable structure for your API documentation. It allows you to create detailed sections, control visibility, and link directly to specific API operations. This flexibility goes beyond what a traditional OpenAPI spec can offer, giving you more control over how your API documentation is organized and presented.
• [API Testing](https://app.theneo.io/theneo/quickstart/api-reference/api-testing.md): Theneo’s API Explorer is an interactive tool that significantly simplifies the API testing process. It allows users to engage with their APIs in real-time, providing an immersive experience that bridges the gap between technical understanding and practical application. Whether you're a developer or a non-technical user, the API Explorer is designed to offer a seamless and intuitive way to explore and validate API functionality. Key Features of API Explorer Real-Time Testing Try in API Explorer Button : Every API request in our documentation includes a “Try in API Explorer” button, allowing instant, live interaction with your APIs. Environment Selection Sandbox and Production Toggle : Test your APIs in a safe sandbox environment or in a live production setting with a simple switch. User-Friendly Interface Form and Code View : Choose your comfort zone—use the Form View for a guided input experience or the Code View to enter your custom code snippets. Seamless Navigation Effortless Section Switching : Navigate between different API sections directly in the Explorer without needing to refer back to the documentation. Informative Fields Field Descriptions : Understand each parameter with clear descriptions and details provided within the Explorer. Advantages of Using API Explorer No Setup Required Automatic Synchronization : Changes made in the editor or updates from your API spec are automatically reflected in the API Explorer, eliminating the need for manual setup. Accessible to All User Levels Designed for Everyone : The API Explorer is crafted to be accessible to users of all skill levels, breaking down barriers to API testing. Enhanced Learning and Debugging Interactive Learning : By experimenting with live API calls, users can learn more effectively and pinpoint issues on the fly.
  • [Pre-Request Scripting](https://app.theneo.io/theneo/quickstart/api-reference/api-testing/pre-request-script.md): Pre-Request Scripts allow you to execute code before each HTTP request, making them ideal for tasks such as authentication, request headers manipulation, and setting up a consistent environment before fetching data from an external API. By incorporating pre-request scripts, you can streamline your request handling process and ensure consistent behavior across various endpoints. 1.Reading Environment Variables You can access environment variables using the following syntax: JavaScript const myVariable = theneo.variables["variable-name"]; 2. Reading Endpoints To retrieve endpoints, use the following code: JavaScript const myEndpoint = theneo.endpoints; 3. Reading Parameters Access parameters in your pre-request script using: JavaScript const myParameter = theneo.parameters; 4. Reading Query Parameters To access query parameters, use the following syntax: JavaScript const myQueryParameter = theneo.queryParameters; 5. Reading Header Variables Header variables can be accessed as follows: JavaScript const myHeader = theneo.headers["header-name"]; 6. Setting Header Values You can modify or set new header values with the following command: JavaScript theneo.headers["header-name"] = "header value"; 7. Reading Request Body To access the request body in JSON format, use: JavaScript const requestBody = theneo.requestBody.json; 8. Sending Requests within Pre-Request Scripts You can send requests to other endpoints using the fetch API or similar methods. For instance, setting an Authorization header might look like this: JavaScript const token = theneo.variables["authToken"]; theneo.headers["Authorization"] = Bearer ${token}; 9. Example Script Here’s a complete example of a pre-request script that generates an HMAC signature and sets custom headers: JavaScript const apiKey = theneo.variables["apiKey"]; const apiSecret = theneo.variables["apiSecretKey"]; const timestamp = new Date().getTime(); console.log("API Key:", apiKey); console.log("API Secret:", apiSecret); console.log("Timestamp:", timestamp); const requestData = JSON.stringify(theneo.requestBody.json); const rawSignature = ${apiKey}:${timestamp}:${requestData}; function generateHMAC(rawSignature, secret) { const signature = CryptoJS.HmacSHA256(rawSignature, secret); return CryptoJS.enc.Hex.stringify(signature); } const signature = generateHMAC(rawSignature, apiSecret); theneo.headers = { "API-Key": apiKey, "Timestamp": timestamp.toString(), "Signature": signature, "Content-Type": "application/json", "Accept": "/" }; console.log("Headers set for request:", theneo.headers); Currently, async operations are limited. Available Libraries Currently, only the crypto library is available for use in your scripts. You can utilize any method provided by the crypto library. If you would like to use any additional library, please contact our support team at hello@theneo.io . Running Your Script 1 Enabling Pre-Request Scripts To enable pre-request scripts: Navigate to your project settings. Go to Settings → Features → Pre-request script . 2 Running Your Script After creating your script, you can run it using the API Explorer: Press the Run Request button. The pre-request script will execute first, followed by your regular request. 3 Verifying Your Script Use the Network tab to check that the correct authorization values are sent during the request. This helps ensure that your pre-request script is functioning as expected. Reading External Query Parameters To authenticate users in your API explorer by reading and using externally passed query parameters, such as ?my_token=<token> and utilizing them in the pre-request script context. Steps to Implement 1 Passing Query Parameters When redirecting users from your website to the API explorer, include the token as a query parameter in the URL. For example: Plain text https://api-explorer.yoursite.com?myToken= 2 Using the Token in Pre-Request Script Modify the pre-request script to access the token from local storage and use it as needed. Setting up a Dynamic Base URL in API Explorer The goal is to allow users to overwrite the default base URL from the API Explorer with a custom base URL set through a new field. This enables requests to be sent to a dynamic base URL specified by the user instead of a predetermined one. 1 Write the Pre-request Script In the Pre-request Script add the following line of code: JavaScript theneo.baseUrl = theneo.variables["baseURL"]; This code will take the value entered in the baseURL field and assign it to the theneo.baseUrl variable, effectively setting the dynamic base URL for the API request. 2 Open API Explorer and Enter the Base URL After saving, open the API Explorer again. You will now see a new field titled baseURL (the system will automatically create this field based on your custom "baseURL" configuration). Enter the custom base URL you want to use for your requests in this baseURL field. 3 Sending Requests with Custom Base URL Once the custom base URL is entered, all requests sent from the API Explorer will use this new base URL instead of the default one. You can now send API requests to any dynamic endpoint by simply entering the base URL in the field, ensuring that the requests are sent to the right location.
  • [API Authentication](https://app.theneo.io/theneo/quickstart/api-reference/api-testing/api-authentication.md): API authentication is a crucial step for securing your API and ensuring that only authorized users can access it. In Theneo, you can easily set up authentication using HTTP Basic Auth, where your API key is included in the HTTP request headers. This process verifies your identity and grants access to the API’s resources. Theneo offers two ways to configure API authentication: From the Theneo Editor Using Pre-request Scripts from the Project Dashboard Setting API Authentication from the Theneo Editor Follow these steps to set up authentication directly within the Theneo editor: 1 Navigate to the API Management Widget: Open your project in the Theneo editor. Select the API Management Widget where you can manage your API endpoints. 2 Access the Header Tab: In the Header Tab , you will see a list of suggested key options for your headers. Select the Authentication option from this list. 3 Add Authentication Information: Enter a sample value for the authentication header. This can be configured or updated in the API Explorer . Optionally, add a description or any additional properties that your API requires. Setting API Authentication Using Pre-request Scripts For more advanced use cases, you can configure authentication using pre-request scripts. Here’s how you can do it: 1 Navigate to the Project Settings: In the Project’s Dashboard , go to the Project Settings . 2 Set an Authentication Header For example, to set an Authorization header, you can write: JavaScript const token = theneo.variables["authToken"]; theneo.headers["Authorization"] = Bearer ${token}; In your pre-request script, you can send requests to other endpoints or set headers dynamically using the Fetch API or similar methods. This script retrieves an authorization token from Theneo variables and applies it to the Authorization header. For more details on how to effectively use pre-request scripts in Theneo, visit our detailed guide
• [API Versioning](https://app.theneo.io/theneo/quickstart/api-reference/api-versioning.md): API versioning in Theneo is designed to be both intuitive and comprehensive, accommodating the natural evolution of your APIs. With Theneo, you can manage and track incremental changes within the same version using the API changelog, as well as create and oversee major version transitions such as moving from v1 to v2 or v3. Theneo now offers a feature for comprehensive API version management. This feature enables users to meticulously handle different versions of their API, such as v2, v3, and beyond, each with unique statuses and configurations. Key Features of API Versioning Multiple Versions : Create and manage multiple versions of your API, whether it’s incremental updates or major releases. Status Labels : Assign statuses like active, beta, or deprecated to each version, along with any custom attributes you may need. Project Configuration : Tailor each API version’s project settings, including access management, SEO settings, and analytics. Version-Level Changelogs : Track changes within specific versions, enabling clear communication of updates from 1.1.2 to 1.1.3, etc. Utilizing the Versioning Feature Add New Versions : Easily add a new version through your project dashboard by importing a new API spec or using an existing one as a base. Import Specs : Use the intuitive interface to upload file, link, import from Postman, or input raw text for your API specs. Manage Versions : Navigate to the settings menu to manage features, access permissions, SEO optimization, and analytics for each API version. Set Version Status : Define the lifecycle stage of each API version with appropriate status labels directly from the project versions screen. Managing API Versions in Theneo Theneo allows you to create and manage multiple API versions seamlessly. Follow the steps below to create new versions, set defaults, and control visibility for better version management. Creating a New API Version Access the API Versioning Tab Navigate to the Project Dashboard and open the API Versioning tab. Manage Versions Click on the Manage Versions button to open the version management modal. Add a New Version Enter a name for the new version. Choose how you want to create the version: Import an updated OpenAPI specification to reflect the latest API changes. Use an existing version as a starting point and make modifications directly in the editor. Save and Apply Changes Once the version is created, you can modify its content, update configurations, and ensure it aligns with your API changes. Managing Version Tags and Default Versions After creating multiple API versions, you can organize them using version tags . You can also select a default version from the list. The default version will be the one automatically loaded when users access the documentation, ensuring they always see the most relevant version. Hiding API Versions from Published Documentation If you want to hide a specific API version from the published documentation: Open the three-dot menu next to the version you want to hide. Click the Hide option. The version will be removed from the public-facing documentation but will remain accessible from the Theneo Dashboard for internal use. You can still view and edit hidden versions, but external users will not be able to see them. Managing API Versions with CLI Automation If you prefer to automate the creation and management of API versions, you can use the Theneo CLI . This approach is ideal for integrating version control into your CI/CD workflows or for teams that manage large-scale API updates programmatically. For detailed instructions on how to create and manage API versions using the CLI, visit our CLI Guide .
• [API Changelog](https://app.theneo.io/theneo/quickstart/api-reference/api-changelog.md): Theneo’s Changelog is an essential tool for developers and stakeholders to track changes and updates to your API specifications. This powerful feature not only documents all modifications automatically but also provides an option for users to subscribe and receive email notifications for each update. Automated Changelog Documentation When a new API specification is imported and the "Publish" button is clicked, Theneo automatically detects and summarizes all changes, including: Breaking changes in the API Newly added endpoints Updates to existing sections Modified descriptions Removed sections or endpoints These updates are meticulously logged on a dedicated changelog page, providing a detailed version history with timestamps. Changelog Release Notes Theneo allows users to include concise release notes or summaries for updates made to their API documentation. These notes help highlight changes clearly for both internal teams and external users, and are automatically displayed on the dashboard and the public changelog page . Feature Purpose The Changelog Release Note feature provides a quick and efficient way to communicate important updates. Whether written manually or generated by AI, these notes help keep everyone informed of what’s new, changed, or removed in each API release. Configuration Details Release notes can be added from the Public Changelog section on your dashboard. How to Add a Release Note Navigate to the Public Changelog section on your dashboard. Click the “Add Release Note” button. A new input field will appear where you can either: Manually enter a brief summary of the changes Or click “Ask AI” to automatically create a professional summary AI Summary for Release Notes In addition to manual input, Theneo offers AI-generated summaries. With a single click, our AI detects all changes in the newly published API specification and provides a professionally written release note . Acts as a technical writer , summarizing key changes Highlights new endpoints, updated descriptions, removed sections, and breaking changes Saves time and ensures consistency in release communications 💡 This is especially useful for teams that want clear, reliable summaries without manual drafting. Saving Release Notes After writing or generating your release note: Click Save to associate the note with the current API update The note will be automatically displayed: On the dashboard , within the changelog section On the public changelog page Deleting a Release Note Hover over an existing release note Click the trash icon that appears The note will be permanently removed from both views Real-Time Email Notifications How to Subscribe Enter Your Email : On the Changelog page, there’s a field to enter your email. Hit Subscribe : Click the “Subscribe” button to start receiving updates on the documentation changes. Benefits of Subscription Immediate Awareness : Get notified as soon as changes are published, allowing for prompt action or adaptation in your workflow. Convenient Overviews : Email notifications provide a summary of the changes, making it easier to stay informed without needing to check the changelog manually. Version Tracking : Keep a close eye on version progression and ensure that all team members and API consumers are aligned with the latest API developments. Changelog Field Visibility Controls Project Editors can now control exactly which fields appear on the public-facing Changelog page. Fields can be marked as hidden directly from the project dashboard, keeping auto-generated or irrelevant entries out of the public view — without deleting the underlying records. Hidden fields remain fully intact in the system and can be made visible again at any time. How It Works Visible fields Appear on the public Changelog page. Readable by anyone with access to your documentation portal. This is the default state for all changelog fields. Hidden fields Excluded from the public Changelog page. The underlying record is preserved in full — hiding a field does not modify or delete it. Only Editors can see hidden fields from the project dashboard. Who Can Use This Feature Changelog field visibility is controlled at the project level by Project Editors . Workspace Admins have the same access. Role Can Hide Fields Can See Hidden Fields in Dashboard Workspace Admin Yes Yes Project Editor Yes Yes Viewer / Public reader No No Hiding Changelog Fields 1 Open your project dashboard Navigate to the Public Changelog tab. 2 Click Manage Visibility Locate the Manage Visibility button. 3 Select the fields to hide Use the multi-select interface to choose one or more fields you want to remove from the public Changelog page. You can select as many fields as needed in a single action. Fields generated automatically - such as those created during API spec imports or system-triggered updates - are common candidates for hiding. 4 Confirm and apply Confirm your selection to apply the visibility changes. All selected fields are immediately hidden from the public Changelog page. A hidden indicator is shown against each field within the dashboard so Editors can identify them at a glance. Changes take effect immediately on the live public Changelog page. No republishing is required. 5 Confirm the public view Open your public-facing Changelog page to verify the selected fields no longer appear. All other fields in the entry remain intact and visible. Making Hidden Fields Visible Again Hidden fields can be restored to the public Changelog page at any time without any data loss. 1 Click Manage Visibility Manage Visibility Hidden 2 Deselect the fields to restore Deselect the fields you want to make public again. You can restore multiple fields in a single action. 3 Confirm and apply Confirm your selection. The restored fields appear immediately on the public Changelog page. No republishing is required. FAQ Can I turn off the changelog? Yes, the changelog feature in Theneo is optional. You can disable it at any time by going to your project settings, navigating to the 'Features' section, and toggling off the changelog feature. Can I edit the changelog? Currently, direct editing of changelog entries is not available. However, if you need to remove a specific entry from the public changelog, you can delete it. To do this, go to your project configuration, select 'Public Changelog,' and use the delete button next to the entry you wish to remove. Can I edit versions? The ability to edit version details is a feature that is in the pipeline and will be available soon. This upcoming feature will provide more control over how you document and present version changes in the changelog. Will this create a new API version if there are breaking changes? Theneo is designed to track changes meticulously. The functionality to automatically create a new API version upon detecting breaking changes is being developed. When released, it will allow users to manage versions more effectively and ensure that versioning reflects significant changes or updates.
• [Web Editor Widgets](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets.md): Theneo's web editor is a rich and intuitive platform, equipped with a variety of widgets that enrich the documentation experience. These widgets add depth and clarity to your API documentation, making it more engaging and informative. You can easily access these widgets by simply going to a new line in the editor and typing / , which brings up the widget options. Let's take a look at the widgets available: Card Card groups Steps Accordion Divider Callout Table Image & Video Code Blocks Object Example Error Codes Status Codes Base URL Language Box Mermaid Diagram Tabs Iframe API Management FAQ What happens when I make changes to the API in Theneo and then import a new API spec? Change Handling: When you import a new API spec, Theneo provides several options to merge these changes: Merging: This logic identifies and imports only the new updates you've made. Overwrite: Overwrites all existing content with the new spec. Append: Adds the new API spec on top of the existing one, useful for combining different API specs. Endpoints: Imports the spec into the 'Collections' tab, allowing you to drag and drop endpoints to your desired location in the documentation. Can I export the content I am working on, including API updates, from the editor? Export Capability: Yes, you can export your work, including any API updates. Export Format: As part of our growth package, you can export your documentation to a YAML file. Repository Syncing: This exported file can then be synced with your repository for version control and collaboration.
  • [Card](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/card.md): Encapsulate content within a styled container for emphasis or organization. Card Title This is how the card widget appears, with an icon, title and link. Clicking on this card will take you to the Image & Video section. How to Add the Card Widget: 1 First Step Navigate to the point in your text where you want to insert the Card widget. 2 Second Step Type /Card on a new line. 3 Third Step Select the Card option that appears. Content Addition Users can add brief description to the card. The content support all styling options, such as text formatting (bold, italics, bullet points, etc.). Add Link The entire card widget is clickable. Users can add a URL to the card, making the whole card act as a hyperlink. The insert link option is available in the three-dot menu. Icons Users can add icons to the card to enhance visual appeal. Three options are available: Emojis Suggested icons Option to upload custom icons Duplicate Card Users have the option to duplicate the entire card along with its content via the three-dot menu. The duplicated card will maintain all the properties of the original card. Delete Card Users can delete the card through the three-dot menu.
  • [Card Groups](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/card-groups.md): Organize and display related cards together for a structured and visually cohesive layout. Double Card Card Title Add description here Card Title Add description here Triple Card Card Title Add description here Card Title Add description here Card Title Add description here Card Grid Card Title Add description here Card Title Add description here Card Title Add description here Card Title Add description here
  • [Steps](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/steps.md): The Steps widget allows users to create a structured sequence of steps, making it easier to outline processes or instructions in a clear, step-by-step format. Benefits of Using the Steps Widget Clarity and Structure : The Steps widget organizes information in a way that is easy to follow, helping users understand complex processes or instructions. Multimedia Support : Each step can include various types of content, such as images, videos, and tables. Flexibility : Users can add, delete, and duplicate steps as needed, allowing for easy adjustments to content. Highlight Important Information : The option to add callouts and dividers helps emphasize critical points, ensuring that essential details are not overlooked. How to Add a Steps Widget 1 First Step Navigate to the point in your text where you want to insert the Steps widget. 2 Second Step Type /Steps on a new line. 3 Third Step Select the Steps option that appears. Default State When the Steps widget is first added, only the first step appears by default. A "+" icon will be visible, allowing you to add additional steps easily. Step Management The Steps widget offers flexible management options, allowing users to customize each step with titles, multimedia content, and easy-to-use tools for organizing and editing steps efficiently. Add Title Each step has the option to add a title, providing a brief description or heading for that step. Content Addition Users can add various types of content to each step, including: Basic Text Content : Support for basic text formatting (bold, italics, bullet points, etc.). Callout : Add a callout box to highlight important information within a step. Table : Insert a table for structured data. Image : Upload or insert images to illustrate the step. Video : Embed video content relevant to the step. Code Block : Add code blocks with syntax highlighting for technical instructions. Card: Encapsulate content within a styled container for emphasis or organization. Divider : Insert a horizontal divider to visually separate content within the step. Step Navigation and Editing Add Step : Click the "+" icon to add a new step below the existing steps. Delete Step : An option to delete an individual step will be displayed as a trash icon on hover above each step's number. You can also delete a step using the keyboard: select the entire step you want to delete and press the Delete key. Delete Widget : Users can delete the entire Steps widget, which will remove all steps and their content from the document. Duplicate Widget : Easily duplicate the entire Steps widget to reuse content or create a similar sequence of steps.
  • [Accordion](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/accordion.md): The Accordion Widget is a collapsible content section that helps organize and display information efficiently. Users can click on an accordion title to expand or collapse the content inside, making it an excellent tool for structuring content without overwhelming the reader. Single Accordion 🚀 Getting Started with the Accordion Widget Welcome to the Accordion Widget! This feature helps keep your content organized and user-friendly. Below are some key details you can include inside an accordion: 📌 Key Features: Expandable and collapsible sections Supports text, images, callouts, and code blocks Ideal for FAQs, step-by-step guides, and technical documentation Accordion Group 📌 What is API Documentation? API documentation provides a detailed guide on how to interact with an API, including endpoint details, request/response formats, authentication methods, and usage examples. 💡 Why is it Important? Helps developers understand API functionality Improves integration efficiency Ensures consistency in API usage 🔑 How to Authenticate API Requests API Authentication Methods: API Key: Include an API key in the request headers. OAuth 2.0: Authenticate via access tokens. JWT Tokens: Secure authentication with signed tokens. 💡 Example API Key Authentication: CURL curl -H "Authorization: Bearer YOUR_API_KEY" https://api.example.com/data ⚠️ Common API Errors 400 Bad Request: Invalid request syntax. 401 Unauthorized: Missing or invalid authentication. 404 Not Found: Requested resource doesn’t exist. 500 Internal Server Error: Unexpected issue on the server. 💡 How to Fix Errors? Double-check request parameters and headers. Ensure authentication credentials are correct. Review API documentation for required inputs Benefits of Using the Accordion Widget Improves Readability : Helps break down long sections of text into manageable parts. Saves Space : Keeps the interface clean and organized by hiding details until needed. Enhances User Experience : Allows users to navigate and find relevant information quickly. Supports Various Content Types : Can include text, images, videos, callouts, code blocks, and more. When to Use the Accordion Widget FAQs : Organize frequently asked questions and answers in a structured format. Step-by-Step Guides : Display instructions in a collapsible manner. Technical Documentation : Provide expandable sections for detailed explanations. Product or Feature Descriptions : Allow users to view or hide additional details about a product or service. Policies and Agreements : Present terms and conditions in a collapsible format to improve readability. Steps to Add an Accordion Widget 1 First step Navigate to the point in your text where you want to insert the accordion widget. 2 Second step Type /accordion on a new line. 3 Third step Select the accordion option that appears. 4 Fourth step Enter a brief summary title for the accordion widget. 5 Fifth step Inside the accordion, add content such as text, images, code blocks, callouts, and video embeds.
  • [Divider](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/divider.md): The Divider widget in Theneo's web editor is a straightforward yet powerful tool for organizing your documentation. By inserting a visual line break, the Divider creates clear separation between sections, making your content easier to navigate and digest for the reader. It's an essential element for maintaining a clean and structured look in your documents. To add a Divider in Theneo's web editor: Navigate to the point in your text where you want to insert a break. Type /divider on a new line. Select the Divider option that appears. The result is a horizontal line, as shown in your example, that neatly segments your content. This can be particularly useful for distinguishing between different topics, API endpoints, or logical sections within your documentation, ensuring that readers can easily follow along and find the information they need.
  • [Callout](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/callout.md): The Callout widget in Theneo's web editor serves as a great way to draw attention to specific pieces of information within your documentation. By providing visual cues, callouts can indicate important details, success messages, warnings, or errors, making them stand out from the rest of the text. Here's how to use the Callout widget: Click into the editor at the point where you want to insert a callout. Type /callout to bring up the widget selection. Choose from one of the callout options: Info, Success, Warning, or Error. Each callout type is color-coded and comes with an icon to quickly convey the message's nature: Use this to provide additional information or explain a concept in more detail. Ideal for indicating successful operations or validations. Highlights potential issues or important considerations that users should be aware of. Signifies critical errors or problems that need immediate attention. All of the Callout elements can be branded in our branding configuration
  • [Table](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/table.md): The Table widget in Theneo's web editor is a straightforward and effective way to organize and present data in a tabular format. Tables are essential for displaying structured data, comparison charts, specifications, and more, making complex information easy to digest. Here's how to insert a table into your documentation: Position your cursor in the editor where you want the table to be. Type /table on a new line to bring up the widget menu. Select the Table widget. Once you've inserted a table, you can: Add or remove columns and rows to suit your data. Click into any cell to start typing your content. Use the toolbar options to format text within the table, align content, or add/remove additional rows and columns. Feature Description Available Authentication Secure user login with OAuth2.0 Yes Rate Limiting Limits the number of requests per hour Yes Data Export Ability to export data in various formats No Real-time Updates Provides live updates without refreshing Yes Multi-Language Support Documentation available in multiple languages Coming Soon The simplicity of the Table widget ensures that your data is presented cleanly and clearly, with no distractions, allowing readers to focus on the content itself. Whether you're summarizing endpoint parameters, listing error codes, or comparing different API versions, the table is an invaluable tool for your documentation needs.
  • [Tabs](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/tabs.md): The Tabs widget lets you group related content into a tabbed interface within any documentation page. Readers switch between tabs without leaving the page, keeping your content organized without splitting it across separate sections or projects. When inserted, the widget starts with one tab by default — you add, rename, and populate tabs from directly within the editor. Adding the Tabs Widget Open the widget menu in the editor and select Tabs . The widget is inserted at your cursor position with a single empty tab ready to edit. Click inside the tab panel to begin adding content. Content You Can Add Inside a Tab Each tab panel supports the following content types. Content Type What It Does Text Add and format body text with bold, italic, bullet points, numbered lists, and inline formatting Callout Highlight important information with a styled callout box (info, warning, success, or error) Table Insert structured data tables to organize reference information clearly Image Upload or insert images to visually support the tab's content Video Embed video content relevant to the tab Code Block Add syntax-highlighted code blocks for technical instructions or examples Divider Insert a horizontal rule to visually separate sections within a tab panel Cards Insert card and card group widgets to surface summaries or feature grids inside a tab Steps Add a sequential step-by-step block for procedures and instructions inside a tab panel Accordion Add collapsible accordion sections for FAQs or supplementary content within a tab Mermaid Diagram Embed Mermaid-syntax diagrams — flowcharts, sequence diagrams, entity relationships, and more — rendered directly inside the tab panel iFrame Embed external content or interactive tools via iFrame within a tab panel Managing Tabs Adding a Tab Click the plus icon on the tab bar to add a new tab. The new tab is appended to the right of the existing tabs and becomes active immediately. Click inside the panel to start adding content. Renaming a Tab Click the tab title to edit it inline. Reordering Tabs Hover over a tab to reveal the drag-and-drop handle . Click and drag the handle to reorder tabs within the tab bar. Deleting a Tab Select the tab you want to delete to make it active. The trash icon appears only on the currently active tab. Click it to delete the tab and all of its content. More Actions Duplicate Creates a full copy of the entire Tabs widget — including all tabs, their titles, and all content within each panel. The duplicate is inserted directly below the original. Delete Removes the entire Tabs widget in a single action — all tabs and all content within them are permanently deleted. Use the trash icon on individual tabs to remove specific tabs without deleting the whole widget. Published View All tab content is rendered correctly in the published documentation view. Readers see the first tab selected by default and can switch between tabs using the tab bar. All formatting, embedded content, and nested widgets display exactly as authored in the editor.
  • [Image & Video](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/image-and-video.md): The Image & Video widgets in Theneo's web editor allow you to seamlessly integrate multimedia elements into your API documentation. Image To add an image: Place your cursor in the editor where you want the image to appear. Type /image to activate the widget menu. Choose to upload your image file directly or insert it via URL. Add Alt text and a Caption (recommended) After adding an image: Hover over the image in the editor. In the image toolbar, select Alt text or Caption . Enter your text: Alt text: Add a short, descriptive explanation of the image content. Caption: Add optional text displayed with the image to provide context for readers. Why Alt text matters Alt text improves: Accessibility : Screen readers can describe the image for users who rely on assistive technologies. SEO : Search engines can better understand the image content and context. Tips for good Alt text Describe what’s essential: what the image shows and why it matters. Keep it clear and concise. Avoid “image of…” or “picture of…” unless necessary - the context usually implies it. When to use a Caption Captions are helpful when you want to: Add context or explanation (e.g., “Architecture diagram for v2 flow”) Reference a figure in the text (e.g., “See Figure 1”) Clarify what the reader should notice Golden-hour light briefly ignites the mountain face above a calm, glassy lake. Video To add a video: Place your cursor in the editor where you want the video to appear. Type /video to activate the widget menu. Paste the URL of the video you wish to embed. The editor typically supports video content from major hosting platforms such as YouTube and Vimeo.
  • [Iframe](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/iframe.md): If you want to embed custom widgets, external websites, or any third-party content into your documentation, you can easily do so using the Iframe Widget in the editor. How to Use the Iframe Widget Open the Editor : Navigate to the section of the documentation where you'd like to embed the content. Add the Iframe Widget : Open the widget menu and select Iframe . Paste the Embed URL : Enter the URL of the content you want to embed (e.g., an external website, video, tool, or custom widget). Save : Click Save to apply the changes. Once saved, the embedded content will be automatically displayed both in the editor and in the published view of your documentation. Make sure the source you’re embedding allows iframe usage and doesn’t have restrictions which can block the content from being displayed. Examples of Embedded Iframes Below are a few examples to illustrate how different types of iframes will appear once embedded: 1. Website Embed Displays a full website within your documentation. 2. Custom Widget or App Ideal for analytics dashboards, calculators, or interactive tools. 3. Embed Theneo Documentation Useful for embedding other Theneo documentation—such as user guides, product overviews, or API references—directly within your current Theneo documentation. This allows you to reference or reuse existing content seamlessly, without requiring users to navigate away.
  • [Mermaid Diagram](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/mermaid-diagram.md): The Mermaid widget lets you embed live, rendered diagrams directly in your Theneo documentation using plain text syntax. No image uploads, no design tools -just write your diagram as code and Theneo renders it instantly. How to Add a Mermaid Diagram 1 Open the widget menu Type / on any empty line to open the widget menu. 2 Choose Mermaid Diagram Find and select Mermaid Diagram from the list. 3 Write your diagram code Write your diagram code in the code editor at the top - the live preview at the bottom updates as you type. Diagram Types Mermaid diagrams let you turn complex logic, data models, and system interactions into clear visuals that readers can understand at a glance. Instead of asking developers to mentally reconstruct a flow from paragraphs of text, a well-placed diagram makes the structure immediately obvious. This is especially valuable for authentication flows, error handling logic, database relationships, and any multi-step process where the order and branching of steps matters. Each tab below covers one diagram type - what it's for, a real-world example, and the rendered output. Mermaid supports additional diagram types beyond the examples covered in this guide. For the full syntax reference and a complete overview of all available diagram types, visit the official Mermaid documentation . Flow Diagram State Diagram Sequence Diagra ER Diagram Flowchart is useful when your reader needs to understand how a system decides what to do. Any logic that branches — request validation, error handling, payment processing — is hard to follow in prose but immediately clear as a flowchart. It gives readers a high-level mental map before they dive into the details. Plain text graph TD A([User]) --> B[Send API Request] B --> C{Auth Token Present?} C -- No --> D[Return 401 Unauthorized] C -- Yes --> E{Token Valid?} E -- No --> F[Return 403 Forbidden] E -- Yes --> G[Return 200 OK] graph TD A([User]) --> B[Send API Request] B --> C{Auth Token Present?} C -- No --> D[Return 401 Unauthorized] C -- Yes --> E{Token Valid?} E -- No --> F[Return 403 Forbidden] E -- Yes --> G[Return 200 OK] B[Send API Request] B --> C{Auth Token Present?} C -- No --> D[Return 401 Unauthorized] C -- Yes --> E{Token Valid?} E -- No --> F[Return 403 Forbidden] E -- Yes --> G[Return 200 OK]" role="button" tabindex="0" title="Click to zoom" data-mermaid-state="ready"> #mermaid-diagram--r51f-{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-diagram--r51f- .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-diagram--r51f- .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-diagram--r51f- .error-icon{fill:#552222;}#mermaid-diagram--r51f- .error-text{fill:#552222;stroke:#552222;}#mermaid-diagram--r51f- .edge-thickness-normal{stroke-width:1px;}#mermaid-diagram--r51f- .edge-thickness-thick{stroke-width:3.5px;}#mermaid-diagram--r51f- .edge-pattern-solid{stroke-dasharray:0;}#mermaid-diagram--r51f- .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-diagram--r51f- .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-diagram--r51f- .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-diagram--r51f- .marker{fill:#444444;stroke:#444444;}#mermaid-diagram--r51f- .marker.cross{stroke:#444444;}#mermaid-diagram--r51f- svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-diagram--r51f- p{margin:0;}#mermaid-diagram--r51f- .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#000000;}#mermaid-diagram--r51f- .cluster-label text{fill:#000000;}#mermaid-diagram--r51f- .cluster-label span{color:#000000;}#mermaid-diagram--r51f- .cluster-label span p{background-color:transparent;}#mermaid-diagram--r51f- .label text,#mermaid-diagram--r51f- span{fill:#000000;color:#000000;}#mermaid-diagram--r51f- .node rect,#mermaid-diagram--r51f- .node circle,#mermaid-diagram--r51f- .node ellipse,#mermaid-diagram--r51f- .node polygon,#mermaid-diagram--r51f- .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-diagram--r51f- .rough-node .label text,#mermaid-diagram--r51f- .node .label text,#mermaid-diagram--r51f- .image-shape .label,#mermaid-diagram--r51f- .icon-shape .label{text-anchor:middle;}#mermaid-diagram--r51f- .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-diagram--r51f- .rough-node .label,#mermaid-diagram--r51f- .node .label,#mermaid-diagram--r51f- .image-shape .label,#mermaid-diagram--r51f- .icon-shape .label{text-align:center;}#mermaid-diagram--r51f- .node.clickable{cursor:pointer;}#mermaid-diagram--r51f- .root .anchor path{fill:#444444!important;stroke-width:0;stroke:#444444;}#mermaid-diagram--r51f- .arrowheadPath{fill:#333333;}#mermaid-diagram--r51f- .edgePath .path{stroke:#444444;stroke-width:2.0px;}#mermaid-diagram--r51f- .flowchart-link{stroke:#444444;fill:none;}#mermaid-diagram--r51f- .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-diagram--r51f- .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-diagram--r51f- .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-diagram--r51f- .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-diagram--r51f- .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-diagram--r51f- .cluster text{fill:#000000;}#mermaid-diagram--r51f- .cluster span{color:#000000;}#mermaid-diagram--r51f- div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-diagram--r51f- .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#mermaid-diagram--r51f- rect.text{fill:none;stroke-width:0;}#mermaid-diagram--r51f- .icon-shape,#mermaid-diagram--r51f- .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-diagram--r51f- .icon-shape p,#mermaid-diagram--r51f- .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-diagram--r51f- .icon-shape rect,#mermaid-diagram--r51f- .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-diagram--r51f- .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-diagram--r51f- .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-diagram--r51f- :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} No Yes No Yes User Send API Request Auth Token Present? Return 401 Unauthorized Token Valid? Return 403 Forbidden Return 200 OK State Diagram is useful when you need to show what an entity looks like at different points in time and what causes it to change. Rather than describing retry logic or status transitions in prose, a state diagram lets developers instantly see every possible state a resource can be in and all the paths between them — setting clear expectations without ambiguity. Plain text stateDiagram-v2 [*] --> Pending : Event triggered Pending --> Sending : Worker picks up Sending --> Delivered : HTTP 2xx Sending --> Failed : Timeout or error Failed --> Retrying : Retry policy active Retrying --> Delivered : Retry succeeds Retrying --> Dead : Max retries exceeded Delivered --> [*] Dead --> [*] stateDiagram-v2 [*] --> Pending : Event triggered Pending --> Sending : Worker picks up Sending --> Delivered : HTTP 2xx Sending --> Failed : Timeout or error Failed --> Retrying : Retry policy active Retrying --> Delivered : Retry succeeds Retrying --> Dead : Max retries exceeded Delivered --> [*] Dead --> [*] Pending : Event triggered Pending --> Sending : Worker picks up Sending --> Delivered : HTTP 2xx Sending --> Failed : Timeout or error Failed --> Retrying : Retry policy active Retrying --> Delivered : Retry succeeds Retrying --> Dead : Max retries exceeded Delivered --> [*] Dead --> [*]" role="button" tabindex="0" title="Click to zoom" data-mermaid-state="ready"> #mermaid-diagram--r5cj-{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-diagram--r5cj- .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-diagram--r5cj- .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-diagram--r5cj- .error-icon{fill:#552222;}#mermaid-diagram--r5cj- .error-text{fill:#552222;stroke:#552222;}#mermaid-diagram--r5cj- .edge-thickness-normal{stroke-width:1px;}#mermaid-diagram--r5cj- .edge-thickness-thick{stroke-width:3.5px;}#mermaid-diagram--r5cj- .edge-pattern-solid{stroke-dasharray:0;}#mermaid-diagram--r5cj- .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-diagram--r5cj- .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-diagram--r5cj- .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-diagram--r5cj- .marker{fill:#444444;stroke:#444444;}#mermaid-diagram--r5cj- .marker.cross{stroke:#444444;}#mermaid-diagram--r5cj- svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-diagram--r5cj- p{margin:0;}#mermaid-diagram--r5cj- defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-diagram--r5cj- g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-diagram--r5cj- g.stateGroup text{fill:#000000;stroke:none;font-size:10px;}#mermaid-diagram--r5cj- g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-diagram--r5cj- g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-diagram--r5cj- g.stateGroup line{stroke:#444444;stroke-width:1;}#mermaid-diagram--r5cj- .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-diagram--r5cj- .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-diagram--r5cj- .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-diagram--r5cj- .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-diagram--r5cj- .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-diagram--r5cj- .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-diagram--r5cj- .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-diagram--r5cj- .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-diagram--r5cj- .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-diagram--r5cj- .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-diagram--r5cj- .edgeLabel .label text{fill:#333;}#mermaid-diagram--r5cj- .label div .edgeLabel{color:#333;}#mermaid-diagram--r5cj- .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-diagram--r5cj- .node circle.state-start{fill:#444444;stroke:#444444;}#mermaid-diagram--r5cj- .node .fork-join{fill:#444444;stroke:#444444;}#mermaid-diagram--r5cj- .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-diagram--r5cj- .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-diagram--r5cj- .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-diagram--r5cj- .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-diagram--r5cj- #statediagram-barbEnd{fill:#444444;}#mermaid-diagram--r5cj- .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-diagram--r5cj- .cluster-label,#mermaid-diagram--r5cj- .nodeLabel{color:#131300;}#mermaid-diagram--r5cj- .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-diagram--r5cj- .statediagram-state .divider{stroke:#9370DB;}#mermaid-diagram--r5cj- .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-diagram--r5cj- .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-diagram--r5cj- .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-diagram--r5cj- .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-diagram--r5cj- .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-diagram--r5cj- .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-diagram--r5cj- .note-edge{stroke-dasharray:5;}#mermaid-diagram--r5cj- .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-diagram--r5cj- .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-diagram--r5cj- .statediagram-note text{fill:black;}#mermaid-diagram--r5cj- .statediagram-note .nodeLabel{color:black;}#mermaid-diagram--r5cj- .statediagram .edgeLabel{color:red;}#mermaid-diagram--r5cj- #dependencyStart,#mermaid-diagram--r5cj- #dependencyEnd{fill:#444444;stroke:#444444;stroke-width:1;}#mermaid-diagram--r5cj- .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#mermaid-diagram--r5cj- :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Event triggered Worker picks up HTTP 2xx Timeout or error Retry policy active Retry succeeds Max retries exceeded Pending Sending Delivered Failed Retrying Dead Sequence Diagram is useful whenever more than one system is talking to each other. It makes the order and direction of communication obvious — who initiates each call, what comes back, and when. Developers integrating with your API don't have to mentally reconstruct a flow from paragraphs of text; they can see the full exchange laid out step by step. Plain text sequenceDiagram autonumber participant U as User participant C as Client App participant A as Auth Server U->>C: Click "Login" C->>A: Redirect to /authorize A->>U: Show login screen U->>A: Approve access A-->>C: Return authorization code C->>A: POST /token A-->>C: Return access_token C-->>U: Logged in sequenceDiagram autonumber participant U as User participant C as Client App participant A as Auth Server U->>C: Click "Login" C->>A: Redirect to /authorize A->>U: Show login screen U->>A: Approve access A-->>C: Return authorization code C->>A: POST /token A-->>C: Return access_token C-->>U: Logged in >C: Click "Login" C->>A: Redirect to /authorize A->>U: Show login screen U->>A: Approve access A-->>C: Return authorization code C->>A: POST /token A-->>C: Return access_token C-->>U: Logged in" role="button" tabindex="0" title="Click to zoom" data-mermaid-state="ready"> Auth Server Client App User Auth Server Client App User #mermaid-diagram--r554-{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-diagram--r554- .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-diagram--r554- .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-diagram--r554- .error-icon{fill:#552222;}#mermaid-diagram--r554- .error-text{fill:#552222;stroke:#552222;}#mermaid-diagram--r554- .edge-thickness-normal{stroke-width:1px;}#mermaid-diagram--r554- .edge-thickness-thick{stroke-width:3.5px;}#mermaid-diagram--r554- .edge-pattern-solid{stroke-dasharray:0;}#mermaid-diagram--r554- .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-diagram--r554- .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-diagram--r554- .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-diagram--r554- .marker{fill:#444444;stroke:#444444;}#mermaid-diagram--r554- .marker.cross{stroke:#444444;}#mermaid-diagram--r554- svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-diagram--r554- p{margin:0;}#mermaid-diagram--r554- .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-diagram--r554- text.actor>tspan{fill:black;stroke:none;}#mermaid-diagram--r554- .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-diagram--r554- .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-diagram--r554- .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#000000;}#mermaid-diagram--r554- .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#000000;}#mermaid-diagram--r554- #arrowhead path{fill:#000000;stroke:#000000;}#mermaid-diagram--r554- .sequenceNumber{fill:white;}#mermaid-diagram--r554- #sequencenumber{fill:#000000;}#mermaid-diagram--r554- #crosshead path{fill:#000000;stroke:#000000;}#mermaid-diagram--r554- .messageText{fill:#000000;stroke:none;}#mermaid-diagram--r554- .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-diagram--r554- .labelText,#mermaid-diagram--r554- .labelText>tspan{fill:black;stroke:none;}#mermaid-diagram--r554- .loopText,#mermaid-diagram--r554- .loopText>tspan{fill:black;stroke:none;}#mermaid-diagram--r554- .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-diagram--r554- .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-diagram--r554- .noteText,#mermaid-diagram--r554- .noteText>tspan{fill:black;stroke:none;}#mermaid-diagram--r554- .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-diagram--r554- .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-diagram--r554- .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-diagram--r554- .actorPopupMenu{position:absolute;}#mermaid-diagram--r554- .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-diagram--r554- .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-diagram--r554- .actor-man circle,#mermaid-diagram--r554- line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-diagram--r554- :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Click "Login" 1 Redirect to /authorize 2 Show login screen 3 Approve access 4 Return authorization code 5 POST /token 6 Return access_token 7 Logged in 8 ER Diagram is useful for onboarding developers who need to understand your data model before they can effectively use your API. Instead of explaining in text that "a User belongs to an Organization which has a Subscription," a single diagram makes those relationships and field structures self-evident at a glance. Plain text erDiagram ORGANIZATION { string id PK string name string plan } USER { string id PK string org_id FK string email string role } SUBSCRIPTION { string id PK string org_id FK string status } ORGANIZATION ||--o{ USER : "has" ORGANIZATION ||--|| SUBSCRIPTION : "holds" erDiagram ORGANIZATION { string id PK string name string plan } USER { string id PK string org_id FK string email string role } SUBSCRIPTION { string id PK string org_id FK string status } ORGANIZATION ||--o{ USER : "has" ORGANIZATION ||--|| SUBSCRIPTION : "holds" #mermaid-diagram--r5g8-{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-diagram--r5g8- .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-diagram--r5g8- .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-diagram--r5g8- .error-icon{fill:#552222;}#mermaid-diagram--r5g8- .error-text{fill:#552222;stroke:#552222;}#mermaid-diagram--r5g8- .edge-thickness-normal{stroke-width:1px;}#mermaid-diagram--r5g8- .edge-thickness-thick{stroke-width:3.5px;}#mermaid-diagram--r5g8- .edge-pattern-solid{stroke-dasharray:0;}#mermaid-diagram--r5g8- .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-diagram--r5g8- .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-diagram--r5g8- .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-diagram--r5g8- .marker{fill:#444444;stroke:#444444;}#mermaid-diagram--r5g8- .marker.cross{stroke:#444444;}#mermaid-diagram--r5g8- svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-diagram--r5g8- p{margin:0;}#mermaid-diagram--r5g8- .entityBox{fill:#ECECFF;stroke:#9370DB;}#mermaid-diagram--r5g8- .relationshipLabelBox{fill:hsl(80, 100%, 96.2745098039%);opacity:0.7;background-color:hsl(80, 100%, 96.2745098039%);}#mermaid-diagram--r5g8- .relationshipLabelBox rect{opacity:0.5;}#mermaid-diagram--r5g8- .labelBkg{background-color:rgba(248.6666666666, 255, 235.9999999999, 0.5);}#mermaid-diagram--r5g8- .edgeLabel .label{fill:#9370DB;font-size:14px;}#mermaid-diagram--r5g8- .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#000000;}#mermaid-diagram--r5g8- .edge-pattern-dashed{stroke-dasharray:8,8;}#mermaid-diagram--r5g8- .node rect,#mermaid-diagram--r5g8- .node circle,#mermaid-diagram--r5g8- .node ellipse,#mermaid-diagram--r5g8- .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-diagram--r5g8- .relationshipLine{stroke:#444444;stroke-width:1;fill:none;}#mermaid-diagram--r5g8- .marker{fill:none!important;stroke:#444444!important;stroke-width:1;}#mermaid-diagram--r5g8- :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} has holds ORGANIZATION string id PK string name string plan USER string id PK string org_id FK string email string role SUBSCRIPTION string id PK string org_id FK string status Interactive controls When a published Mermaid diagram is clicked, it opens in an interactive view with the following controls: Zoom in / Zoom out — Use the + and - buttons to zoom in and out on the diagram. This is especially useful for large or complex diagrams where the full structure is difficult to read at default scale. Pan / Move — Click and drag anywhere on the diagram to move around it. This allows you to navigate to any part of the diagram freely without losing your zoom level. These controls ensure that even detailed, multi-node diagrams remain fully readable in your published developer portal. Readers are never constrained to a fixed viewport.
  • [AI Writer](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/ai-writer.md): The AI Writer widget helps you generate, improve, and structure documentation - without leaving the editor. Use it to continue writing, simplify content, fix grammar, expand sections, or provide a custom prompt. AI Writer also supports Theneo’s rich content widgets, so outputs can be formatted as code blocks, callouts, steps, cards , and more. What you can do with AI Writer AI Writer is designed for common documentation workflows: Continue Writing : Generate the next paragraph to move past writer’s block. Simplify Content : Rewrite text to be clearer and easier to understand. Expand Sections : Add more detail, examples, or explanations while keeping the same structure. Custom Prompt : Ask for exactly what you need (e.g., “Turn this into a step-by-step guide with a warning callout.”) Add AI Writer to your document Place your cursor where you want the AI-generated content to appear Type " /" (to open the widget menu). Select Write with AI . Best practices Be specific in prompts: Mention tone, audience, and format (e.g., “concise, developer-focused, include code block”). Use AI to structure content: Ask for steps, callouts, and examples to make docs more scannable. Always review before publishing: AI Writer accelerates drafting, but you should validate technical accuracy and product details.
  • [Code Blocks](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/code-blocks.md): The Theneo web editor's Code Block widget allows you to easily insert code snippets into your documentation. Syntax highlighting is supported for a wide range of programming languages, making your code snippets clear and easy to understand. To insert a code snippet: Navigate to a new line in the Theneo web editor where you want the code block to appear. Type /code to trigger the widget selection menu. Choose 'Code Block' from the list of widgets. Select the programming language from the drop-down menu to apply syntax highlighting. Paste or type your code into the code block. Here's an example of a formatted code snippet in JavaScript: JavaScript // Theneo API Magic Elixir Mixer function createElixir(elixirName, ingredients) { console.log(Creating ${elixirName} Elixir with the following ingredients:); ingredients.forEach((ingredient, index) => { console.log(${index + 1}. ${ingredient}); }); console.log(${elixirName} Elixir is ready to empower your API!); } // Mix a 'Restful Rejuvenation' elixir for your API createElixir('Restful Rejuvenation', ['REST', 'JSON', 'OAuth 2.0', 'CORS']);
  • [Object Example](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/object-example.md): The Object Example widget in Theneo's web editor is a versatile tool that enhances the documentation of API objects. It provides a structured and interactive way to present and explain the different components of an API object. Here's how you can use this widget effectively: Adding an Object Example Position your cursor where you want to insert the object example in your documentation. Type /object example to bring up the widget menu and select the Object Example widget. A new tab will be created where you can define your object example. Working with Object Examples Code View : This view allows you to input raw JSON or other supported formats directly. The editor will parse and display the data in an organized and readable format. Form View : Here, you can add more detailed information about each field of your object, such as whether the field is required, provide descriptions, and set additional properties like minimum or maximum values. Managing Multiple Object Examples You can create multiple tabs for different object examples as needed, allowing you to document various objects within the same context. Switch between tabs to manage or view different examples. Supported Languages The Object Example widget supports the same languages as the code block highlight feature, providing consistency in how code and objects are presented throughout your documentation. Extended Use Case Interestingly, some customers have creatively used the Object Example widget for code snippet highlights, taking advantage of the tab feature to organize and display multiple code examples side-by-side. This widget is just another way Theneo empowers you to create comprehensive and user-friendly documentation, making complex API objects understandable at a glance.
  • [Error Codes](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/error-codes.md): The Error Codes widget in Theneo's web editor is a specialized tool for documenting the different types of errors that can occur while using an API. This widget helps to organize and present error information clearly, so developers and users can quickly understand and troubleshoot issues when they arise. Here's how you can effectively use this widget: Utilizing the Error Codes Widget Insert the Widget : Go to the desired section in your document, start a new line, type /error codes , and select the Error Codes widget from the dropdown. Add Error Details : For each error, click on the Add button to create a new entry. Fill in the details such as: The type of error (e.g., authentication_error , rate_limit_error , etc.) A concise yet comprehensive description that explains when this error might be encountered. Reorder Errors : If you want to prioritize certain errors or arrange them in a particular order, use the up and down arrows to move them within the list. Edit or Delete Errors : Should you need to update an error's details or remove it from your documentation, click on the edit icon to modify the information or the trash can icon to delete the entry. Clarity and Actionability : Ensure that each error type has a clear name and description. Where applicable, provide actionable steps users can take to resolve the error. Remember, the Error Codes widget is designed to help users understand specific errors related to your API's functionality, separate from the general HTTP status codes which are managed with the Status Codes widget. Using this widget enhances the usability of your API documentation by making error handling clearer and more accessible.
  • [Status Codes](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/status-codes.md): The Status Codes widget in Theneo's web editor is a feature that allows you to document the HTTP status codes that your API might return. This helps users understand the responses they receive from your API. Here's a guide to using this widget effectively: Insert the Widget : Navigate to the section in your documentation where you want to list the status codes. Start a new line, type /status codes , and select the Status Codes widget from the dropdown menu. Add Status Codes : Use the Add button to insert new entries for each status code your API uses. For each status code, provide: The status code number (e.g., 200 , 400 , 404 , etc.). A brief title for the status code (e.g., OK , Bad Request , Not Found ). A clear description explaining when this status code is returned and what it signifies. Utilize the Library : As you type the status code, you'll notice that Theneo's library suggests existing status codes as a reference. This helps maintain consistency and accuracy in your documentation. Organize and Edit : You can reorder the status codes using the up and down arrows to match the flow of your documentation or delete any unnecessary status code entries using the trash icon. Completeness : Ensure you document all status codes that your API might return, including success and error responses, to provide comprehensive documentation.
  • [Base URL](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/base-url.md): The Base URL widget is a crucial element in Theneo's web editor, enabling you to clearly specify the root URL(s) for API requests. Here's how to use it: Insert the Widget : In your documentation, navigate to the place where you want to mention the base URL. On a new line, type /base url and select the Base URL widget from the dropdown. Edit Base URL : To edit the base URL, click the edit icon in the base URL widget or open the More Actions menu in the API Management widget and select the Base URL configuration option. A dialog box will appear, allowing you to add or modify URLs for different environments, such as Production and Sandbox. Save Environment URLs : Enter the title for each environment and the corresponding URL. For example, you could have "Production" with the URL http://api.example.com and "Sandbox" with the URL http://sandbox.api.example.com . Automatic Updates : Once you save your base URLs, they will be dynamically updated across all sections of your documentation. If you adjust the base URL, the changes will reflect throughout the documentation without the need for manual updates in each section. API Explorer Synchronization : The base URL also synchronizes with the API explorer, allowing users to switch between environments like Sandbox and Production effortlessly while trying out API calls. Managing Base URLs Default Setup By default, your documentation includes a Production environment with a sample base URL: http://example.io . Adding Multiple Base URLs You can enhance your documentation by configuring multiple base URLs within the same environment. For instance, under the Production environment, you can define two distinct base URLs such as http://example.io and http://example.prod.io . Follow these steps to add and customize base URLs: 1 Access Base URL Configuration Modal Open the base URL configuration modal for the desired environment. 2 Add Another Base URL Click on the "Add Another Base URL" button. Enter a valid base URL in the input field. 3 Submit or Customize Further To Add Only: Press Submit , and the new URL will appear in the base URL widget. To Customize: Click the Settings icon in the modal. A separate window will appear. Select specific endpoints or sections where you want to apply this base URL. Press Save to confirm your changes. 4 Apply Changes Your updates will reflect in the editor immediately. Once published, the changes will also apply to the published documentation and API Explorer . Adding New Environments You can create unlimited environments tailored to your API needs, such as “Sandbox,” “Testing,” or “Staging.” Here’s how to define multiple environments: 1 Access Base URL Configuration Modal Navigate to the base URL configuration modal 2 Add a New Environment Click the "Add New Environment" button. Provide a name for the environment, e.g., "Sandbox." Add a valid base URL for the environment. 3 Assign Environment to Endpoints Use the same steps as configuring base URLs: Select specific endpoints or sections for the environment. Save your changes. Customizing Environment Settings Each environment can have its own set of base URLs and configurations, allowing you to align them with your development, staging, or production workflows. Benefits of Configuring Base URLs and Environments Flexibility to manage multiple base URLs under a single environment. Seamless switching between environments for different stages of API development. Centralized configuration improves collaboration and consistency across your documentation. Updates are instantly reflected in both the editor and published documentation, ensuring accuracy. FAQ: Can I edit the name of the environment? Yes, you can. By default, sample environment names are provided, but you have the flexibility to update and customize them to suit your preferences. Will I need to update the base URL in every section if it changes? No, once you update the base URL in the widget, it will automatically reflect across all sections of your documentation, saving you time and ensuring consistency.
  • [Language Box](https://app.theneo.io/theneo/quickstart/editor/web-editor-widgets/language-box.md): The Language Box widget in Theneo's web editor serves as a quick reference for users to identify which client libraries and programming languages are supported by your API. It enhances user experience by allowing them to switch between different languages and view the corresponding API requests. How to Use the Language Box Widget Insert the Widget : Place the Language Box widget in your documentation wherever you want to display the supported languages. Typically, it's positioned at the top of your API reference. Showcase Client Libraries : The widget displays icons for each supported language like cURL, Ruby, Python, PHP, Java, Node.js, Go, and .NET. Interactive Language Switching : Users can click on any language icon, and the API requests throughout the documentation will automatically update to show code snippets in the selected language. Custom Placement : While the Language Box is automatically included in the API reference, you can choose to add or remove it from other sections as needed. FAQ Can I remove any of the default languages from the Language Box? Full customization of the Language Box is planned for a future update. In the meantime, you can remove a language from the Language Box using our Custom CSS/JS feature. For detailed instructions on how to use Custom CSS/JS in Theneo, click here . Can I add my own SDK to the Language Box? Yes, with our business package, you have the capability to import and showcase your own SDK in the Language Box. For detailed instructions and more information on how to do this, please contact our support team at hello@theneo.io
• [API Management inside the editor](https://app.theneo.io/theneo/quickstart/editor/api-management.md): The API Management widget allows users to efficiently define, configure, and manage API endpoints within their projects. It offers a structured way to input and manage essential information for request and response parameters, ensuring comprehensive API setup. How to Add and Configure the API Management Widget 1 Insert the widget Insert the Widget: To insert the API Management Widget, navigate to the desired section in your documentation. Type / to bring up the widget menu and select API Management. 2 Confgiure API Configure the HTTP Method: Click on the method dropdown in the widget’s header to select an HTTP method (e.g., POST, PUT, PATCH, DELETE). Define the Endpoint Path: Enter the endpoint path next to the HTTP method, which will be appended to the base URL. Press the Save Changes button or hit Enter to save. Detail Request Specifications: Headers: Add headers such as content type or authorization tokens. Parameters: Input query parameters or path variables required by the endpoint. Body: For methods like POST or PUT, specify the request body structure. Form and Code Views : Switch between: Form View: A user-friendly interface for entering request details. Code View: For scripting or pasting raw data. Configuring the Response Add the Response Widget: Navigate to the Response tab within the API Management widget. Click the "Add Response" button, which will trigger the response widget to appear. Add Response Codes : By default, a 200 OK response is included. Add other response codes by clicking the + icon. Detail the Response : Form View : Add descriptions and structure the returned data. Code View : Paste in JSON or other formatted responses, and the widget will parse them for easy reading. Multiple Responses : Document responses for various status codes (e.g., 200 OK, 400 Bad Request, 500 Internal Server Error) to cover different API outcomes. Additional Configuration Options Parameter Properties : Click the icon in the right corner of each parameter to trigger a modal for adding extra properties. Required Parameters : Mark parameters as required using a asterisk icon. Parameter Actions : Use the three-dot menu to delete or duplicate parameters. Ask AI : Use AI to suggest descriptions for each parameter by clicking the "Ask AI" button in the description field. Code Beautify : Use the beautify button to format code in code view. Full Screen Mode : Use the full-screen option in the header to manage endpoints more easily. More Actions Menu : The three-dot menu includes options to delete the entire API management section or hide descriptions for request and response parameters in the published view. If you prefer a cleaner look, use the three-dot menu to hide the description column on the left. This can make the published documentation appear more streamlined. Video Guide on how API Management widget works
• [Live Collaboration](https://app.theneo.io/theneo/quickstart/editor/live-collaboration.md): We know, great collaboration leads to great results, and the Live Collaboration feature in our editor ensures that your team can work together in real-time to achieve just that. Whether you're working on documentation or complex projects, this feature allows multiple users to make updates simultaneously, ensuring everyone is on the same page and contributing effectively. With real-time visibility into who’s editing what, collaboration becomes smooth, organized, and more productive. Key Features of Live Collaboration See Who’s Currently Editing a Section : At any point during the editing process, users can see which collaborators are actively editing a particular section. This visibility helps avoid confusion or duplication of work and ensures smooth collaboration among team members. View Where Others Are Editing : Within a section, users can see exactly where their collaborators are making changes in real-time. The editor highlights the text being edited by another user, giving you immediate feedback on what is being updated. Cursor Visibility : For greater clarity, the cursor of the collaborator is visible within the section description. This allows users to pinpoint the exact location where edits are happening, ensuring that changes are made in the correct area. See Who’s Editing Which Section in the Menu :The menu provides an overview of who is editing which section. Each section that is being actively worked on by a user is marked with their name, making it easy to track where collaborators are focused. This feature enhances coordination, especially in larger documents with multiple sections. How to Use Live Collaboration Start Editing Together : Once users are invited to collaborate on a project or document, they can begin editing simultaneously. As soon as one user starts editing a section, others will see their presence and activity in real-time. Communicate with Collaborators : Although the collaboration feature does not include a built-in chat, the real-time presence indicators allow for smooth coordination. Teams can also supplement this feature with external communication tools to enhance collaboration further. Conflict Avoidance : Since all users can see who is editing a section, this minimizes the risk of conflicting edits. It helps maintain organized teamwork and ensures that changes are consolidated without accidental overwrites.
• [Preview Changes](https://app.theneo.io/theneo/quickstart/editor/preview-changes.md): In Theneo, users can switch to Preview Mode at any time while editing to review the latest changes before publishing. This feature offers several key benefits: Accurate Rendering : Preview Mode allows you to see exactly how your content will appear in the final published documentation. This helps ensure that all formatting, layout, and design elements are rendering as intended. Section-Specific Previews : You can preview changes for individual sections, ensuring that every detail is correct before publishing. This is especially useful when working on larger documents with multiple sections. How to Use Preview Mode Locate the Switcher Button : In the editor’s header, you’ll find the Editor/Preview switcher button. This is your key to moving between edit mode and preview mode effortlessly. Switch to Preview Mode : When you're ready to preview your content, click on the switcher to enter Preview Mode . This will display the most recent version of your documentation as it will appear to end users. Preview Specific Sections : You can preview any section of your document to see how changes to that section look. If the preview meets your expectations, you can move forward by selecting the Publish option. Once confirmed, your documentation will go live with all the updates and enhancements you've applied. Note: Preview mode is a visualization tool to give you a sense of your project's design and layout. It may not represent the full interactivity of your live documentation, such as functional API explorers or live code examples. Use this mode to make any final adjustments before updating your live documentation.
• [Publish a Documentation](https://app.theneo.io/theneo/quickstart/publishing-documentation/publish-a-documentation.md): Once you’ve finished editing your documentation and are ready to publish, you can do so from the Editor , Dashboard , or via CLI automation . After publishing, your documentation will be accessible to the selected audience. Private Publishing By default, project access settings are set to private , meaning that after publishing, the documentation will not be accessible to external users. You can invite users as editors or viewers through Project Access Management settings . Alternatively, set up password-based access for your documentation under a custom domain . For more details on managing access, visit here . Public Publishing If you want your documentation to be accessible to a public audience , you can: Publish the documentation. Change the access settings from private to public under Project Access Management . Publishing Without Search Engine Indexing By default, your documentation is indexed by search engines . However, you can choose to disable indexing so that while your docs remain accessible on the web, they won’t appear in search results. How to Disable Indexing: Navigate to Project SEO Management . Enable the No-Indexing toggle. Even with indexing disabled, your documentation remains accessible to anyone with the direct link. This feature is useful for publishing beta versions or conducting large-scale user testing without impacting SEO due to potential duplicate content. Unpublishing the Documentation To unpublish your documentation: Go to Project Access Management settings . Select the Draft option from the access dropdown. Note: Once unpublished, the documentation link will no longer be accessible to users.
• [Branding & Styling](https://app.theneo.io/theneo/quickstart/publishing-documentation/branding-and-styling.md): Craft a distinctive look and feel for your Theneo documentation with extensive branding and styling customization options. From choosing the right color palette to setting a custom domain, Theneo empowers you to align your documentation with your brand identity. Key customization features Light and Dark Mode Customization : Tailor your documentation's appearance for both light and dark mode preferences with dedicated logos and color schemes, ensuring a consistent user experience in any setting. Color Customization : Fine-tune the color of text, buttons, backgrounds, and more with an easy-to-use color picker. Double-click to access HEX codes for precise matching to your brand colors. Custom CSS and JavaScript : For advanced customization, inject custom CSS and JavaScript to take full control over the look and functionality of your documentation. Custom Domains : Strengthen your brand's online presence by hosting your documentation on a custom domain, creating a seamless transition from your main website to your Theneo-hosted content. With Theneo's customization tools, you can create documentation that not only serves its purpose but also resonates with your brand's aesthetic and ethos, making every interaction with your API an extension of your brand experience. General Settings Logos : Upload separate logos for light and dark modes, ensuring clear visibility regardless of theme. Ideal dimensions are provided for optimal display. Favicon : Customize the small icon that appears in browser tabs and bookmarks to make your site easily identifiable. Logo Hyperlink : Direct users to your desired URL through the logo in your documentation. Attribution : Toggle the "Powered by Theneo" attribution on or off to match your branding preferences. Document Font : Select from a variety of fonts to maintain consistency across your documentation. Color Customization of the published view projects: Color customization is available on Business and Growth plans . Global Settings: Body Text : Determine the color of the main text for readability against the background. Section Headings : Highlight section titles with distinct colors for better navigation. Background : Choose a primary color for the project's backdrop. Accents : Accentuate borders and outlines with a complementary color. Buttons : Set the background and text colors for buttons to align with your brand. Links : Define the color of hyperlink texts to make them noticeable or integrated. Left Sidebar Menu: Item Colors : Manage the colors of individual items and the active selection to enhance the sidebar's functionality and aesthetics. Background : Select a primary background color for the sidebar for a unified look. Content Cards: Code Snippets : Customize header and body background colors for code snippet cards for clarity. Base URL : Adjust the color scheme of the Base URL card headers and bodies. General Info : Set the header and body background colors for general information cards. Feedback and Text Selection: Feedback Button : Ensure your feedback button stands out or matches your design with customizable colors. Text Selection : Personalize the background and font colors of text selections to reflect your brand. API Explorer Buttons and Response Boxes: Buttons : Choose colors for your API Explorer buttons that prompt users to interact. Response Boxes : Assign colors to property and value texts in response boxes for distinct visibility. Alerts: Customize background, icon, text, and border colors for warning, primary, danger, and success panels, ensuring that each alert type is distinct and noticeable. Each of these elements can be adjusted for both light and dark modes, maintaining consistency or providing contrast as per your branding guidelines. Tip for HEX Codes: To quickly use your brand's HEX color codes, simply double-click on the RGB section within the color picker to switch to HSL, where the HEX code input will appear. This allows you to paste your HEX codes directly for precise color matching. Custom CSS & Javascript Custom CSS and JS are available on Growth plan. Custom CSS and JavaScript are powerful tools for personalizing and enhancing the functionality of your Theneo documentation. This guide will walk you through the process of implementing custom CSS and JS to tailor the look and feel of your project. 1 Step 1: Access Custom CSS and JS Settings Navigate to the 'Branding' section in your Theneo dashboard. Within the Branding menu, you will find a tab or section labeled 'Custom CSS & JS.' This is where you can add your code snippets. 2 Step 2: Write or Paste Your Custom CSS In the Custom CSS field, you can write your own CSS rules or paste existing snippets. This can include styles for: Custom fonts and text styles Overriding default padding and margins Background images or gradients Custom animations or transitions Responsive adjustments beyond the standard layout Ensure that your CSS is properly formatted and does not contain any syntax errors to avoid any display issues. 3 Step 3: Write or Paste Your Custom JavaScript The Custom JS field is where you can add JavaScript to your documentation. Common uses for Custom JS include: Implementing third-party scripts such as analytics or live chat support Custom interactions or behaviors for buttons and links Dynamic content loading or page manipulation Form validation and submission handling Make sure your JavaScript is well-tested to prevent any conflicts with Theneo's existing scripts. 4 Step 4: Save Your Changes After adding your custom CSS or JS, click on the 'Save' button to apply the changes. It's important to review your changes to ensure that they produce the desired effect without interfering with the user experience or functionality. Custom Font Customizing fonts in your documentation is an excellent way to enhance branding and readability. This guide will walk you through the steps to add a custom font to your documentation using the Custom CSS feature. 1 Step 1: Select a Font Choose a font : Visit Google Fonts or any other trusted font source. Browse and select the font that fits your style. Get the import URL : @import url(' https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&family=Sofia&display=swap '); Alternatively, you can use a Base64-encoded font if you have one, which allows embedding fonts directly without external links. 2 Step 2: Add the Font to Your CSS Create the necessary CSS code to apply the font to your documentation. Below is an example: In this example: The @import rule links to the custom font's source. The font-family property applies the chosen font to all text in your documentation ( * is the universal selector). CSS @import url('https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&family=Sofia&display=swap'); * { font-family: "Sofia", serif; font-weight: 400; font-style: normal; } 3 Step 3: Update Your Documentation Open Theneo Dashboard and navigate to Branding Configuration Locate the Custom CSS section. Paste the CSS code from Step 2 into the provided field. Save the changes. Branding Template Selector The Branding Template Selector lets workspace Admins and Editors apply a complete visual identity to their documentation portal in a single click. Instead of configuring colors, CSS, and JavaScript individually, you choose one of three predefined templates — Solid , Bloom , or Roboto — and all branding fields are populated automatically across your entire workspace. Who Can Use This Feature Workspace Admin Full access to the Branding General Settings page. Can select, apply, and override any template, and may further customize individual branding fields after applying. Workspace Editor Can select and apply branding templates from the General Settings page. Changes apply workspace-wide in the same way as Admin-applied templates. Viewers and project-level collaborators cannot access Branding General Settings and will not see the Template Selector. Available Templates Each template ships with a complete set of branding values — primary and background colors, custom CSS, and custom JS. Selecting a template overwrites any previously configured values in all three fields. Solid Bloom Roboto What gets applied: — Primary and accent color palette with solid, opaque fills — CSS reset and layout rules for dense, structured pages — Minimal custom JS for navigation state management Solid What gets applied: — Pastel-toned color palette with gradient overlays — CSS for card softness, rounded radii, and elevated surfaces — Custom JS for smooth scroll and animated section transitions Bloom What gets applied: — Teal/emerald base palette with configurable accent — CSS scoped around Roboto font loading, line height, and spacing scale — Lightweight custom JS for code block copy and sidebar state Roboto What a Template Populates Applying any template automatically fills the following branding fields. Fields you have previously configured will be overwritten. Branding Field Scope Can Be Edited After Applying Color palette (primary, background, accent) Workspace-wide Yes Custom CSS Workspace-wide Yes Custom JavaScript Workspace-wide Yes How to Apply a Template 1 Open Branding General Settings Settings → Branding → General 2 Preview the available templates Solid Bloom Roboto 3 Select your template Click the template you want to apply. A confirmation prompt will appear summarizing which branding fields will be overwritten. If you have existing custom CSS or JS, the prompt will explicitly list these fields. Review carefully before confirming — this action cannot be undone automatically, though you can reapply a different template or restore values from history. 4 Confirm and apply Apply Template 5 Fine-tune if needed Settings → Branding → General Switching Templates You can switch between templates at any time. Each new template selection fully overwrites the current branding configuration, including any manual edits made after your previous template was applied. Branding History & Version Revert The History tab in Branding settings gives workspace Admins and Editors a chronological audit log of every branding change made across the workspace - who made it, when it was saved, and the ability to roll back to any of the three most recent versions instantly. Accessing Branding History Navigate to Settings → Branding → History . The History tab sits alongside the General tab on the Branding settings page and is visible to all Admins and Editors in the workspace. Viewers and project-level collaborators cannot access the Branding settings page and will not see the History tab. Revert Eligibility Not every log entry can be reverted. The revert action is available on the three most recent branding versions only. Revert is workspace-wide and immediate. How to Revert a Branding Version 1 Open the History tab Settings → Branding → History 2 Identify the version to restore Review the log entries. Each of the three most recent versions shows the workspace member who saved it and the exact timestamp. Use this to confirm which state you want to restore. 3 Click Revert Revert 4 Confirm the revert Confirm Revert
• [Custom Domain](https://app.theneo.io/theneo/quickstart/publishing-documentation/custom-domain.md): A custom domain is a unique branded label that identifies your presence on the Internet. It's essential for establishing brand identity and ensuring a professional appearance for your Theneo projects and Developer Portal. Here's a step-by-step guide to setting up a custom domain for your Theneo-hosted content. Custom domain is available on Business and Growth plans. Custom Domain for Projects Access Project Settings : Log in to your Theneo account. Navigate to the settings of the project you want to assign a custom domain to. Select the "Custom Domain" section. Enter Your Domain : Specify the custom domain you wish to use, such as docs.yourdomain.com . Configure DNS Settings : Log into your domain provider’s control panel. Add a CNAME record pointing your custom domain to Theneo’s hosting environment, typically custom.theneo.io . For example, the DNS entry would look like this: developers.example.com. 3600 IN CNAME custom.theneo.io . Finalize Setup in Theneo : After updating DNS settings, go back to Theneo and save your custom domain configuration. It may take some time for DNS changes to propagate. Once done, your project will be accessible via the custom domain. Custom Domain for Developer Portal Access Developer Portal Settings : Go to the Developer Portal settings within Theneo by visiting https://app.theneo.io/developers-hub/settings . Specify Custom Domain : Enter the custom domain for your Developer Portal, ensuring it aligns with your brand, such as developers.yourdomain.com . DNS Configuration : Similar to project settings, establish a CNAME record in your DNS configuration, pointing to Theneo’s specified domain. Activate Your Domain : Finalize your domain settings in Theneo's Developer Portal settings page. Check for successful DNS propagation before the domain goes live. Important Tips: DNS Propagation : Changes to DNS records can take up to 48 hours to propagate fully across the Internet. SSL Certificates : Theneo automatically generates SSL certificates for custom domains, ensuring secure connections.
• [llms.txt](https://app.theneo.io/theneo/quickstart/publishing-documentation/llms-txt.md): The .llms.txt feature allows your documentation site to expose a structured, machine-readable index that helps large language models (LLMs) discover and understand your content more efficiently. What Is .llms.txt? .llms.txt is a plain-text file that provides a structured summary of your documentation, including: The title and description of each section Direct links to the corresponding Markdown ( .md ) source files A hierarchical overview of your content structure This allows AI tools, developer assistants, and LLM-powered integrations to index your documentation accurately - without needing to crawl or parse your full rendered HTML site. How It Works Theneo generates your .llms.txt file automatically using the SEO management data you have already configured for each page in your documentation. No additional setup is required for content that already has SEO fields filled in. The file is built from the following existing fields: Title Description Field Description Title The section title used in search engine metadata Description The SEO meta description for the page Slug The URL path segment used to construct the page link Each entry in the .llms.txt file maps one documentation page to its title, a short description, and the direct link to its Markdown source file. File Format The generated .llms.txt file follows the standard format below: Markdown # <Site Title> > <Site-level description> ## <Section Name> - [<Page Title>](<link-to-.md-file>): <Page description> - [<Page Title>](<link-to-.md-file>): <Page description> ## <Section Name> - [<Page Title>](<link-to-.md-file>): <Page description> Managing SEO Data for Better Coverage Since .llms.txt is generated from your existing SEO fields, the quality of your index depends on how thoroughly those fields are filled in. To ensure complete and accurate coverage: Title: Keep titles concise and descriptive. Avoid generic labels like "Overview" when a more specific title such as "Authentication Overview" is more informative. Description: Write descriptions that summarize what the page covers in one to two sentences. This text appears directly in the .llms.txt file and is what LLMs will use to understand the page's purpose. Slug: Use clean, readable slugs that reflect the page hierarchy (e.g., /guides/authentication rather than /page-42 ). To review or update SEO data for a page: From the project dashboard, navigate to SEO Management. Edit the Title, Description, and Slug fields as needed. Click Save Changes. Verifying Your .llms.txt File You can verify the file is live and correctly formatted by visiting your documentation URL directly in a browser or using a tool such as curl : Bash curl https://app.theneo.io/theneo/quickstart/llms.txt Check the following: All major sections of your documentation are represented. Each entry includes a title, a valid link to a .md file, and a description. The file is accessible without authentication (it must be publicly reachable to be useful to external LLM systems). Frequently Asked Questions Which pages are included in the file? All published pages with SEO metadata (title, description, and slug) are included. Draft pages and unpublished content are excluded automatically. How often is the file updated? The file regenerates each time you publish a change to your documentation. There is no manual refresh required. What happens if a page is missing a description? Pages without a description will still appear in the file but the description field will be left blank. It is recommended to fill in descriptions for all pages to maximize usefulness to LLM consumers. Will header sections be automatically excluded from .llms.txt? Yes. Header sections - sections that serve as labels or groupings in your navigation without content of their own - are automatically excluded from the generated .llms.txt file.
• [Feedback & Analytics](https://app.theneo.io/theneo/quickstart/publishing-documentation/feedback-and-analytics.md): Theneo's Documentation Analytics provides in-depth insights into the content you have published and user activity on your documentation. This feature helps you track engagement, identify areas for improvement, and optimize your content based on user interactions. The analytics data is divided into three key sections: Traffic : Displays overall visitor statistics, including the number of users, page views, and session counts. Pages & Feedback : Shows detailed feedback from users on specific pages and sections. AI Search History : Logs user search queries to help you understand their needs and improve documentation accordingly. By default, Documentation Analytics is enabled once your documentation is published. The analytics data, including visitor numbers, documentation views, and sessions, can be accessed from the Theneo Dashboard or your Project’s Analytics Page . If needed, you can disable this feature anytime from the Project Settings page under the Features tab. Filtering Analytics Data To gain better insights, you can filter analytics data by selecting a specific date range using the Date Filter . This allows you to track trends over time and analyze how documentation performance changes based on updates or user engagement. Documentation Views Tracking Theneo tracks documentation views to help you measure the popularity and reach of your content. Every time a user visits a page on your documentation site, it is recorded as a documentation view . AI Search History The AI Search History section logs the queries users search for within your documentation. This feature helps you: Identify common topics and questions users are interested in Understand gaps in your documentation where users struggle to find information Improve your content by adding missing or unclear information You can search through AI Search History to analyze specific queries and take action accordingly. Section Feedback The Section Feedback feature allows users to provide direct feedback on individual sections of your documentation. Users can: Rate sections as helpful or not Leave comments about their experience Suggest improvements for clarity or accuracy Ask questions if they need further clarification Viewing and Managing Feedback Feedback left by users is an essential tool for continuous documentation improvement. You can: View a list of comments submitted by visitors Identify patterns in user concerns or suggestions Make data-driven updates to your documentation By addressing feedback and updating your content accordingly, you can enhance the overall user experience and ensure that your documentation remains accurate, clear, and useful. Best Practices for Using Documentation Analytics To make the most of Theneo’s analytics features, consider the following best practices: Regularly monitor analytics data – Track visitor trends and feedback to stay informed about how your documentation is performing. Identify weak spots – Use AI Search History and low-performing pages as indicators of where improvements are needed. Act on feedback – Respond to user comments, update unclear sections, and make necessary changes based on insights from Section Feedback. Compare trends over time – Use date filtering to observe how documentation changes impact user engagement. Custom Analytics Integrating Google Analytics (GA) or Google Tag Manager (GTM) with your Theneo platform allows you to track user interactions and gain insights into how your application is being used. Follow the steps below to add your unique GA tag or GTM ID: Custom Analytics is available on Business and Growth plans. Step 1: Navigate to Branding Settings Log in to your Theneo account. On the dashboard, locate and click on the “Branding” option in the main navigation menu. Step 2: Access Analytics Configuration Within the Branding section, you will see a submenu. Click on the “Analytics” tab to open the analytics configuration options. Step 3: Adding Your Google Analytics Tag ID To add a Google Analytics tag: Find the field labeled "Google tag ID." Click on the pencil icon (edit button) next to the field. Enter your Google Analytics ID, which usually starts with “G-” followed by a series of numbers. Step 4: Adding Your Google Tag Manager ID To add a Google Tag Manager ID: Locate the field marked "Google tag manager." Click on the pencil icon (edit button) next to this field. Input your GTM ID, which typically begins with “GTM-” or “UA-” followed by a series of numbers. Step 5: Save Your Changes After entering your IDs, ensure to save the changes by clicking the save icon or button typically located at the bottom or top-right of the page. Step 6: Using Custom JavaScript for Other Analytics Services If you use an analytics service other than Google Analytics or Google Tag Manager: Go back to the submenu under “Branding.” Select “Custom CSS & JS” to access the custom scripting functionality. Here, you can add your own JavaScript tracking codes as needed for other analytics services. Important Notes Verification: After adding your GA or GTM IDs, it is crucial to verify that they are working correctly. You can do this by checking your GA or GTM dashboard to see if it is receiving data from your Theneo platform. Custom JavaScript: If you are not familiar with JavaScript and need to implement custom tracking scripts, consider consulting with a developer or your analytics provider for assistance
• [Theneo UI](https://app.theneo.io/theneo/quickstart/publishing-documentation/theneo-ui.md): Theneo's published view is crafted to enhance user experience, offering a seamless and intuitive interface for navigating and reading API documentation. This section aims to elucidate the key features of Theneo's published view, providing you with detailed insights and instructions to fully leverage the capabilities of our documentation system. By understanding and utilizing these features, you can streamline your workflow, improve accessibility, and ensure an efficient documentation experience. Side Menu The side menu is an integral part of Theneo's published view, providing an organized and accessible way to navigate through the documentation. Features: Sections and Subsections: The side menu displays all sections and subsections of the documentation, allowing for quick and easy access to different parts of the content. Custom Headers and Icons: Users can create custom headers and add icons for a more visually appealing and easily navigable menu. Continuous Scrolling Theneo's continuous scrolling enhances navigation by allowing you to scroll through the documentation without needing to click to navigate to other pages. Benefits: Seamless Navigation: No need to click through multiple pages; just scroll down to continue reading. Improved User Experience: Continuous scrolling ensures a smooth and uninterrupted reading experience. Search and AI Search Finding specific information within the documentation is made easy with our search functionalities. Features: Standard Search: Quickly locate content by typing keywords into the search bar. ChatGPT Search: Utilize the power of ChatGPT to search for documentation content with more natural language queries. Custom Menu The custom menu feature allows you to add any item or group of items in a dropdown for shortcut access. Customization Options: Add Items: Include any documentation pages, links, or tools you frequently use. Group Items: Organize related items into groups within the dropdown for easier access. Custom Menu Main Button Highlighting To make navigation even more intuitive, the Main Button feature allows users to mark one item (excluding subitems) as the main button in the custom menu. This visually distinct button serves as a primary point of focus in the menu. Main Button Design in Published View: The Main Button will have a distinct design with a highlighted background to make it stand out from other menu items. This ensures that users can easily identify the most important or relevant section of the documentation at a glance. Anchor Tags for Headers Anchor links enhances the ability to share and reference specific parts of the documentation. How it Works: Anchor Tags: Each header in a section is equipped with an anchor tag, allowing you to link directly to that header. Easy Referencing: Share the URL with the specific anchor tag to direct others to the exact part of the documentation you are referencing. HTTP Method Display in the Side Menu In your API documentation, you can choose to display HTTP methods (GET, POST, PUT, DELETE, etc.) for each endpoint directly in the side menu. This feature makes it easier for users to quickly identify the type of request each endpoint supports. Configuring the HTTP Method Display Option To enable this feature, follow the steps below: Navigate to Project Settings: Go to your project's dashboard and open the Project Settings. Locate the Features Tab: Inside Project Settings, click on the Features tab to access additional project configuration options. Enable the HTTP Method Display: In the Features tab, find the toggle option labeled HTTP Method Display. By default, this option is turned off. Switch the toggle to on to enable it. Republish the Project: After enabling the HTTP Method Display, republish your project to apply the changes. Once republished, the HTTP methods will be automatically displayed next to each endpoint in the side menu, making the documentation more intuitive for developers. FAQ Can I disable continuous scrolling and have only one page at a time? Yes, with our recent updates, you can switch between continuous scrolling and the single-page template based on your specific needs and document structure. To do so, navigate to the Project Settings on the dashboard, locate the 'Single Page Template' option, and toggle it on. Can we have a section as a link? Yes, you can set a section as a redirect link in your documentation. To do this, follow these steps: Navigate to the Editor: Go to the project's editor where you manage your documentation. Choose the Section: Select the section where you want to set the redirect link. Open the More Actions Menu: Click on the three-dot menu (More Actions) next to the section. Set the Redirect Link: In the menu, find and click on the option labeled "Set Redirect Link". Paste the desired URL into the input field provided. Optional: Open in a New Tab: If you'd like the link to open in a new tab, check the "New tab" option. Save and Publish: Save the changes and republish your documentation. The section will now redirect users to the specified link.
• [Github Actions](https://app.theneo.io/theneo/quickstart/automation-and-dev-tools/github-actions.md): 1 Create Theneo Documentation Begin by creating a documentation project within Theneo to house your API details. 2 Set Up GitHub Workflow Set Up GitHub Workflow Configure a workflow in your GitHub repository that will interact with Theneo: Create a Workflow File : Add a file named Theneo.yml to the .github/workflows/ directory in your GitHub repository. This file will define the actions to be taken. Example Theneo.yml Workflow : YAML name: Update Documentation on: pull_request: branches: - main jobs: update-doc: name: Update Theneo Documentation runs-on: ubuntu-latest steps: - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event." - name: Checkout uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: "18" - name: Update Documentation on Theneo uses: Theneo-Inc/api-documentation@1.8.0 with: FILE_PATH: doc/api.yml PROJECT_SLUG: <project_slug> VERSION_SLUG: <version_slug> WORKSPACE_SLUG: <workspace_slug> SECRET: ${{secrets.SECRET}} AUTO_PUBLISH: true IMPORT_OPTION: merge PARAMETER_DESCRIPTION_MERGE_STRATEGY: keep_new SECTION_DESCRIPTION_MERGE_STRATEGY: keep_old INCLUDE_GITHUB_METADATA: true 3 Locating Your Theneo Project Slug To configure GitHub Actions, you'll need your Theneo project slug: Go to your project dashboard in Theneo. Open the desired project. The project slug is part of the URL: https://app.theneo.io/<workspace-name>/<project-slug>/[version-slug] . For example, if the URL is https://app.theneo.io/theneo/github-demo , your project slug is github-demo . Use this project slug for the PROJECT_SLUG variable in your GitHub workflow. 4 Inputs Define the following inputs in your workflow file to configure the GitHub Action: FILE_PATH : The path to your API documentation file within the repository. PROJECT_SLUG : Your project's unique identifier in Theneo, accessible under project settings. VERSION_SLUG : Project version slug to import documentation under a specific version, otherwise default version will be used. WORKSPACE_SLUG : Project workspace slug to import documentation under specific workspace. SECRET : Your Theneo API token for authentication, which can be found in your Theneo profile. IMPORT_OPTION : Determines how to handle the imported documentation. Options include overwrite , merge , and endpoints . AUTO_PUBLISH : If set to true , Theneo will automatically publish the changes. If false , you can review changes in the editor before manual publication. INCLUDE_GITHUB_METADATA : Includes metadata like the GitHub actor in the documentation, visible only in Theneo's editor. SECTION_DESCRIPTION_MERGE_STRATEGY : Merging strategy for section descriptions to keep old descriptions from theneo editor if needed, valid values are keep_new or keep_old. PARAMETER_DESCRIPTION_MERGE_STRATEGY : Merging strategy for parameter descriptions to keep old descriptions from theneo editor if needed, valid values are keep_new or keep_old. 5 Import Options Choose how Theneo handles incoming changes: overwrite : Replaces the current documentation with the new spec entirely. merge : Attempts to merge changes; this is experimental and may append changes in some cases. endpoints : Adds new spec endpoints into a dedicated section for manual arrangement. 6 Auto-Publish Option Control the publication of your documentation: true : Automatically updates the published documentation with the latest changes. false : Allows for a review in Theneo's editor before you decide to publish. Using Theneo's GitHub Actions integration, the process of maintaining accurate and current API documentation becomes automated, seamless, and efficient. Your team and users gain immediate access to the latest documentation, ensuring everyone is on the same page with API updates and changes.
• [Visual Studio Code Extension](https://app.theneo.io/theneo/quickstart/automation-and-dev-tools/visual-studio-code-extension.md): Visual Studio Code (VS Code) is a preferred editor for many developers due to its versatility and extensive extension ecosystem. To enhance the experience further, Theneo offers a dedicated VS Code extension that simplifies the creation and previewing of API references directly within the editor. Installation and Configuration Install Theneo VS Code Extenstion Configure the Extension : After installation, sign in to your Theneo account at app.theneo.io Once signed in, navigate to your profile settings. Within your profile settings, locate and select the "Tools & Integrations" section. In the "Tools & Integrations" section, find and copy your Theneo API key. In VS Code Extension open the command palette by pressing Ctrl+Shift+P (or Cmd+Shift+P on Mac). Type 'Preferences: Open Settings (UI)' and select it. Search for Theneo Markdown in the “Extensions” section Paste your Theneo API key New Features Ability to export projects from Theneo as markdown and json. Ability to Import markdown into theneo directly. Ability to merge json to an existing project in Theneo. Usage Export Project from Theneo Open the command palette by pressing Ctrl+Shift+P (or Cmd+Shift+P on Mac). Search for “Theneo: Export Project from Theneo”. Select the project from your list of published projects created in Theneo. Enter a parent directory to export the project and press enter. Import Project to Theneo Open the command palette by pressing Ctrl+Shift+P (or Cmd+Shift+P on Mac). Search for “Theneo: Import Project To Theneo”. Enter project name after “/”. example /project Choose if you want to publish the document. Merge Project to Theneo Open the command palette by pressing Ctrl+Shift+P (or Cmd+Shift+P on Mac). Search for "Theneo: Merge Project To Theneo". Copy the relative path to the section that you want to merge. Pick the project you are merging with (usually the same project as you exported). Go over the changes and press commit merge button. Open Preview Open the command palette by pressing Ctrl+Shift+P (or Cmd+Shift+P on Mac). Search for “Theneo: Open Current Project Preview”. Type the project name and press enter. The Theneo VS Code extension streamlines the API documentation process by integrating it into your development environment. It saves time and enhances efficiency by eliminating the need to switch between tools for documentation tasks. With just a few clicks, you can generate a live preview of your API documentation, making it easier to develop and review your API descriptions and endpoints without ever leaving VS Code.
• [Theneo CLI](https://app.theneo.io/theneo/quickstart/automation-and-dev-tools/theneo-cli.md): What is Theneo CLI? Theneo CLI is a command-line interface tool that enables you to manage the Theneo platform directly from your terminal. It provides a streamlined workflow for creating, updating, publishing, and managing API documentation without requiring a web browser interface. Key Features Create and manage API documentation projects - Build comprehensive API docs from the command line Import API specifications from multiple sources - Support for OpenAPI, Postman, files, and URLs Publish documentation automatically - Make documentation available to your audience instantly Manage project versions and versions - Track API evolution with semantic versioning Export documentation in multiple formats - Markdown, OpenAPI, and more Manage workspaces and collaborate with teams - Organize documentation across teams Work with tabs for multi-API documentation - Document multiple related APIs in one project Support for environment-specific configurations - Handle different deployment environments System Requirements Node.js 12.x or higher npm (Node Package Manager) Git (for repository operations) Access to Theneo platform account Installation & Setup Installation Methods Global Installation (Recommended) Install Theneo CLI globally to use it from any directory: Bash npm install -g @theneo/cli@latest This command installs the latest version of Theneo CLI globally on your machine, making it accessible from any terminal session. Verifying Installation To verify the CLI is installed correctly: Bash theneo -V This command displays the installed version number. If successful, you can proceed with authentication. Authentication & Configuration Authentication Methods Token-Based Login Login with an API token Bash theneo login --token <theneo-api-key> Project Management Creating Projects Standard Project Creation: Bash theneo project create Creating from OpenAPI Specification Import from a local OpenAPI file: Bash theneo project create \ --name api-documentation \ --file ./examples/openapi-spec.json \ --generate-description overwrite \ --publish \ --public Creating from URL Import directly from a remote API specification: Bash theneo project create \ --name api-documentation \ --link https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/uspto.json \ --publish \ --public Creating from Postman Collections Import one or multiple Postman collections: Bash theneo project create \ --name api-documentation \ --postman-api-key <key> \ --postman-collection <id-1> \ --postman-collection <id-2> Project Creation Options Title Description Title Option Description Example --workspace Specify the workspace slug where project should be created --workspace myteam --empty Create an empty project without initial specifications --empty --sample Create project with sample template for quick start --sample --publish Automatically publish the project after creation --publish --public Make published documentation publicly accessible --public --generate-description Control AI description generation: fill, overwrite, or no_generation --generate-description fill --profile Use a specific profile from your config file --profile production Importing into Existing Projects Update an existing project with new API specifications: Bash theneo project import \ --project <project-slug> \ --file <file> \ --publish Import Type Options Different import strategies for handling specification updates: endpoints - Update only endpoint definitions overwrite - Replace entire documentation append - Add new content without removing existing merge_v2 - Intelligently merge old and new specifications (preserves customizations) Merge with Parameter Preservation When using merge import type, preserve custom parameter descriptions: Bash theneo project import \ --project <project-slug> \ --workspace <workspace-slug> \ --projectVersion <version-slug> \ --publish \ --file ./api-spec.json \ --import-type merge_v2 \ --keepOldParameterDescription \ --keepOldSectionDescription Note: Use the merge import type when you have made custom descriptions and want to preserve them while updating endpoint definitions. Publishing Projects Publish a project to make it available: Bash theneo project publish --project <project-slug> This makes your documentation publicly accessible or available to your team depending on the privacy settings. Deleting Projects Remove a project permanently: Bash theneo project delete --project <project-slug> Warning: This action cannot be undone. All documentation and versions will be deleted. Version Management About Versions Versions allow you to maintain multiple iterations of your API documentation independently. Each version can have its own endpoints, descriptions, and publishing status. This is essential for managing API evolution. Listing Versions View all versions of a project: Bash theneo version list \ --project <project-slug> \ --workspace <workspace-slug> Creating Versions Create a new project version: Bash theneo version create \ --name v2.0 \ --project <project-slug> \ --workspace <workspace-slug> Duplicate Previous Version Create a version by duplicating content from an existing version: Bash theneo version create \ --name v2.0 \ --project <project-slug> \ --workspace <workspace-slug> \ --previousVersion v1.0 This is useful when making a new major version where you want to start with the previous version's content. Deleting Versions Remove a specific version: Bash theneo version delete \ --project <project-slug> \ --workspace <workspace-slug> \ --version <version-slug> Note: Ensure you have at least one published version for your users. Managing Changelog Subscribers Add email subscribers to receive changelog notifications: Bash theneo version add-subscriber \ --project <project-slug> \ --workspace <workspace-slug> \ --projectVersion <version-slug> \ --email user@example.com Multiple subscribers: Run the command multiple times with different email addresses to add multiple subscribers. Data Import & Export Exporting Documentation Export as Markdown Export project documentation in Markdown format: Bash theneo export \ --project <project-slug> \ --projectVersion <version-slug> \ --workspace <workspace-slug> \ --dir ./docs Benefits: Create a structured Markdown directory with your documentation Version control your docs using Git Enable team collaboration via pull requests Maintains consistency with code repository Export as OpenAPI Specification Export your Theneo documentation back to OpenAPI format: Bash theneo export \ --openapi \ --format json \ --project <project-slug> \ --projectVersion <version-slug> \ --workspace <workspace-slug> \ --dir ./spec Supported formats: JSON export: Bash theneo export --openapi --format json --project <slug> --dir ./spec YAML export: Bash theneo export --openapi --format yaml --project <slug> --dir ./spec Importing from Markdown Create a new project from Markdown files: Bash theneo create \ --dir ./docs \ --name my-api \ --workspace <workspace-slug> Updating from Markdown Update an existing project from Markdown files: Bash theneo import \ --project <project-slug> \ --workspace <workspace-slug> \ --dir ./docs Tab Management Note: Tab operations are only available if the Tabs feature has been enabled for your workspace. Contact Theneo support to activate this feature. Managing Tabs Within Projects What are Tabs? Tabs allow you to manage multiple APIs within a single Theneo project. Each tab can have its own API specification and documentation while maintaining a unified project interface. Use cases for tabs: Multiple microservices with related functionality Different versions of the same API Related but independent APIs under one umbrella Breaking down large API documentation into manageable pieces Export Specific Tab Export documentation for a specific tab: Bash theneo export \ --project <project-slug> \ --projectVersion <version-slug> \ --workspace <workspace-slug> \ --tab <tab-slug> \ --dir ./tab-docs Export Tab as OpenAPI Export a tab's API specification: Bash theneo export \ --openapi \ --format json \ --project <project-slug> \ --projectVersion <version-slug> \ --workspace <workspace-slug> \ --tab <tab-slug> \ --dir ./spec Import Markdown to Specific Tab Update a specific tab from Markdown files: Bash theneo import \ --project <project-slug> \ --workspace <workspace-slug> \ --tab <tab-slug> \ --dir ./docs Import OpenAPI to Specific Tab Update a tab's API specification: Bash theneo project import \ --file ./api-spec.json \ --project <project-slug> \ --tab <tab-slug> \ --publish Common Tasks Checklist Title Description Task Command Login theneo login --token <key> Create project theneo project create --name api-docs --file ./spec.json Import updates theneo project import --project api-docs --file ./spec.json --import-type merge_v2 Create version theneo version create --name v2.0 --project api-docs Publish project theneo project publish --project api-docs Export docs theneo export --project api-docs --dir ./docs Export OpenAPI theneo export --openapi --format json --project api-docs Check version theneo -V Get help theneo [command] --help Troubleshooting Authentication Issues If you encounter authentication errors: Verify API key - Ensure your API key is correct and not expired Check environment variable - Verify THENEO_API_KEY is properly set Try fresh login - Re-authenticate: theneo login --token <key> Check account permissions - Verify account role in Theneo web interface Validate workspace access - Ensure you have access to the workspace Import Errors When import fails: Validate specification - Ensure API spec follows OpenAPI 3.x format Check file permissions - Verify file paths and read permissions Verify project/workspace - Confirm project and workspace slugs exist Check specification size - Very large specs may require timeout adjustments Publishing Issues If publishing fails: Check endpoints - Confirm project contains valid endpoints Review descriptions - Verify descriptions meet any length requirements Version Management Issues When working with versions: List versions - Check existing versions: theneo version list --project <slug> Verify slug spelling - Ensure previous version slug is spelled correctly Check permissions - Verify workspace and project ownership Performance Optimization Keep directories clean - Remove unnecessary Markdown files Use profiles - Avoid re-authenticating with every command Run exports periodically - Create regular backups of your documentation
• [Merge 2.0](https://app.theneo.io/theneo/quickstart/automation-and-dev-tools/merge-2-0.md): Merge 2.0 is a redesigned import workflow that uses a two-phase, two-level diffing engine to identify and apply only what has actually changed in your API spec. Instead of rewriting every section on every import, it compares your new spec against the live state of your project and targets only added, removed, or genuinely modified endpoints - leaving everything else completely untouched. The result is fewer unintended overwrites, preserved customizations, and a more reliable re-import experience at any scale. What Gets Preserved What Why It Matters Section IDs on matched endpoints External links, integrations, and bookmarks to specific sections remain valid after re-import Menu structure and ordering Existing navigation hierarchy is untouched for unchanged and changed sections - only added and removed items modify the menu User customizations on unchanged sections SEO titles, descriptions, display preferences, access control, and viewer lists are never overwritten because unchanged sections are never written to Removed section documents Sections removed from the menu are kept in the database - no content is permanently deleted Improved Changelog Accuracy Because the diff engine knows precisely which endpoints changed and why, the auto-generated Changelog now reflects only real API contract changes. Entries for unchanged sections - which previously appeared as modified due to full re-merge writes - no longer surface in the Changelog. The result is a cleaner, more trustworthy change history with no irrelevant or auto-generated noise. How to Use Merge 2.0 Editor UI CLI Open the Editor UI . Type / to open the widget menu . From the menu, select Import Collection . In the modal window, locate the Import Type dropdown. Choose Merge 2.0 . Proceed with the import. Using the CLI Run the following command: Bash theneo project import \ --project <project-slug> \ --workspace <workspace-slug> \ --projectVersion <version-slug> \ --publish \ --file ./api-spec.json \ --import-type merge_v2 Requirements Theneo CLI version 19.1 or later To verify your CLI version, run: Bash theneo --version
• [Model Context Protocol](https://app.theneo.io/theneo/quickstart/automation-and-dev-tools/model-context-protocol.md): The Model Context Protocol (MCP) is an open standard that allows AI assistants and developer tools, such as Claude, Cursor, and other LLM-powered clients, to interact directly with external services and APIs in a structured, context-aware way. Instead of an AI assistant simply reading documentation, MCP enables it to actively call your API, understand its capabilities, and execute operations on behalf of the user. Theneo's MCP Server feature lets you generate a fully configured MCP server directly from your existing API specification. Once generated, your API becomes immediately consumable by any MCP-compatible AI client - without requiring custom integration work on your end. How it works, in three steps: You configure and generate an MCP server from your API spec in Theneo. Theneo produces a ready-to-run server that exposes your selected API operations as structured tools. An MCP-compatible AI client connects to your server and can discover, understand, and call your API operations in real time. Accessing MCP Settings Navigate to the MCP configuration page directly at: https://editor.theneo.io/mcp Configuration Base URL Override The Base URL Override field allows you to specify a custom API base URL for your MCP server (e.g., https://api.example.com ). Leave this field empty if you want the MCP server to use the base URL already defined in your OpenAPI specification. Transport Method Use the Transport Method dropdown to select how your MCP server will communicate. The following options are available: STDIO - Standard input/output. Best suited for local development environments and CLI-based integrations. HTTP - Standard HTTP transport. Recommended for server-to-server communication and web-based deployments. Server-Sent Events (SSE) - Enables real-time, one-directional streaming from server to client. Ideal for use cases requiring live updates. Select the transport method that best fits your deployment environment and infrastructure requirements. API Operations The API Operations section displays all available endpoints from your API specification. Each operation is listed with its HTTP method, path, and a brief description. Use the checkboxes to select or deselect individual operations you want to include in the generated MCP server. Click Deselect All to quickly clear all selections, or reselect operations individually as needed. Only the operations you select will be exposed through the generated MCP server. Authentication & Security The Authentication & Security section allows you to manage access controls and protect your data by configuring the authentication settings required for your MCP server. These controls ensure that only authorized users can connect and interact with your server safely. Security schemes are automatically detected from your OpenAPI specification. For each scheme, you can define the Environment Variable Name that your MCP server will use to resolve the corresponding credential at runtime. Advanced Settings The Advanced section provides additional configuration options to fine-tune your MCP server's behavior. Request Timeout (ms) Defines the maximum time (in milliseconds) the MCP server will wait for a response before timing out. The default value is 30,000 ms (30 seconds). Adjust this value based on the expected response times of your API. Enable Pagination Hints Check this option to add pagination support for list-based operations. When enabled, the MCP server will include hints that help AI clients understand how to paginate through results effectively. Generating the MCP Server Once you have completed your configuration click the Generate MCP server button located in the bottom-right corner of the page. Theneo will process your configuration and generate a ready-to-use MCP server based on your API specification and the options you defined. Tips If you are unsure which transport method to use, STDIO is recommended for local testing, while HTTP or Server-Sent Events are better suited for production deployments. Ensure all required environment variables are configured in your runtime environment before starting the MCP server to avoid authentication failures. You can return to https://editor.theneo.io/mcp at any time to regenerate your MCP server with updated settings or a different selection of API operations. Need Help? If you would like to enable the MCP Server feature for an existing Theneo workspace or project, please contact the Theneo support team at hello@theneo.io . The team will assist you in getting the feature activated.
• [Theneo SDK](https://app.theneo.io/theneo/quickstart/automation-and-dev-tools/theneo-sdk.md): The Theneo SDK is a comprehensive package designed to simplify API requests to the Theneo API, enabling easy integration of Theneo's features into various applications. This SDK abstracts the complexities of API requests and error handling, providing a more streamlined experience for developers. This documentation provides an overview of the Theneo SDK package. The SDK package includes classes and interfaces for working with the Theneo API. Theneo is a platform for managing API documentation projects. You can find the Github repository here Install Install the Theneo SDK Package: Use npm to install the Theneo SDK package: Bash npm install @theneo/sdk Usage To use the Theneo SDK package, import the necessary classes and interfaces, and create an instance of the Theneo class with the required options. Then, you can use the methods provided by the SDK to interact with the Theneo API. JavaScript import { Theneo, TheneoOptions, Result, Workspace, ProjectSchema, CreateProjectOptions } from "@theneo/sdk"; // Define Theneo options const options: TheneoOptions = { apiKey: "YOUR_API_KEY" }; // Create a Theneo instance const theneo = new Theneo(options); // Example usage async function listWorkspaces() { const result: Result<Workspace[]> = await theneo.listWorkspaces(); if (result.ok) { const workspaces: Workspace[] = result.unwrap(); console.log("Workspaces:", workspaces); } else { console.error("Error:", result.unwrap()); } } // Create a new project async function createProject() { const projectOptions: CreateProjectOptions = { name: "My Project", workspace: { key: "workspace-key" }, publish: true, isPublic: true, data: { // Specify the data source using one of the following attributes: // 1. Import from a file // file: '/path/to/api-documentation.json', // 2. Import from a URL // link: 'https://example.com/api-documentation.json', // 3. Import from a text string // text: 'API documentation content as a string', // 4. Import from a Postman collection // postman: { // apiKey: 'YOUR_POSTMAN_API_KEY', // collectionIds: ['collection-id-1', 'collection-id-2'], // }, } as ApiDataInputOption }; const result: Result<CreateProjectResponse> = await theneo.createProject(projectOptions); if (result.ok) { const createdProject: CreateProjectResponse = result.unwrap(); console.log("Created Project:", createdProject); } else { console.error("Error:", result.unwrap()); } } // Use the SDK methods as needed listWorkspaces(); createProject(); Import API documentation An example demonstrating how to use the importProjectDocument method to import API documentation to an existing project using the Theneo SDK in TypeScript: JavaScript import { Theneo, TheneoOptions, Result, ImportProjectOptions, ImportResponse, ApiDataInputOption } from "@theneo/sdk"; // Define Theneo options const options: TheneoOptions = { apiKey: "YOUR_API_KEY" }; // Create a Theneo instance const theneo = new Theneo(options); // Define the import options const importOptions: ImportProjectOptions = { projectId: "project-id", // Replace with the actual project ID publish: true, // Set to true if you want to publish the imported data data: { // Specify the data source using one of the following attributes: // 1. Import from a file // file: '/path/to/api-documentation.json', // 2. Import from a URL // link: 'https://example.com/api-documentation.json', // 3. Import from a text string // text: 'API documentation content as a string', // 4. Import from a Postman collection // postman: { // apiKey: 'YOUR_POSTMAN_API_KEY', // collectionIds: ['collection-id-1', 'collection-id-2'], // }, } as ApiDataInputOption }; // Import API documentation to the project async function importApiDocumentation() { const result: Result<ImportResponse> = await theneo.importProjectDocument(importOptions); if (result.ok) { const importResponse: ImportResponse = result.unwrap(); console.log("Imported API Documentation:", importResponse); } else { console.error("Error:", result.unwrap()); } } // Run the import function importApiDocumentation(); In this example: We first create an instance of the Theneo class and provide the necessary API key in the options object. We define the import options in the importOptions object. You should replace 'project-id' with the actual ID of the project where you want to import the API documentation. Inside the data attribute of importOptions , you can specify the source of the API documentation to be imported. You can choose one of the four options: Import from a file (specify the file path). Import from a URL (specify the URL). Import from a text string (specify the content as a string). Import from a Postman collection (specify the Postman API key and collection IDs). The publish option is set to true to indicate that the imported data should be published. The importApiDocumentation function uses the importProjectDocument method to perform the import operation. Make sure to replace the placeholder values ( 'YOUR_API_KEY' , 'project-id' , and any others) with your actual API key and project details before running the code. TheneoOptions (Interface) Options for initializing the Theneo SDK. apiKey?: string : API key for the Theneo application. apiClientName?: string : Name of the client making the API call (default is theneo-sdk:${SDK_VERSION} ). baseApiUrl?: string : Theneo API URL. baseAppUrl?: string : Theneo APP URL. Theneo (Class) The main class for interacting with the Theneo API. Methods listWorkspaces(role?: UserRole): Promise<Result<Workspace[]>> : Lists workspaces available for a user. listProjects(): Promise<Result<ProjectSchema[]>> : Lists user projects. deleteProjectById(projectId: string): Promise<Result<void>> : Deletes a project by ID. publishProject(projectId: string): Promise<Result<PublishProjectResponse>> : Publishes API documentation for a project. getPreviewProjectLink(projectId: string): string returns preview link for a project. importProjectDocument(options: ImportProjectOptions): Promise<Result<ImportResponse>> : Imports API documentation to an existing project. createProject(options: CreateProjectOptions): Promise<Result<CreateProjectResponse>> : Creates a new project on the Theneo platform. getDescriptionGenerationStatus(projectId: string): Promise<Result<ProjectCreationStatusResponse, Error>> : Gets the description generation status for a project. waitForDescriptionGeneration(projectId: string, progressUpdateHandler?: DescriptionGenerationProgressHandler, retryTime?: number, maxWaitTime?: number): Promise<Result<never>> : Waits for description generation to finish. static listPostmanCollections(postmanApiKey: string): Promise<Result<PostmanCollection[]>> : Returns list of Postman Collections using the api key DescriptionGenerationType (Enum) An enum representing different types of description generation options. FILL : Generate descriptions for parameters that do not have descriptions already. OVERWRITE : Overwrite descriptions for parameters that do not have descriptions already. NO_GENERATION : Do not generate descriptions for parameters that do not have descriptions already. DescriptionGenerationProgressHandler (Type) A callback function type that receives the progress percentage of description generation. PostmanImportOptions (Interface) Options for importing Postman collections. apiKey: string : Postman API key. collectionId: string[] : Postman collection IDs to be imported. WorkspaceOption (Interface) Workspace options for creating a project. key?: string : Workspace key. id?: string : Workspace ID. ApiDataInputOption (Interface) Data input options for creating a project. Specify only one of the following attributes. file?: fs.PathLike : Path to a file containing API documentation. link?: URL : URL to a file containing API documentation. text?: string : API documentation as a string. postman?: PostmanImportOptions : Postman collection to create the project from. CreateProjectOptions (Interface) Options for creating a project. name: string : Project name. workspace?: WorkspaceOption : Workspace where to create the project (default is the user's default workspace). publish?: boolean : Indicates if the project should be published after creation (default is false ). isPublic?: boolean : Indicates if the project is public (default is false ). data?: ApiDataInputOption : API documentation data for creating the project. sampleData?: boolean : Indicates if the project should be created with sample data. descriptionGenerationType?: DescriptionGenerationType : Description generation type. progressUpdateHandler?: DescriptionGenerationProgressHandler : Callback for description generation progress. ImportOption (Enum) An enum representing different options for importing API specifications. ENDPOINTS_ONLY : Import only the endpoints. OVERWRITE : Overwrite existing data. MERGE : Merge with existing data. ImportProjectOptions (Interface) Options for importing API documentation to an existing project. projectId: string : Project ID. publish: boolean : Indicates if the imported data should be published. data: ApiDataInputOption : API documentation data for importing. importOption?: ImportOption : Import option. PublishProjectResponse (Interface) A response object after publishing a project. projectKey: string : Project key. baseUrlRequired: boolean : Indicates if a base URL is required. companySlug: string : Company slug. publishedPageUrl: string : URL of the published page. CompanySchema (Interface) A schema representing company information. id: string : Company ID. name: string : Company name. slug: string : Company slug. corporateId: string : Corporate ID. createdAt: Date : Creation date. updatedAt: Date : Last updated date. createdBy: string : Created by user. ProjectSchema (Interface) A schema representing project information. id: string : Project ID. name: string : Project name. key: string : Project key. isPublic: boolean : Indicates if the project is public. companyId: string : Company ID. createdAt: Date : Creation date. company: CompanySchema : Company information. CreateOtherTypeOfDocOptions (Interface) Options for creating other types of documentation. docType: string : The type of documentation. gettingStartedSections?: { introduction: boolean; prerequisites: boolean; quickStart: boolean; resources: boolean; } : Sections for getting started documentation. sdk?: { overview: boolean; supportedLibraries: boolean; sampleCode: boolean; troubleshooting: boolean; } : SDK documentation sections. faq?: { generalInfo: boolean; authentication: boolean; usage: boolean; billing: boolean; } : FAQ sections. CreatedProjectStatusEnum (Enum) An enum representing different statuses for a created project. CREATED : Project creation completed successfully. STARTED : Project creation is in progress. FINISHED : Project creation finished successfully. ERROR : Project creation encountered an error. CREATED_WITHOUT_AI_GENERATION : Project created without AI generation. CreateProjectResponse (Interface) A response object after creating a project. projectId: string : Project ID. publishData?: PublishProjectResponse : Information about the published project. ProjectCreationStatusResponse (Interface) A response object containing information about the status of project creation. name: string : Project name. key: string : Project key. creationStatus: CreatedProjectStatusEnum : Creation status. descriptionGenerationProgress: number : Progress of description generation in percentage. updatedAt: string : Last updated date. ImportResponse (Interface) A response object after importing a project. collectionId: string : Collection ID. publishData?: PublishProjectResponse : Information about the published project. UserRole (Enum) An enum representing different user roles. ADMIN : Administrator. EDITOR : Editor. Workspace (Interface) Workspace information. workspaceId: string : Workspace ID. name: string : Workspace name. slug: string : Workspace slug/key. role: UserRole : Workspace role. isDefault: boolean : Indicates if the workspace is the default workspace. isCorporate: boolean : Indicates if the workspace is corporate. isSubscribed: boolean : Indicates if the workspace is subscribed. ResultImp (Abstract Class) An abstract class representing the result of an operation that can either succeed with a value of type T or fail with an error of type E . Methods unwrap(): T : Unwraps the successful result value. If the result is an error, this method will throw an exception. unwrap<U>(ok: (value: T) => U): U : Unwraps the successful result value and applies a function to it. unwrap<U, V>(ok: (value: T) => U, err: (error: E) => V): U | V : Unwraps the result value and applies functions based on whether it's a success or an error. unwrap<U>(ok: (value: T) => U, err: (error: E) => U): U : Unwraps the result value and applies a function based on whether it's a success or an error. map<U>(ok: (value: T) => U): Result<U, E> : Transforms a successful result into a new result with a different value type. map<U, F extends Error>(ok: (value: T) => U, err: (error: E) => F): Result<U, F> : Transforms a result into a new result with different value and error types. chain<X>(ok: (value: T) => Result<X, E>): Result<X, E> : Chains a function that produces a new result based on the success value. chain<X>(ok: (value: T) => Result<X, E>, err: (error: E) => Result<X, E>): Result<X, E> : Chains functions for both success and error cases. chain<X, U extends Error>(ok: (value: T) => Result<X, U>, err: (error: E) => Result<X, U>): Result<X, U> : Chains functions with different error types. OkResult (Class) A class representing a successful result. Properties value: T : The successful value. ErrResult (Class) A class representing an error result. Properties error: E : The error object. Ok(value: T): Result(Function) A function for creating a successful result. value: T : The value to wrap in the result. Err(error?: E): Result (Function) A function for creating an error result. error?: E : An optional error object. ResponseSchema (Interface) An interface representing the schema of a response object. data: T : The data payload of the response. message: string : A message associated with the response.
• [Postman Sync](https://app.theneo.io/theneo/quickstart/automation-and-dev-tools/postman-sync.md): Theneo supports automatic synchronization with Postman collections via GitHub. This powerful integration ensures that any changes you make to your Postman API collections are seamlessly updated in your Theneo documentation—without manual effort. By setting up a GitHub integration in Postman and configuring a Theneo GitHub Action workflow, you can keep your API documentation fully aligned with your latest API definitions. Benefits of Postman Sync Real-time Updates : Every change you make in Postman is reflected in Theneo. No Manual Uploads : Eliminate the need to manually export and upload collections. Version Control : Changes are tracked through GitHub, enabling better collaboration and rollback capability. Streamlined Workflow : Developers can focus on building APIs while keeping docs always up-to-date. Automated Publishing : With auto-publish enabled, your docs stay fresh without extra steps. How to Set Up Postman to GitHub Sync 1 Open Integrations in Postman Open Postman . Navigate to the Integrations tab. 2 Connect GitHub to Postman Search for GitHub in the integrations list. Select "Back up a collection" from the available configuration options. Enter your GitHub API key to authorize the connection. 3 Choose Postman Workspace and Collection Select the Postman workspace that contains your collection. Choose the collection you want to sync with GitHub. 4 Set GitHub Repository and File Details Pick the GitHub repository where the collection will be stored. (Optional) Enter a directory path if you want to save the file in a specific folder. Define the file name (e.g., api.yml ). Choose the branch where the file should be committed (typically main ). After completing this setup, all updates made in Postman will be automatically pushed to your GitHub repository. Syncing GitHub Updates with Theneo To ensure updates also sync to Theneo automatically, you'll need to configure Theneo GitHub Actions in your repository. Create a Workflow File Add a file named Theneo.yml in the .github/workflows/ directory of your GitHub repo. Here’s an example workflow file: YAML name: Update Documentation on: pull_request: branches: - main jobs: update-doc: name: Update Theneo Documentation runs-on: ubuntu-latest steps: - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event." - name: Checkout uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: "18" - name: Update Documentation on Theneo uses: Theneo-Inc/api-documentation@1.8.0 with: FILE_PATH: doc/api.yml PROJECT_SLUG: <project_slug> VERSION_SLUG: <version_slug> WORKSPACE_SLUG: <workspace_slug> SECRET: ${{secrets.SECRET}} AUTO_PUBLISH: true IMPORT_OPTION: merge PARAMETER_DESCRIPTION_MERGE_STRATEGY: keep_new SECTION_DESCRIPTION_MERGE_STRATEGY: keep_old INCLUDE_GITHUB_METADATA: true Replace placeholders like <project_slug> , <version_slug> , and <workspace_slug> with your actual Theneo values. Make sure to add your Theneo secret in GitHub repository secrets. Need help setting this up visually? 👉 Here is the video guide for more guidance : More Resources For complete details on how to configure Theneo GitHub Actions, visit our setup guide here. Once you've successfully configured GitHub sync in Postman and set up the Theneo GitHub Action workflow, your API documentation in Theneo will stay automatically in sync with your latest Postman updates.
• [GitLab Sync](https://app.theneo.io/theneo/quickstart/automation-and-dev-tools/gitlab-sync.md): Theneo offers seamless synchronization with GitLab repositories, enabling automatic pushing of your API specifications or entire documentation folders to your Theneo workspace. This guide walks you through the steps to configure GitLab CI/CD for Theneo sync. Before starting, make sure you have: A GitLab repository where you manage your API specs or documentation. Your Theneo API Key . The following Theneo configuration variables set in your GitLab CI/CD settings: THENEO_API_KEY : Your Theneo API token, used for authentication, can be found in your Theneo profile settings. THENEO_PROJECT_SLUG : Your project's unique identifier in Theneo, accessible under project settings. THENEO_WORKSPACE_SLUG : Project workspace slug to import documentation under specific workspace, accessible under project settings. THENEO_VERSION_SLUG : Project version slug to import documentation under a specific version, otherwise default version will be used. THENEO_FILE_PATH : The path to your API documentation file within the repository (for API spec import). Folder_PATH : The path to your documentation folder within the repository (for folder import). Setup Instructions You can configure the sync by either editing your existing .gitlab-ci.yml file or creating a new one in your repository. Import API Specs Only To push a single OpenAPI spec file to Theneo, use the following .gitlab-ci.yml script: YAML image: node:22 stages: - push-to-theneo push-openapi-to-theneo: stage: push-to-theneo script: - npm install -g @theneo/cli@latest - echo "Logging in to Theneo..." - theneo login --token $THENEO_API_KEY - echo "Listing Theneo projects..." - theneo project list - echo "Importing OpenAPI spec to Theneo..." - | theneo project import \ --project $THENEO_PROJECT_SLUG \ --workspace $THENEO_WORKSPACE_SLUG \ --projectVersion $THENEO_VERSION_SLUG \ --publish \ --file $THENEO_FILE_PATH \ --import-type overwrite You can also specify how Theneo handles incoming changes using the --import-type option: overwrite – Replaces the existing documentation with the new specification entirely. merge (beta) – Attempts to combine new content with existing documentation. May append or blend content based on: PARAMETER_DESCRIPTION_MERGE_STRATEGY: keep_new SECTION_DESCRIPTION_MERGE_STRATEGY: keep_old endpoints – Adds new spec endpoints into a separate section for manual arrangement later in the editor. Import an Entire Folder To push an entire folder to Theneo, use this alternative script: YAML image: node:22 stages: - push-to-theneo push-openapi-to-theneo: stage: push-to-theneo script: - npm install -g @theneo/cli@latest - echo "Logging in to Theneo..." - theneo login --token $THENEO_API_KEY - echo "Listing Theneo projects..." - theneo project list - echo "Importing OpenAPI spec to Theneo..." - | theneo import \ --project $THENEO_PROJECT_SLUG \ --workspace $THENEO_WORKSPACE_SLUG \ --projectVersion $THENEO_VERSION_SLUG \ --publish \ --dir $Folder_PATH \ Notes Make sure the @theneo/cli version is kept up to date to benefit from the latest features and fixes. The --publish flag will automatically make your imported content live on Theneo.
• [Bitbucket](https://app.theneo.io/theneo/quickstart/automation-and-dev-tools/bitbucket.md): Bitbucket’s collaborative environment is ideal for teams to manage their codebase. Integrating Bitbucket with Theneo ensures your API documentation stays in sync with your repository changes. Here’s how to set up Bitbucket integration: Usage Step 1: Create Theneo Documentation Initiate your API documentation by creating a project on the Theneo platform. Prerequisites for Bitbucket Integration An established API documentation project on Theneo. A generated API key from your account → https://app.theneo.io/account-settings/toolsandintegrations Your API documentation file located within your Bitbucket repository. After setting up the Bitbucket pipeline with the appropriate Theneo variables, your API documentation will automatically reflect changes pushed to your repository. This seamless integration facilitates an up-to-date and accurate representation of your API for developers and stakeholders. Step 2: Configure Bitbucket Pipeline Incorporate Theneo's automation into your Bitbucket repository: Add a Pipeline : Integrate Theneo's pipeline into your bitbucket-pipelines.yml file to update your Theneo documentation with each repository update. Configure the Pipeline : Use the snippet below in your bitbucket-pipelines.yml file to set up the pipeline. For Importing a single API Spec YAML # bitbucket-pipelines.yml image: node:22 pipelines: default: - step: name: Import OpenAPI spec to Theneo caches: - node script: # Install CLI + login - npm install -g @theneo/cli@latest - echo "Logging in to Theneo..." - theneo login --token "THENEO_API_KEY" # Import the spec file - | theneo project import \ --project "THENEO_PROJECT_KEY" \ --workspace "$THENEO_WORKSPACE_SLUG" \ --publish \ --file "API_DOCUMENT_PATH" \ --import-type merge Variables for Bitbucket Pipeline : API_DOCUMENT_PATH : The path to your API spec within your repository. e.g docs THENEO_PROJECT_KEY : The unique slug of your Theneo project. Find this in your Theneo project URL: https://app.theneo.io/[workspace-name]/[project-slug] . For example, if your Theneo project URL is https://app.theneo.io/theneo/bitbucket-demo , the bitbucket-demo is your project slug. THENEO_API_KEY : Your Theneo API key, which you can generate from the Theneo website. Sample script Plain text # bitbucket-pipelines.yml image: node:22 pipelines: default: - step: name: Import OpenAPI spec to Theneo caches: - node script: # Install CLI + login - npm install -g @theneo/cli@latest - echo "Logging in to Theneo..." - theneo login --token "8dd818-f628-40fd-9ff2-b84f7d42da6d" # Import the spec file - | theneo project import \ --project "demo" \ --workspace "demo" \ --publish \ --file "docs/petstore.yaml" \ --import-type merge # bitbucket-pipelines.yml image: node:22 pipelines: default: - step: name: Import OpenAPI spec to Theneo caches: - node script: # Install CLI + login - npm install -g @theneo/cli@latest - echo "Logging in to Theneo..." - theneo login --token "8dd818-f628-40fd-9ff2-b84f7d42da6d" # Import the spec file - | theneo project import \ --project "demo" \ --workspace "demo" \ --publish \ --file "docs/petstore.yaml" \ --import-type merge In here, this is my sample token --token "8dd81-f628-40fd-9ff2-b84f7d42da6d" , testdoc is the project slug --project "testdoc" , and my api spec is located here docs/petstore.yaml Import Options Choose how Theneo handles incoming changes: overwrite: Replaces the current documentation with the new spec entirely. merge: Attempts to merge changes; this is experimental and may append changes in some cases. endpoints: Adds new spec endpoints into a dedicated section for manual arrangement. For Importing an entire folder (markdowns + API) If you would like to import exported markdown content + API configuration, then you can use the following script YAML # bitbucket-pipelines.yml image: node:22 pipelines: default: - step: name: Push OpenAPI to Theneo caches: - node script: - npm install -g @theneo/cli@latest - echo "Logging in to Theneo..." - theneo login --token "THENEO_API_KEY" - echo "Listing Theneo projects..." - theneo project list - echo "Importing OpenAPI spec to Theneo..." - echo "Updating a Project in Theneo..." - theneo import --project "THENEO_PROJECT_KEY" --workspace "Workspace_name" --dir path_to_yourfolder
  • [Atlassian Compass](https://app.theneo.io/theneo/quickstart/automation-and-dev-tools/bitbucket/atlassian-compass.md): Atlassian Compass is a powerful tool for managing microservices and software components. By integrating Theneo with Compass, you can bring your API documentation directly into your Compass environment, enhancing collaboration and visibility. Here’s a step-by-step guide on how to set up the Theneo integration in Compass. Installation Access Compass : Log into your Compass account. Install the Theneo App : Navigate to 'Apps' from the top menu bar in Compass. Find the Theneo tile and select 'Install'. Configuration : After installation, if you are an admin, select 'Configure' to proceed with setting up the integration. Setting Up the Integration Install Theneo App on Compass : Within Compass, go to the Theneo app configuration. Paste your copied Theneo API key to link your Theneo account with Compass. Create or Link a Theneo Project : You can choose to start a new API documentation project in Theneo or link an existing one. Adding a Project to a Compass Component Upload a File Find the Compass Component : Go to the component where you want to add the spec file and select 'Theneo'. Under the 'Upload File' tab, drag and drop your spec file onto the drop zone or browse to select the file from your computer. The file size limit is 10MB. Using Webhook cURL Command Example: Bash curl -F file=@<FILE_NAME_TO_IMPORT> -F project_name=<PROJECT_NAME_TO_CREATE> -F ai_option=<none|full|enhance> -H "x-theneo-api-key:<YOUR_API_KEY>" https://api.theneo.io/project/import/specfile Replace placeholders with your file name, project name, AI option, and Theneo API key. AI options include 'none', 'full', and 'enhance'. Linking to an Existing Project Select from Published Projects : Use the dropdown menu to choose from your published projects in Theneo. AI Assistance for API Documentation Full AI Assistance : Generates new content for your documentation. Enhance Existing Content : AI enhances your existing documentation by filling in missing descriptions. Removing the Project from a Compass Component In your project view, find the dropdown menu on the top right and select 'Generate new project'. Removing the API Key from a Compass Component Navigate to Theneo under 'Apps', click on 'Configure', and then find the option to 'Replace API Key'. Note: This action is restricted to administrators.
• [AI Co-Pilot](https://app.theneo.io/theneo/quickstart/ai-co-pilot-and-chat/ai-co-pilot.md): Theneo AI Co-Pilot revolutionizes the way you create API documentation by automating the generation of descriptive content. This powerful feature saves you significant time and effort, particularly when your API undergoes frequent updates. Here’s how you can leverage the AI Co-Pilot in Theneo: 1. Opting for AI Assistance During Project Creation: Full AI Assistance: Choose this to allow the AI to craft new content for each part of your documentation, replacing existing descriptions for consistency and engagement. Enhance Existing Content: Select this for the AI to smartly fill in missing pieces without modifying what you’ve already crafted, preserving the originality of your content. No AI Assistance: If you prefer manual control over your content, opt for this to keep the existing documentation untouched by AI. 2. Using AI Assistant Within the Editor: Click on "AI Assistant" in the editor when working on an API spec. The AI Assistant proactively suggests detailed descriptions for each component of your API request, such as headers, body, parameters, and responses. Example Workflow: Imagine you're documenting an order creation endpoint with a body parameter like idempotency_key . The AI Co-Pilot might suggest a description such as "Provide a unique key to prevent duplicate orders on network failure," clarifying its use for your consumers. Advantages of Theneo AI Co-Pilot: Time Efficiency: It dramatically reduces the time required to write and update documentation. Consistency: Ensures uniformity in language and style across all documentation segments. Accuracy: AI-generated content is designed to be precise, reducing potential errors and misunderstandings. Focus on Core Tasks: Frees up your time to concentrate on API design and development rather than documentation. Integrating Theneo AI Co-Pilot: The Theneo AI Co-Pilot is an invaluable resource, akin to having a dedicated technical writer on your team. It enhances your documentation process, ensuring that your API is documented thoroughly, accurately, and in a way that’s easy to understand for users, all while you remain focused on the more strategic aspects of API design and functionality.
• [AI Search](https://app.theneo.io/theneo/quickstart/ai-co-pilot-and-chat/ai-search.md): Theneo's ChatGPT integration allows users to interact with your documentation in a conversational manner. They can ask any questions related to the documentation content, ranging from technical queries to business-related inquiries, directly within the docs. Enabling ChatGPT Integration: Navigate to the Settings area of your Theneo dashboard. Locate the Features section. Find the AI search option and toggle the switch to enable it. Republish your documentation to make the AI search feature live. Using AI Search in Theneo: Once enabled, users can ask questions directly within the documentation interface. The system is designed to comprehend the context of the documentation and provide relevant answers, leveraging the powerful capabilities of GPT-4 turbo. Continuous Conversation Ask AI now supports fully persistent, multi-turn conversations. Instead of each query being treated independently, the AI retains context across your messages - so you can ask follow-up questions, refine your request, or explore a topic in depth without repeating yourself. Two delivery modes are available depending on how you access Ask AI. Embedded Chat Conversation threads run directly within the existing search component. Open Ask AI as usual — the chat interface replaces the single-query input with a persistent thread that holds context for the duration of your session. Side-Panel Assistant A slide-out modal that opens alongside your published documentation, keeping the page content visible while you converse with the AI. Ideal for referencing docs and asking follow-up questions in parallel without losing your place. Choosing a Layout To set which mode your project uses, go to your project dashboard and open Settings → Features . Locate the AI Search toggle and select your preferred layout from the dropdown beneath it. 1 Open project settings Settings → Features 2 Locate the AI Search toggle AI Search 3 Select your layout Search box Side-Panel Conversation context is retained for the duration of your session. Starting a new Ask AI session begins a fresh thread. FAQ: Does Theneo send entire documentation content to ChatGPT for processing? No, Theneo ensures that only pertinent snippets of information are sent to ChatGPT based on the user's query to maintain efficiency and privacy. Which AI model does Theneo use for processing user queries? Theneo uses the latest GPT-4 turbo, ensuring that users benefit from the most advanced language model for their queries. By integrating AI Search, Theneo enhances the user experience by providing an interactive, AI-driven approach to navigating and understanding API documentation. This feature not only adds a layer of user engagement but also aids in quickly resolving queries, making the documentation more accessible and user-friendly. Note: You can try AI Search even in this doc, simply click on search and then click on “ask AI” button
• [AI Chatbot](https://app.theneo.io/theneo/quickstart/ai-co-pilot-and-chat/ai-chatbot.md): The AI Chatbot feature is designed to streamline the process of finding information about Theneo, helping users quickly receive accurate answers without having to sift through extensive documentation. Located on Theneo's dashboard, this intelligent assistant is trained on Theneo's documentation, knowledge base, and other relevant content to ensure users get the information they need with ease. But there’s more! You can harness the same power for your documentation by creating and embedding your own AI chatbot. Let’s explore how this feature can enhance your support experience and why it’s a game-changer for you and your users. Why Use the AI Chatbot? For Theneo Users Quick Problem Solving : Have a specific question about Theneo? Just ask the chatbot! It provides fast, accurate answers without requiring you to navigate through extensive guides. Ease of Use : The intuitive interface ensures that even first-time users can interact seamlessly with the chatbot and find what they need in seconds. Comprehensive Knowledge : With access to Theneo’s entire knowledge base and documentation, the chatbot covers all aspects of the platform, from simple FAQs to in-depth technical details. For Your Own Documentation The AI Chatbot is not just for Theneo users. You can also: Train the Chatbot on Your Content : Input your own documentation, FAQs, and support materials, creating a tailored chatbot for your platform. Provide 24/7 Support : Offer uninterrupted assistance to your users without increasing support team resources. Enhance Productivity : Free up your support team to focus on complex queries while the chatbot handles routine questions efficiently. Features That Make the AI Chatbot Stand Out Smart, Context-Aware Assistance The chatbot understands context and nuances, ensuring it provides the most relevant responses to user queries. Customizable for Your Brand Configure the chatbot to align with your brand’s tone, style, and voice, creating a consistent experience across your platforms. Seamless Integration Embed the chatbot into your documentation or platform effortlessly. Whether it’s your developer portal, website, or product interface, the chatbot fits right in. Search Export Capability Export the chatbot’s functionality to external platforms like websites, apps, or customer portals. This feature extends its utility beyond the documentation, offering users a unified experience wherever they interact with your content. Benefits of Exporting and Embedding the Chatbot Wider Reach : Bring your chatbot to where your users are—on your platform, website, or mobile app. Streamlined User Journeys : Offer users quick answers and guidance directly within the interface they’re using, eliminating the need to switch between platforms. Improved User Satisfaction : By providing instant support, you make your users feel valued and supported, fostering loyalty and trust. How to Get Started Click here to learn how you can integrate your own intelligent help bot and elevate your user support experience.
• [AI Export](https://app.theneo.io/theneo/quickstart/ai-co-pilot-and-chat/ai-export.md): The AI/Markdown Export feature in Theneo allows you to quickly generate Markdown versions of your documentation. Markdown files are lightweight, structured, and optimized for AI processing. By exporting your content in Markdown, you can: Achieve better response accuracy when using AI tools. Reduce token usage and improve processing speed. Provide AI assistants with full context of your documentation. This feature is particularly helpful when working with AI tools like ChatGPT , Claude , Gemini , and Perplexity , as well as AI-powered code assistants such as Cursor , Codex , and Copilot . Tip: Curious to see it in action? Feel free to test the AI Export feature directly within this Theneo user guide. How to Enable AI/Markdown Export Follow these steps to enable and use the AI/Markdown Export functionality: 1 Step 1: Access Project Settings Sign in to your Theneo dashboard . Navigate to the project you want to enable the feature for. Open Project Settings → Features . 2 Step 2: Enable the AI Helper & Export Locate the AI Helper & Export option in the Features list. Toggle the switch ON . 3 Step 3: Configure Export Options Once the feature is enabled, select which options you want to appear in the AI Export dropdown. 4 Step 4: Export Markdown Navigate to your project documentation pages and use the AI Export dropdown to generate a Markdown version of your content. You can use these Markdown files directly in AI tools. Note: The AI/Markdown Export feature is only available for public projects .
• [Templates](https://app.theneo.io/theneo/quickstart/developer-portal/templates.md): Theneo provides a rich selection of templates specifically designed for Developer Portals, offering visually appealing and functional designs to showcase your APIs and developer resources effectively. Find Your Perfect Developer Portal Browse real examples in Theneo’s catalog to inspire and guide your ideal developer experience. Selecting the Right Template Diverse Range : Explore Theneo's variety of Developer Portal templates, each crafted to meet different aesthetic preferences and functional requirements. Industry-Specific Options : Choose from templates tailored to various industries, ensuring that the design aligns with industry norms and appeals to your target developer audience. Customization : While templates offer a predefined layout and design, they are flexible enough for customization. Adapt the chosen template to your brand’s colors, logos, and other visual elements to maintain brand consistency. Content Integration : Seamlessly integrate essential elements like API documentation, SDKs, guides, and interactive tools into the template. This integration ensures that developers have easy access to all necessary resources. Interactivity and Engagement : Many templates include features like interactive API explorers or AI chatbots to enhance user engagement and provide practical experience with your API. Responsive Design : With mobile responsiveness being a key consideration, these templates ensure that your Developer Portal is accessible and user-friendly across various devices. Advantages of Using Theneo Templates for Developer Portals Quick Setup : Templates accelerate the creation process, allowing you to launch a professional-looking Developer Portal in less time. Professional and Cohesive Design : Each template is professionally designed, ensuring that your Developer Portal not only functions well but also visually communicates your brand's professionalism. Ease of Navigation : Templates are structured to provide intuitive navigation, making it easier for developers to find the information they need. Consistent User Experience : A uniform design across all pages of the Developer Portal enhances user experience and brand perception. By utilizing Theneo’s templates for your Developer Portal, you can create an inviting and efficient environment for developers. This approach not only saves time and resources but also ensures that your portal stands out in terms of both functionality and design, ultimately enhancing developer engagement and API adoption. Here are some of the examples: Rimsy's API Catalogue powered by Theneo: Paymob's Interactive Developer portal for various regions: Explore our sample templates: Solid Bloom Roboto
• [Custom Design](https://app.theneo.io/theneo/quickstart/developer-portal/custom-design.md): Theneo's Developer Portal offers a service that caters to clients who desire a custom design for their developer portal. If you have a design ready in Figma or any other design tool, Theneo's team is capable of transforming that design into a fully functional developer portal. Here's a quick guide on how to avail of this service: Steps for Custom Design Implementation: Design Preparation : Finalize your design in Figma or your preferred design tool. Ensure that the design is detailed and includes all the necessary elements you want to have on your developer portal. Submit Your Design : Contact the Theneo support team and provide them with your design files. Design Review and Confirmation : The Theneo team will review your design to ensure that it's feasible and aligns with their platform capabilities. They may provide feedback or suggestions to optimize the design for the developer portal environment. Implementation Phase : Once the design is approved, Theneo's team will start the implementation process. The team utilizes your design as a blueprint to create a custom-tailored developer portal. Delivery and Review : Theneo aims to deliver the implemented design within 3 business days. Once delivered, review the developer portal to ensure it meets your expectations and that the design has been implemented accurately. Revisions if Necessary : If there are any discrepancies or additional tweaks needed, communicate these to the Theneo team. Theneo will work on the revisions to match your specifications. Finalization and Go-Live : After any necessary adjustments, the developer portal is finalized. You can then proceed to publish the portal and make it accessible to your users. Custom design is available on Growth plan .
• [Developer Portal Editor](https://app.theneo.io/theneo/quickstart/developer-portal/developer-portal-editor.md): Theneo's Developer Portal Editor offers a flexible environment where you can drag and drop various elements to construct a customized interface for your developer portal. For those who are more comfortable with direct coding, the editor provides an option to dive into the HTML and CSS code, allowing for granular control over the design and functionality. Additionally, the editor includes a feature to export your code, enabling you to work on it offline or in a different environment and then import it back into Theneo seamlessly. Key Elements and Functionalities HTML Tab : Directly edit the HTML structure of your portal. You can add, remove, or modify elements like divs, sections, and other HTML5 elements. CSS Tab : Style your portal with custom CSS. You have the freedom to define styles, manage layouts, and ensure your branding is on point with precision. Export to ZIP : Safeguard your work or collaborate with others by exporting your entire project's codebase. This feature is particularly useful for backing up your work or transferring it to another platform or team member. Code Import : Already have code ready to go? Import it directly into the editor to jump-start your portal development. This feature supports a seamless transition from other development environments into Theneo. Using the Editor for Customization Layout Management : Use the drag-and-drop feature to organize your layout with elements like columns, image blocks, and text sections. Interactive Elements : Add interactive components such as forms, buttons, and navigation bars to enhance user interaction. Multimedia Integration : Embed multimedia content with image and video blocks to enrich your content. Custom Styling : Access the CSS tab to apply custom styles, adjust layouts, or fine-tune the appearance of your portal. Content Structuring : Edit the HTML directly to structure your content semantically, ensuring a logical hierarchy and SEO-friendly markup. Backup and Version Control : Use the export feature to create backups of your portal's code, allowing you to maintain different versions or revert changes if necessary. Collaboration : Share your exported code with team members to collaborate on the development of your portal, ensuring everyone can contribute their expertise. Final Touches : Before publishing, import your code back into Theneo to see your changes reflected in real-time, ensuring your portal looks and functions exactly as intended.
• [Export / Import Code](https://app.theneo.io/theneo/quickstart/developer-portal/export-import-code.md): If you need to add functionalities or customize the appearance of your HTML beyond what is available in the Theneo Developer Portal's online editor, such as intricate hover effects or specific color gradients, exporting and editing your code is a straightforward process. Here's a detailed guide to exporting your code for customization and then importing it back into the Developer Portal. Exporting Code for Advanced Customization 1 Step 1: Export Your Code from the Developer Portal Navigate to the Developer Portal. Access the code editor by clicking on the code icon. Click on "Export to ZIP" to download your current project's code. 2 Step 2: Customize Your HTML and CSS Code Extract the ZIP file on your local machine. Open the HTML and CSS files in your chosen text editor for modifications. You can now add custom styles or scripts that you require. For example: To change a hover effect color or gradient, you can directly modify the CSS. 3 Step 3: Merging HTML and CSS Files for Import Create a <style> tag in the HTML file, and paste all the styles from the CSS file into this tag. Ensure that for both dark and light themes, there is a <div class="content-wrapper"> for the light theme. To enable dark mode, add the class <div class="content-wrapper dark-theme"> . Importing Customized Code Back into the Developer Portal Return to the Theneo Developer Portal. Click on the import icon within the code editor. You can now paste the updated HTML code directly into the editor.
• [Developer Portal Dashboard & Page Management](https://app.theneo.io/theneo/quickstart/developer-portal/developer-portal-dashboard-and-page-management.md): The Developer Portal section on the dashboard serves as a centralized hub where users can manage multiple developer portal pages efficiently. It includes the following sub-sections: Analytics , Settings , Page Management , and SEO Management . This guide walks you through each part of the Developer Portal section. 1. Analytics This is the default landing tab when accessing the Developer Portal section. Features: Displays aggregated analytics data across all developer portal pages. Includes key metrics: Users Sessions Views 2. Settings Provides global configuration options that affect all developer portal pages . Includes: Theme Selector – Choose a unified theme for all portals. Default Dark Theme Toggle – Set a global dark mode as the default experience. 3. Branding & Logo Logic While not a separate tab, logo handling follows a clear display logic: If no logo is uploaded in the Developer Portal section: → The system uses the logo from Branding settings . If a logo is uploaded in Developer Portal settings: → That logo is displayed across all developer portal pages . 4. Custom Domain Manage custom domain configuration for your developer portals. Note: Custom domain settings are global and apply to all portal pages — individual pages cannot have separate custom domains. Note: Custom domain settings are global and apply to all portal pages — individual pages cannot have separate custom domains. 5. Page Management Create and manage individual developer portal pages from this section. Creating a Page: Click the “Add New Page” button. A modal will appear with the following required fields: Page Name Slug Template Selector (choose from predefined templates) Managing Existing Pages: All created pages are listed with the following options: Edit (Update name and slug) More Actions (⋮ menu): Go to Editor Visit Published View Duplicate Page Delete Page 6. SEO Management Each developer portal page can have its own SEO configuration to enhance search engine visibility. Editable Fields: Meta Title Meta Description Focus Keywords These settings help optimize how your pages appear in search engines like Google.
• [Project Management](https://app.theneo.io/theneo/quickstart/global-settings/project-management.md): Theneo's Project Management system provides a wide array of features accessible via a comprehensive dashboard. Here, you can get a bird's eye view of all your projects, navigate between them effortlessly, and dive into each project's specifics with just a click. The dashboard is your command center, your starting point to manage, modify and optimize various aspects of your projects. Within each project, you will find multiple sub-sections designed to handle different facets of your project. These include: Analytics Gain valuable insights into how your documentation is performing. Track key metrics like users, sessions, views, AI search questions, and feedback per section. Use intuitive filters to drill down by date or specific pages, helping you optimize content and engagement. Project Settings Customize general settings like project name, slug, and logos. Enable or disable features such as Feedback & Analytics, API Explorer, and GPT Search. Access Management Manage project visibility and permissions by setting access to private or public, inviting team members, and assigning roles. SEO Management In the ever-evolving digital landscape, Search Engine Optimization (SEO) is critical. Theneo provides a dedicated section to manage SEO settings for your API documentation, allowing you to maximize your project's online visibility.
  • [Analytics](https://app.theneo.io/theneo/quickstart/global-settings/project-management/analytics.md): The Project Analytics feature helps you monitor and understand how users are interacting with your documentation. It provides detailed insights including user activity, content engagement, AI-powered search usage, and feedback collected per documentation section. 1. Accessing Analytics To access Project Analytics : Navigate to your Project Dashboard . Select the Analytics tab from the top navigation menu. 📌 Note: Analytics is available for all published documentation projects. 2. Overview of Analytics Metrics The Analytics section is divided into several key metrics: a. Users Displays the total number of unique users who accessed the documentation. b. Sessions Represents the total number of individual user sessions (including repeat visits). c. Page Views Counts how many times documentation pages were viewed. 3. AI Search Questions This section shows all AI-powered search queries made by users within your documentation. Key Features: View the exact questions users are asking via the search bar. Gain insight into what users are looking for and how well your documentation answers their queries. Helps identify gaps or opportunities to improve content based on real search behavior. 4. Feedback Polling Feedback analytics offer qualitative insights directly from users through documentation feedback prompts. Includes: Section-specific feedback (e.g., thumbs up/down, comments). Identifies which sections are helpful or need improvement. Can be used to track sentiment trends over time. 5. Filters & Breakdown To explore data more deeply: Use the date range filter to focus on specific time periods. Use the page filter dropdown to analyze data per documentation page or section. 6. Use Cases & Benefits Improve Content : Spot which pages or sections have high activity or low feedback ratings. Identify Gaps : Analyze AI search questions to find missing or unclear information. Track Engagement : Understand how often your documentation is accessed and how users interact with it. Best Practices Review analytics regularly to stay on top of user behavior. Use feedback and search data to guide your documentation updates. Combine insights from sessions, views, and feedback to make data-driven content decisions.
  • [Project Settings](https://app.theneo.io/theneo/quickstart/global-settings/project-management/project-settings.md): In Theneo, Project Settings is the central hub from which you can customize various aspects of your project, from general settings such as project name and logo to specific features like API Explorer and GPT Search. It enables you to ensure that your project fits your needs, and the needs of your users, in the best possible way. General Settings This is the starting point for setting up your project. Here, you can set your Project name and the Project slug, which will be the URL of your project. You can also upload Light and Dark theme project logos. This ensures your branding remains consistent, irrespective of the theme your users choose. Features In the features tab, you can enable or disable various features based on your needs: Feedback & Analytics Feature: This allows users to provide feedback on your documentation and provides you with valuable analytics on user interactions. API Explorer: It allows users to try out your API endpoints directly from the documentation. Automatic Changelog: Theneo simplifies the process of generating changelogs for your projects. The Auto Changelog Doc feature automatically compiles and updates changelogs, saving you time and effort. The software scans your project for changes and automatically generates a comprehensive changelog. Default Dark Theme Mode: Enabling this will make Dark Theme the default view mode for your project. AI Search: This feature integrates with OpenAI's GPT-4 to provide powerful search functionality. When enabled, it allows users to ask questions in natural language and get answers directly from your documentation. This can greatly enhance the user experience by making it easier for them to find the information they're looking for. HTTP Method Display: This feature enhances API documentation by displaying HTTP methods (GET, POST, PUT, DELETE, etc.) in the side menu navigation. It allows users to quickly identify the type of request associated with each API endpoint, improving clarity and usability when browsing the documentation. Iframe Generation: Provides the ability to generate iframes for embedding Theneo documentation into other platforms or web pages. This feature enables seamless integration of API documentation within external applications, ensuring accessibility without redirecting users away from their current environment. URL Encoding: Ensures that API request URLs are properly encoded to handle special characters, spaces, and unsafe characters correctly. This prevents issues related to incorrect URL formatting and ensures compatibility with web standards for smooth API communication. Custom Menu Custom Menu allows users to personalize the default menu structure in Theneo by adding, removing, or modifying menu items. This flexibility ensures that the documentation’s navigation aligns with specific project needs. Users can include additional references, link relevant content, and streamline the navigation process, making it easier for viewers to access important information efficiently. Custom Menu Main Button Highlighting To make navigation even more intuitive, the Main Button feature allows users to mark one item (excluding subitems) as the main button in the custom menu. This visually distinct button serves as a primary point of focus in the menu. Star Icon Functionality: A star icon is displayed next to all items in the custom menu (excluding subitems). Clicking the star icon marks the item as the Main Button . Main Button Design in Published View: The Main Button will have a distinct design with a highlighted background to make it stand out from other menu items. This ensures that users can easily identify the most important or relevant section of the documentation at a glance.
  • [Access Management](https://app.theneo.io/theneo/quickstart/global-settings/project-management/access-management.md): Access management in Theneo allows you to take complete control over who has access to your projects and to what extent they can interact with your documentation. Providing you with granular control over access and permissions, Theneo ensures you can effectively manage your team's involvement while ensuring your project's security. When you navigate to the Access Management section within a project, you'll find options to change the permission of the document from private to public, and to invite new members. This robust access management system is designed to provide you with flexibility, security, and ease of collaboration. Public and Private Settings By default, every project in Theneo is private, meaning that only you, as the project's creator, can view and interact with the documentation. However, Theneo understands that collaboration is key in many instances, and therefore, it allows you to toggle your project's accessibility from private to public. Making a project public allows anyone with the project's URL to view your documentation. This is particularly useful when you want your API documentation to be accessible to a wide audience, such as your API's user base. Inviting New Members With Theneo, you're not working in isolation; you can invite your team members to collaborate on the project. Whether it's developers, product managers, or technical writers, inviting new members to the project is as easy as entering their email addresses and clicking "Enter". Each invitee will receive an email invitation to view or edit the project based on the permissions you set. Permission Levels There are two levels of permissions you can assign to team members: Editor and Viewer (or Guest). Editors have the authority to make changes to the project. They can add, modify, or delete sections, update content, manage SEO settings, and perform other edits as needed. Viewers , on the other hand, can only view the project. They have access to the published project and can leverage the information but can't make any changes to the content. Advanced Access Management Theneo provides robust access management capabilities, allowing for both project-wide and section-specific access controls. This ensures that only authorized users can view or edit specific sections or subsections within a project. Here's a detailed guide on how to manage access at these granular levels. Before managing user-specific access, ensure the user is invited to the project. Once users have access to the project, you can refine their access to specific sections Within the project access management, navigate to the advanced access management area. Select the section or subsection you want to manage. Set Access Permissions : For each section or subsection, you will have the option to set it as public, private, or user-specific. Select the desired access level. Invite Users to Sections : For user-specific sections, you will need to invite users to those specific sections. Enter the email addresses of the users who should have access to the section. Confirm the invitations, making the section visible only to these users. Password-Based Access for Private Projects Quick Access to Password-Protected Projects with Custom Domains allows you to grant access to multiple users without inviting each one individually through access management. Prerequisites Before proceeding, ensure the following prerequisites are met: Project Privacy : The project must be set to private. Custom Domain : The project should have a custom domain configured. For more information on setting up a custom domain, click here . Step-by-Step Instructions Step 1: Navigate to Project Access Management Open your project dashboard. Locate and click on the Access Management tab. Step 2: Verify Project Settings Ensure the project is set to Private . Confirm that the project has a Custom Domain set up. Step 3: Set a Password for Easy Project Access Within the Access Management section, locate the field labeled Set Password for Easy Project Access . Enter a secure password in the provided field. Click on the Set Password button. Step 4: Share the Project URL and Password Copy the project URL with the custom domain. Note : This functionality will not work if you share the project URL using Theneo's domain. Share the custom domain URL and the password with your customers. Step 5: Accessing the Project Users will open the shared URL. They will be prompted to enter the project password. Once the correct password is entered, the project content will be accessible. Troubleshooting Common Issues Incorrect URL : Ensure the URL shared is the one with the custom domain and not Theneo's domain. Forgotten Password : If users are unable to access the project due to a forgotten password, reset the password through the Access Management section and share the new password. By providing different access levels, Theneo ensures that you can effectively manage your team and project resources, keeping your project's integrity intact while fostering productive collaboration. Access Management in Theneo is simple yet powerful, designed to facilitate seamless collaboration while maintaining control over who can access and modify your technical documentation.
  • [SEO Management](https://app.theneo.io/theneo/quickstart/global-settings/project-management/seo-management.md): In the digital age, visibility on search engines is critical for any product, and your technical documentation is no exception. Theneo's SEO Management tools provide you with all the options you need to optimize your documentation for search engines, enhancing visibility, and making it easier for your users to find the information they need. Navigating to the SEO Management section in your project settings will reveal an array of options to customize your project's SEO. Here's what you can do: Title, Meta Description, and Keywords Your project's SEO title and meta description are what users see in search engine results. The SEO title is the main title that appears in search engine results, and the meta description is the brief summary underneath. In Theneo, you can customize these for every section of your project, ensuring that each part of your documentation is accurately represented in search engine results. Adding relevant keywords is another crucial aspect of SEO. Theneo's SEO Management allows you to input keywords related to each section of your project, helping search engines understand the content and context of your documentation better. Open Graph Management Open Graph protocol enhances the richness of your project when shared on social media platforms like Facebook and LinkedIn. With Theneo, you can manage Open Graph settings, such as the title, description, and image, to control how your project appears when shared on social platforms. This not only enhances the look of your shared links but can also improve engagement and click-through rates. No-Index Option There may be instances where you want your project to be public but not indexed by search engines. For example, if the project is still in the early stages or contains sensitive information. In these cases, Theneo allows you to enable the 'no-index' option. This instructs search engines not to index your project, ensuring it won't appear in search results even while being publicly accessible. SEO management in Theneo provides a blend of accessibility and control. It ensures that your technical documentation can reach your intended audience effectively, be it through search engines or social media platforms, while giving you the control to guide that visibility as per your project's requirements. Sitemap generator The Sitemap Generator helps you export an up-to-date XML sitemap for your project’s public documentation - so search engines can discover and index your docs more effectively. Sitemaps are generated on demand from the SEO Management tab and can be downloaded instantly. Importantly, any documentation sections marked Private through Advanced Access Management are automatically excluded , ensuring sensitive content is never exposed. What you can do With Sitemap Generator, project Editors and Admins can: Generate a sitemap XML for the Project Download the sitemap file immediately Where to find it Open your Project Navigate to SEO Management Find the Generate Sitemap button The sitemap contains only publicly visible documentation URLs for your Project Portal. Privacy and access rules Private content is never included Pages and sections marked Private in Advanced Access Management are excluded automatically. This prevents restricted documentation from appearing in: Sitemaps Search engine discovery workflows. When to regenerate your sitemap Since generation is manual, regenerate whenever you make meaningful changes to public docs, such as: Publishing new pages Changing slugs or URLs Reorganizing navigation Making previously-private content public (or vice versa) FAQ Who can generate a sitemap? Project Editors and Admins can generate and download the sitemap (based on project permissions). Why might sitemap generation fail or be temporarily unavailable? To prevent abuse, backend sitemap generation may be rate-limited. If you hit a limit, wait a moment and try again.
• [Workspace Configuration](https://app.theneo.io/theneo/quickstart/global-settings/workspace-configuration.md): What are Workspaces? Workspaces in Theneo are distinct areas within the platform designed to manage different projects or teams under one umbrella organization. They serve as separate containers that allow for distinct management of APIs, documentation, and team access. Each workspace can have its own branding, permissions, and configurations, making it an ideal solution for companies with multiple products or teams. Benefits of Using Workspaces: Team Management : Allocate specific workspaces to different teams within the organization. Set permissions and roles to control access and maintain security. Brand Consistency : Customize branding for each workspace to align with the product or team identity. Manage multiple branding configurations without affecting other workspaces. Organized Documentation : Keep documentation for different products or APIs separate and organized. Provide tailored information relevant to the users of each workspace. Targeted Landing Pages : Design and use different landing pages for each workspace to cater to the specific audience or user base. Enhance user experience by directing them to the relevant workspace right from the start. When are Multiple Workspaces Relevant? Multiple Products : If your company offers a range of products, each with its own set of APIs and documentation, separate workspaces allow for tailored content management without overlap. Distinct Branding : Companies that operate different brands under one corporation can use workspaces to manage and present APIs in line with each brand’s guidelines. Team-Specific Access : For organizations with several engineering teams, each responsible for different APIs, workspaces provide a way to segment API ownership and control who has access to what. Project Phases : During different stages of development, such as testing and production, workspaces can be used to segregate and manage these environments effectively. Implementing Workspaces: Setup : Administrators can create and configure workspaces from the Theneo dashboard. Customization : Each workspace can be customized with its own branding and landing pages. Access Control : Assign team members to workspaces and define their roles and permissions. Content Management : Develop and maintain API documentation that's specific to the needs of each workspace. In summary, workspaces in Theneo provide a powerful means to segment and manage your API documentation and teams. They offer the flexibility to support multiple products, brands, and teams within a single platform, ensuring that each can operate with its required level of autonomy and specificity
  • [Workspace Management](https://app.theneo.io/theneo/quickstart/global-settings/workspace-configuration/workspace-management.md): Workspaces are the foundation of how Theneo organizes documentation across teams, products, and initiatives. A single user can belong to multiple workspaces - often with different roles and permissions in each. Workspaces: the basics Your first workspace (created during sign-up) When you sign up for Theneo, you create your first workspace as part of the onboarding flow. You are assigned the Admin role in that workspace. Multiple workspaces, multiple roles You may also: Be invited to other workspaces by teammates or other organizations Have different roles in different workspaces (for example, Admin in one workspace and Editor in another) Your access and permissions always depend on the role you have in each specific workspace . Personal vs. Corporate workspaces When creating a workspace, you can choose one of two types: Personal (often used for individual or freelance use) Corporate (recommended for team collaboration) Our recommendation: Create Corporate workspaces We strongly recommend creating a Corporate workspace , even if you’re just getting started. Corporate workspaces are designed for collaboration and unlock team-oriented capabilities such as: Collaborating with team members in the same workspace Inviting members to workspaces and projects Working together within a project Sharing private projects with other team members Domain whitelisting Other domain/company-related features These capabilities are restricted in Personal workspaces . Both Personal and Corporate workspaces are available on the Free plan. We generally only recommend a Personal workspace when you have a specific individual-only use case. Switching from Personal to Corporate (one-way) You can upgrade a workspace from Personal → Corporate from the Admin configuration . Important: This change is permanent There is no step back You cannot switch Corporate → Personal Viewing your workspaces From the Theneo dashboard, open the Workspaces page to see: All workspaces you’re currently a member of Your role in each workspace Actions available to you (such as Leave ) Create an additional workspace You can create more workspaces any time - useful for separating documentation by team, product, client, or environment. Steps Open the Workspaces page. Click + Create Workspace next to the page title. Complete the form: Name (required) Slug (auto-generated from Name, editable) Type (Personal or Corporate - default is Personal) 4. Click Create . What happens next The new workspace appears immediately in your list. You are assigned the Admin role in the newly created workspace. Leave a workspace If you’ve been invited to workspaces you no longer need, you can leave them to keep your workspace list organized. Steps Open the Workspaces page. Find the workspace you want to leave. Click Leave on the right side of the workspace row. After you leave The workspace disappears from your list immediately. Set a default workspace You can choose one workspace as your default workspace . This workspace becomes the starting point for key workflows across Theneo. What the default workspace affects 1) New projects All projects you create will be created in your default workspace by default - unless you choose a different workspace during the Create Project flow. 2) Branding When you open the Branding page, Theneo loads branding settings for your default workspace first . 3) Developer Portal Developer Portal configuration is also loaded based on your default workspace first . This helps you stay focused if you primarily work in one workspace. Switch workspaces in Branding Even though Branding loads from your default workspace, you can switch context at any time. Steps Open Branding . Use the workspace dropdown to select another workspace. The page updates to show branding settings for the selected workspace. Switch workspaces in the Developer Portal Developer Portal settings also support workspace switching. Steps Open Developer Portal configuration. Use the workspace dropdown to select the workspace you want to manage. The configuration updates to match the selected workspace. FAQ Can I create a project in a workspace that isn’t my default? Yes. The default workspace is the preselected option, but you can choose a different workspace during the Create Project flow. Why should I choose Corporate if I’m on the Free plan? Because Corporate unlocks collaboration and company features (like inviting members, sharing private projects, and domain whitelisting), and it’s included in Free. Personal workspaces are best only for specific individual-only use cases. If I leave a workspace, what happens to my access? Leaving a workspace removes your workspace-level access , not your project membership. This means: You won’t be able to create new projects in that workspace. You won’t be able to access or change that workspace’s Branding or Developer Portal configuration. You do not automatically lose access to projects you’re part of. You’ll only lose access to a specific project if you are removed from that project separately . Why do Branding and Developer Portal load based on the default workspace? It provides a consistent “home” context and reduces switching for users who primarily manage one workspace. You can still switch anytime via the dropdown.
  • [Documentation Publishing Rights](https://app.theneo.io/theneo/quickstart/global-settings/workspace-configuration/documentation-publishing-rights.md): Role-based publishing configuration helps you control who can publish documentation in your workspace. This is especially useful when you want an approval step before content goes live, while still allowing Editors to do day-to-day documentation work. How it works Publishing permissions are managed at the workspace level by a Workspace Admin using the Documentation publishing roles setting. There are two available modes: Workspace editors and admins (default) Editors and Admins can publish documentation. Just admins Only Admins can publish documentation. Editors can still edit and configure docs, but they can’t publish changes. Default behavior By default, Workspace editors and admins is selected. This means: Admins can publish Editors can publish Both roles can continue editing and maintaining docs as usual Configure publishing roles (Admin only) Go to Workspace Admin Settings . Locate Documentation publishing roles . Select your preferred option: Workspace editors and admins (default) Just admins Permissions by role Admins (always) Admins have full access. They can: View documentation Access the editor Edit content Update documentation configuration Publish documentation Even when publishing is restricted, Admins retain all capabilities. Editors (depends on selected option) When “Workspace editors and admins” is selected (default) Editors can: View documentation Access the editor Edit content Update documentation configuration Publish documentation When “Just admins” is selected Editors can: View documentation Access the editor Edit content Update documentation configuration Editors cannot: Publish documentation (An Admin must publish instead.) When to use Admin-only publishing Choose Just admins when you need: An approval or review step before docs go live Governance for public-facing documentation Consistent tone, quality, or compliance controls FAQ Can an Editor request an Admin to publish a document? Not yet. We’re improving this flow and plan to release enhancements soon. If publishing is restricted to Admins, can Editors still work normally? Yes. Editors can still write, edit, and update documentation configuration - only publishing is restricted. Does this setting hide documentation from Editors? No. Editors can still view and access documentation as usual. Does this apply to all docs in the workspace? Yes. Documentation publishing roles is a workspace-level setting and affects publishing permissions across the entire workspace. What happens if an Editor tries to publish when only Admins can publish? The publish action will be blocked. The Publish button will be disabled , and the Editor will see a notification to contact an Admin to publish the document . An Admin will then need to publish instead. Can I allow publishing for specific Editors only? Not currently. This setting supports role-based control only (Admins only, or Admins + Editors). Will changing this setting affect already published docs? No. It doesn’t modify existing published docs - it only controls who can publish going forward.
  • [Whitelisting a Domain](https://app.theneo.io/theneo/quickstart/global-settings/workspace-configuration/whitelisting-a-domain.md): Theneo's Domain Whitelisting feature enables workspace administrators to authorize an entire domain, allowing users with email addresses from that domain to access the workspace. This feature simplifies user management by automatically granting permissions to users within the whitelisted domain. Setting Up Domain Whitelisting Accessing Workspace Settings: Navigate to the ‘Settings’ on the Theneo sidebar. Click on ‘Workspace Settings’ under the Admin section. Enabling Domain Whitelisting: Locate the ‘Domain whitelisting’ section. Enter your domain in the ‘Whitelist domain’ field (e.g., "yourcompany.io"). Toggle the switch to the ‘On’ position to enable whitelisting. Assigning Permissions: Choose the default permission level for new users from the dropdown menu. Options include: Viewer Editor Admin Managing Project Access Navigating to Project Settings: Select the project you want to manage from your Theneo dashboard. Click on the ‘Settings’ tab within the project. Configuring Project Access: In the ‘Access Management’ tab, look for the ‘Project access management’ dropdown. Select the visibility setting for the project—options include: Private Public Domain (if you want the project to be accessible only to users from the whitelisted domain) Setting Workspace Permissions: Toggle the ‘Anyone in the workspace can view or edit the project’ switch to the desired setting. Select the level of permission for the workspace from the dropdown next to the toggle switch. This sets the default access for all users from the whitelisted domain. Automatic User Addition Once Domain Whitelisting is enabled and configured, users with email addresses matching the whitelisted domain will be automatically added to the workspace with the default permissions set in the previous steps. Tips and Best Practices Review Permissions Regularly: Regularly check the permissions assigned to the domain to ensure they align with your organization's access control policies. Communicate Changes: When changes are made to domain whitelisting or project access settings, communicate these to your team to avoid confusion. Use Domain-Specific Emails: Ensure that your team members are using their domain-specific emails to leverage the benefits of this feature fully. Technical Requirements and Limitations Email Domain Verification: Your domain must be verified with Theneo to use this feature. Only email addresses matching the verified domain will be automatically added. Permission Levels: Understand the implications of each permission level (viewer, editor, admin) to avoid unintentional access grants. Project Visibility: Be aware that setting the project to 'Domain' restricts access to users outside the whitelisted domain, even if the project is otherwise set to 'Public'. By following these steps, workspace administrators can effectively manage user access and streamline the process of onboarding new users within their organization
  • [Email-Based Two-Factor Authentication (2FA)](https://app.theneo.io/theneo/quickstart/global-settings/workspace-configuration/email-based-two-factor-authentication-2fa.md): With 2FA, even if your password is compromised, your account remains protected through an additional layer of security. 1. Enabling 2FA in Workspace Settings (Admin Guide) As a workspace admin, you can enforce 2FA across your workspace to ensure that all users are required to use this security feature. Steps: 1. Navigate to Workspace Settings: Log in to your admin account and go to the workspace settings page. 2. Enable 2FA: Find the admin section within the settings. Toggle the "Two-Factor Authentication" option to enable it. 2. Signing In with 2FA (User Guide) After setting up 2FA, you will need to complete the 2FA process every time you sign in. Steps: 1. Login Prompt: Enter your username and password on the login page. 2FA Code Generation: After submitting your login credentials, a one-time login code will be generated and sent to your registered email address. 2. Enter 2FA Code: Check your email for the code. Enter the code on the login page and click "Verify" to proceed. 3. Access Granted: If the code is valid and not expired, you will be granted access to your account. Troubleshooting: Code Expiration: If the code expires (after 10 minutes), request a new code by re-entering your username and password. Incorrect Code: If the code is incorrect, try entering it again. Ensure there are no typos. 3. Managing 2FA Settings If you need to manage your 2FA settings, such as updating your registered email address, you can do so within your account settings. Steps: 1. Navigate to Account Settings: Log in and go to your account settings page. 2. Update Email Address: Under the “User Profile” section, find the option to update your registered email address. https://app.theneo.io/# 3. Save Changes: After updating your email, save the changes to ensure that future 2FA codes are sent to the correct address. Frequently Asked Questions (FAQ) Q: What happens if I lose access to my email? If you can no longer access your registered email, contact our support team for assistance in resetting your email. Q: Can I use another method for 2FA? Currently, only email-based 2FA is supported. Ensure that your registered email is secure and accessible. Q: What if I didn't receive the 2FA code? Check your spam or junk folder in case the email was filtered incorrectly. If you still don't receive the code, ensure your registered email is correct and request a new code.
  • [Audit Logs](https://app.theneo.io/theneo/quickstart/global-settings/workspace-configuration/audit-logs.md): The Audit Logs section in the Admin Panel gives Workspace Admins a comprehensive, tamper-evident record of all activity performed by members across the workspace. Every significant action from publishing documentation to modifying branding or developer portal settings is captured with a full metadata trail including the actor's IP address, making Audit Logs a reliable foundation for internal accountability and compliance reporting. Audit Logs are available only for the Enterprise tier. Accessing Audit Logs Navigate to Admin Panel → Audit Logs . The log table loads automatically, showing the most recent activity first. No additional configuration is required — logging begins as soon as your workspace is active and cannot be disabled. What Gets Logged Audit Logs capture a broad range of workspace events across four primary categories. Documentation Branding & Portal Workspace & Members Admin Actions Documentation events Publishing a documentation Creating a documentation Deleting a documentation Documentation-specific settings and configuration updates Branding and developer portal events Applying or switching a branding template (Solid, Bloom, Roboto) Saving changes to colors, custom CSS, or custom JavaScript Reverting to a previous branding version Updating custom domain configuration Workspace and membership events Inviting a new member to the workspace Changing a member's role (e.g. Editor → Admin) Removing a member from the workspace Member login and logout events SSO configuration changes Admin-specific events Modifying workspace-level settings Log Entry Structure Every entry in the Audit Log contains the following fields. Field Description Example Member Name and account of the workspace member who performed the action Jane Smith (jane@company.com) Action A description of the specific event that was recorded Published documentation project Timestamp Date and time the action occurred, shown in the viewer's local timezone Apr 3, 2026 · 14:32 UTC+4 IP Address The IP address from which the action was performed 192.168.1.1 Using Audit Logs for Compliance Audit Logs are designed to support internal security reviews, compliance reporting, and incident investigation workflows. 1 Identify the event or timeframe Admin Panel → Audit Logs 2 Filter by member or event type Use the member filter to isolate activity from a specific account, or the event type filter to focus on a particular category — such as all branding changes or all publish actions — across any time range.
  • [Custom Webhook](https://app.theneo.io/theneo/quickstart/global-settings/workspace-configuration/custom-webhook.md): Custom webhooks let you push real-time Theneo activity directly to any external endpoint — internal dashboards, alerting systems, Slack pipelines, or custom tooling — without writing integration code. Once configured, Theneo sends an HTTP POST request to your endpoint whenever a subscribed event occurs. Webhooks are configured from the Admin Panel and are available to Workspace Admins . Custom Webhook is available only for the Enterprise tier. Supported Event Types Webhooks can be configured to fire on two categories of workspace events. Project Feedback Fires whenever a reader submits feedback on a documentation page. Use this to route feedback notifications to your support queue, Slack channel, or internal dashboard in real time. Audit Log Events Fires whenever a loggable workspace action occurs — publishing, branding changes, member activity, and more. Use this to stream your audit trail into a SIEM, compliance tool, or alerting system. You can configure multiple webhooks pointing to different endpoints, each with its own event subscription. How to Configure a Webhook 1 Open the Webhooks section Admin Panel → Webhooks Add Webhook 2 Enter your endpoint URL Paste the full HTTPS URL of the endpoint that will receive webhook deliveries. Theneo only delivers to secure endpoints — plain HTTP URLs are not accepted. 3 Select event subscriptions Project Feedback Audit Log Events 4 Save and verify Save Webhook
  • [Microsoft Entra SSO](https://app.theneo.io/theneo/quickstart/global-settings/workspace-configuration/entra-sso.md): How to Set Up Microsoft Entra Single Sign-On (SSO) with Theneo Microsoft Entra Single Sign-On (SSO) enables your organization to securely access Theneo using your existing Azure Active Directory credentials. This simplifies user management, enhances security, and provides seamless integration for your team. This guide provides detailed instructions to help administrators configure Microsoft Entra SSO with Theneo. Microsoft Entra SSO is available only for the Enterprise tier. Step 1: Initiate Sign-In To get started with enabling SSO, you'll first initiate the process from Theneo. Navigate to the Theneo login page. Select "Sign in with Microsoft Azure AD" . This will begin the authentication process and redirect you to Microsoft's authentication page. Step 2: Provide Consent on Behalf of Your Organization To allow Theneo to integrate securely with your organization's Azure Active Directory, you'll need to grant administrative consent. Upon redirection to Microsoft, enter your administrator credentials if prompted. You will see a permissions request screen displaying the permissions Theneo is requesting (e.g., viewing your basic profile and maintaining access to data). Select the checkbox labeled "Consent on behalf of your organization" . This ensures that individual users won't have to consent separately, simplifying the experience for your entire team. Click "Accept" to authorize the integration. Microsoft will confirm this authorization and redirect you back to Theneo. Step 3: Configure Theneo Application Access in Microsoft Entra With the initial authorization complete, you need to manage which users or groups can access Theneo. Sign in to the Microsoft Entra admin center . Navigate to the Enterprise Applications section. In the search bar, type "Theneo" and press enter to locate the Theneo application. Click on the Theneo application to open its settings page. Navigate to "Users and groups" from the sidebar to specify who can access Theneo. Click "Add user/group" , then select specific users or groups from your Azure AD that need access to Theneo. This allows precise control over who within your organization can use the application. After selecting the users/groups, click "Assign" to confirm their access permissions. Step 4: Verify User Access It's good practice to verify that the configuration has been successful: Instruct assigned users to navigate to Theneo's login page. Have them select "Sign in with Microsoft Azure AD" . Ensure that users can log in successfully and access their Theneo accounts without issues. Additional Recommendations Conditional Access Policies: Configure Conditional Access policies within Microsoft Entra to enforce additional security measures such as restricting access based on geographical location, device compliance, or user risk levels. Audit Logs and Insights: Regularly review the "Sign-in logs" and "Audit logs" in Microsoft Entra. These logs provide valuable insights and help monitor for unusual activity or unauthorized access attempts. Self-service Access Management: Enable self-service options within Microsoft Entra, allowing users to request access directly, reducing administrative effort and streamlining processes. By thoroughly following this guide, administrators can successfully set up and manage secure Single Sign-On access to Theneo through Microsoft Entra, significantly simplifying user access management and improving overall security.
  • [SSO-Only Authentication Enforcement](https://app.theneo.io/theneo/quickstart/global-settings/workspace-configuration/sso-only-authentication-enforcement.md): SSO-Only Authentication Enforcement lets workspace admins restrict how members sign in to Theneo. When enabled, the standard email and password login fields are disabled, members must authenticate exclusively through your configured SSO provider. This ensures your organization's identity and access policies are consistently enforced across the workspace. SSO-Only Enforcement applies to all workspace members. Make sure your SSO integration is fully configured and tested before enabling this toggle. Prerequisites Before enabling SSO-Only enforcement, confirm the following: SSO Integration Configured Your workspace has an active SSO connection set up. At least one SSO provider (e.g. Okta, Google, Azure AD) must be enabled. Admin Role Required Only workspace admins can toggle SSO-Only enforcement. Ensure you have the appropriate permissions before proceeding. Members Notified Inform your team before enabling this setting. Members who attempt to use email and password after the toggle is turned on will be redirected to SSO login. Enabling SSO-Only Authentication 1 Open Workspace Settings Open Admin panel → workspace settings 4 Enable the SSO-Only toggle Enforce SSO-Only Authentication This change takes effect immediately. Email and password fields will be disabled for all workspace members as soon as you confirm. 5 Verify the enforcement is active SSO-Only mode is enforced Member Experience After Enforcement When SSO-Only Authentication is enabled, the login experience changes for all workspace members - if a member attempts to enter their email and password, the fields will not accept input and a message will appear explaining that SSO is required for this workspace. They will be guided to use the SSO login option. Members who do not yet have an account linked via SSO should contact their admin to ensure their identity provider account is properly set up. Disabling SSO-Only Authentication To revert to allowing both email/password and SSO login, follow the same steps and toggle Enforce SSO-Only Authentication off. Email and password login will be re-enabled for all members immediately. Disabling this setting does not affect your SSO configuration - members can continue to use SSO login alongside email and password after enforcement is turned off. Frequently Asked Questions What happens to members who only use email and password? They will lose the ability to sign in via email and password as soon as SSO-Only mode is enabled. Admins should ensure all members have valid accounts with the configured SSO provider before turning on enforcement. Can I exclude specific members from SSO enforcement? No - SSO-Only enforcement applies to all members of the workspace uniformly. There is currently no per-member override. If you need mixed authentication modes, consider keeping enforcement disabled. What if our SSO provider goes down? If your SSO provider is unavailable and SSO-Only is enforced, members will be unable to log in until the provider is restored. Workspace admins should plan for SSO downtime contingencies with their identity provider team.