Bytewells Cloud provides a REST API compatible with the Apify API v2, plus marketplace endpoints for the Store, rentals, credits and publishing (see Marketplace).

Base URLCopy Anchor Link

https://bytewells.com/api/v2

AuthenticationCopy Anchor Link

All requests require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://bytewells.com/api/v2/datasets

All resource endpoints are user-scoped — authenticated users can only access their own resources.

Three token kinds are accepted:

• cp_-prefixed API keys (created via the endpoints below, shown in full only once at creation).
• JWTs returned by /v2/auth/login and /v2/auth/register.
• Run-scoped tokens (rt_<runId>.<signature>) that the runner injects into each Actor container as APIFY_TOKEN. They act as the run's owner only while the run is active (plus a 10-minute grace period) and only on the storage and run endpoints an Actor needs; every other endpoint returns 403.

As an alternative to the Bearer header, a ?token= query parameter is accepted on any authenticated route — useful for browser download links that can't set custom headers.

Registration is open when PUBLIC_REGISTRATION=true (the default). Every new user gets a personal organization that holds billing, credits and published listings. The first admin user is created on startup from the ADMIN_EMAIL / ADMIN_PASSWORD environment variables.

DatasetsCopy Anchor Link

Store and retrieve scraped data.

Push ItemsCopy Anchor Link

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"title": "Item 1"}, {"title": "Item 2"}]' \
  https://bytewells.com/api/v2/datasets/{id}/items

Retrieve ItemsCopy Anchor Link

Supports pagination with offset and limit query parameters (max limit: 1000).

curl -H "Authorization: Bearer $TOKEN" \
  "https://bytewells.com/api/v2/datasets/{id}/items?offset=0&limit=100"

Omitting limit returns the entire dataset (matching real Apify), streamed as plain JSON with Apify-style pagination headers — no in-memory materialization on the server, and offset is still honored. Passing an explicit limit uses the paged path. Before v1.6.0 the no-limit case silently defaulted to 100 items; Apify-compatible clients fetching without a limit were truncated.

Pass ?download=1 to stream the entire dataset as a single JSON array file (attachment disposition) — same zero-materialization path.

Key-Value StoresCopy Anchor Link

Store arbitrary data by key.

Common KeysCopy Anchor Link

• INPUT — Actor input configuration
• OUTPUT — Actor output/results

Presigned Record URLsCopy Anchor Link

GET .../records/:key?presigned=1 returns a presigned S3 URL valid for 1 hour instead of the record body — useful for large or binary values (screenshots, big JSON) the browser should fetch directly from object storage.

Request QueuesCopy Anchor Link

Manage URLs to crawl with automatic deduplication.

DeduplicationCopy Anchor Link

Requests are deduplicated by uniqueKey. Adding a request with an existing uniqueKey is a no-op.

LockingCopy Anchor Link

The lock endpoint (POST .../head/lock) supports distributed crawling. Parameters:

• lockSecs — Lock duration in seconds (max 86400)
• limit — Number of requests to fetch (max 1000)
• clientKey — Unique identifier for the crawling client

ActorsCopy Anchor Link

Manage Actor definitions.

Wherever :id identifies an Actor, you can pass its id, the name of one of your own Actors, or username~actor-name (Apify style) for a Store Actor.

GET /v2/acts/:id also returns inputSchema, readme, username and, when the Actor is listed in the Store, a listing summary. Users entitled to run an Actor they don't own get a read-only view.

Entitlement and billingCopy Anchor Link

Starting a run (POST /v2/acts/:id/runs, run-sync, reruns and schedules) checks, in order:

1. Entitlement. You own the Actor, or its listing is free, or your organization has a live rental (TRIALING/ACTIVE) or an unexpired time-window pass. On run-start paths only (not run-scoped tokens), if pass auto-purchase is enabled a fare-capped pass may be bought from prepaid credits. Otherwise 402 with error type rental-required, data.listingSlug, and when the Actor sells passes a machine-readable data.passes offer.
2. Credits. Non-owner runs (and any run by a non-admin) need a positive prepaid credit balance, else 402 insufficient-credits.

Request and response shapes of these endpoints are unchanged from Apify's.

Runs are billed at COMPUTE_PRICE_PER_CU_USD (default $0.15) per compute unit: 1 CU = 1 GB of memory for 1 hour, billed per second with a 60-second minimum.

Deleting ActorsCopy Anchor Link

