Notes

Create AI-generated notes from URLs or files, validate inputs, and list existing notes using an API key.

Notes

The Notes API lets you:

Create notes from websites or YouTube videos.
Create notes from audio files, documents, or images.
Validate an input before processing it.
List notes owned by the current account.
Track note generation through the Tasks API.

Base URL:

https://api.notexapp.com

Send the API key through X-API-Key:

-H "X-API-Key: ntx_live_..."

Response format

interface ApiResponse<T> {
  statusCode: number;
  message?: string;
  data: T;
}

Task status values:

type TaskStatus =
  | 'PENDING'
  | 'PROCESSING'
  | 'SUCCESS'
  | 'FAIL';

Create a note

POST /v9/create/note

Creates an AI-generated note and summary from a URL or an uploaded file.

Request content type:

Content-Type: application/json

Provide exactly one source:

web_url for a website or YouTube video.
file_url for a previously uploaded file.

Do not send both fields in the same request.

Request body

Field	Type	Required	Description
`web_url`	`string`	Conditional	Website or YouTube URL
`file_url`	`string`	Conditional	URL or path of a previously uploaded file
`language_hints`	`string[]`	No	Preferred output languages, such as `["en"]` or `["vi"]`
`use_ocr`	`boolean`	No	Run OCR for document or image sources
`summary_style`	`string`	No	Summary-style preset
`writing_style`	`string`	No	Writing-style preset
`human_style`	`string \| null`	No	Humanized writing-style option
`is_record`	`boolean`	No	Whether the input is a recording
`duration`	`number`	No	Input duration in seconds
`bot_id`	`string`	No	Meeting bot ID
`record_session_id`	`string`	No	Recording session ID
`device_meeting_id`	`string`	No	Device meeting ID
`target_language`	`string`	No	Deprecated. Use `language_hints` instead

Create a note from a URL

curl -X POST https://api.notexapp.com/v9/create/note \
  -H "X-API-Key: ntx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "web_url": "https://youtu.be/xxxx",
    "language_hints": ["en"]
  }'

Create a note from an uploaded file

curl -X POST https://api.notexapp.com/v9/create/note \
  -H "X-API-Key: ntx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://cdn.notexapp.com/uploads/lecture.mp3",
    "language_hints": ["en"],
    "is_record": true,
    "duration": 1800
  }'

Example response

{
  "status": "PROCESSING",
  "data": {
    "task_id": "task_123456",
    "user_id": "665f...",
    "step": "transcribing",
    "progress": 10,
    "estimated_time": 120,
    "timestamp": 1784011200
  }
}

Response fields

Field	Type	Description
`status`	`TaskStatus \| null`	Initial task status
`data.task_id`	`string`	ID used to poll the Tasks API
`data.user_id`	`string`	Account ID that created the task
`data.note_id`	`string`	Note ID, when immediately available
`data.step`	`string`	Current processing step
`data.progress`	`number`	Estimated progress percentage
`data.estimated_time`	`number`	Estimated remaining time in seconds
`data.timestamp`	`number`	Task creation timestamp
`data.stream_sse`	`string`	SSE URL, when available
`folder_id`	`string`	Destination folder ID, when available

After receiving task_id, poll the Tasks API until the task reaches SUCCESS, FAILURE, or FAIL.

TypeScript types

export interface CreateNoteV9RequestBody {
  web_url?: string;
  file_url?: string;
  language_hints?: string[];
  use_ocr?: boolean;
  summary_style?: string;
  writing_style?: string;
  human_style?: string | null;
  is_record?: boolean;
  duration?: number;
  bot_id?: string;
  record_session_id?: string;
  device_meeting_id?: string;
  target_language?: string;
}

export interface CreateNoteResType {
  status: TaskStatus | null;
  data: {
    task_id: string;
    user_id: string;
    note_id?: string;
    step?: string;
    progress?: number;
    estimated_time?: number;
    timestamp?: number;
    stream_sse?: string;
  };
  folder_id?: string;
  stream_sse?: string;
}

Validate an input

POST /v9/create/validate

Validates a URL or uploaded file before creating a note.

Use this endpoint to:

Check whether Notex supports the source.
Detect the input type.
Read metadata such as duration or caption languages.
Avoid creating an invalid task.

Request body

Field	Type	Required	Description
`web_url`	`string`	Conditional	Website or YouTube URL
`file_url`	`string`	Conditional	Previously uploaded file URL

Provide one source field.

Example request

