featurebase/docs/api-reference.md

+++
title = "API Reference"
+++


## API Reference

#### `/index`

##### `GET`

Returns the schema of all indexes in JSON.

Request:
```
curl -XGET localhost:10101/index
```

Response:
```
{"indexes":[{"name":"user","frames":[{"name":"collab"}]}]}
```

#### `/index/<index-name>`

##### `GET`

Returns the schema of the specified index in JSON.

Request:
```
curl -XGET localhost:10101/index/user
```

Response:
```
{"index":{"name":"user"}, "frames":[{"name":"collab"}]}]}
```

##### `POST`

Creates an index with the given name.

The request payload is in JSON, and may contain the `options` field. The `options` field is a JSON object which may contain the following fields:

* `columnLabel` (string): column label of the index.

Request:
```
curl localhost:10101/index/user \
     -X POST \
     -d '{"options": {"columnLabel": "user_id"}}'
```

Response:
```
{}
```

##### `DELETE`

Removes the given index.

Request:
```
curl -XDELETE localhost:10101/index/user
```

Response:
```
{}
```

#### `/index/<index-name>/query`

##### `POST`

Sends a query to the Pilosa server with the given index. The request body is UTF-8 encoded text and response body is in JSON by default.

Request:
```
curl localhost:10101/index/user/query \
     -X POST \
     -d 'Bitmap(frame="language", id=5)'
```

Response:
```
{"results":[{"attrs":{},"bits":[100]}]}
```

In order to send protobuf binaries in the request and response, set `Content-Type` and `Accept` headers to: `application/x-protobuf`.

The response doesn't include column attributes by default. To return them, set `columnAttrs` query argument to `true`.

Request:
```
curl localhost:10101/index/user/query?columnAttrs=true \
     -X POST \
     -d 'Bitmap(frame="language", id=5)'
```
Response:
```
{
  "results":[{"attrs":{},"bits":[100]}],
  "columnAttrs":[{"id":100,"attrs":{"name":"Klingon"}}]
}
```

#### `/index/<index-name>/time-quantum`

##### `PATCH`

Changes the time quantum for the given index. This endpoint should be called at most once right after creating a database.

The payload is in JSON with the format: `{"timeQuantum": "${TIME_QUANTUM}"}`. Valid time quantum values are:

* (Empty string)
* Y: year
* M: month
* D: day
* H: hour
* YM: year and month
* MD: month and day
* DH: day and hour
* YMD: year, month and day
* MDH: month, day and hour
* YMDH: year, month, day and hour

Request:
```
curl localhost:10101/index/user/time-quantum \
     -X POST \
     -d '{"timeQuantum": "YM"}'
```

Response:
```
{}
```

#### `/index/<index-name>/frame/<frame-name>`

##### `POST`

Creates a frame in the given index with the given name.

The request payload is in JSON, and may contain the `options` field. The `options` field is a JSON object which may contain the following fields:

* `rowLabel` (string): Row label of the frame.
* `timeQuantum` (string): [Time Quantum]({{< ref "data-model.md#time-quantum" >}}) for this frame.
* `inverseEnabled` (boolean): Enables [the inverted view]({{< ref "data-model.md#inverse" >}}) for this frame if `true`.
* `cacheType` (string): [ranked]({{< ref "data-model.md#ranked" >}}) or [LRU]({{< ref "data-model.md#lru" >}}) caching on this frame. Default is `lru`.
* `cacheSize` (int): Number of rows to keep in the cache. Default 50,000.

Request:
```
curl localhost:10101/index/user/frame/language \
     -X POST \
     -d '{"options": {"rowLabel": "language_id"}}'
```

Response:
```
{}
```

##### `DELETE`

Removes the given frame.

Request:
```
curl -XDELETE localhost:10101/index/user/frame/language
```

Response:
```
{}
```

#### `/index/<index-name>/frame/<frame-name>/time-quantum`

##### `PATCH`

Changes the time quantum for the given frame. This endpoint should be called at most once right after creating a frame.

The payload is in JSON with the format: `{"timeQuantum": "${TIME_QUANTUM}"}`. Valid time quantum values are:

* (Empty string)
* Y: year
* M: month
* D: day
* H: hour
* YM: year and month
* MD: month and day
* DH: day and hour
* YMD: year, month and day
* MDH: month, day and hour
* YMDH: year, month, day and hour

Request:
```
curl localhost:10101/index/user/frame/language/time-quantum \
     -X POST \
     -d '{"timeQuantum": "YM"}'
```

Response:
```
{}
```

#### `/hosts`

##### `GET`

Returns the hosts in the cluster.

Request:
```
curl -XGET localhost:10101/hosts
```

Response:
```
[{"host":":10101","internalHost":""}]
```

#### `/version`

##### `GET`

Returns the version of the Pilosa server.

Request:
```
curl -XGET localhost:10101/version
```

Response:
```
{"version":"v0.3.0-353-ge633247"}
```