# What you can query

Every query in OpenGate is a `POST` to a URL that names **what** you are querying, with a JSON body that
says **which rows** you want. This page is the index of that first half: find your resource, take the URL,
and write the body using the [query language](../data_lake/).

## The URL pattern

```bash
POST https://api.opengate.es/north/v80/search/<resource>
```

That covers most resources, which are global or scoped by your API key. Two families depart from it, and
knowing which one you are in saves a lot of guessing.

**Time series and data sets** — you query one *named* store, so the organization and its identifier are part
of the URL:

```bash
POST /north/v80/timeseries/provision/organizations/{organization}/{identifier}/data
POST /north/v80/datasets/provision/organizations/{organization}/{identifier}/data
```

**Operations** — note the **missing `north` prefix**, which the operations service predates:

```bash
POST /v80/search/jobs
```

Three more resources invert the shape into `/<resource>/search`:
[rules](../../management/organizations/channels/rules/),
[provision processors](../../management/organizations/channels/entities/bulk/provision_functions/) and
[operation types](../../operations/operation_types/).

{{% notice style="info" title="The /summary variant" icon="lightbulb" %}}
Most search endpoints have a twin ending in `/summary` that returns aggregated counters instead of rows.
Same URL, same body, different answer: use it when you want *how many*, not *which ones*. See
[Summary](../data_lake/features/summary/). Endpoints offering it are marked below.
{{% /notice %}}

{{% notice style="note" title="Paths in the tables below" icon="circle-info" %}}
Paths are shown **relative to `/north/v80`**, except in the operations table, where they are relative to
`/v80`. A `+` in the *Summary* column means the endpoint also has a `/summary` twin. `{org}` is the
organization name and `{id}` the identifier of the time series or data set.
{{% /notice %}}

## Collected data

What the devices have sent you.

| To query | POST to | Summary | Documented in |
|---|---|---|---|
| Current data stream values | `search/datastreams` | | [Data streams](../data_streams/) |
| Historical data points — **deprecated** | `search/datapoints` | | [Data points](../data_points/) |
| All raised alarms | `search/entities/alarms` | + | [Alarms](../alarms/) |
| Alarms on devices | `search/entities/devices/alarms` | + | [Alarms](../alarms/) |
| Alarms on subscriptions | `search/entities/subscriptions/alarms` | + | [Alarms](../alarms/) |
| Data of one time series | `timeseries/provision/organizations/{org}/{id}/data` | | [Time series](../time_series/) |
| A time series aggregated per device | `timeseries/provision/organizations/{org}/{id}/dataset` | | [Time series](../time_series/) |
| A time series as a Parquet export | `timeseries/provision/organizations/{org}/{id}/export` | | [Time series](../time_series/) |
| Data of one data set | `datasets/provision/organizations/{org}/{id}/data` | | [Data sets](../data_sets/) |
| The data set catalog | `search/catalog/datasets` | | [Data sets](../data_sets/) |

## Entities and provisioning

What you have registered on the platform.

| To query | POST to | Summary | Documented in |
|---|---|---|---|
| Any entity, whatever its type | `search/entities` | + | [Entities](../../management/organizations/channels/entities/) |
| Devices | `search/devices` | + | [Devices](../../management/organizations/channels/entities/devices/) |
| Assets | `search/assets` | + | [Assets](../../management/organizations/channels/entities/asset/) |
| Subscribers | `search/subscribers` | + | [Subscribers](../../management/organizations/channels/entities/subscribers/) |
| Subscriptions | `search/subscriptions` | + | [Subscriptions](../../management/organizations/channels/entities/subscriptions/) |
| Channels | `search/channels` | + | [Channels](../../management/organizations/channels/) |
| Organizations | `search/organizations` | + | [Organizations](../../management/organizations/) |
| Work groups | `search/workgroups` | + | [Work groups](../../management/organizations/work_groups/) |
| Users | `search/users` | + | [Users](../../management/organizations/work_groups/users/) |
| Geo-areas | `search/areas` | | [Geo-areas](../../management/organizations/areas/) |
| Tickets | `search/tickets` | + | [Tickets](../../management/organizations/tickets/) |
| Data models | `search/datamodels` | | [Data models](../../management/organizations/data_models/) |
| Software and configuration bundles | `search/bundles` | | [Bundles](../../management/organizations/work_groups/bundles/) |
| Certificates | `search/certificates` | | [Certificates](../../management/certificates/) |
| Hardware catalog | `search/catalog/hardwares` | + | [Hardware catalog](../../management/base_hardware_catalog/) |
| Mobile operators catalog | `search/catalog/operators` | | [Operators](../../catalogs/operators/) |
| Rules | `rules/search` | | [Rules](../../management/organizations/channels/rules/) |
| Provision processors | `provisionProcessors/bulk/search` | | [Provision functions](../../management/organizations/channels/entities/bulk/provision_functions/) |
| Asynchronous bulk requests | `search/bulk/async` | | [Bulk](../../management/organizations/channels/entities/bulk/classic/) |

## Operations

What you have asked the devices to do. Note the missing `north` prefix.

| To query | POST to | Summary | Documented in |
|---|---|---|---|
| Jobs | `search/jobs` | + | [Jobs](../../operations/jobs/) |
| Tasks | `search/tasks` | | [Tasks](../../operations/tasks/) |
| Operations on devices | `search/entities/devices/operations` | + | [Jobs](../../operations/jobs/) |
| Operations on subscribers | `search/entities/subscribers/operations` | + | [Jobs](../../operations/jobs/) |
| Operations on subscriptions | `search/entities/subscriptions/operations` | + | [Jobs](../../operations/jobs/) |
| Closed operations history | `search/entities/operations/history` | + | [Jobs](../../operations/jobs/) |
| Operation types | `operationTypes/search` | | [Operation types](../../operations/operation_types/) |

## Which fields can I filter on?

The clause syntax is the same everywhere, but the **field names** depend on the resource. They are dotted
paths, and entity searches expose two families of them:

| Field family | Example | Holds |
|---|---|---|
| `provision.*` | `provision.device.administrativeState` | Provisioned configuration |
| `<entity>.*` | `device.serialNumber` | Entity attributes, including collected ones |
| `<resource>.*` | `datapoints.datastreamId`, `jobs.report.summary.status` | The fields of a non-entity resource |
| A column name | `Prov Identifier` | Data sets and time series, where you define the columns yourself |

Arrays are addressed with `[]`, optionally indexed:
`provision.device.communicationModules[].mobile.imei`.

Each resource's filterable fields are listed in its own API specification, rendered on the page named in the
tables above. The fastest shortcut, though, is to run the query with an empty body `{}` and read the paths
off the response: those are exactly the paths you can filter, sort and select on.