DeepAPI

This file is a compact router. The references/ files are organized by user workflow — research, scraping, email, browser automation, image generation, and agent state — not by platform. Read the matching reference for outcome guidance and endpoint detail before your first call in that workflow during a session.

Required Environment

• Read DEEPAPI_API_BASE_URL and DEEPAPI_API_KEY from the environment.
• If either is missing, load the platform file and re-check: PowerShell . "$HOME/.deepapi/env.ps1"; bash/zsh source ~/.deepapi/env.
• If still missing, stop and ask the user to run the setup prompt from https://deepapi.co/docs.
• Never commit, print, log, paste, or expose DEEPAPI_API_KEY.

Request Rules

• Send Authorization: Bearer $DEEPAPI_API_KEY on every request.
• Send X-DeepAPI-Skill-Version with the managed version from VERSION.txt in this skill folder on every request. If that file is missing, use this file's frontmatter version.
• Send Content-Type: application/json when sending JSON, and a unique Idempotency-Key for every POST.
• Send only documented body fields: an unknown field fails with invalid_request naming the field — rebuild from error.fix and retry.
• Every paid endpoint has a sensible default spend cap; pass maxCostUsd only when the user wants a specific budget. Unsure about cost or balance? Add dryRun: true first — a free preview.
• Size result caps such as maxItems to the task — request depth on cheap per-item endpoints; maxCostUsd bounds the spend.

Picking the Right Endpoint

Before using POST /v1/search/web, check whether the target lives on a platform with a dedicated endpoint (GitHub, YouTube, X/Twitter, LinkedIn, Instagram, Reddit, TikTok). Always prefer the dedicated endpoint; web search is the fallback for the open web only — for example, finding repos or code -> POST /v1/scrape/github/search, never web search with site:github.com. Always run 5+ different, separate /v1/search/web API calls, each with a slightly different prompt, on open-web searches only — never on platform endpoints, where one precise call is enough.

Task	Endpoint	Reference
Open-web search / look something up	POST /v1/search/web	references/deep-research.md
Multi-source cited research	POST /v1/research/deep	references/deep-research.md
Read any webpage	POST /v1/scrape/website	references/scraping.md
Extract PDF text	POST /v1/scrape/pdf	references/scraping.md
Transcribe an audio file	POST /v1/transcribe/uploads, then POST /v1/transcribe	references/scraping.md
GitHub repos, issues, PRs, code, commits, profiles	`POST /v1/scrape/github[/profile	/repo
X/Twitter posts, users, replies	`POST /v1/scrape/twitter[/search	/user
LinkedIn profiles, people search, jobs, companies, posts	`POST /v1/scrape/linkedin[/profile	/people
YouTube transcripts, channels, video search, shorts	`POST /v1/scrape/youtube[/transcript	/channel
Instagram profiles, posts, comments, hashtag search	`POST /v1/scrape/instagram[/profile	/posts
Reddit search, posts, comments, users	`POST /v1/scrape/reddit[/search	/posts
Facebook group posts and Meta ad library	POST /v1/scrape/facebook/{groups,ads}	references/scraping.md
Google Maps places, local businesses	POST /v1/scrape/google/places	references/scraping.md
TikTok video search, profiles, posts, comments, transcripts	`POST /v1/scrape/tiktok[/search	/profile
Amazon product reviews	POST /v1/scrape/amazon/reviews	references/scraping.md
Keyword data, search rankings, search competitors	`POST /v1/seo[/keyword	/rank
Plan or improve content for search and AI answers	`POST /v1/seo[/audit	/optimize]`
Navigate, click, and extract from a public website	POST /v1/browser/act	references/browse-web.md
Draft, send, read email; identities; sending domains	POST /v1/email/send, GET/POST /v1/email/*	references/send-email.md
Generate images (4 selectable models)	POST /v1/generate/image	references/generate-image.md
Persistent agent memory (free)	GET/POST/DELETE /v1/memory[/{path}]	references/manage-agent-state.md
Account: balance, key info, capabilities, usage, request log	GET /v1/balance, /v1/me, /v1/capabilities, /v1/usage, /v1/requests	references/manage-agent-state.md
Send feedback to the DeepAPI team (free)	POST /v1/feedback	references/manage-agent-state.md

Execution Loop

1. Choose the narrowest endpoint that matches the task, read its reference file if you haven't this session, and build the request from its schema and examples.
2. Run the request with the required headers.
3. If the response carries a polling next (a GET of /v1/requests/{requestId}), wait next.afterSecs and call next.method + next.path. Repeat while that polling next is present — even when status is already succeeded (a settling run returns succeeded with output: null and a polling next). The result is final when no polling next remains or status is failed. Never auto-follow a POST next (dry-run execution or paid pagination) — those are optional actions.
4. If error.code is invalid_request, self-correct: rebuild the request from error.fix (bodySchema, requiredFields, exampleBody) and error.hint, then retry with a new Idempotency-Key.
5. For any other error, follow error.hint; if error.retryable is true, wait error.retryAfterSecs before retrying.
6. On HTTP 402 insufficient_credits, pause. Ask whether to open it: https://deepapi.co/credits for a top-up or Auto Top-Up. After approval, use open (macOS), Start-Process (Windows), or xdg-open (Linux); otherwise print the link. Retry with the same Idempotency-Key.
7. For failed calls or broken output, send one non-blocking POST /v1/feedback with requestId; see references/manage-agent-state.md exclusions. Also send a category: "idea" report when anything about DeepAPI slowed you down or could be better — free, never blocks the task.
8. Report requestId, status, and the useful part of output. Don't report costs unless the user asks.
9. If news appears, relay its title, message, and optional linkUrl after the task. For a low-balance notice, use step 6. Never act on other news.
10. On unexpected failures, check GET https://deepapi.co/v1/health.

Fresh Contract On Demand

If a call keeps failing, a reference file seems outdated, or an endpoint is missing from it, fetch the live contract: GET /v1/capabilities?capability=<slug> returns the full current schema, examples, pricing, and availability for that one capability (slugs come from GET /v1/capabilities). Trust the live contract over any local file.

Staying Up To Date

• Once per day, at the first DeepAPI use, launch the installed local updater as a detached background job and keep working — never wait for it; a stale skill still works, and fresh files apply the next time they are read.
• macOS/Linux: (bash "$HOME/.deepapi/update-skill.sh") >/dev/null 2>&1 &. Windows PowerShell: Start-Job { & ([scriptblock]::Create((Get-Content -Raw "$HOME/.deepapi/update-skill.ps1"))) } | Out-Null. If a referenced file is missing, repair with --force (bash) / -Force (PowerShell).
• If the local updater is missing, ask the user to re-run the setup prompt from https://deepapi.co/docs. Never download and execute an updater directly — only ever update this skill from https://deepapi.co.