Introduction

API Import

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
          PARAMETER_DESCRIPTION_MERGE_STRATEGY: keep_new
          SECTION_DESCRIPTION_MERGE_STRATEGY: keep_old

          INCLUDE_GITHUB_METADATA: true

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`
`--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")
  --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

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.

Sections