> For the complete documentation index, see [llms.txt](https://docs.silk.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.silk.us/api-reference/using-the-api/url-structure-and-filtering.md).

# URL structure and filtering

How resource URLs are built, and how to page, sort, and filter collections.

Use Silk's URL structure and object manipulation features to construct API requests. The API provides a distinct resource URL for each entity collection. For example:

<table><thead><tr><th width="214.8148193359375">Entity collection</th><th>URL structure</th></tr></thead><tbody><tr><td>Hosts</td><td><code>https://{silk_ip}/api/v2/hosts</code></td></tr><tr><td>Volumes</td><td><code>https://{silk_ip}/api/v2/volumes</code></td></tr></tbody></table>

Within each collection, you can reference an entity explicitly by its ID. The entity ID is generated and managed by the management controller (MC). Explicit object URLs are called **canonical URLs**, for example `/api/v2/volumes/38`.

Object relations are defined through URL references. For example, volume objects have a `volume_group.ref` property that references the volume group they belong to. A reference can be mandatory, as in the volume–volume group relationship, or optional, as in the host–host group relationship.

```json
"volume_group": { "ref": "/volume_groups/1" }
```

Issue a `GET` request to the root endpoint, `https://{host-address}/api/v2`, to list the resources and endpoints the API supports.

## Paging and sorting

Each collection URL accepts these ordering and paging parameters:

<table><thead><tr><th width="199.25927734375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>__limit</code></td><td>Caps the number of returned entities at the given limit.</td></tr><tr><td><code>__offset</code></td><td>Returns results starting from the given offset. Useful for paging.</td></tr><tr><td><code>__pretty</code></td><td>Returns indented results. Otherwise responses are minified.</td></tr><tr><td><code>__sort</code></td><td>Sorts results by the given comma-separated object properties.</td></tr><tr><td><code>__sort_order</code></td><td>Sort direction: <code>asc</code> or <code>desc</code>.</td></tr></tbody></table>

{% hint style="info" %}
To retrieve a collection in chunks using `__limit` and `__offset`, you must also provide a sorting parameter.
{% endhint %}

Collection responses are wrapped in an envelope:

```json
{
  "hits": [ ... ],
  "limit": 100,
  "offset": 0,
  "total": 1
}
```

## Filtering

Silk supports exact-match filters against each object field. Pass the property name and value in the query string:

```
GET /api/v2/volume_groups?name=vg1
```

This returns the volume group with its ID (for example, `14`). You can then get that group's volumes by filtering on the reference:

```
GET /api/v2/volumes?volume_group.ref=/volume_groups/14
```

Combine several filters in one request:

```
GET /api/v2/volumes?volume_group.ref=/volume_groups/14&vmware_support=true
```

### Modifiers

For more complex queries, append a modifier to the property name. For example:\
&#x20;`GET /api/v2/volumes?name__contains=oracle`.

<table><thead><tr><th width="225.9259033203125">Modifier</th><th>Description</th></tr></thead><tbody><tr><td><code>__contains</code></td><td>Field contains the exact string given.</td></tr><tr><td><code>__contains_some</code></td><td>Field contains any substring of the given string.</td></tr><tr><td><code>__gt</code></td><td>Greater than (numeric fields only).</td></tr><tr><td><code>__lt</code></td><td>Less than (numeric fields only).</td></tr><tr><td><code>__gte</code></td><td>Greater than or equal to (numeric fields only).</td></tr><tr><td><code>__lte</code></td><td>Less than or equal to (numeric fields only).</td></tr><tr><td><code>__neq</code></td><td>Field value is not equal to the given string.</td></tr><tr><td><code>__in</code></td><td>Accepts a comma-separated list (for example <code>val1,val2,val3</code>) and matches objects whose field contains any of these values.</td></tr><tr><td><code>__prefix</code></td><td>Field value starts with the given string.</td></tr><tr><td><code>__regexp</code></td><td>Field value matches the given regular expression.</td></tr></tbody></table>

## Examples

{% tabs %}
{% tab title="Get by ID" %}

```http
GET /api/v2/volumes/1
```

```json
{
  "name": "OracleTest1",
  "size": 128000000000,
  "volume_group": { "ref": "/volume_groups/1" },
  "description": "Run tests on Oracle",
  ...
}
```

{% endtab %}

{% tab title="Sort" %}
Return a host list ordered by type and then by name, in ascending order.

```http
GET /api/v2/hosts?__sort=type,name&__sort_order=asc
```

```json
{
  "hits": [
    {
      "auth_profiles_count": 0,
      "connectivity_type": "iSCSI",
      "host_group": null,
      "host_group_id": null,
      "host_type": "single",
      "id": 4,
      "is_part_of_group": false,
      "name": "d9fb-o5sf7-6",
      "type": "Linux",
      "views_count": 0,
      "volumes_count": 34
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 1
}
```

{% endtab %}

{% tab title="Page" %}
Return one host, starting from the second, using default ordering.

```http
GET /api/v2/hosts?__limit=1&__offset=1
```

```json
{
  "hits": [
    {
      "auth_profiles_count": 0,
      "connectivity_type": "iSCSI",
      "host_group": null,
      "host_group_id": null,
      "host_type": "single",
      "id": 5,
      "is_part_of_group": false,
      "name": "d9fb-j2kmb-4",
      "type": "Windows",
      "views_count": 0,
      "volumes_count": 25
    }
  ],
  "limit": 1,
  "offset": 1,
  "total": 2
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.silk.us/api-reference/using-the-api/url-structure-and-filtering.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
