Customize your API Portal

You've created a solid API Portal with auto-generated API documentation, but the real magic happens when you customize your Portal to match your brand, add helpful content, and optimize it for both developers and search engines.
This guide will walk you through some essential customizations that will elevate your portal from functional to exceptional.

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
Drive more traffic to your Portal by optimizing it for search engines that help developers find your APIs

Each section builds upon the previous one, but you can also jump to specific customizations based on your immediate needs. Let's get started!

note

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

1. Add a Documentation page to the 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.

Navigate to the content/guides directory in your project source:
```
cd hello-apimatic/content/guides
```
Create a new markdown file:
Create a new markdown file and open it in your favourite text editor

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.

Update your 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.
Note: If your portal’s live preview is still running, you will either need to terminate it before running this command, OR run this command in a new terminal window.
```
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: /your-project/content/toc.yml
```
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 portal!

2. Add a Recipe to the 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 Portal using the API Recipe creation wizard. The API Recipe wizard will guide you through:

Recipe Setup: Create a recipe and add it to the API Portal
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 portal match your company’s brand identity:

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

Insert the following theme at the end of the portalSettings object

​​"portalSettings": {
    "theme": {
        "colors": {
          "primaryColor": { "light": "#400072", "dark": "#D8A3FF" },
          "secondaryColor": { "light": "#CAF55C", "dark": "#CAF55C" },
          "linkColor": { "light": "#8C21DF", "dark": "#CAF55C" }
        },
        "colorMode": { "defaultMode": "system", "disableSwitch": false  }
  }
}

Preview your Portal
To preview your updated 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 Portal with the following changes:

Dark Mode is now enabled.
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.

Update your build configuration:

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

Ensure you replace baseUrl with the URL of your local development server.

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

Understanding LLMs.txt Files

After adding the above configurations, your 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 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 portal is now AI-accessible!

5. 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:

{
  "generatePortal": {
    "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:

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

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 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:

What You'll Accomplish​

1. Add a Documentation page to the Portal​

2. Add a Recipe to the Portal​

3. Customize the API Portal Theme and Layout​

4. Generate an LLMs.txt file​

5. Enable SEO optimization​

What's Next?​

Learn more about the API Portal​