api.theomnix.net

API Docs

Request parameters, cookies, and response shapes for every available endpoint.

GET/docs

Human-readable API documentation page for all endpoints.

Expected Params

No request params are required.

Returns

200

Returns the HTML documentation page.

{ "content-type": "text/html" }

GET/api/health

Returns runtime status, environment, and domain metadata.

Expected Params

No request params are required.

Returns

200

Health check succeeded.

{
  "ok": true,
  "service": "Omnix API",
  "domain": "api.theomnix.net",
  "environment": "production",
  "timestamp": "2026-03-25T12:00:00.000Z"
}

POST/api/contact

Validates and accepts a contact form submission.

Expected Params

name

body | string | required

Contact name, 2 to 100 characters.

email

body | string | required

Valid email address.

company

body | string | optional

Optional company name up to 120 characters.

message

body | string | required

Message body, 10 to 2000 characters.

Returns

201

Submission accepted.

{
  "ok": true,
  "message": "Contact request accepted.",
  "domain": "api.theomnix.net",
  "submission": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "company": "Omnix",
    "message": "Tell me more about your platform.",
    "receivedAt": "2026-03-25T12:00:00.000Z"
  }
}

422

Validation failed.

{
  "ok": false,
  "error": {
    "message": "Validation failed.",
    "details": {
      "fieldErrors": {
        "email": ["Invalid email address"]
      }
    }
  }
}

GET/auth/tiktok/start

Starts TikTok OAuth and redirects the user to TikTok.

Expected Params

scope

query | string | optional

Optional override for the configured TikTok OAuth scope.

Returns

307

Redirects to the TikTok authorization URL.

Location: https://www.tiktok.com/v2/auth/authorize/?client_key=...&redirect_uri=...&scope=user.info.basic,user.info.profile,video.publish&state=...

500

OAuth environment is missing or invalid.

{
  "error": "Server configuration error"
}

GET/auth/tiktok/callback

Validates the state, exchanges the code for tokens, stores them temporarily, and redirects to the frontend completion page.

Expected Params

code

query | string | required

Authorization code returned by TikTok after consent.

state

query | string | required

CSRF state value that must match the HttpOnly cookie.

error

query | string | optional

OAuth error returned by TikTok if the user denies consent.

error_description

query | string | optional

Optional TikTok error detail.

omnix_tiktok_oauth

cookie | string | required

HttpOnly cookie containing the original OAuth state.

Returns

307

Redirects to the frontend completion page on success.

Location: http://localhost:3000/auth/complete?provider=tiktok&status=success&open_id=...&username=...&display_name=...&avatar_url=...&granted_scopes=user.info.basic,user.info.profile,video.publish&can_post=true

307

Redirects to the frontend completion page on failure.

Location: http://localhost:3000/auth/complete?provider=tiktok&status=error&reason=invalid_state

GET/auth/tiktok/session

Returns the temporarily stored TikTok session, granted scopes, and fetched user profile for a given open_id.

Expected Params

open_id

query | string | required

TikTok open_id returned after a successful callback.

Returns

200

Stored TikTok session found.

{
  "ok": true,
  "open_id": "afd97af1-b87b-48b9-ac98-410aghda5344",
  "scope": "user.info.basic,user.info.profile,video.publish",
  "can_post": true,
  "expires_in": 86400,
  "received_at": "2026-03-25T12:00:00.000Z",
  "profile": {
    "open_id": "afd97af1-b87b-48b9-ac98-410aghda5344",
    "display_name": "TikTok Creator",
    "username": "creator_handle",
    "avatar_url": "https://...",
    "profile_deep_link": "https://www.tiktok.com/@creator_handle"
  }
}

404

Session not found in the temporary in-memory store.

{
  "ok": false,
  "error": "No TikTok session found for the provided open_id."
}

GET/auth/youtube/start

Starts Google OAuth for YouTube Data API access using the youtube.readonly and youtube.upload scopes by default.

Expected Params

scope

query | string | optional

Optional override for the configured Google OAuth scopes. Google expects scopes to be space-delimited.

Returns

307

