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.

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`
Multi-source dossier on a person, company, or topic	`POST /v1/scrape/deep`	`references/scraping.md`
Extract structured JSON from web pages	`POST /v1/scrape/extract`	`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 products, search, and reviews	`POST /v1/scrape/amazon/{product,search,reviews}`	`references/scraping.md`
Exact Meta Threads posts by URL	`POST /v1/scrape/threads/posts`	`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`
Run scripts, shell tools, tests, or Docker in a virtual machine	`POST /v1/vm/run`	`references/browse-web.md`
Email workflows, contact data, and company enrichment	`GET/POST /v1/email/*` , `POST /v1/company/enrich`	`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	`GET /v1/balance` , `/v1/me` , `/v1/capabilities` , `/v1/usage`	`references/manage-agent-state.md`
Recover the result of a recent request (free)	`GET /v1/requests` , then `GET /v1/requests/{requestId}`	`references/manage-agent-state.md`
Send feedback to the DeepAPI team (free)	`POST /v1/feedback`	`references/manage-agent-state.md`

Execution Loop

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.
Run the request with the required headers.
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.

error.code

invalid_request

, self-correct: rebuild the request from

error.fix

(

bodySchema

requiredFields

exampleBody

) and

error.hint

, then retry with a new

Idempotency-Key

For any other error, follow
```
error.hint
```
; if
```
error.retryable
```
is true, wait
```
error.retryAfterSecs
```
before retrying.
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
```
.
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.
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.
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.
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.

deepapi

NPX Install

Tags

SKILL.md Content