Developer reference

Pickable API

Read your scan data, request an asynchronous scan, and connect an MCP client.

Machine-readable contract: OpenAPI 3.1 JSON. API catalog: RFC 9727 linkset.

Start a REST scan

Read csrf_token from GET /api/config, then post exactly one JSON field: domain for a domain scan, or url for an exact public page URL. The url form preserves the path and safe query parameters for product analysis, while dropping fragments. The domain form is restricted to the root: It accepts a bare public domain such as example.com or an HTTP(S) root URL such as https://example.com/; ports, credentials, non-root paths, authentication query parameters, IP literals, and private or reserved destinations are rejected. Other query parameters are preserved. A successful request returns HTTP 202 with job_id. An operator-issued bearer key configured as PICKABLE_AGENT_API_KEY is an alternative for scan creation.

GET /api/config

POST /api/scans
Content-Type: application/json
X-CSRF-Token: <csrf_token>

{"domain":"example.com"}

Poll GET /api/scans/{job_id}. Its report may be partial while sources run. GET /api/scans/{job_id}/report returns 404 until a report is available.

Read endpoints

Request	Response
`GET /api/config`	CSRF token and demo/live mode.
`GET /api/health`	Service health response.
`GET /api/scans`	Stored scan metadata scoped to the caller’s network peer.
`GET /api/scans/{job_id}`	Job status, source states, and a partial or complete report when available.
`GET /api/scans/{job_id}/report`	Normalized report JSON; 404 when not yet available.
`GET /api/scans/{job_id}/preview`	Website preview metadata.

Scan history, reports, and previews are scoped to the caller’s direct network peer IP. This is not account authentication: callers behind the same proxy may share access. Raw provider responses are not exposed. Submit only public URLs without credentials.

Scan creation errors

Status	Meaning
400	Missing or malformed Content-Length, invalid JSON, or body shape/domain is invalid.
403	Host or Origin is disallowed, or neither a valid session CSRF token nor configured bearer key was accepted.
408	Request body read timed out.
413	Request body exceeds the 2,048-byte limit.
415	Content-Type is not application/json.
429	Queue or scan rate limit reached. Follow the Retry-After header.
503	Scan backend is unavailable.

For MCP request headers, protocol negotiation, and tools, see the agent integration guide. Read as Markdown: api.md and api-llms.txt.