# Data Serve API

> Base URL, protocol conventions, and endpoints for synchronous data integrations

Data Serve is a synchronous, server-to-server JSON API. It runs data source
adapters with `POST /data`, runs one data function with `POST /func`, and
reports service health with `GET /status`.

## Regional base URLs

| Region | Base URL |
| --- | --- |
| United States | `https://api.us.datastruct.co` |
| Asia Pacific | `https://api.apse1.datastruct.co` |
| Europe | `https://api.euw1.datastruct.co` |

Use the base URL for the region assigned to your integration. Data Serve has
one API version, and the version is not part of the URL.

## Endpoints

| Method | Endpoint | Description |
| --- | --- | --- |
| `POST` | [`/data`](/docs/api/data-serve/data-run/) | Run data sources |
| `POST` | [`/func`](/docs/api/data-serve/func-run/) | Run one function |
| `GET` | [`/status`](/docs/api/data-serve/status/) | Read service status |

## Media type

Requests and responses use `application/json`. Send
`Content-Type: application/json` with `POST` requests. Data Serve currently
accepts a JSON body without that header for backward compatibility.

Every response includes these security headers:

```http
X-Frame-Options: DENY
Content-Security-Policy: frame-ancestors 'none'
```

Data Serve sends no Cross-Origin Resource Sharing (CORS) headers and cannot be
called directly from browser code.

## Authentication

Every `/data` and `/func` request requires an access token and a workflow
identifier. Send them in Datastruct headers, an authorization header plus the
workflow header, or the JSON body. See
[Authentication](/docs/api/data-serve/authentication/) for the accepted forms
and resolution order.

`GET /status` does not require authentication.

## Shared response envelope

By default, both run endpoints return this top-level shape:

```json
{
  "transaction_id": "trx_01k2v8q9m7f3zb6cw4h5n0j1xd",
  "config": {},
  "outputs": {},
  "status": {},
  "response_time_ms": 412
}
```

`outputs` and `status` use the same source or function identifier as their key.
Read `status` before consuming `outputs`. `/func` can instead return a
function-defined passthrough response; its endpoint reference defines that
mode.

## HTTP status semantics

HTTP status reports whether Data Serve accepted and processed the request. It
does not report whether a data source found data or whether a function
completed successfully.

| Status | Meaning |
| --- | --- |
| `200` | Request ran; inspect `status` for source or function outcomes |
| `401` | The token or workflow was missing or rejected |
| `422` | The request body did not match the endpoint schema |
| `500` | Data Serve could not process a valid request |

Vendor timeouts, missing vendor credentials, unknown source identifiers, and
valid no-match results can all return `200`. See
[Errors](/docs/api/data-serve/errors/) for complete error shapes and retry
constraints.

## Compatibility

New response fields can be added without a new API version. Clients must ignore
fields they do not recognize.

Data Serve does not provide pagination, idempotency keys, rate-limit headers,
webhooks, callbacks, or access-token scopes. Each run returns one complete
synchronous result. Retrying starts external calls again and can be billable.

## Shared reference

- [Authentication](/docs/api/data-serve/authentication/) defines access tokens,
  workflow selection, and authentication failures.
- [Source configuration](/docs/api/data-serve/data-sources/) defines source
  identifiers and vendor credential resolution.
- [Transactions](/docs/api/data-serve/transactions/) defines identifiers,
  timing, context, and recorded data.
- [Errors](/docs/api/data-serve/errors/) defines HTTP and per-run failures.