# Nominal data sources

Manages data sources (logical groupings of series) that are stored by Nominal.

OpenAPI file: [`NominalDataSourceService.json`](https://dev.nominal.io/api/_downloads/aaa7a8330708d7450bc492b7c1f59245/NominalDataSourceService.json)

## Endpoints

### Create

POST `/storage/data-source/v1`

**Deprecated:** Use CatalogService#createDataset instead.

Creates a data source.

Body

`id` string required
:   A human readable identifier. Must be unique within an organization.

`description` string
:   ​

`granularity` [`Granularity`](https://dev.nominal.io/api/rest/nominal-data-sources.md#granularity)
:   Specifies the timestamp granularity of the datasource. Defaults to nanosecond granularity.

    Values of `Granularity`

    `NANOSECONDS`
    :   ​

`inMemoryStreamingEnabled` boolean
:   ​

`workspace` string (RID)
:   The workspace in which to create the datasource. If not provided, the datasource will be created in the default workspace for the user’s organization, if the default workspace for the organization is configured.

Response

`rid` string (RID)
:   ​

`id` string
:   ​

`description` string
:   ​

`dataLastWrittenAt` string (date-time)
:   Returns the approximate timestamp at which data was written to the data source. Will be accurate to within 1 minute.

`granularity` [`Granularity`](https://dev.nominal.io/api/rest/nominal-data-sources.md#granularity)
:   ​

    Values of `Granularity`

    `NANOSECONDS`
    :   ​

`inMemoryStreamingEnabled` boolean
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/storage/data-source/v1" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "<nominal data source id>"
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/storage/data-source/v1",
    headers={"Authorization": "Bearer <api key>"},
    json={"id": "<nominal data source id>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/storage/data-source/v1",
    headers={"Authorization": "Bearer <api key>"},
    json={"id": "<nominal data source id>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/storage/data-source/v1",
            headers={"Authorization": "Bearer <api key>"},
            json={"id": "<nominal data source id>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<nominal data source rid>",
  "id": "<nominal data source id>",
  "description": "<description>",
  "dataLastWrittenAt": "2026-01-01T00:00:00Z",
  "granularity": "NANOSECONDS",
  "inMemoryStreamingEnabled": true
}
```

### Update

PUT `/storage/data-source/v1/{rid}`

Path parameters

`rid` string (RID) required
:   ​

Body

`inMemoryStreamingEnabled` boolean required
:   ​

Response

`rid` string (RID)
:   ​

`id` string
:   ​

`description` string
:   ​

`dataLastWrittenAt` string (date-time)
:   Returns the approximate timestamp at which data was written to the data source. Will be accurate to within 1 minute.

`granularity` [`Granularity`](https://dev.nominal.io/api/rest/nominal-data-sources.md#granularity)
:   ​

    Values of `Granularity`

    `NANOSECONDS`
    :   ​

`inMemoryStreamingEnabled` boolean
:   ​

Request

**curl**

```shell
curl -X PUT "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "inMemoryStreamingEnabled": true
}'
```

**requests**

```python
import requests

response = requests.put(
    "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={"inMemoryStreamingEnabled": True},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={"inMemoryStreamingEnabled": True},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>",
            headers={"Authorization": "Bearer <api key>"},
            json={"inMemoryStreamingEnabled": True},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<nominal data source rid>",
  "id": "<nominal data source id>",
  "description": "<description>",
  "dataLastWrittenAt": "2026-01-01T00:00:00Z",
  "granularity": "NANOSECONDS",
  "inMemoryStreamingEnabled": true
}
```

### Batch get

POST `/storage/data-source/v1/batch-get`

Retrieves the data sources for the given data source RIDs.

Excludes data sources that do not exist or are unauthorized. A maximum of 1000 rids can be requested.

Body

The body is an array of string (RID).

Response

The body is an array of [`NominalDataSource`](https://dev.nominal.io/api/rest/nominal-data-sources.md#nominaldatasource).

Fields of `NominalDataSource`

`rid` string (RID)
:   ​

`id` string
:   ​

`description` string
:   ​

`dataLastWrittenAt` string (date-time)
:   Returns the approximate timestamp at which data was written to the data source. Will be accurate to within 1 minute.

`granularity` [`Granularity`](https://dev.nominal.io/api/rest/nominal-data-sources.md#granularity)
:   ​

    Values of `Granularity`

    `NANOSECONDS`
    :   ​

`inMemoryStreamingEnabled` boolean
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/storage/data-source/v1/batch-get" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  "<nominal data source rid>"
]'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/storage/data-source/v1/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json=["<nominal data source rid>"],
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/storage/data-source/v1/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json=["<nominal data source rid>"],
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/storage/data-source/v1/batch-get",
            headers={"Authorization": "Bearer <api key>"},
            json=["<nominal data source rid>"],
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
[
  {
    "rid": "<nominal data source rid>",
    "id": "<nominal data source id>",
    "description": "<description>",
    "dataLastWrittenAt": "2026-01-01T00:00:00Z",
    "granularity": "NANOSECONDS",
    "inMemoryStreamingEnabled": true
  }
]
```

### Update last written timestamp

PUT `/storage/data-source/v1/{rid}/last-written`

Sets the timestamp that the Nominal Data Source in question was last written to. Only needs to be called once per minute.

Path parameters

`rid` string (RID) required
:   ​

Body

The body is a string (date-time).

Response

No content (HTTP 204).

Request

**curl**

```shell
curl -X PUT "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>/last-written" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '"2026-01-01T00:00:00Z"'
```

**requests**

```python
import requests

response = requests.put(
    "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>/last-written",
    headers={"Authorization": "Bearer <api key>"},
    json="2026-01-01T00:00:00Z",
)
response.raise_for_status()
```

**httpx**

```python
import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>/last-written",
    headers={"Authorization": "Bearer <api key>"},
    json="2026-01-01T00:00:00Z",
)
response.raise_for_status()
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>/last-written",
            headers={"Authorization": "Bearer <api key>"},
            json="2026-01-01T00:00:00Z",
        ) as response:
            response.raise_for_status()

asyncio.run(main())
```

Response: `204`

No content.

### Ensure dataset for data source

POST `/storage/data-source/v1/{rid}/ensure-dataset`

Ensures a corresponding dataset exists for the given NominalDataSource. If the dataset already exists, this is a no-op. If it doesn’t exist, creates one with the same UUID as the NominalDataSource. This is to facilitate the migration from NominalDataSource to Dataset.

Path parameters

`rid` string (RID) required
:   ​

Response

The body is a string (RID).

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>/ensure-dataset" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>/ensure-dataset",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>/ensure-dataset",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/storage/data-source/v1/<rid>/ensure-dataset",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
"<dataset rid>"
```

## Errors

[Errors](https://dev.nominal.io/api/legacy.md#errors) shows how these errors are sent.

Each error’s `errorName` is `NominalDataSource:` followed by its name below.

| Status | Name | Notes |
| --- | --- | --- |
| 400 | `InvalidNominalDataSource` |  |
| 404 | `DataSourceNotFound` |  |
| 404 | `DataSourcesNotFound` |  |
| 409 | `NominalDataSourceConflict` | The requested data source already exists. |

## Types

### Granularity

`NANOSECONDS`
:   ​

### NominalDataSource

A logical grouping of series.

`rid` string (RID) required
:   ​

`id` string required
:   ​

`description` string
:   ​

`dataLastWrittenAt` string (date-time)
:   Returns the approximate timestamp at which data was written to the data source. Will be accurate to within 1 minute.

`granularity` [`Granularity`](https://dev.nominal.io/api/rest/nominal-data-sources.md#granularity) required
:   ​

`inMemoryStreamingEnabled` boolean
:   ​

Page design based on [Scalar](https://scalar.com), MIT License.