NetShort API — Free Actor, Your Ezvid API Key

Run NetShort content requests as an Apify Actor and export results to a dataset. Version 1.0.0 uses a bundled OpenAPI snapshot from 2026-10-10 covering the NetShort provider and 8 GET endpoints. Each run selects an action or resource on NetShort.

Register with Ezvid and use your own API key. The intended Store model is a free Actor with no developer fee, configured as pay per usage in Apify Console. Apify compute/storage/network usage and Ezvid API access/quota are separate and depend on your accounts. The code contains no custom charging calls. Deploying it does not change an existing Actor's pricing; follow DEPLOY.md.

Get started

1. Register with Ezvid and obtain your own API key. Start with the Ezvid API documentation for API access information. If key issuance is not available there, request access from Ezvid's operator. This Actor does not create Ezvid accounts or issue keys.
2. Enter that key in the required Your registered Ezvid API key input field.
3. Choose an action or resource on NetShort, then run the Actor.

Start with a small languages request to verify your key:

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "provider": "netshort",
  "action": "languages"
}

Replace the placeholder with your key in the Apify input form. Open the run's Results output for dataset records and Run summary for the OUTPUT record. Use home, trending, or search to discover content IDs before requesting detail, episodes, or playback sources.

The apiKey field uses Apify's encrypted secret input. Every API request sends it only in X-API-Key. Missing/blank keys fail before any HTTP request; Ezvid validates the supplied key and its permissions. There is no embedded key and no EZVID_API_KEY environment fallback. Authentication errors do not include upstream bodies or keys in logs. Local INPUT files contain plaintext secrets: keep them in the ignored storage/ directory.

Supported resources

See RESOURCES.md for the complete generated reference, including all required path arguments and native query parameters.

Coverage includes languages, home, trending, search, detail, episode listings and the episode source endpoint exposed by NetShort. The service routes /, /health, /openapi.json are not content resources.

Use provider: "netshort" with the exact resource template below. Supply the exact relative path template, such as detail/{id} or episodes/{id}/{episodeId}/source, and named arguments in pathParams. A full /api/netshort/... template is also accepted, provided it matches provider. Arbitrary URLs are not accepted.

For convenience, action supports exact resource names and these familiar aliases:

• home: home
• detail / episodes: detail/{id} and episodes/{id} (path-based, not query).
• languages / langs: resolves to the documented langs endpoint.
• source: resolves to the unique episodes/{id}/{episodeId}/source route.
• trending: trending
• loadmore: loadmore (cursor-only continuation for opaque NetShort cursors).

Unsupported or ambiguous actions fail with a request to select an exact resource.

Input

Field	Purpose
apiKey	Required, your own registered Ezvid key; no default/shared key.
provider	Required, must be netshort; this Actor targets NetShort only.
action	Convenience action; defaults to home.
resource	Exact resource template; overrides action.
pathParams	Object containing native path arguments; overrides id/ep.
queryParams	Object containing native query arguments; overrides shortcuts. Unknown keys fail validation.
id	Shortcut for the first path parameter (e.g. NetShort detail/{id}).
ep	Shortcut for the episodeId path parameter on the source route. May be an opaque ID.
query	Search text, mapped to the documented q parameter on NetShort.
language	Sent to the documented language parameter; omit for upstream default.
category	Sent when the endpoint documents category.
limit	1–100, default 20; sent only if documented and may be capped upstream.
page	NetShort resources do not document page/p; supply cursor instead.
cursor	Starting opaque cursor for NetShort's cursor-based resources.
maxPages	1–50, default 1; maximum page fetches for a paginated resource. Retries are additional HTTP attempts.
pagination	auto (default), none, cursor, or page. NetShort only documents cursor.
outputMode	records (default) or response.

Optional shortcuts are sent only where supported. Use queryParams for strict parameter checking and provider-specific options such as cursor.

Search NetShort

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "provider": "netshort",
  "action": "search",
  "query": "love",
  "language": "en"
}

Fetch NetShort episodes

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "provider": "netshort",
  "action": "episodes",
  "id": "YOUR_NETSHORT_ID"
}

Browse NetShort trending starting at a known cursor

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "provider": "netshort",
  "resource": "trending",
  "language": "en",
  "cursor": "OPAQUE_CURSOR_FROM_PREVIOUS_RESPONSE",
  "maxPages": 3
}