Redirects to Google consent for YouTube authorization.

Location: https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=https://api.theomnix.net/auth/youtube/callback&response_type=code&scope=https://www.googleapis.com/auth/youtube.readonly%20https://www.googleapis.com/auth/youtube.upload&access_type=offline&include_granted_scopes=true&prompt=consent&state=...

GET/auth/youtube/callback

Validates the OAuth state, exchanges the Google authorization code for YouTube tokens, fetches the authenticated channel, stores the session temporarily, and redirects to the frontend completion page.

Expected Params

code

query | string | required

Authorization code returned by Google after consent.

state

query | string | required

CSRF state value that must match the HttpOnly cookie.

error

query | string | optional

OAuth error returned by Google if the user denies consent.

error_description

query | string | optional

Optional Google error detail.

omnix_youtube_oauth

cookie | string | required

HttpOnly cookie containing the original OAuth state.

Returns

307

Redirects to the frontend completion page on success.

Location: http://localhost:3000/auth/complete?provider=youtube&status=success&channel_id=UC...&channel_title=Omnix&custom_url=@omnix&granted_scopes=https://www.googleapis.com/auth/youtube.readonly%20https://www.googleapis.com/auth/youtube.upload&can_read=true&can_upload=true

307

Redirects to the frontend completion page on failure.

Location: http://localhost:3000/auth/complete?provider=youtube&status=error&reason=invalid_state

GET/auth/youtube/session

Returns the temporarily stored YouTube session, granted scopes, and cached authenticated channel for a given channel_id.

Expected Params

channel_id

query | string | required

YouTube channel ID returned after a successful callback.

Returns

200

Stored YouTube session found.

{
  "ok": true,
  "channel_id": "UC1234567890",
  "scope": "https://www.googleapis.com/auth/youtube.readonly https://www.googleapis.com/auth/youtube.upload",
  "can_read": true,
  "can_upload": true,
  "expires_in": 3599,
  "received_at": "2026-03-25T12:00:00.000Z",
  "channel": {
    "id": "UC1234567890",
    "title": "Omnix",
    "custom_url": "@omnix",
    "thumbnail_url": "https://yt3.googleusercontent.com/...",
    "uploads_playlist_id": "UU1234567890"
  }
}

404

Session not found in the temporary in-memory store.

{
  "ok": false,
  "error": "No YouTube session found for the provided channel_id."
}

GET/api/youtube/channel

Fetches the authenticated user's current YouTube channel using the stored server-side access token and the youtube.readonly scope.

Expected Params

channel_id

query | string | required

Channel ID used to look up the stored server-side OAuth session.

Returns

200

Fresh channel data returned from channels.list?mine=true.

{
  "ok": true,
  "channel": {
    "id": "UC1234567890",
    "title": "Omnix",
    "subscriber_count": "1500",
    "video_count": "42",
    "view_count": "98765",
    "privacy_status": "public",
    "long_uploads_status": "allowed"
  }
}

403

Stored session is missing the required readonly scope.

{
  "ok": false,
  "error": "The stored YouTube session is missing the youtube.readonly scope."
}

POST/api/youtube/videos/upload

Uploads a video to the authenticated YouTube channel using the resumable videos.insert flow and the youtube.upload scope.

Expected Params

channel_id

body | string | required

Channel ID used to look up the stored server-side OAuth session.

video

body | file | required

Binary video file sent as multipart/form-data.

title

body | string | required

Video title, max 100 characters.

description

body | string | optional

Video description, max 5000 characters.

privacy_status

body | string | optional

One of private, public, or unlisted.

tags

body | string | optional

Comma-delimited tag list.

category_id

body | string | optional

Optional YouTube video category ID.

Returns

200

Video upload completed successfully.

{
  "ok": true,
  "upload": {
    "id": "a1b2c3d4",
    "kind": "youtube#video"
  }
}

403

Stored session is missing the required upload scope.

{
  "ok": false,
  "error": "The stored YouTube session is missing the youtube.upload scope."
}

Quick Links

Home Health JSON Start TikTok OAuth Start YouTube OAuth