apify

# Apify

Run any of the 17,000+ Actors on [Apify Store](https://apify.com/store) and retrieve structured results via the REST API.

Full OpenAPI spec: [openapi.json](openapi.json)

## Authentication

All requests need the `APIFY_TOKEN` env var. Use it as a Bearer token:

```bash
-H "Authorization: Bearer $APIFY_TOKEN"
```

Base URL: `https://api.apify.com`

## Core workflow

### 1. Find the right Actor

Search the Apify Store by keyword:

```bash
curl -s "https://api.apify.com/v2/store?search=web+scraper&limit=5" \
  -H "Authorization: Bearer $APIFY_TOKEN" | jq '.data.items[] | {name: (.username + "/" + .name), title, description}'
```

Actors are identified by `username~name` (tilde) in API paths, e.g. `apify~web-scraper`.

### 2. Get Actor README and input schema

Before running an Actor, fetch its default build to get the README (usage docs) and input schema (expected JSON fields):

```bash
curl -s "https://api.apify.com/v2/acts/apify~web-scraper/builds/default" \
  -H "Authorization: Bearer $APIFY_TOKEN" | jq '.data | {readme, inputSchema}'
```

`inputSchema` is a JSON-stringified object — parse it to see required/optional fields, types, defaults, and descriptions. Use this to construct valid input for the run.

You can also get the Actor's per-build OpenAPI spec (no auth required):

```bash
curl -s "https://api.apify.com/v2/acts/apify~web-scraper/builds/default/openapi.json"
```

### 3. Run an Actor (async — recommended for most cases)

Start the Actor and get the run object back immediately:

```bash
curl -s -X POST "https://api.apify.com/v2/acts/apify~web-scraper/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startUrls":[{"url":"https://example.com"}],"maxPagesPerCrawl":10}'
```

Response includes `data.id` (run ID), `data.defaultDatasetId`, `data.status`.

Optional query params: `?timeout=300&memory=4096&maxItems=100&waitForFinish=60`

- `waitForFinish` (0-60): seconds the API waits before returning. Usefu...