Get an episode source from NetShort

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "provider": "netshort",
  "resource": "episodes/{id}/{episodeId}/source",
  "pathParams": { "id": "YOUR_NETSHORT_ID", "episodeId": "YOUR_EPISODE_ID" },
  "outputMode": "response"
}

NetShort trending with native language override

{
  "apiKey": "YOUR_REGISTERED_EZVID_KEY",
  "provider": "netshort",
  "action": "trending",
  "language": "id",
  "maxPages": 3
}

Pagination and output

Auto pagination uses an explicitly supplied cursor, otherwise the endpoint's cursor query parameter. NetShort resources do not document page or p; page/p modes therefore reject before any HTTP request. The Actor stops on empty results, end markers, repeated pages/tokens, missing next cursor, or maxPages. It does not invent cursor values or silently switch to another resource. Dedicated loadmore resources can be selected explicitly.

The default dataset contains records with _meta (provider, resource, page, url, fetchedAt). Records mode unwraps common data/result/payload envelopes and list arrays. Entity/detail objects retain nested episodes; primitive values are wrapped in { "value": ... }.

Home responses containing several collections (for example shelves, tabs, featured titles and rankings) remain a single object so none of those sections are discarded. A dataset record is not necessarily one movie.

Provider fields are preserved rather than normalized to a universal movie schema. Ezvid's OpenAPI does not describe response field schemas. For an unfamiliar resource or to preserve all envelope metadata, use outputMode: "response", which stores { "response": <complete JSON>, "_meta": ... } for each nonempty page.

The OUTPUT key-value record contains provider, resource, pagination, outputMode, pagesFetched, recordsPushed, maxPages, stopReason, timestamps, and continuation values (nextCursor/nextPage when maxPages is reached). pagesFetched counts parsed responses, including a final empty or repeated page; it does not count retry attempts. A numeric next page is a candidate if the upstream did not supply an explicit next-page marker. Pass nextCursor as input cursor to continue with the same resource and filters. A later failure fails the run; previously written dataset records remain, but a success summary is not written.

Requests time out after 60 seconds. Network errors, HTTP 429 and 5xx get up to three retries, with backoff and Retry-After handling capped at 60 seconds. 401/403 and other client errors fail immediately. The Actor returns metadata and playback URLs; it does not download or stream video. Playback URLs may expire.

Verification and provider availability

On 2026-10-10, all 32 automated tests passed on Node.js 22 and the Apify input schema passed CLI validation. Tests cover request construction for all 8 endpoints, authentication requirements, parsing, pagination, retries and the Apify SDK lifecycle with mocked HTTP responses.

Live checks using a registered key covered the NetShort home request and returned HTTP 200 with parsed records. Other NetShort resources were verified through the request-construction contract, not via live calls. These counts describe the test run, not a permanent availability guarantee. All 8 endpoints were checked against the contract, but not all were called live.

See LIVE_CHECKS.md for NetShort-specific findings. An unavailable home resource does not necessarily mean every resource is down. Ezvid can wrap provider errors as HTTP 400; the Actor reports those separately from ordinary request validation errors.

Development

Use Node.js 22+ and, for apify run/deployment, the Apify CLI.

npm ci
npm test
npm run validate:input

Create the local input directory:

$mkdir -p storage/key_value_stores/default

Save one of the input examples above as storage/key_value_stores/default/INPUT.json, replacing the key placeholder locally. Then run npm start (Apify SDK storage) or npm run start:local (Apify CLI). The storage/ directory is ignored by Git.

Local results are written to storage/datasets/default/; the summary is at storage/key_value_stores/default/OUTPUT.json. These paths assume the default local storage configuration. Back up results before starting another local run, because the SDK purges default storage on startup while preserving input.

Command	Purpose
npm start	Run src/main.js through the Apify SDK.
npm run start:local	Run through the installed Apify CLI.
npm test	Run automated tests; no real Ezvid key or API requests required.
npm run validate:input	Validate the input schema using the installed CLI.
npm run generate	Regenerate the resource reference from the bundled snapshot.
npm run sync:resources	Download the public OpenAPI snapshot and regenerate the reference.
npm run deploy	Deploy with apify push; requires Apify login.

npm run sync:resources   # download the public contract, refresh schema/reference
npm test
npm run validate:input

Resource changes are reviewed at build time; each Actor run uses the checked-in snapshot. Updating the snapshot does not prove NetShort is available: end-to-end verification requires a valid key with access to those resources.

See DEPLOY.md to publish a free/pay-per-usage Actor.

License

MIT.