# AdsCrawl Agent Quickstart

Inspect this codebase, obtain an API key through https://api.adscrawl.net/auth.md if needed,
and integrate the requested AdsCrawl capability using the project's existing stack.

## Configuration

- `ADSCRAWL_API_KEY`: secret, server-side only.
- `ADSCRAWL_API_URL`: `https://api.adscrawl.net` for this deployment.
- Read the API reference at https://app.adscrawl.net/dashboard/docs for current request
  fields and response shapes before choosing an operation.

Use an existing HTTP client or the language's standard client. No AdsCrawl SDK,
CLI, or MCP package is required for HTTPS integration. Do not invent package names
or install a package merely because a similarly named one exists.

## Choose the operation

| Need | Endpoint | Authentication |
| --- | --- | --- |
| Rendered HTML or Markdown | `POST /html` | `x-api-key` |
| Screenshot | `POST /screenshot` | `x-api-key` |
| Template extraction | `POST /spa-extract` | `x-api-key` |
| Interactive remote browser | `POST /cdp/sessions` | `x-api-key` |
| Close an interactive session | `DELETE /cdp/sessions/{sessionId}` | `x-api-key` |

For a simple content integration, send one request:

```bash
curl --fail-with-body --max-time 90 "$ADSCRAWL_API_URL/html" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $ADSCRAWL_API_KEY" \
  -d '{"url":"https://example.com","contentMode":"markdown","timeoutMs":60000}'
```

Load credentials in the process environment first. Avoid printing the expanded
command, use the project's secret handling conventions, and redact request headers
in debug/error logs. The legacy `/html` endpoint returns the requested content as
text; read Markdown with the client's text reader rather than assuming JSON.

## Implement in the codebase

1. Find the server-side entry point and configuration conventions. A browser-only
   project needs a server-side boundary before it can safely call AdsCrawl.
2. Reuse existing credentials. Otherwise finish the browser authorization flow
   before making authenticated requests.
3. Add a focused integration module with bounded timeouts, explicit credential
   validation, and useful errors for 401, 402, 429, 5xx, empty results and invalid
   responses. Avoid blind retries that can duplicate paid work.
4. Connect the module to the actual feature or entry point requested by the user.
   Keep unrelated configuration and code intact.
5. For CDP, use the documented returned connection URL with Playwright or
   Puppeteer, and close the remote session in a `finally` block. Do not log URLs
   containing tokens or API keys.
6. Update example environment configuration with placeholders, add a short run
   command, and follow the repository's existing test conventions.

## Verify

Run focused local checks for success, missing credentials, empty data and service
errors. When a live check is authorized, make one small request and verify the
HTTP status and result shape without exposing credentials. Live requests consume
account credits. Do not start bulk crawls, purchases, or recurring jobs merely to
verify setup. Always release test browser sessions.

Finish with the changed files, how to run the integration, checks performed, and
whether a live request succeeded. If browser authorization or live access is still
pending, report that clearly and do not claim the integration is live-verified.