<div align="center">

# Netdata API

**Fully typed SDK for the Netdata Cloud & Agent APIs**

[![npm version](https://img.shields.io/npm/v/netdata?color=cb0000&label=npm&logo=npm)](https://www.npmjs.com/package/netdata)
[![npm downloads](https://img.shields.io/npm/dm/netdata?color=cb0000&logo=npm)](https://www.npmjs.com/package/netdata)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

<sub>Generated from the Netdata OpenAPI specs · Works with **Vanilla Fetch** · **React Query** · **SWR**</sub>

</div>

```sh
npm install netdata
```

Two separate entry points — import whichever API you need:

```ts
import createAgentClient from 'netdata/agent'
import createCloudClient from 'netdata/cloud'
```

---

## Agent API

### Vanilla

```ts
import createAgentClient from 'netdata/agent'

const agent = createAgentClient({ baseUrl: 'http://localhost:19999' })

const { data: nodes } = await agent.GET('/api/v3/nodes')
console.log(nodes?.nodes?.map(node => node.nm))

const { data: cpu } = await agent.GET('/api/v3/data', {
    params: {
        query: {
            contexts: 'system.cpu',
            after: -900,
            points: 60,
            format: 'json2',
            options: ['jsonwrap']
        }
    }
})
console.log(cpu)
```

### React Query

```tsx
import createAgentQueryClient from 'netdata/agent/query'

const rq = createAgentQueryClient({ baseUrl: 'http://localhost:19999' })

function NodesList() {
    const { data, isLoading, error } = rq.useQuery('get', '/api/v3/nodes')

    if (isLoading) return <div>Loading...</div>
    if (error) return <div>Error loading nodes</div>

    return (
        <ul>
            {data?.nodes?.map(node => (
                <li key={node.ni}>
                    {node.nm} ({node.version ?? 'unknown version'})
                </li>
            ))}
        </ul>
    )
}
```

### SWR

```tsx
import createAgentSWR from 'netdata/agent/swr'

const swr = createAgentSWR({ baseUrl: 'http://localhost:19999' })

function ContextsList() {
    const { data, error, isLoading } = swr.useQuery('/api/v3/contexts')

    if (isLoading) return <div>Loading...</div>
    if (error) return <div>Error loading contexts</div>

    return (
        <ul>
            {Object.entries(data?.contexts ?? {}).map(([id, context]) => (
                <li key={id}>
                    {id} ({context.live ? 'live' : 'historic'})
                </li>
            ))}
        </ul>
    )
}
```

---

## Cloud API

### Vanilla

```ts
import createCloudClient from 'netdata/cloud'

const cloud = createCloudClient({
    baseUrl: 'https://app.netdata.cloud',
    headers: {
        Authorization: `Bearer ${process.env.NETDATA_TOKEN}`
    }
})

const { data: spaces } = await cloud.GET('/api/v3/spaces')
console.log(spaces)
```

### React Query

```tsx
import createCloudQueryClient from 'netdata/cloud/query'

const rq = createCloudQueryClient({
    baseUrl: 'https://app.netdata.cloud',
    headers: {
        Authorization: `Bearer ${process.env.NETDATA_TOKEN}`
    }
})

function SpacesList() {
    const { data, isLoading } = rq.useQuery('get', '/api/v3/spaces')

    if (isLoading) return <div>Loading...</div>

    return (
        <ul>
            {data?.spaces?.map(space => (
                <li key={space.id}>{space.name}</li>
            ))}
        </ul>
    )
}
```

### SWR

```tsx
import createCloudSWR from 'netdata/cloud/swr'

const swr = createCloudSWR({
    baseUrl: 'https://app.netdata.cloud',
    headers: {
        Authorization: `Bearer ${process.env.NETDATA_TOKEN}`
    }
})

function SpacesList() {
    const { data, isLoading } = swr.useQuery('/api/v3/spaces')

    if (isLoading) return <div>Loading...</div>

    return (
        <ul>
            {data?.spaces?.map(space => (
                <li key={space.id}>{space.name}</li>
            ))}
        </ul>
    )
}
```

---

## Tips

If your Agent has bearer protection enabled, pass the token when creating the client:

```ts
import createAgentClient from 'netdata/agent'

const agent = createAgentClient({
    baseUrl: 'http://localhost:19999',
    headers: {
        Authorization: `Bearer ${process.env.NETDATA_TOKEN}`
    }
})
```

## Contributing

Contributions are welcome. The OpenAPI specs live in the `openapi/` folder (`agent.json` and `cloud.json`). After updating a spec, regenerate the types with `npm run gen:types` and keep the README examples aligned with the generated clients.


<br />
<br />

<div align="center">
<sub>Made for the Netdata community</sub>
</div>