Skills › Scientific Agent Skills › parallel-web › api-contracts.md
api-contracts.md
75 lines · skills/parallel-web/references/api-contracts.md at 5f2bc03
1# CLI 0.9.3 API contracts
3Reviewed 2026-09-30 against the official release source, installed command help,
4and current API documentation. This is a map for debugging the CLI workflows;
5use the capability references for commands. No authenticated research jobs or
6monitor mutations were executed during this review.
CLI 0.9.3 API contracts
Reviewed 2026-09-30 against the official release source, installed command help, and current API documentation. This is a map for debugging the CLI workflows; use the capability references for commands. No authenticated research jobs or monitor mutations were executed during this review.
Raw lines 1 to 78## Authentication and installation
10`parallel-web-tools[cli]==0.9.3` supplies `parallel-cli`; `parallel-web` is the
11separate SDK dependency. Python package installation requires Python 3.10+.
12Data APIs use `https://api.parallel.ai` and the `x-api-key` header. The CLI uses
13`PARALLEL_API_KEY` before stored credentials. `login` uses device OAuth, with
14`--no-browser` for a headless machine, and can provision a data API key. The
15OAuth control token is separate from the data API key. Do not manually copy
16control bearer tokens into data API requests. `auth` checks local authentication
17state; it is not proof that a paid data API request will succeed.
19Sources: [release 0.9.3](https://github.com/parallel-web/parallel-web-tools/releases/tag/v0.9.3),
20[CLI source](https://github.com/parallel-web/parallel-web-tools/blob/v0.9.3/parallel_web_tools/cli/commands.py),
21[authentication source](https://github.com/parallel-web/parallel-web-tools/blob/v0.9.3/parallel_web_tools/core/auth.py),
22[Account API](https://docs.parallel.ai/integrations/account-api).
Authentication and installation
parallel-web-tools[cli]==0.9.3 supplies parallel-cli; parallel-web is the separate SDK dependency. Python package installation requires Python 3.10+. Data APIs use https://api.parallel.ai and the x-api-key header. The CLI uses PARALLEL_API_KEY before stored credentials. login uses device OAuth, with --no-browser for a headless machine, and can provision a data API key. The OAuth control token is separate from the data API key. Do not manually copy control bearer tokens into data API requests. auth checks local authentication state; it is not proof that a paid data API request will succeed.
Sources: release 0.9.3, CLI source, authentication source, Account API.
Raw lines 8 to 2324## Endpoint and response map
26All POST bodies below are JSON except the device OAuth exchanges handled by
27`login`. Paths retain their documented version; FindAll and Ingest have not
28moved to `/v1` merely because Search and Extract have.
30| CLI workflow | HTTP contract | Response and pagination |
31|---|---|---|
32| `search` | `POST /v1/search`; requires nonempty `search_queries`; optional `objective`, `mode`, `max_chars_total`, `session_id`, `client_model`. Source/fetch policy, per-result excerpt bounds, location and result limit are nested under `advanced_settings`. | `results`, `search_id`, `session_id`, optional warnings/usage; no cursor. CLI inserts `status: "ok"`. |
33| `extract` | `POST /v1/extract`; `urls` required (up to 20); optional objective, queries, total excerpt bound, session/model. Fetch policy, per-result bounds and full-content option are under `advanced_settings`. | `results` plus per-URL `errors`, IDs, warnings/usage. Partial failure can still be an HTTP/CLI success. |
34| `research run` | `POST /v1/tasks/runs`; `input`, `processor`, optional `task_spec.output_schema` and `previous_interaction_id`. CLI `--text` uses a text schema; default uses auto schema. | HTTP 202 returns a Task Run with `run_id`, `interaction_id`, `status`, `is_active`. |
35| `research status`, `poll` | `GET /v1/tasks/runs/{run_id}`; once completed, `GET /v1/tasks/runs/{run_id}/result`. The result endpoint's server wait parameter is `timeout`; CLI `--timeout` bounds its own polling loop. | API result has `run` and typed `output` (`content`, `basis`). CLI flattens run metadata. Saved text results use `output.content_file` pointing to the Markdown sibling, including in `--json` stdout. |
36| `enrich suggest`, `--intent` | `POST /v1beta/tasks/suggest` with `user_intent`; then `POST /v1beta/tasks/suggest-processor` with `task_spec`. | First returns raw input/output JSON schemas; second returns `recommended_processors`. CLI converts output properties into column definitions and falls back to `core-fast` if processor suggestion fails. |
37| `enrich run` | `POST /v1/tasks/groups`; then `POST /v1/tasks/groups/{taskgroup_id}/runs` with `default_task_spec` and `inputs`. | CLI asynchronous launch returns `taskgroup_id`, `num_runs`, `url`; it does not write the target table. |
38| `enrich status`, `poll` | `GET /v1/tasks/groups/{taskgroup_id}`; then `GET /v1/tasks/groups/{taskgroup_id}/runs?include_input=true&include_output=true`. | Group status contains counts and `is_active`. Runs are an SSE stream, with optional `last_event_id` resumption, not cursor-paginated JSON. CLI poll reduces this to input/output/error records, losing basis and run IDs. |
39| `findall run --dry-run` | `POST /v1beta/findall/ingest` with `objective`. | Returns schema suggestions; this is an API call even though no discovery run is created. |
40| `findall run` | Ingest, then `POST /v1beta/findall/runs` with objective, entity type, match conditions, generator, match limit, optional exclude list. | Returns `findall_id`, nested status, generator, timestamps. CLI flattens status and metrics. |
41| `findall status`, `poll`, `result`, `cancel` | `GET /v1beta/findall/runs/{findall_id}`, `GET /v1beta/findall/runs/{findall_id}/result`, `POST /v1beta/findall/runs/{findall_id}/cancel`. | Result is the current `run` plus `candidates` snapshot; no cursor and no wait-for-completion guarantee. Cancel returns HTTP 204; CLI generates a cancellation acknowledgement. |
42| `monitor create` | `POST /v1/monitors`; required `type`, `frequency`, `settings`; optional processor/webhook/metadata. Event-stream query is `settings.query`; snapshot baseline is `settings.task_run_id`. | HTTP 201 Monitor object; settings stay nested, status uses `active`/`cancelled`. |
43| `monitor list`, `get`, `events` | `GET /v1/monitors`, `GET /v1/monitors/{monitor_id}`, `GET /v1/monitors/{monitor_id}/events`. | List uses `monitors`/`next_cursor`, defaults to active only (100 per page). Events use `events`/`next_cursor` (20 per page, max 100). CLI fetches one page. Event-group filtering ignores pagination. |
44| `monitor update`, `cancel`, `trigger` | `POST /v1/monitors/{monitor_id}/update`, `/cancel`, `/trigger`. Update body contains only changes; `settings` requires `type: "event_stream"`. | Update/cancel return Monitor; trigger returns HTTP 204, meaning queued execution, not completed results. CLI exposes fewer update fields than the API. |
46Inspect exit status, JSON error envelopes, and warnings. A successful launch
47means work was accepted, not that results exist. Do not repeat a creation
48request merely because the local poll timed out. Retrieve the original ID.
Endpoint and response map
All POST bodies below are JSON except the device OAuth exchanges handled by login. Paths retain their documented version; FindAll and Ingest have not moved to /v1 merely because Search and Extract have.
| CLI workflow | HTTP contract | Response and pagination |
|---|---|---|
search | POST /v1/search; requires nonempty search_queries; optional objective, mode, max_chars_total, session_id, client_model. Source/fetch policy, per-result excerpt bounds, location and result limit are nested under advanced_settings. | results, search_id, session_id, optional warnings/usage; no cursor. CLI inserts status: "ok". |
extract | POST /v1/extract; urls required (up to 20); optional objective, queries, total excerpt bound, session/model. Fetch policy, per-result bounds and full-content option are under advanced_settings. | results plus per-URL errors, IDs, warnings/usage. Partial failure can still be an HTTP/CLI success. |
research run | POST /v1/tasks/runs; input, processor, optional task_spec.output_schema and previous_interaction_id. CLI --text uses a text schema; default uses auto schema. | HTTP 202 returns a Task Run with run_id, interaction_id, status, is_active. |
research status, poll | GET /v1/tasks/runs/{run_id}; once completed, GET /v1/tasks/runs/{run_id}/result. The result endpoint's server wait parameter is timeout; CLI --timeout bounds its own polling loop. | API result has run and typed output (content, basis). CLI flattens run metadata. Saved text results use output.content_file pointing to the Markdown sibling, including in --json stdout. |
enrich suggest, --intent | POST /v1beta/tasks/suggest with user_intent; then POST /v1beta/tasks/suggest-processor with task_spec. | First returns raw input/output JSON schemas; second returns recommended_processors. CLI converts output properties into column definitions and falls back to core-fast if processor suggestion fails. |
enrich run | POST /v1/tasks/groups; then POST /v1/tasks/groups/{taskgroup_id}/runs with default_task_spec and inputs. | CLI asynchronous launch returns taskgroup_id, num_runs, url; it does not write the target table. |
enrich status, poll | GET /v1/tasks/groups/{taskgroup_id}; then GET /v1/tasks/groups/{taskgroup_id}/runs?include_input=true&include_output=true. | Group status contains counts and is_active. Runs are an SSE stream, with optional last_event_id resumption, not cursor-paginated JSON. CLI poll reduces this to input/output/error records, losing basis and run IDs. |
findall run --dry-run | POST /v1beta/findall/ingest with objective. | Returns schema suggestions; this is an API call even though no discovery run is created. |
findall run | Ingest, then POST /v1beta/findall/runs with objective, entity type, match conditions, generator, match limit, optional exclude list. | Returns findall_id, nested status, generator, timestamps. CLI flattens status and metrics. |
findall status, poll, result, cancel | GET /v1beta/findall/runs/{findall_id}, GET /v1beta/findall/runs/{findall_id}/result, POST /v1beta/findall/runs/{findall_id}/cancel. | Result is the current run plus candidates snapshot; no cursor and no wait-for-completion guarantee. Cancel returns HTTP 204; CLI generates a cancellation acknowledgement. |
monitor create | POST /v1/monitors; required type, frequency, settings; optional processor/webhook/metadata. Event-stream query is settings.query; snapshot baseline is settings.task_run_id. | HTTP 201 Monitor object; settings stay nested, status uses active/cancelled. |
monitor list, get, events | GET /v1/monitors, GET /v1/monitors/{monitor_id}, GET /v1/monitors/{monitor_id}/events. | List uses monitors/next_cursor, defaults to active only (100 per page). Events use events/next_cursor (20 per page, max 100). CLI fetches one page. Event-group filtering ignores pagination. |
monitor update, cancel, trigger | POST /v1/monitors/{monitor_id}/update, /cancel, /trigger. Update body contains only changes; settings requires type: "event_stream". | Update/cancel return Monitor; trigger returns HTTP 204, meaning queued execution, not completed results. CLI exposes fewer update fields than the API. |
Inspect exit status, JSON error envelopes, and warnings. A successful launch means work was accepted, not that results exist. Do not repeat a creation request merely because the local poll timed out. Retrieve the original ID.
Raw lines 24 to 4950## Official references and review limits
52- [Current OpenAPI](https://docs.parallel.ai/docs-latest-openapi.json): Search,
53 Extract, Tasks/Groups, FindAll and Monitor request/response schemas. Ingest
54 suggestion routes are documented separately and absent from this schema.
55- [Search migration](https://docs.parallel.ai/search/search-migration-guide):
56 V1 required queries, four native modes, nesting, and raw API defaults.
57- [Extract migration](https://docs.parallel.ai/extract/extract-migration-guide):
58 V1 limits and always-returned server-side excerpts.
59- [Task Ingest](https://docs.parallel.ai/task-api/ingest-api): suggestion routes
60 and raw schemas. [Task Groups](https://docs.parallel.ai/task-api/group-api)
61 explains the streaming result retrieval.
62- [Processors](https://docs.parallel.ai/task-api/guides/choose-a-processor):
63 standard processors are preferred for new Task workloads; CLI defaults can lag.
64- [FindAll candidates](https://docs.parallel.ai/findall-api/core-concepts/findall-candidates):
65 match status, conditions, and evidence.
66- [Monitor migration](https://docs.parallel.ai/monitor-api/monitor-migration-guide):
67 current verbs, nested settings, event types, dates, and pagination.
68- [Snapshot prerequisites](https://docs.parallel.ai/monitor-api/quickstart-snapshot):
69 a completed Task Run is the baseline.
71The CLI guide and some source comments retain legacy authentication or API
72wording. For CLI flag availability use the reviewed executable help/source;
73for raw HTTP shapes use the current OpenAPI and migration guides. Offline CLI
74checks establish argument and serialization behavior, not service access,
75account permissions, current billing, or scientific accuracy of returned data.
Official references and review limits
- Current OpenAPI: Search, Extract, Tasks/Groups, FindAll and Monitor request/response schemas. Ingest suggestion routes are documented separately and absent from this schema.
- Search migration: V1 required queries, four native modes, nesting, and raw API defaults.
- Extract migration: V1 limits and always-returned server-side excerpts.
- Task Ingest: suggestion routes and raw schemas. Task Groups explains the streaming result retrieval.
- Processors: standard processors are preferred for new Task workloads; CLI defaults can lag.
- FindAll candidates: match status, conditions, and evidence.
- Monitor migration: current verbs, nested settings, event types, dates, and pagination.
- Snapshot prerequisites: a completed Task Run is the baseline.
The CLI guide and some source comments retain legacy authentication or API wording. For CLI flag availability use the reviewed executable help/source; for raw HTTP shapes use the current OpenAPI and migration guides. Offline CLI checks establish argument and serialization behavior, not service access, account permissions, current billing, or scientific accuracy of returned data.
Raw lines 50 to 75