Customize your API Portal

Great job completing the quickstart! You now have a functional API Portal with auto-generated documentation. But the real magic happens when you customize it to match your brand, add helpful content, and unlock advanced features that will make developers (and AI Agents) love your API.

This guide will walk you through some essential customizations that will elevate your API Portal from functional to exceptional.

note

If you haven't created an API Portal yet, please refer to the Quickstart guide.

What You'll Accomplish

In the next 15 minutes, you'll learn how to:

• Enrich your content by adding custom documentation pages that provide context beyond your API reference
• Guide developers through complex workflows using interactive API recipes
• Match your brand with custom themes and colors that reflect your company's identity
• Make you Documentation AI-accessible by generating LLMs.txt files
• Enable an AI assistant to answer Developer questions about your API
• Drive more traffic to your Portal by optimizing it for search engines that help Developers find your APIs

Before you begin

• All commands in this guide should be run from your project root directory (the directory containing your APIMATIC-BUILD.json file).

  Make sure you're in the correct location before starting:

  cd your-project-name/src
  ls  # You should see the directory structure, including the APIMATIC-BUILD.json file 

• Each section builds upon the previous one, but you can also jump to specific customizations based on your immediate needs.

Let's get started!

1. Add a Documentation page to the API Portal

Enhance your API Portal with a custom documentation page. Custom documentation pages allow you to add product guides, FAQs or any other relevant documentation to your API Portal.

1. Navigate to the content/guides directory in your project source directory:

   cd content/guides

2. Create a new markdown file:

   Create a new markdown file and open it in your favourite text editor

   touch my-first-guide.md
   code my-first-guide.md

3. Add content to your markdown page:

   # Ode to an API
   In realms where data flows like streams, APIs fulfill developers’ dreams. A JSON handshake, crisp and clean, Connects the apps behind the screen.
   With endpoints nested deep and wide, They summon structs with practiced pride. Auth tokens guard the sacred gate, While headers speak of client state.
   A GET for facts, a POST to send, A PATCH to fix, a DELETE to end. With Swagger scrolls and OpenAPI, They whisper truth to SDKs nigh.
   So raise a curl to RESTful peers, To webhooks pinging through the years— For every call that we compose, An interface of prose arose.

4. Update your API Portal navigation:

   The new page you created needs to be added to the API Portal’s side-nav. This can be done by running the portal:toc:new command. This command overwrites your existing toc.yml file; any changes made to your project directory are reflected in the updated file.

   💡Tip: Keep your live preview running (portal:serve) in one terminal and run this command in a new terminal window. Your changes will appear automatically in your live preview!

   apimatic portal:toc:new

   Expected output

   ◇  A toc file already exists at the specified destination path, do you want to overwrite it?
   │  Yes
   │
   └  ✅ TOC file successfully created at: /src/content/toc.yml

5. View your new page:

   Start your local development server by running the following command, and then look for the page you just added in the Portal’s Side Navigation:

   apimatic portal:serve

✅ Success: Your custom page is now part of your API Portal!

2. Add a Recipe to the API Portal

API Recipes are interactive tutorials that help developers learn about and try complex API workflows.

See how Verizon deploys API Recipes to help Developers learn about 5G APIs

Create and add your first API recipe to the API Portal using the API Recipe creation wizard. The API Recipe wizard will guide you through:

1. Recipe Setup: Create a recipe and add it to the API Portal
2. Step Configuration: Add steps to demonstrate an API workflow.

apimatic portal:recipe:new

Expected output

┌  Welcome to the API Recipe Generation Wizard. 🪄
│
│  Let's get started! 🚀
│
◇  📘 Enter a name for your API Recipe:
│  User Authentication Flow 
│
◇  🔧 Add Steps to your Recipe:
│
◇  ➕ Select the type of step you want to add:
│  Endpoint Step
│
◇  Select the endpoint group name:
│  Authentication
│
◇  Select the name of the endpoint:
│  POST /auth/token
│
◇  Enter a description for the endpoint:
│  Calculates the expression using the specified operation.
│
◇  ✅  Step has been added successfully.
│
◇  Do you want to add another step?
│  No
│
◇  🎉 Recipe has been added successfully!
...

View your new recipe:

Start your local development server by running the following command, and then look for the recipe you just added in the Portal’s Side Navigation:

apimatic portal:serve

Your API Portal now includes a foundational API Recipe. However, API recipes offer more extensive capabilities, such as the ability to transfer data between steps and to set default values for individual steps. Taking advantage of these advanced features will require you to write some basic JavaScript code; consult the API Recipes documentation to learn more.

✅ Success: Your API recipe is now available to guide developers!

3. Customize the API Portal Theme and Layout

Make your API Portal match your company’s brand identity:

1. Open the APIMATIC-BUILD.json file in a code editor.

2. Add the following colors configuration to the end of the portalSettings.theme object

     "colors": {
       "primaryColor": { "light": "#400072", "dark": "#D8A3FF" },
       "secondaryColor": { "light": "#CAF55C", "dark": "#CAF55C" },
       "linkColor": { "light": "#8C21DF", "dark": "#CAF55C" }
     }

3. Preview your API Portal

   To preview your updated API Portal, ensure your development server is running. If it's not, start it by executing the following command:

   apimatic portal:serve

Theme Updates Explained

The theme object you added has customized your API Portal with the following changes:

