Ressources to use the API needed!

I feel super dumb trying to use the API, yeah the new one: TrueNAS Websocket Documentation

I don’t want to mention how many years I spent coding and using APIs, I’d be even more ashamed.

Seriously, I thought it’d be a 10mn think to start using the API and consolidate an Infra As Code base.

I can’t understand how to read its documentation. It only shows an exemple of connection, and the link to: TrueNAS uses DDP: meteor/packages/ddp/DDP.md at devel · meteor/meteor · GitHub, which isn’t helpful at all.
I can only find few examples on the forum, AI is wrong wrong wrong, I’m stuck.

I’m using midctl hoping for a no-auth quick start:
Shouldn’t this be working?

midclt call pool.snapshottask.query '[{"dataset": "tank/mydataset"}]'

I get a

[EINVAL] query-filters: Item#0 is not valid per list types: [query-filter] Not a list

As i understand it, this only outputs json formatted data. But I only use the API this way, which isn’t the best way.

Agreed, new API docs really could be better. Filters should be list of lists where each item is [key, op, value], possible keys and value types are in second column (or one could just call method without filters and look for anything useful in output), operations are =, !=, >, <

Example to find only enabled tasks for given ds:

midclt call pool.snapshottask.query \
  '[ ["dataset", "=", "pool/name"], ["enabled", "=", true] ]'
1 Like

Just to understand what we’re talking about here, are we referring to the “new” API docs meaning the 13.0 Websocket documentation linked in the first post?

Unfortunately, like the rest of CORE, there aren’t any planned changes to improve on the 13.0 API docs, beyond possible API updates in the case of a security fix.

On a positive note, the actual new API docs coming with 25.04 have been completely rewritten to, among other things, include more how-to content.

midclt call pool.snapshottask.query '[{"dataset": "tank/mydataset"}]'

No that shouldn’t work because {"dataset": "tank/mydataset"} is not a list.
midclt call pool.snapshottask.query '[["dataset", "=", "tank/mydataset"]]'
is a properly-formatted query-filter. We actually have pretty extensive documentation on how to use query-filters under ip of server/api/docs

https://www.truenas.com/docs/scale/24.10/api/scale_websocket_api.html
If you browse to bottom there’s a query-methods section.

We also give some hints about how to translate typical SQL-style syntax into query-filters and query-options via API.

1 Like

Thanks, that’s the proper section to be able to understand how to query the API.
It’s hard to find somehow, I would expect it to be the first section of the documentation

Sounds better that the actual presentation indeed.
Where is this available? Only if you install 25.04? I couldn’t find it on the TN website

It’s available through the 25.04 UI. I don’t know anything about plans for a public URL

2 Likes