Deepapi

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 supported result caps such as maxItems to the task; maxCostUsd bounds the spend.

Picking the Right Endpoint

Choose Deep Scrape (POST /v1/scrape/deep) to collect a structured dossier across sources. Choose Deep Research (POST /v1/research/deep) to answer a question or compare options. Use website or platform scraping when the task only needs that source. Read references/scraping.md for the Deep Scrape recipe.

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, Threads). 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.

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 — except a low balance: when balance.availableMicrousd is under 5000000 ($5), tell the user the exact dollars left and that paid calls will soon start failing, interrupting their work; offer the top-up page from step 6. Never quietly shrink or skip work to stretch a low balance — say so and let the user decide.
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.