Introduction

The Typemill API allows you to retrieve and update content and data using simple HTTP requests. It primarily powers the Typemill author interface, meaning you can perform all the same actions via the API that you would in the interface. Additionally, some extra endpoints have been introduced to support external use.

Use Cases

Typemill is rarely used for headless content management or JAMstack integrations. Instead, it excels at creating documentation and manuals. A great use case is integrating a documentation or knowledge base as inline help within another software. We have implemented this approach with the Typemill documentation itself, which also serves as the content repository for the inline help system in Typemill installations.

Limitations

Unlike traditional APIs that use fixed IDs to identify pages, Typemill relies on relative URLs. This works seamlessly within the author interface but can be a limitation for external integrations. If a page's URL changes, external systems relying on the old URL may no longer be able to find the content. To address this, we introduced an alternative endpoint that allows pages to be found using their slugs, which are more stable and less likely to change frequently.

URL

The URL format is:

{protocol}://{domain}/api/{version}/{endpoint}

Example:

https://mytypemillwebsite.com/api/v1/navigation

Activate the API

API calls are tied to user accounts. You can enable API access by checking a box in the user's profile settings. This can be done for multiple users as needed.

Authentication

To authenticate API calls, use Basic Authentication with the username and password of the respective user:

curl -X GET "https://typemill.net/api/v1/navigation" \
     -u username:password \
     -H "Accept: application/json"

Authorization

Permissions are determined by the user's role. Check the documentation about user roles for more details.

Trusted IPs and Hosts

You can restrict API access based on IP addresses or hostnames, which can be configured in the Developer tab of the system settings. Check the admin guide for more details.

Recommendations

• Create separate user accounts for API access.
• Use clear and descriptive usernames for API user (e.g. with prefixes to easily identify them).
• Use strong passwords and the lowest role needed (e.g. with just read access).
• Allow API calls only from whitelisted IPs or hosts.

CORS

Typemill does not support CORS headers, meaning the API cannot be accessed directly from the browser (e.g., using JavaScript). Only server-side calls are allowed.

Endpoints and Methods

HTTP Status Codes

The API will return the following status codes.