Two surfaces, one evidence model

Authentication

Three credential kinds reach the same API, scoped to the same tenant.

An API key is shown exactly once, when you create it. Only its prefix and a hash are stored, so a lost key is revoked and replaced, never recovered.

REST API quickstart

Seven curl calls from nothing to citable records. The first four use a cookie jar because account and compliance actions need an interactive owner; the rest use an API key.

1. Create an account

curl -X POST https://api.powerscraping.app/v1/auth/signup \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
        "email": "you@example.com",
        "password": "a-long-passphrase-you-chose",
        "organisation_name": "Acme Guides"
      }'

Passwords must be at least 12 characters. The response returns your tenant, user and plan, and sets the session cookie in cookies.txt.

2. Accept the acceptable-use terms

curl -X POST https://api.powerscraping.app/v1/legal/accept \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"document": "acceptable_use"}'

Omit version and the current published version is recorded. Read it first at https://api.powerscraping.app/v1/legal/acceptable-use.

This is the one endpoint that insists on a signed-in user: the cookie from step 1, or the button in the dashboard. An API key or an MCP token is refused with permission_denied, because accepting the terms is the customer's own act and nothing running unattended may perform it on their behalf.

3. Declare an authorized target

curl -X POST https://api.powerscraping.app/v1/targets \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{
        "platform": "instagram",
        "username": "trattoriadaoscar",
        "authorization_basis": "client_mandate",
        "authorization_reference": "MSA-2026-114, schedule 2"
      }'

4. Mint an API key

curl -X POST https://api.powerscraping.app/v1/keys \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"name": "ingest worker"}'

{
  "id": "key_7c1f…",
  "name": "ingest worker",
  "prefix": "psa_live_9Qd2",
  "active": true,
  "api_key": "psa_live_9Qd2………",
  "notice": "Copy this key now. It is shown once and cannot be retrieved again."
}

Export it for the calls below: export PSAPP_KEY=psa_live_9Qd2…. Store it in your secret manager, not in source control.

5. Submit a collection job

curl -X POST https://api.powerscraping.app/v1/jobs \
  -H "Authorization: Bearer $PSAPP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: oscar-2026-09-17" \
  -d '{
        "kind": "collect",
        "target_username": "trattoriadaoscar",
        "platform": "instagram",
        "params": {"max_posts": 50, "include_comments": true}
      }'

Job kinds: collect (bounded recent posts), complete_history (Agency only), enrich_only (re-enrich the last release) and export (repackage a release). Re-sending the same Idempotency-Key returns the original job instead of starting a second one.

6. Poll the job

curl https://api.powerscraping.app/v1/jobs/job_5f2a \
  -H "Authorization: Bearer $PSAPP_KEY"

{
  "id": "job_5f2a",
  "kind": "collect",
  "target_username": "trattoriadaoscar",
  "status": "succeeded",
  "posts_processed": 48,
  "records_written": 48,
  "release_id": "rel_2026_09_17_01",
  "is_terminal": true,
  "results_available": true
}

Statuses are pending, running, succeeded, failed and cancelled. A job that ends with error_code: "access_blocked" met a challenge and stopped — that is the engine behaving correctly, not a bug to retry around.

7. Read the records

curl "https://api.powerscraping.app/v1/jobs/job_5f2a/results?limit=10&offset=0" \
  -H "Authorization: Bearer $PSAPP_KEY"

Errors

Every failure you can act on has the same shape and a stable machine-readable code.

{
  "error": {
    "code": "collection_not_authorized",
    "message": "No active authorized target for 'trattoriadaoscar' on instagram.",
    "detail": {"platform": "instagram", "username": "trattoriadaoscar"}
  }
}

Endpoint reference

The full generated specification lives at https://api.powerscraping.app/api/openapi.json, with interactive docs at https://api.powerscraping.app/api/docs.