Create a destination API reference

Credentials are encrypted at rest by the service and are never returned. For gcs, the HMAC key is used through GCS's S3-compatibility endpoint.

Request

POSThttps://api.scrapercompany.com/v1/async/destinations

Authenticate with your API key in the x-api-key header (see Authentication).

Body

JSON object. Unknown fields are rejected with 422.

namestringrequiredmin length 1, max length 80
Display name, unique per account.
kindstringdefault s3
s3 for AWS/R2/B2/MinIO and any S3-compatible store; gcs for a Google Cloud Storage HMAC key (its S3-compatibility endpoint).
One ofs3gcs
bucketstringrequiredmin length 3, max length 63
Bucket name. It must already exist and the credentials must be allowed to write to it.
prefixstring | nullmax length 200
Optional key prefix inside the bucket, for example scrapercompany. A job writes <prefix>/async-jobs/<date>/<job_id>/manifest.json and one gzipped object per item under items/.
regionstring | nullmax length 40
S3 region (ignored for GCS, which uses auto).
endpointstring | nullmax length 300
Optional custom S3 endpoint (R2, B2, MinIO). It must be public HTTPS: the hostname is resolved when the destination is saved and again on every upload, and private, loopback, link-local, CGNAT and cloud-metadata addresses are rejected, including after a redirect. GCS always uses https://storage.googleapis.com.
path_stylebooleandefault false
Use path-style addressing, needed by some S3-compatible stores (MinIO, B2). GCS always uses virtual-host style.
formatstringdefault json
How each item object is encoded. json and jsonl are one gzipped JSON document per item; csv is one gzipped row. manifest.json lists the object keys.
One ofjsonjsonlcsv
access_key_idstringrequiredmin length 1, max length 256
S3 access key id, or a GCS HMAC key id.
secret_access_keystringrequiredmin length 1, max length 512
S3 secret access key, or a GCS HMAC secret. Stored encrypted and never returned.

Example request

curl -X POST "https://api.scrapercompany.com/v1/async/destinations" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key_id": "AKIAEXAMPLE123456",
    "bucket": "acme-rate-archive",
    "format": "jsonl",
    "kind": "s3",
    "name": "nightly-comp-set",
    "prefix": "scrapercompany",
    "region": "us-east-1",
    "secret_access_key": "replace-with-the-secret"
  }'

Response

201 — Saved destination; the secret is never returned.

201 response

{
  "id": "asyncdst_0123456789abcdef0123456789abcdef",
  "name": "nightly-comp-set",
  "kind": "s3",
  "bucket": "acme-rate-archive",
  "prefix": "scrapercompany",
  "region": "us-east-1",
  "endpoint": "https://s3.us-east-1.amazonaws.com",
  "path_style": false,
  "format": "jsonl",
  "access_key_id": "...3456",
  "secret_configured": true,
  "created_at": "2026-10-22T09:00:00Z",
  "updated_at": "2026-10-22T09:00:00Z"
}

Errors

Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.

Status	Meaning	Retry?
`401`Unauthorized	Missing or invalid API key. `{"detail":"missing or invalid API key"}`	No, fix the request
`409`Conflict	The Idempotency-Key was already used for a different request body. `{"detail":"Idempotency-Key was already used for a different request"}`	No, fix the request
`422`Unprocessable Content	Request validation failed. `detail` is a list of problems for schema errors, or a string for semantic checks performed by the endpoint. `{"detail":[{"loc":["body","name"],"msg":"Field required","type":"missing"}]}`	No, fix the request
`429`Too Many Requests	Too many requests: the key's requests-per-minute limit was exceeded, or (in `enforce` credits mode) the plan's concurrent-request limit. No rate-limit or Retry-After headers are sent; back off and retry. `{"detail":"rate limit 60/min exceeded"}`	Yes, with backoff
`503`Service Unavailable	Temporarily unavailable: a dependency of this endpoint is down, or the upstream source changed its contract. Retry later. `{"detail":"database unavailable: OperationalError"}`	Yes, with backoff

Try it

Async jobs, destinations, schedules and the callback secret are not changed from the docs; call this with your own key.

Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? start a free trial).
Copy the cURL example above and run it in a terminal.

Request#

Body#

Example request#

Response#

Errors#

Try it#