API Reference

Base URL

https://api.nexqdata.io

All paths below are relative to it, and start with /api — for example, https://api.nexqdata.io/api/scraper-agents.

Always use https://. A plain http:// request is redirected, but by then your key has already crossed the network unencrypted.

Call this address directly with your API key. The dashboard at app.nexqdata.io is for signing in with a browser; it doesn't accept API keys.

Every request sends an API key — X-Api-Key: nxd_live_… or Authorization: Bearer nxd_live_…. See Authentication.

Bodies are JSON (Content-Type: application/json).
Ids are GUIDs, except an agent's externalAgentId, which is a string. See Agent ids.
Times are ISO 8601, in UTC unless a field says otherwise.
Every JSON response uses one envelope:

{
  "success": true,
  "message": "Job started.",
  "data": { },
  "errorCode": null
}

File downloads return the file itself, not an envelope.

Every endpoint in these docs, grouped by area. Each area links to the page that documents it.

Method	Path	Does
`GET`	`/api/scraper-agents`	List your agents
`GET`	`/api/scraper-agents/{id}`	Read one agent
`GET`	`/api/scraper-agents/{id}/sample-output`	Read the agent's sample output
`GET`	`/api/scraper-agents/{id}/sample-output/download`	Download the sample as JSON

Method	Path	Does
`POST`	`/api/scraper-agents/{externalAgentId}/start-job`	Start a job (recommended)
`POST`	`/api/scraper-agents/{externalAgentId}/run`	Start a single run
`POST`	`/api/scraper-agents/runs/{runId}/stop`	Stop a run

Method	Path	Does
`GET`	`/api/scraper-agents/jobs`	Jobs across your agents
`GET`	`/api/scraper-agents/{id}/jobs`	One agent's jobs
`GET`	`/api/scraper-agents/jobs/{jobId}/runs`	A job's runs
`GET`	`/api/scraper-agents/jobs/{jobId}/export`	Download a job's data
`GET`	`/api/scraper-agents/jobs/{jobId}/dataset`	A job's dataset id
`GET`	`/api/scraper-agents/jobs/active-count`	Jobs in progress
`GET`	`/api/scraper-agents/jobs/status-counts`	Jobs by status

Method	Path	Does
`GET`	`/api/scraper-agents/{id}/runs`	One agent's runs
`GET`	`/api/scraper-agents/runs`	Runs across your agents
`POST`	`/api/scraper-agents/runs/{runId}/refresh`	Re-read a run's state
`POST`	`/api/scraper-agents/runs/{runId}/dismiss-attention`	Ignore a failure
`POST`	`/api/scraper-agents/runs/{runId}/restore-attention`	Track a failure again
`GET`	`/api/scraper-agents/runs/active-count`	Runs in progress
`GET`	`/api/scraper-agents/runs/attention-count`	Failures needing attention
`GET`	`/api/scraper-agents/runs/status-counts`	Runs by status

Method	Path	Does
`GET`	`/api/search-groups`	List groups
`GET`	`/api/search-groups/{id}`	Read one group
`POST`	`/api/search-groups`	Create a group
`PUT`	`/api/search-groups/{id}`	Rename, describe, or disable a group
`PUT`	`/api/search-groups/{id}/members`	Replace a group's members
`DELETE`	`/api/search-groups/{id}`	Delete a group
`POST`	`/api/search-groups/{groupId}/run`	Run a group
`GET`	`/api/search-groups/runs`	List group runs
`GET`	`/api/search-groups/runs/{groupRunId}`	Follow a group run
`POST`	`/api/search-groups/runs/{groupRunId}/members/{agentId}/retry`	Start a member that didn't start
`DELETE`	`/api/search-groups/runs/{groupRunId}`	Delete a group run
`GET`	`/api/scraper-agents/group-runs/{groupRunId}/export`	Download a group run's data

Method	Path	Does
`GET`	`/api/pipelines`	List pipelines
`GET`	`/api/pipelines/{id}`	Read one pipeline
`POST`	`/api/pipelines`	Create a pipeline
`PUT`	`/api/pipelines/{id}`	Rename, describe, or disable a pipeline
`PUT`	`/api/pipelines/{id}/steps`	Replace a pipeline's stages
`DELETE`	`/api/pipelines/{id}`	Delete a pipeline
`POST`	`/api/pipelines/{pipelineId}/run`	Run a pipeline
`GET`	`/api/pipelines/runs`	List pipeline runs
`GET`	`/api/pipelines/runs/{pipelineRunId}`	Follow a pipeline run
`GET`	`/api/pipelines/runs/{pipelineRunId}/export`	Download a pipeline run's data
`DELETE`	`/api/pipelines/runs/{pipelineRunId}`	Delete a pipeline run

Method	Path	Does
`GET`	`/api/scraper-agents/runs/{runId}/export`	Download a run's data
`GET`	`/api/scraper-agents/runs/{runId}/dataset`	A run's dataset id
`GET`	`/api/data-explorer/datasets/{datasetId}/preview`	Preview
`POST`	`/api/data-explorer/datasets/{datasetId}/query`	Search, filter, sort, and page
`GET`	`/api/data-explorer/datasets/{datasetId}/download`	Download

Method	Path	Does
`GET`	`/api/scraper-agents/cached-exports`	List your datasets
`DELETE`	`/api/scraper-agents/cached-exports/{datasetId}`	Delete a dataset
`GET`	`/api/data-explorer/datasets/{datasetId}/lineage`	Where it came from
`GET`	`/api/data-explorer/datasets/{datasetId}/access`	Read sharing
`PUT`	`/api/data-explorer/datasets/{datasetId}/access`	Share with your company
`POST`	`/api/data-explorer/bulk/export`	Export several as one zip
`POST`	`/api/data-explorer/bulk/delete`	Delete several
`GET`	`/api/data-explorer/saved-queries`	List saved queries
`POST`	`/api/data-explorer/saved-queries`	Save a query
`DELETE`	`/api/data-explorer/saved-queries/{id}`	Delete a saved query

Method	Path	Does
`GET`	`/api/webhooks`	List your endpoints
`POST`	`/api/webhooks`	Add an endpoint (returns its secret once)
`PUT`	`/api/webhooks/{id}`	Change an endpoint, or enable it again
`DELETE`	`/api/webhooks/{id}`	Delete an endpoint
`POST`	`/api/webhooks/{id}/rotate-secret`	Issue a new signing secret
`POST`	`/api/webhooks/{id}/test`	Send a test `ping`
`GET`	`/api/webhooks/{id}/deliveries`	The delivery log
`POST`	`/api/webhooks/deliveries/{deliveryId}/redeliver`	Send a delivery again

Method	Path	Does
`GET`	`/api/api-keys`	List your keys
`POST`	`/api/api-keys`	Generate a key (revokes the active one)
`DELETE`	`/api/api-keys/{id}`	Revoke a key

Generated reference coming next

Full request and response schemas for every endpoint will be generated from the API's OpenAPI contract, so they stay in step with the API itself.