Netdata API

Fully typed SDK for the Netdata Cloud & Agent APIs

Generated from the Netdata OpenAPI specs · Works with Vanilla Fetch · React Query · SWR

npm install netdata

Two separate entry points — import whichever API you need:

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

Agent API

Vanilla

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

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

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

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

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

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:

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.