API Documentation

This document describes the external API system that allows external applications to access project data using API keys.

Overview

The external API provides secure, project-specific access to:

• Project structure (folders and articles metadata)
• Individual articles in HTML or Markdown format
• Complete project exports as ZIP archives

Authentication

All external API endpoints require API key authentication using the X-API-Key header. API keys are tied to a specific project and provide access only to that project's data.

Base URL: app.hintoai.com/api/external/v1

curl -H "X-API-Key: your-api-key-here" \
     https://app.hintoai.com/api/external/v1/projects/structure

Getting Started

Obtaining an API Key

API Key Properties

• Project-Specific: Each API key provides access to only one project
• Read-Only: API keys provide read-only access to project data
• Expiration: Keys may have expiration dates set by the project owner
• Revocation: Project owners can deactivate or delete keys at any time

Available Endpoints

1. Get Project Structure

Endpoint: GET /api/external/v1/projects/structure Authentication: Required (Project API Key)

Returns the hierarchical structure of folders and articles within the authenticated project.

Response:

{
  "project": {
    "id": "uuid",
    "name": "Project Name",
    "description": "Project description",
    "url": "https://project-website.com",
    "logoUrl": "https://logo-url.com/logo.png",
    "projectBrandData": { /* branding data */ },
    "isSearchEngineIndexed": true
  },
  "structure": {
    "folders": [
      {
        "id": 1,
        "name": "Folder Name",
        "articles": [
          {
            "id": 1,
            "title": "Article Title",
            "created_at": "2024-01-01T00:00:00Z",
            "updated_at": "2024-01-01T00:00:00Z",
            "video_id": "uuid"
          }
        ],
        "children": [/* nested folders */]
      }
    ],
    "rootArticles": [
      {
        "id": 2,
        "title": "Root Article",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z",
        "video_id": "uuid"
      }
    ]
  }
}

2. Get Single Article

Endpoint: GET /api/external/v1/articles/{id} Authentication: Required (Project API Key)

Returns a specific article with its content in HTML or Markdown format.

Query Parameters:

• format (optional): Export format
• html (default): Returns HTML content
• markdown: Returns Markdown content
• clean (optional): Set to true or 1 for clean HTML export with processed article links (HTML format only)

Response (HTML format):

{
  "article": {
    "id": 1,
    "title": "Article Title",
    "project_id": "uuid",
    "folder_id": 1,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  "content": {
    "html": "<h1>Article Title</h1><p>Article content...</p>",
    "format": "html"
  },
  "project": {
    "slug": "project-slug",
    "name": "Project Name"
  }
}

Response (Markdown format):

{
  "article": {
    "id": 1,
    "title": "Article Title",
    "project_id": "uuid",
    "folder_id": 1,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  "content": {
    "markdown": "# Article Title\n\nArticle content...",
    "format": "markdown"
  },
  "project": {
    "slug": "project-slug",
    "name": "Project Name"
  }
}

3. Export Complete Project

Endpoint: GET /api/external/v1/projects/export Authentication: Required (Project API Key)

Downloads the entire project as a ZIP archive or single file.

Query Parameters:

• format (optional): Export format
• html (default): HTML files in ZIP archive
• markdown: Markdown files in ZIP archive
• llm-text: Single plain text file (all articles combined)

Response:

• For html/markdown: Binary ZIP file download with folder structure
• Content-Type: application/zip
• Content-Disposition: attachment; filename="project-name.zip"
• For llm-text: Plain text file download (single file)
• Content-Type: text/plain
• Content-Disposition: attachment; filename="project-name.txt"

Error Responses

All endpoints return consistent error responses:

{
  "error": "Error type",
  "message": "Detailed error message"
}

Common error codes:

• 401 - Missing or invalid API key
• 403 - Access denied to resource
• 404 - Resource not found
• 405 - Method not allowed
• 500 - Internal server error

Usage Examples

Get Project Structure

curl -H "X-API-Key: your-api-key" \
     https://app.hintoai.com/api/external/v1/projects/structure

Get Specific Article (HTML)

curl -H "X-API-Key: your-api-key" \
     https://app.hintoai.com/api/external/v1/articles/123

Get Article in Markdown Format

curl -H "X-API-Key: your-api-key" \
     https://app.hintoai.com/api/external/v1/articles/123?format=markdown

Get Article with Clean HTML

curl -H "X-API-Key: your-api-key" \
     https://app.hintoai.com/api/external/v1/articles/123?clean=true

Export Project as ZIP

curl -H "X-API-Key: your-api-key" \
     https://app.hintoai.com/api/external/v1/projects/export?format=html \
     -o project-export.zip

Export Project as LLM Text

curl -H "X-API-Key: your-api-key" \
     https://app.hintoai.com/api/external/v1/projects/export?format=llm-text \
     -o project-export.txt

Export Project as Markdown

curl -H "X-API-Key: your-api-key" \
     https://app.hintoai.com/api/external/v1/projects/export?format=markdown \
     -o project-export.zip