• The primary color is set to "#400072" in light mode and "#D8A3FF" in dark mode.
• The secondary color is "#CAF55C" in both light and dark modes.
• The link color is "#8C21DF" in light mode and "#CAF55C" in dark mode.

APIMatic offers extensive theme and page layout customization options for your Portal, beyond these basic customizations. For more details, refer to APIMatic's documentation on Theme and Layout configurations.

✅ Success: Your API Portal looks sleek!

4. Generate an LLMs.txt file

LLMs.txt is a new web standard that makes your documentation AI-accessible. It enables tools like Cursor, GitHub Copilot, ChatGPT, and Claude to quickly understand your documentation.

1. Open the APIMATIC-BUILD.json file in a code editor.

2. Update your build configuration:

   Add the following configuration to the end of the generatePortal object in your APIMATIC-BUILD.json file.

   Note: The baseUrl should match where your portal is running locally. If you're using the default portal:serve command, this will be http://localhost:3000.

     "baseUrl": "http://localhost:3000",
     "llmsContextGeneration": {
       "enable": true
       }

Understanding LLMs.txt Files

After adding the above configurations, your API Portal will generate two files:

• llms.txt: This is a small, summary-focused index file that provides a structured overview of the content of your API Portal.
• llms-full.txt: This is a much larger, comprehensive file that includes the full content of your API Portal in one consolidated markdown file.

You can learn more about LLMs.txt files here.

View your LLMs.txt Files

To preview the newly generated files, ensure your development server is running. If it's not, start it by executing the following command:

apimatic portal:serve

Next, navigate to the /llms.txt path of your API Portal to view the llms.txt file and the /llms-full.txt path to view the llms-full.txt file, for instance ,http://localhost:3000/llms-full.txt.

✅ Success: Your API Portal is now AI-accessible!

5. Enable API Copilot

Add an AI-powered assistant to help developers learn and integrate with your API. API Copilot provides instant answers to questions about your API directly within your documentation portal.

Configure API Copilot

Run the copilot configuration command to select and set up your AI assistant:

apimatic portal:copilot

Expected output

  ◇  Select API Copilot key from your subscription:
  │  2ab56808-aaaa-47a1-1234-zn44m5964ef3
  │
  └  API Copilot is configured successfully with key '2ab56808-aaaa-47a1-1234-zn44m5964ef3'. You can now generate a portal using the command 'apimatic portal:generate'

Understanding API Copilot

After running the configuration command, your APIMATIC-BUILD.json file will be updated with copilot settings that enable:

• Contextual AI assistance: API Copilot learns from your API specification and documentation to provide accurate answers
• Interactive developer support: API Copilot appears as a chat interface within your API Portal, allowing developers to ask questions directly without leaving the documentation.

View your API Copilot

Start your local development server to see the copilot in action:

apimatic portal:serve

Look for the chat interface in the bottom-right corner of your API Portal. Click it to interact with your new AI assistant! You can learn more about the API Copilot in our documentation.

✅ Success: Your API Portal now includes an AI-powered assistant to answer Developer questions!

6. Enable SEO optimization

The default API Portal is a Single-Page Application (SPA). SPAs aren't SEO-friendly but more straightforward to deploy and less prone to deployment mistakes.

APIMatic supports generating an SEO-friendly API Documentation Portal with a few changes to the Build file and support from the server-side.

To optimize your Portal for search engines, add the following configuration to the end of the generatePortal object in your APIMATIC-BUILD.json file:

  "indexable": {}

If you followed along with the steps in the previous section to generate an llms.txt file, your generatePortal object should already contain a baseUrl property. If it doesn't already exist, you will need to add it as well.

Note: The baseUrl should match where your portal is running locally. If you're using the default portal:serve command, this will be http://localhost:3000.

  "baseUrl": "http://localhost:3000"

This is what your generatePortal configuration should look like now:

{
  "generatePortal": {
    .
    .
    .
    "baseUrl": "http://localhost:3000",
    "indexable": {}
  }
}

View your SEO-enabled API Portal

Start your local development server to see your SEO-enabled Portal:

apimatic portal:serve

SEO optimizations explained

Enabling SEO for an APIMatic API Portal:

• Generates HTML files for all pages with correct <title> and canonical tags.
• Ensures that the API Portal uses HTML History API for crawler-friendly routing.
• Generates a Meta redirect HTML file for redirects.
• Generates a _redirect file for all necessary redirects.
• Generates a sitemap.xml for page discovery.
• Generates a 404.html to prevent SPA misidentification.
• Generates a customizable robots.txt to guide crawlers.

Learn more about APIMatic’s support for SEO optimization here.

✅ Success: Your API Portal is optimized for search engines!

What's Next?

See Your API's Full Potential–Request a Free Custom Demo!

Here's what we're offering you, completely free:

• A personalized demo showcasing the full platform capabilities
• A custom proof of concept built with your actual API specification
• Expert consultation on optimizing your developer experience strategy
• Zero commitment required–seriously, no strings attached!

Our team has helped companies like PayPal, Verizon, and hundreds of others transform their API programs. We'd love to show you what's possible for your APIs too.

🎯 Get Your Free Custom Demo & POC →

Learn more about the API Portal

Ready to go deeper? Explore these advanced topics:

• Add a Custom header and footer to your API Portal
• Inject Authentication information
• Implement RBAC
• Automate deployments via CI/CD Pipelines