T
testing
Backups & Restorations Initializing Projects from External Sources

Starting a new documentation project doesn't mean you have to start from scratch. Whether you have an existing OpenAPI specification, a GitHub repository full of Markdown files, or a live website, you can automatically bootstrap your new project using your existing external data.

By importing your current resources, you can instantly generate a structured, ready-to-edit documentation site, saving you hours of manual setup.

GitHub Repository

Pull your existing Markdown files and folder structures directly from your repositories.

OpenAPI / Swagger

Instantly generate comprehensive API references from your existing specs.

Live Website

Crawl and import content from your current live documentation or website.

How Initialization Works

When you create a new documentation project, it starts in a "pending" state. You then choose an initialization method to populate it with content.

flowchart LR
    A["External Sources"] --> B{"GitDocAI Engine"}
    C["OpenAPI Spec"] --> A
    D["GitHub Repo"] --> A
    E["Live Website"] --> A
    F["Local Files"] --> A
    B --> G["Structured Documentation"]
    B --> H["Navigation Scaffold"]

Supported Initialization Methods

We offer several endpoints to help you bootstrap your project depending on where your data currently lives:

Source TypeDescriptionAPI Endpoint
OpenAPI / SwaggerImport an existing API specification file.POST /v1/documentation/{organization_id}/{documentation_id}/initialize-from-openapi
GitHub RepositorySync files directly from a connected repository.POST /v1/documentation/{organization_id}/{documentation_id}/initialize-from-repository
WebsiteCrawl and extract content from a public URL.POST /v1/documentation/{organization_id}/{documentation_id}/initialize-from-website
File ImportUpload local files or archives.POST /v1/documentation/{organization_id}/{documentation_id}/initialize-from-file
AI PromptDescribe what you need, and AI will generate the scaffold.POST /v1/documentation/{organization_id}/{documentation_id}/initialize-from-ai
Preset TemplateStart with a best-practice layout for your industry.POST /v1/documentation/{organization_id}/{documentation_id}/initialize-from-template
Blank ScaffoldStart fresh with a basic default structure.POST /v1/documentation/{organization_id}/{documentation_id}/initialize-blank

If you are migrating from another platform, the Website and GitHub Repository initialization methods are usually the fastest ways to port your content over.

Bootstrapping a Project via API

If you are automating your documentation setup, you can initialize a project programmatically.

  1. 1

    Identify your Organization and Project IDs

    You will need your organization_id and the documentation_id of the pending project you just created.

  2. 2

    Select your source and prepare the payload

    Depending on the initialization method, you may need to provide additional details in your request body (such as a repository URL, a website link, or an OpenAPI file).

  3. 3

    Send the initialization request

    Make a POST request to the relevant initialization endpoint. For example, to initialize from a GitHub repository:

    curl -X POST "https://api.gitdocai.com/v1/documentation/org_123/doc_456/initialize-from-repository" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"repo_url": "https://github.com/your-org/your-repo", "branch": "main"}'

Initialization endpoints are designed for new, pending projects. Running an initialization command on an already populated documentation project may overwrite existing content.

Frequently Asked Questions

Can I combine multiple external sources?

Currently, a project can only be initialized from a single primary source. However, once the initial bootstrap is complete, you can manually import additional files or link other repositories to specific sections of your documentation.

What happens if I make a mistake during initialization?

If your project didn't initialize the way you wanted, you can safely delete the pending project and create a new one to try again. If the project is already live, we recommend using our Backup & Restore features to revert to a previous state.

Does the Website import copy my styling?

No. The website crawler extracts the raw text, headings, and structure (Markdown) from the target URL. It strips out external CSS and scripts so your new documentation perfectly matches your GitDocAI theme.

Next Steps: Backups and Restorations

Once your project is successfully initialized from an external source, it's highly recommended to configure a backup repository. This ensures that your newly imported data is safely version-controlled.

You can set up your backup location using the PUT /v1/documentation/{organization_id}/{documentation_id}/backup/repository endpoint.