Skip to content
Qortex
Back to platform
API reference · v1

Qortex API User Guide

Submit batches of page or video URLs, poll until they finish, then fetch signals per URL. Explore authentication, endpoints, response fields and all nine signal types. No account is required to read this guide.

Base URL https://api.qortex.aiHeader X-API-KEY
01

Quickstart

Three calls: upload a batch, wait for it to finish, then read results per URL. Examples use the video endpoints; page endpoints follow the same pattern.

  1. 1.

    Set your key as an environment variable

    shell
    export QORTEX_API_KEY="paste-your-key-here"
  2. 2.

    Upload a newline-separated file of URLs

    shell
    # urls.txt: one URL per line, up to 500
    curl -X POST "https://api.qortex.ai/api/v1/video/batch/upload" \
      -H "X-API-KEY: $QORTEX_API_KEY" \
      -F "file=@urls.txt"
  3. 3.

    Check status until COMPLETED or ERROR

    shell
    curl "https://api.qortex.ai/api/v1/video/batch/BATCH_ID/status" \
      -H "X-API-KEY: $QORTEX_API_KEY"
  4. 4.

    Fetch results for each submitted URL

    shell
    # The URL must exactly match the submitted URL, path-encoded
    VIDEO_URL=$(python3 -c 'import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=""))' "https://example.com/watch/123")
    curl "https://api.qortex.ai/api/v1/video/$VIDEO_URL" \
      -H "X-API-KEY: $QORTEX_API_KEY"
02

Authentication

Every request must include your API key in the X-API-KEY header.

header
-H "X-API-KEY: $QORTEX_API_KEY"
A missing key returns 401; an invalid key returns 403. Keep keys out of source control and client-side code. Selecting a plan submits your key request automatically. Qortex prepares your key after prepaid payment or postpaid approval and delivers it securely off-platform; keys are never shown on this page.
03

Batch upload

Send a multipart request with a file field named file containing up to 500 URLs, one per line.

  • POST
    /api/v1/page/batch/upload

    Submit web page URLs. Qortex discovers and processes videos on those pages.

  • POST
    /api/v1/video/batch/upload

    Submit publicly accessible video URLs to process directly.

shell
curl -X POST "https://api.qortex.ai/api/v1/page/batch/upload" \
  -H "X-API-KEY: $QORTEX_API_KEY" \
  -F "file=@pages.txt"
A successful upload returns 201 with an id. An invalid upload, or more than 500 URLs, returns 400. A 429 means too many requests: wait before trying again.
04

Batch status

Poll a batch until its status is COMPLETED or ERROR, then stop.

  • GET
    /api/v1/{page|video}/batch/{id}/status

    Batch state plus success, in-progress and failure counts. Replace {page|video} with page or video.

  • GET
    /api/v1/{page|video}/batch/{id}/state

    Lighter response containing only the batch id and overall status.

  • GET
    /api/v1/page/batch/{id}/poll?cursor=…

    Page batches only. Returns per-URL completion updates. Pass the returned cursor on the next poll to read updates not yet read with that cursor; omit it on the first call.

shell
curl "https://api.qortex.ai/api/v1/page/batch/BATCH_ID/state" \
  -H "X-API-KEY: $QORTEX_API_KEY"
shell
# First poll: omit cursor.
# Next poll: add ?cursor=THE_RETURNED_CURSOR
curl "https://api.qortex.ai/api/v1/page/batch/BATCH_ID/poll" \
  -H "X-API-KEY: $QORTEX_API_KEY"
A COMPLETED batch can still contain URLs that could not be processed. Check the successful and failed counts in the status response rather than assuming every URL succeeded.

Batch states: NEW (created), SUBMITTED (queued), IN_PROGRESS (processing), COMPLETED (finished) and ERROR (failed and will not finish). Stop polling at either terminal state.

05

Fetch results

Request results per URL. The URL must exactly match what you submitted and must be path-encoded.

  • GET
    /api/v1/page/{pageUrl}

    Signals for one page URL.

  • GET
    /api/v1/video/{videoUrl}

    Signals for one video URL.

shell
curl "https://api.qortex.ai/api/v1/page/ENCODED_PAGE_URL" \
  -H "X-API-KEY: $QORTEX_API_KEY"
Page results
Expire 24 hours after the containing batch was created.
Video results
Do not expire.
A video lookup can return 202 with a full body while some signals are still PENDING. Do not treat that as final. A finished video lookup returns 200. Page lookups return 202 while processing or 204 if the page could not be retrieved.

Page results include url, iabCategorization and up to 500 entries in videos. Only finished videos with a transcript are included; videos with no speech and ads are left out. Page results require your account to have submitted the URL in a batch created within the last 24 hours.

Video results include url, lookup status and a video object. Its status can be COMPLETED, PARTIAL, PENDING or ERROR. Metadata includes the video URL, resolution and duration (hh:mm:ss.fffffff, with no fractional part for whole seconds). The features array contains the available signals. Signals are the same whether the video was submitted directly or discovered on a page.

IAB category fields

Page and transcript categories include uniqueId, version, parent, name, tier1 through tier4, their corresponding tier IDs and score. Unused tiers are empty strings and unused tier IDs are null. A higher score means a stronger category match.

