Run data sources

Run one or more data source adapters in parallel and return each source result.

POST /data

POST /data runs every source in config.sources in parallel. Each source receives the fields from inputs that its input schema accepts. The response returns after all selected sources finish.

Authorization

Requires an access token and a workflow belonging to the token organization. See Authentication.

Headers

Header	Required	Description
`X-Datastruct-Access-Token`	Conditional	Datastruct token
`X-Datastruct-Workflow`	Conditional	Header-token workflow
`Authorization`	Conditional	Alternative token header: `Bearer <token>`
`Content-Type`	Recommended	`application/json`; omission is accepted

Request body

{
  "access_token": "<access-token>",
  "workflow": "wfl_01jykdqt8yejf9hz2yvcqwb4gd",
  "config": {
    "context": "prod",
    "sources": {
      "ip-api__geolocation": true
    }
  },
  "inputs": {
    "query": "8.8.8.8"
  }
}

Field	Type	Required	Default	Description
`access_token`	string or null	No	`null`	Body token
`workflow`	string or null	No	`null`	Body-token workflow
`config`	object	Yes	—	Run configuration
`config.context`	string	No	`dev`	One of `prod`, `test`, or `dev`
`config.sources`	object	Yes	—	Non-empty source map
`inputs`	object	No	`{}`	Fields shared by all selected sources

Unknown top-level fields are accepted and ignored. inputs is one flat object; it is not namespaced by source. See Source configuration for the accepted source values and credential fields.

Each source declares an input JSON Schema. Data Serve filters inputs to the property names in that schema before the source runs. Properties from every oneOf, anyOf, or allOf branch are included.

A request can therefore contain the union of fields needed by all selected sources. A misspelled or undeclared field is silently dropped rather than rejected.

Request example

curl --request POST \
  --url https://api.us.datastruct.co/data \
  --header 'Content-Type: application/json' \
  --header 'X-Datastruct-Access-Token: <access token>' \
  --header 'X-Datastruct-Workflow: wfl_01jykdqt8yejf9hz2yvcqwb4gd' \
  --data '{
    "config": {
      "context": "prod",
      "sources": {
        "ip-api__geolocation": true,
        "dsmock__person_alpha": {}
      }
    },
    "inputs": {
      "query": "8.8.8.8",
      "first_name": "John",
      "last_name": "Doe",
      "state": "CA"
    }
  }'

Successful response

HTTP/1.1 200 OK
Content-Type: application/json
X-Frame-Options: DENY
Content-Security-Policy: frame-ancestors 'none'

{
  "transaction_id": "trx_01k2v8q9m7f3zb6cw4h5n0j1xd",
  "config": {
    "context": "prod",
    "sources": {
      "ip-api__geolocation": true,
      "dsmock__person_alpha": {}
    }
  },
  "outputs": {
    "ip-api__geolocation": {
      "status": "success",
      "country": "United States",
      "city": "Ashburn",
      "query": "8.8.8.8"
    },
    "dsmock__person_alpha": {
      "first_name": "John",
      "last_name": "Doe",
      "state": "CA"
    }
  },
  "status": {
    "ip-api__geolocation": {
      "success": true,
      "message": "Success",
      "match": true,
      "response_time_ms": 96
    },
    "dsmock__person_alpha": {
      "success": true,
      "message": "Success",
      "match": true,
      "response_time_ms": 12
    }
  },
  "response_time_ms": 104
}

Response fields

Field	Type	Description
`transaction_id`	string	Opaque `trx_` transaction identifier
`config`	object	Validated configuration with defaults
`outputs`	object	One entry per requested source
`outputs.<source>`	object	Source output, or `{}` after failure
`status`	object	One entry per requested source
`status.<source>.success`	boolean	Source completion outcome
`status.<source>.message`	string	Outcome text; do not parse
`status.<source>.match`	boolean	Whether the vendor found a record
`status.<source>.response_time_ms`	integer	Source time
`response_time_ms`	integer	Total service time

The response config includes the default context when the request omits it. Each source defines its own output schema. Source output fields can be added; clients must read the fields they need and ignore unrecognized fields.

Confirmation needed: Confirm whether response configuration should echo request-supplied credential fields. Current behavior can return plaintext credential fields when a caller sends them.

Outcome combinations

`success`	`match`	Meaning
`true`	`true`	The source completed and returned a record
`true`	`false`	Source completed without a record (valid result)
`false`	`false`	The source did not complete; its output is `{}`

All sources start at the same time. One source failure does not stop another. Total response_time_ms is close to the slowest source time, not the sum.

Per-source failures

Every failure below appears in an HTTP 200 response.

Message prefix	Cause
`Adapter not found for`	Unknown source identifier
`Adapter error:`	Credential, input, timeout, or vendor failure
`Unexpected error:`	Data Serve failed while collecting the result

Message wording can change. Branch on success and match, not message.

Request errors and retries

This endpoint can return 401, 422, or 500. An empty or missing config.sources currently returns 500. See Errors for error bodies.

Data Serve has no idempotency key. A retry runs each selected vendor call again and can be billable. Retry only sources that failed because of a timeout or vendor 5xx response.