curl -X POST https://api.notexapp.com/v9/create/validate \
  -H "X-API-Key: ntx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "web_url": "https://youtu.be/xxxx"
  }'

Valid input response

{
  "is_valid": true,
  "input_type": "youtube",
  "metadata": {
    "video_id": "xxxx",
    "status": "available",
    "duration": 1260,
    "has_captions": true,
    "available_languages": ["en", "vi"]
  }
}

Invalid input response

{
  "is_valid": false,
  "input_type": "youtube",
  "error_key": "unsupported_source",
  "error_message": "The provided source is not supported."
}

Response fields

Field	Type	Description
`is_valid`	`boolean`	Whether the input is valid
`input_type`	`string`	Detected input type
`error_key`	`string`	Machine-readable validation error
`error_message`	`string`	Human-readable error message
`metadata.video_id`	`string`	YouTube video ID
`metadata.status`	`string`	Source status
`metadata.duration`	`number`	Duration in seconds
`metadata.has_captions`	`boolean`	Whether captions are available
`metadata.available_languages`	`string[]`	Available source languages

TypeScript types

export interface ValidateLinkBodyType {
  web_url?: string;
  file_url?: string;
}

export interface ValidateLinkResType {
  is_valid: boolean;
  input_type: string;
  error_key?: string;
  error_message?: string;
  metadata?: {
    video_id?: string;
    status?: string;
    duration?: number;
    has_captions?: boolean;
    available_languages?: string[];
  };
}

Upload a local file

Before creating a note from a local file:

Request a presigned upload URL.
Upload the file directly with PUT.
Pass the returned file_url to Create Note.

See the complete Presigned URL guide.

Short example

# 1. Get the upload URL
RESPONSE=$(curl -s --get \
  "https://api.notexapp.com/v1/presigned-url" \
  -H "X-API-Key: ntx_live_..." \
  --data-urlencode "file_name=lecture.mp3")

UPLOAD_URL=$(echo "$RESPONSE" | jq -r '.data.upload_url')
FILE_URL=$(echo "$RESPONSE" | jq -r '.data.file_url')

# 2. Upload the file
curl --fail -X PUT "$UPLOAD_URL" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @lecture.mp3

# 3. Create the note
curl -X POST https://api.notexapp.com/v9/create/note \
  -H "X-API-Key: ntx_live_..." \
  -H "Content-Type: application/json" \
  -d "{
    "file_url": "$FILE_URL",
    "language_hints": ["en"]
  }"

Do not send the API key to upload_url.

List my notes

GET /v2/user/notes

Returns notes owned by the account that created the API key.

Query parameters

Parameter	Type	Required	Description
`type`	`string`	No	Filter by note type
`tab`	`string`	No	Filter by tab
`limit`	`number`	No	Maximum number of notes per page
`cursor`	`string`	No	Cursor for the next page
`page`	`number`	No	Page number
`sort_field`	`string`	No	Field used for sorting
`sort_order`	`1 \| -1`	No	`1` ascending, `-1` descending

Example request

curl "https://api.notexapp.com/v2/user/notes?limit=20&sort_field=createdAt&sort_order=-1" \
  -H "X-API-Key: ntx_live_..."

Example response

{
  "statusCode": 200,
  "data": [
    {
      "note_id": "note_123456",
      "title": "Introduction to AI agents",
      "folder_id": null,
      "type": "youtube",
      "duration": 1260,
      "short_summary": "An introduction to AI agent architecture...",
      "is_public": false,
      "is_password_protected": false,
      "share_link": null,
      "createdAt": "2026-07-24T02:00:00Z",
      "updatedAt": "2026-07-24T02:10:00Z"
    }
  ]
}

See User API for detailed field definitions.

Typical flows

Create from a URL

Validate the URL
       ↓
Create the note
       ↓
Receive task_id
       ↓
Poll the Tasks API
       ↓
Receive note_id

Create from a local file

Get a presigned URL
       ↓
Upload the file with PUT
       ↓
Create the note with file_url
       ↓
Receive task_id
       ↓
Poll the Tasks API
       ↓
Receive note_id

Important notes

Send either web_url or file_url, not both.
Validate user-provided URLs before creating a task.
Do not send the API key to a presigned upload URL.
Use file_url, not upload_url, when creating a note.
target_language is deprecated; use language_hints.
A task may occasionally return note_id immediately, but integrations should still support the asynchronous task_id flow.
Optional progress fields may be omitted.
Keep the API key on a controlled backend or server.

Was this page helpful?