06

Signals

Which signals you receive depends on your account access.

Page and transcript taxonomy
IAB Content 2.2
Advertiser categories
IAB 3.1
TRANSCRIPTION
Text transcript of the video audio.
SUMMARIZE
A concise summary of the content.
RISK_PROFILE
11 risk categories, each scored 0 to 5, plus an overall risk score from 0 to 100.
SUITABILITY
Brand suitability level (for example None, Medium or High), sensitive categories and explanation.
SEMANTIC_ANALYSIS
Key terms, term types and aliases.
SENTIMENT
Overall sentiment, emotional tone, excitement, controversy and per-entity sentiment.
STORYBOARD_ANALYSIS
Settings, scenes, objects, logos and on-screen text.
CONTENT_OVERVIEW
Content characteristics, including how scripted the video is on a 1 to 10 scale.
ADVERTISER_OPPORTUNITIES
Relevant IAB categories, product and service types, and aligned brands.
Metadata
Video duration and resolution.

Each feature has a type and status. Signal states are COMPLETED, PENDING, ERROR, SKIPPED and NOT_REQUESTED. A signal’s result is only included when its status is COMPLETED; transcription uses its own fields below. Paths are relative to a feature entry.

TRANSCRIPTION fields
transcript
Speech transcript. A video with no transcript has no TRANSCRIPTION entry.
iabCategorization
IAB 2.2 categories detected from the transcript.
iabStatus
Processing status of the transcript’s IAB categorization.
SUMMARIZE fields
result.summary
A short summary of the video’s content.
RISK_PROFILE fields
result.overallRiskScore
Overall risk score, from 0 to 100.
result.categories[].category
ADULT_CONTENT, VIOLENCE, HATE_SPEECH, DRUGS, WEAPONS, CRIME, PROFANITY, ALCOHOL_TOBACCO, GAMBLING, POLITICAL_EXTREMISM or NEGATIVE_NEWS.
result.categories[].score
Category risk score, from 0 to 5.
result.categories[].reasoning
Reason for the score; empty when the score is 0.
SUITABILITY fields
result.level
Brand suitability level, for example None, Medium or High.
result.categories
Array of sensitive content categories that apply.
result.explanation
Why the suitability level was assigned.
SEMANTIC_ANALYSIS fields
result.terms[].term
Key term from the video.
result.terms[].type
Kind of term, such as topic, person, organization, place, object, event, concept or theme.
result.terms[].aliases
Array of other names or phrases referring to the term.
SENTIMENT fields
result.overallSentiment
Overall sentiment, for example positive or mixed.
result.overallSentimentExplanation
Why the overall sentiment was assigned.
result.signals.sentiment
Short sentiment description.
result.signals.emotionalTone
Emotional tone of the video.
result.signals.excitementLevel
Excitement level: low, medium or high.
result.signals.controversy
How controversial the content is, for example low.
result.entities[]
Sentiment toward each person, organization, product or topic: name, type, sentiment, emotionalTone, excitementLevel and controversy.
STORYBOARD_ANALYSIS fields
result.analysis.overall_scene_and_setting
Settings and locations shown in the video.
result.analysis.overall_narrative_tone_feeling
What happens and the overall tone.
result.analysis.overall_genre
Genre, such as news or event coverage.
result.analysis.overall_content_type
Footage type, such as live_action or mixed_media.
result.analysis.overall_scenes
Comma-separated scenes.
result.analysis.overall_objects
Comma-separated people and objects seen on screen.
result.analysis.overall_logos
Comma-separated logos; unidentified logos include a short description.
result.analysis.overall_texts
Comma-separated on-screen text.
CONTENT_OVERVIEW fields
result.overall_theme
Main theme.
result.primary_subject
Main subject.
result.description
Short description.
result.inferred_title
Likely title.
result.inferred_genre
Likely genre.
result.inferred_origin_country
Likely country of origin.
result.inferred_year
Likely year of production (integer).
result.language
Language code, for example en.
result.content_type
Kind of content, such as a celebrity interview or advertisement.
result.scripted_score
Integer from 1 to 10; higher means more scripted.
result.tone
Tone of the video.
result.keywords
Array of descriptive keywords.
ADVERTISER_OPPORTUNITIES fields
result.iab_categories
Array of relevant IAB Content Taxonomy 3.1 category names. Page and transcript categories use IAB 2.2 instead.
result.advertising_opportunities
Array of product and service types suited to advertising alongside the video.
result.aligned_brands
Array of brands whose advertising would align with the video.
07

Status codes and errors

A 202 is not a final answer. Everything else tells you what to do next.

  • 200Results readyVideo processing has finished; inspect video and individual signal states.
  • 201Batch createdUpload succeeded. Save the returned id to check progress.
  • 202PendingAccepted but not final yet. Keep polling at a sensible interval.
  • 204No contentThe page could not be retrieved. Not retryable as-is.
  • 400Bad requestUpload invalid, or the file contains more than 500 URLs.
  • 401UnauthorizedThe X-API-KEY header is missing.
  • 403ForbiddenThe API key is invalid.
  • 404Not foundNo result for that URL, or a page result has expired.
  • 429Rate limitedToo many requests. Back off and retry later.