---
name: sila-onboarding
description: Set up Sila, the scrape and crawl API that returns web pages as clean markdown. Install the MCP server or CLI, log in to get an API key, then choose live tools, app integration, or plain REST. Use when the user wants to scrape or crawl a website with Sila and has no credentials yet.
---

# Sila onboarding

Sila fetches a web page, or crawls a whole site, and returns clean markdown plus page signals (title, description, language, category, JSON-LD, forms, detected integrations). It renders JavaScript and WAF-protected pages in a headless browser when a static fetch is not enough.

- API base URL: `https://api.sila.sh`. Every endpoint is under `/v1`.
- Auth: `Authorization: Bearer sila_…`. A key is `sila_` plus 48 lowercase hex characters.
- Credits: 1 per page fetched statically, 5 per page that needed the headless browser or any request with the `screenshot` format. Free plan: 500 credits a month, no card needed.
- There is no keyless tier. Every request needs an API key or an OAuth sign-in. A `401 unauthorized` always means: get credentials (step 2).

## 1. Install

Pick the route that fits your environment. You can use both.

### MCP server (preferred when your client supports MCP)

The hosted server is `https://api.sila.sh/mcp`. It accepts OAuth (your client opens a browser to sign in) or a Bearer API key.

Claude Code:

```bash
claude mcp add --transport http sila https://api.sila.sh/mcp
```

Other clients, JSON config:

```json
{ "mcpServers": { "sila": { "url": "https://api.sila.sh/mcp" } } }
```

To use an API key instead of OAuth, send the header `Authorization: Bearer sila_…`.

Tools: `sila_scrape`, `sila_crawl`, `sila_crawl_status`, `sila_crawl_pages`, `sila_crawl_cancel`, `sila_usage`.

### CLI

```bash
npx -y @sila-sh/cli@latest init --all --browser
```

`init` logs in (unless a saved key already works), installs the Sila skills for your agents, and prints the MCP setup lines. Useful flags: `--skip-auth`, `--skip-skills`, `--agent <name>` (repeatable). Or install it globally with `npm install -g @sila-sh/cli` and run `sila`.

## 2. Get credentials

Use the first of these that applies.

1. **The user already has a key.** Use `SILA_API_KEY` from the environment, or the key the user gives you. Check it:

   ```bash
   curl -s https://api.sila.sh/v1/usage -H "Authorization: Bearer $SILA_API_KEY"
   ```

   A `200` with `remainingCredits` means it works.

2. **CLI login (recommended).** Run `sila login --browser`. It opens a browser page where the user approves; the CLI saves the key to `~/.config/sila/config.json` (or `$XDG_CONFIG_HOME/sila/config.json`). Check with `sila status`.

3. **Browser login without the CLI (PKCE).** Use this when you can run shell commands but have no CLI.

   ```bash
   SESSION=$(openssl rand -hex 32)
   VERIFIER=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n')
   CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
   echo "Open: https://sila.sh/app/cli-auth?session=$SESSION&challenge=$CHALLENGE&name=agent"
   ```

   - `session` is 64 hex characters. `challenge` is the 43-character base64url SHA-256 of `VERIFIER`. `name` (1–60 characters) is shown to the user on the approval page.
   - Give the user the URL and ask them to open it, sign in or sign up, and click **Authorize**. The link expires after 10 minutes.
   - Poll every 3 seconds:

     ```bash
     curl -s https://sila.sh/api/cli-auth/status \
       -H 'content-type: application/json' \
       -d "{\"session\":\"$SESSION\",\"verifier\":\"$VERIFIER\"}"
     ```

     The response is `{"status":"pending"}`, then `{"status":"complete","apiKey":"sila_…"}`, or `{"status":"expired"}`. The key is returned once. Save it as `SILA_API_KEY` and never print it back to the user.

4. **Manual key.** Tell the user to sign up or sign in at `https://sila.sh/login`, open **API keys** in the dashboard, create a key, and paste it.

## 3. Choose your path

### A. Live tools: the agent scrapes while working

Use the MCP tools, or the CLI.

| Goal | MCP tool | CLI |
|---|---|---|
| Read one page as markdown | `sila_scrape` | `sila scrape <url>` |
| Crawl a site | `sila_crawl`, then `sila_crawl_status` and `sila_crawl_pages` | `sila crawl <url> --wait -o <dir>` |
| Stop a crawl | `sila_crawl_cancel` | `sila crawl cancel <id>` |
| Check credits | `sila_usage` | `sila status` |

For detailed command usage, install the `sila` skill:

```bash
npx -y skills@latest add https://sila.sh -g -y
```

### B. Integrate Sila into application code

Build scrape and crawl calls into the user's app against the REST API (base `https://api.sila.sh`, Bearer `sila_…`).

- `POST /v1/scrape` returns markdown and signals for one URL.
- `POST /v1/crawls` starts an asynchronous crawl. Read results with `GET /v1/crawls/{id}` (status, stats), `GET /v1/crawls/{id}/pages?cursor=0` (stored pages, cursor paged) and `GET /v1/crawls/{id}/errors`. `POST /v1/crawls/{id}/cancel` stops it.
- `GET /v1/usage` returns plan, credits used and `remainingCredits`.
- Crawl webhooks are signed with `Sila-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>` over `<t>.<raw body>` with the workspace signing secret (`whsec_…`, on the **Webhooks** page). Verify against the raw body and reject requests older than 300 seconds.
- Errors use `{"error":{"code","message"}}`.

Install the `sila-build` skill for patterns, signature verification code and error handling:

```bash
npx -y skills@latest add https://sila.sh -g -y
```

### C. REST without installing anything

```bash
curl -X POST https://api.sila.sh/v1/scrape \
  -H "Authorization: Bearer $SILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","formats":["markdown"]}'
```

Response fields: `url`, `finalUrl`, `statusCode`, `renderedViaHeadless`, `creditsUsed`, and one key per requested format (`markdown`, `html`, `signals`, `siteInfo`, `screenshot`).

## Error handling

| Status | Code | What to do |
|---|---|---|
| 401 | `unauthorized` | The key is missing, wrong or revoked. Go back to step 2. |
| 402 | `credits_exhausted` | No credits left this month. Credits reset on the first of the UTC month. Tell the user to upgrade at `https://sila.sh/pricing`. |
| 429 | `rate_limited` / `concurrency_limit` | Wait a few seconds and retry; for crawls, wait for a running crawl to finish. |
| 400 | `invalid_url` / `invalid_request` | Fix the input. |
| 422 | `target_http_error` | The page itself returned a non-2xx status (`targetStatus`). |

## More

- Docs: `https://docs.sila.sh` (LLM-friendly index: `https://sila.sh/llms.txt`).
- Marketing pages are also served as markdown: send `Accept: text/markdown` or add `.md` (for example `https://sila.sh/pricing.md`).
- Support: support@sila.sh