DELETE /v2/acts/:id refuses to delete an Actor that has runs, returning 409 with error type actor-has-runs. Pass ?force=true to cascade-delete the Actor together with its run history (and the runs' webhook deliveries). Force delete still returns 409 (actor-has-active-runs) while any run is READY, RUNNING, or ABORTING — abort those first.

Input ValidationCopy Anchor Link

Actor create/update bodies are validated with the following constraints:

• name — 1-100 chars, alphanumeric with dots, dashes, underscores
• title — Max 200 chars
• description — Max 5000 chars
• defaultRunOptions.timeoutSecs — Max 86400 seconds (24h)
• defaultRunOptions.memoryMbytes — Max 16384 MB (16 GB)
• maxRetries — 0-10
• retryDelaySecs — 1-3600 seconds
• version — 1-64 chars, alphanumeric with . _ + -

The run-dispatch body (POST /v2/acts/:id/runs) uses bare timeout and memory fields instead, with the same 86400-second and 16384-MB caps.

Actor Versions & BuildsCopy Anchor Link

Manage source versions and Docker image builds for an Actor.

Hosted builds from sourceCopy Anchor Link

POST /v2/acts/:id/builds/source?version=0.0&tag=latest with body application/gzip (a tar.gz of the Actor directory) uploads the source and queues a build on the builder. It returns { data: Build }; poll the build or read its logs until it finishes. Builds fill the Actor's inputSchema, readme and actor.json from .actor/input_schema.json, README.md and .actor/actor.json. bw push uses this endpoint.

Images are named bytewells/<username>/<actor-name> with tags latest and b-<buildId>, prefixed by the image registry in production.

RunsCopy Anchor Link

Monitor Actor executions.

Platform extensions (not part of the Apify v2 surface)Copy Anchor Link

These endpoints power the dashboard and are safe to use from custom tooling, but don't expect them from apify-client or the Apify platform:

Run Status ValuesCopy Anchor Link

Run response shape (v1.0-committed)Copy Anchor Link

Every endpoint that returns a run (LIST, GET-by-id, PUT, abort, resurrect, rerun) emits the same shape. Notable fields:

Note on webhooks: the webhook payload's resource.stats is built by the runner from the ingested Crawlee statistics blob and does NOT currently mirror stats.datasetItemCount — webhook receivers that need the dataset count should query /v2/actor-runs/:id from the resource.id they receive. This is tracked for parity in v1.0.1.

WebhooksCopy Anchor Link

Receive HTTP callbacks when runs reach a terminal state. Webhooks can be standalone (catalog) or attached to a single run via the webhooks field on run dispatch.

Supported event types are the four terminal run events:

• ACTOR.RUN.SUCCEEDED
• ACTOR.RUN.FAILED
• ACTOR.RUN.TIMED_OUT
• ACTOR.RUN.ABORTED

Subscriptions to other Apify event types (e.g. ACTOR.RUN.CREATED) are rejected with a 400.

SchedulesCopy Anchor Link

Run Actors automatically on a cron schedule.

UsersCopy Anchor Link

GET /v2/users/me uses optional authentication: unauthenticated callers receive an anonymous stub instead of a 401. The Apify SDK calls this endpoint to resolve the proxy password (data.proxy.password) when APIFY_PROXY_PASSWORD is not set in the container environment.

System & OperationsCopy Anchor Link

The /health* and /metrics endpoints are served at the root, outside the /v2 prefix.

MarketplaceCopy Anchor Link

Bytewells extensions for the Store, rentals, credits and publishing. They are not part of the Apify API.

Money model: compute is prepaid credits kept by Bytewells; passes are one-off debit of those credits with earnings paid to the developer monthly; rentals are Stripe subscription Checkout (programmatic Product+Price) charged on the platform account, with earnings paid to the developer monthly. See Billing and Passes.

Store (public, no auth)Copy Anchor Link

RentingCopy Anchor Link

Paid rentals use Stripe Checkout mode=subscription with the listing's Product/Price. Trials use the listing's trialDays (0–30). Body must include consentToShareContact: true.

One trial per (listing, renter org), ever. Publisher must be payable (409 publisher-not-payable).

PassesCopy Anchor Link

Passes debit prepaid credits (not Checkout). No card confirmation.

402 insufficient-credits if the balance cannot cover the charge; 409 publisher-not-payable if the developer has been unable to receive payouts for over 90 days (or is in an unsupported payout country).

Organization and creditsCopy Anchor Link

Credits pay for compute and for pass purchases. The sign-up credit expires after 90 days.

PublishingCopy Anchor Link

Commission on a new rental or pass: 0% if the renter signed up with your referral link, otherwise 10%. Stripe’s card processing and billing fees are deducted from the developer’s earning at cost; Bytewells pays the fixed Connect fees. Earnings are held 14 days, then paid in one monthly transfer once the payable balance reaches $50 (converted to the platform settlement currency, e.g. EUR, at a rate locked on the payout).

Stripe webhook and adminCopy Anchor Link