Endpoint Reference

Base URL: https://app.hintoai.com/api/external/v2

All requests require the X-API-Key header. See Authentication for details.

Machine-readable spec: https://app.hintoai.com/api/external/v2/openapi (OpenAPI 3.1)

Async jobs

Several operations take time (video import, content generation, publishing). These endpoints return 202 Accepted immediately with a job object:

{
  "jobId": "uuid",
  "type": "generate",
  "status": "pending",
  "output": null,
  "error": null,
  "createdAt": "2026-06-01T10:00:00Z",
  "completedAt": null
}

Poll GET /generate/{jobId} until status is completed or failed. On completion, output contains the result. On failure, error contains the message.

Alternatively, pass a callbackUrl in the request body to receive a webhook when the job finishes (see Webhooks).

Videos

Scope required: read for GET, write for DELETE, generate for import/upload.

Method	Path	Description
GET	/videos	List videos (limit, offset query params)
GET	/videos/{videoId}	Get a video by ID
GET	/videos/{videoId}/status	Get processing status
DELETE	/videos/{videoId}	Delete a video
POST	/videos/import	Import a video from a public URL (async)
POST	/videos/upload/presigned	Get a presigned S3 URL for direct upload
POST	/videos/upload/complete	Confirm a presigned upload is complete

Import a video from a URL:

curl -X POST https://app.hintoai.com/api/external/v2/videos/import \
  -H "X-API-Key: hinto_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/demo.mp4"}'

Response (202):

{ "jobId": "uuid", "type": "import_video_url", "status": "pending", "output": null, "createdAt": "..." }

Poll GET /generate/{jobId} — when completed, output.videoId contains the video ID.

Generate

Scope required: generate.

Method	Path	Description
POST	/generate	Start article generation from a video (async)
GET	/generate/{jobId}	Poll a job (generation, import, publish, translate)
POST	/generate/structure	Generate article structure from a video (async)

Start article generation:

curl -X POST https://app.hintoai.com/api/external/v2/generate \
  -H "X-API-Key: hinto_..." \
  -H "Content-Type: application/json" \
  -d '{"videoId": "video-uuid", "templateId": 1}'

Response (202): job object. Poll GET /generate/{jobId} until completed.

Articles

Scope required: read for GET/list, write for create/update/delete/move.

Method	Path	Description
GET	/articles	List articles (folderId, limit, offset query params)
GET	/articles/{id}	Get article with full content (`format=markdown\
POST	/articles	Create article from Markdown (title, content, folderId)
POST	/articles/empty	Create empty article (title, folderId)
PATCH	/articles/{id}	Update title, slug, or SEO fields
DELETE	/articles/{id}	Delete an article

Get an article as Markdown:

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

Folders

Scope required: read for GET/list, write for create/update/delete.

Method	Path	Description
GET	/folders	List folders
POST	/folders	Create a folder (name, parentId)
PATCH	/folders/{id}	Rename or reparent a folder
DELETE	/folders/{id}	Delete a folder

Templates

Scope required: read.

Method	Path	Description
GET	/templates/article	List available article templates
GET	/templates/structure	List available structure templates

Publish

Scope required: publish.

Method	Path	Description
POST	/publish	Publish the project (async — returns jobId)
POST	/publish/republish	Republish with latest content (async — returns jobId)
GET	/publish/status	Get current publish status

Export

Scope required: read.

Method	Path	Description
GET	/export	Export project as ZIP or LLM text (`format=html\

Project

Scope required: read.

Method	Path	Description
GET	/project	Get project metadata
GET	/project/structure	Get full folder + article tree
GET	/project/languages	List configured languages