> For the complete documentation index, see [llms.txt](https://docs.redivis.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.redivis.com/api/client-libraries/redivis-js/getting-started.md).

# Getting started

## Installation

The redivis library is [hosted on npm](https://www.npmjs.com/package/redivis). Use npm, or your package manager of choice, to install:

```bash
npm install redivis
```

The library is an ES module, and runs unchanged in the browser. You can also load it from a CDN, without a build step:

```html
<script type="module">
  import redivis from 'https://cdn.jsdelivr.net/npm/redivis/+esm';
</script>
```

{% hint style="info" %}
When loading the library from a CDN in production, pin a specific version (e.g., `https://cdn.jsdelivr.net/npm/redivis@<version>/+esm`), so that a new release doesn't change your page's behavior.
{% endhint %}

## Example usage

```javascript
import redivis from 'redivis';

const organization = redivis.organization('demo');
const dataset = organization.dataset('cms_2014_medicare_data');
const table = dataset.table('home_health_agencies');

const rows = await table.toRowsArray(100); // An array of row objects
const arrowTable = await table.toArrowTable(); // An Apache Arrow table
```

When referencing datasets, workflows, and tables on Redivis, you should be familiar with the [resource reference syntax](https://docs.redivis.com/api/referencing-resources.md).

{% embed url="<https://observablehq.com/@imathews/climate-notebook>" %}

{% embed url="<https://observablehq.com/@imathews/nine-judges-and-a-world-record>" %}

## Authentication

Public data can be read without authenticating. Whenever a resource requires it, the library authenticates automatically, so you generally don't need to do anything. You can also call [`redivis.authorize()`](https://docs.redivis.com/api/client-libraries/redivis-js/reference/redivis/redivis.authorize.md) to authenticate up front.

### From Node.js (OAuth)

The first time you access a resource that requires authentication, a browser window opens for you to log in to Redivis (if a browser can't be opened, a link is printed instead). Your credentials are then cached in `~/.redivis`, or the directory set by the `REDIVIS_CONFIG_DIR` environment variable, so you only need to log in once. To log out, call [`redivis.deauthorize()`](https://docs.redivis.com/api/client-libraries/redivis-js/reference/redivis/redivis.deauthorize.md).

### From the browser (OAuth)

When a resource requires authentication, a popup prompts the user to sign in to Redivis. The resulting token is held only for the current tab, and is read-only unless more access is required by the request. Since browsers may block popups that aren't opened in response to a user action, you may want to call `redivis.authorize()` from a click handler:

```javascript
button.addEventListener('click', async () => {
  await redivis.authorize();
  // ... read data
});
```

### From a long-running service (API token)

If you are developing a service that regularly interacts with Redivis without human intervention – for example, a recurring job that runs a data ingest pipeline – you can [generate an API token](https://docs.redivis.com/api/rest-api/authorization.md#api-token) to allow the service to act on your behalf.

{% hint style="danger" %}
API tokens must be treated with extreme care, as a leaked token can allow somebody else to act on your behalf. These tokens should be treated like passwords, and never committed to source control, stored as strings in the text of your code, or sent to a user's browser.

API tokens are only required for long-running services that operate without a human actor. If you are engaging with the Redivis API interactively, you should instead use the simpler and more secure OAuth flow mentioned above.
{% endhint %}

In Node.js, set the token as the `REDIVIS_API_TOKEN` [environment variable](https://docs.redivis.com/api/client-libraries/redivis-js/reference.md#environment-variables) before running your script:

```bash
export REDIVIS_API_TOKEN=YOUR_TOKEN
```

Alternatively, provide a token at runtime (it's held in memory only):

```javascript
redivis.authorize({ apiToken: process.env.MY_REDIVIS_TOKEN });
```

### From a web application (API proxy)

To read data in your users' browsers without them having a Redivis account, and without exposing your credentials, route the library's requests through your own server, which adds an API token before forwarding them to `https://redivis.com/api/v1`:

```javascript
redivis.setApiProxy('https://example.com/redivis-proxy');
```

Requests made through a proxy never prompt a login. See [`redivis.setApiProxy()`](https://docs.redivis.com/api/client-libraries/redivis-js/reference/redivis/redivis.setapiproxy.md).

## Node.js and the browser

Everything works in both environments, except for functionality that needs a filesystem, which is only available in Node.js (e.g., downloading files and exports, uploading from a file path etc.). These throw a [`ValueError`](https://docs.redivis.com/api/client-libraries/redivis-js/reference/redivis/redivis.errors.md) in the browser. See [Using in the browser](https://docs.redivis.com/api/client-libraries/redivis-js/examples/using-in-the-browser.md) for more.

## TypeScript

The package includes type declarations, so editors and the TypeScript compiler understand every class, method, and option without any additional packages.

## Learn more

{% content-ref url="/pages/7uOwSeY1BH6UhGFRbHf4" %}
[Reference](https://docs.redivis.com/api/client-libraries/redivis-js/reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MlI0Hk4rLJbwAw2lEzU" %}
[Examples](https://docs.redivis.com/api/client-libraries/redivis-js/examples.md)
{% endcontent-ref %}


---

# 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.redivis.com/api/client-libraries/redivis-js/getting-started.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.
