HTTP API: Making Progress But a Few Questions

I discovered that the API documentation note Requests - API Reference - Blues Developers has a “curl” example for a number of the requests.

Pro-tip: running curl with the --libcurl filename.c option generates a c file with the libcurl translation of the curl command.

So I am making progress.

I have a couple observations however:

  1. The Notehub events web page does not seem consistent with what I fetch via http. For example, I deleted all the notes, added some notes with HTTP, and pulled those notes with HTTP. The web page shows the added notes but with I pulled the notes I got some stale ones (i.e. those which had been deleted). At the moment, the web page shows 4 notes but I pulled 7 (now 5 because I deleted a couple).

  2. The API suggests (?) that you can ask note.changes with delete to true (something like

{“req”:“note.changes”,“file”:“data.qi”, “delete”:true}

and the notes which are received are deleted from Notehub. I get the notes, but they are not deleted. Repeated note.changes deliver the same notes with delete:true. I observe in the API example there is a curl Peek but no curl Pop example which may be telling.

I can, however, explicitly delete a note with note.delete, but this requires a transaction for each note.

I realize the API may be a work in progress but I thought I’d ask.

Hi @BrianP ,

When you say you “deleted all the notes”, did you do that in the UI by selecting notes and deleting them?

Yes, I did it on the Notehub Events web page. I selected them all and clicked delete. Then the page was blank until I added some more.

I just double checked: I added 3 notes with test May 13 -1, 2, 3 and on the web page I see 7 notes. When I do a get I get 10.

{“notes”: {
“1:2121”:{“body”:{“api-key1”:“this is another test”}},
“1:2385”:{“body”:{“api-key1”:“this is another test2”}},
“1:2684”:{“body”:{“api-key1”:“this is another test2”}},
“1:2876”:{“body”:{“api-key1”:“this is another test 1”}},
“1:3304”:{“body”:{“api-key1”:“this is another test 2”}},
“1:3352”:{“body”:{“api-key1”:“this is another test 3”}},
“1:3651”:{“body”:{“api-key1”:“this is another test 3”}},
“1:3942”:{“body”:{“api-key1”:“May 13 - 1”}},
“1:4241”:{“body”:{“api-key1”:“May 13 - 2”}},
“1:4428”:{“body”:{“api-key1”:“May 13 - 3”}}

It’s not a big deal but I thought I’d ask.

This can be a bit confusing, I agree, and we’re working on improving the UX in Notehub.

Here is what I think is happening: You are deleting a (pending) inbound note on Notehub. This is effectively saying: “remove this inbound note during the next sync with the Notecard”.

So it will disappear from Notehub, but will still appear in API calls until you perform your next sync with the Notecard. Then it will truly be purged.

OK. I think that makes sense. It’s only an issue because I’m testing my http code.

Any thoughts on delete:true ?

Also - I thought I’d ask - as I write the code I’m asking for a lot of session tokens as I iterate the code. I have never done this sort of code before so I hope that doesn’t cause grief at your end. Its a 32 byte string so I assume I won’t exhaust them before they expire.

If you’re using the API to perform a note.changes request to delete a note, it still won’t truly be purged until there is a sync with the device. It’s basically marking it to be deleted at next sync.

If that’s not the behavior you’re seeing, please let me know so I can do a reproduction locally!

I am a bit confused.

If I am using the HTTP API to look at notes, I assume that in most cases these would be notes sent by the Notecard post sync. That’s not how I’m doing it at the moment, but bear with me.

If I do a note.changes, I want to somehow record the fact that I’ve pull these notes from hub. Hence I’d want to be able to “pop” those notes via an HTTP API request.

I can explicitly delete a note by name and that does not require a sync. This does not seem consistent, plus it requires a lot more work since I have to get the note changes, parse the notes, record the note names, then explicitly deleted them one at a time.

I don’t think that’s a major issue but I would imagine that for something like an Android app where you’d want to limit (billed) traffic it would make sense to do an HTTP pop as you no doubt can with the routes.

If that is not how it currently works, please consider adding it.


Hi @BrianP,

I’m slowly but surely working through a local reproduction of the issue so I can see what’s going on for myself. While I get some help internally, is the following a decent summary of what you are seeing?

Create an inbound note:

curl -L '{productUID}&device={deviceUID}' -H 'X-SESSION-TOKEN: {token}' -d '{"req":"note.add","file":"testing.qi", "body": {"key1":"val1"}}'

Use the note.changes API to query for any updates:

curl -L '{productUID}&device={deviceUID}' -H 'X-SESSION-TOKEN: {token}' -d '{"req":"note.changes","file":"testing.qi"}'

(this returns the added notes)

Use the note.changes API again, but this time with the delete:true parameter:

curl -L '{productUID}&device={deviceUID}' -H 'X-SESSION-TOKEN: {token}' -d '{"req":"note.changes","file":"testing.qi","delete":true}'

And what you would expect now is that those notes would be gone, but instead they still exist on Notehub.

That seems right, except they aren’t just on the Notehub, they are returned with the note.changes.

I realize that it doesn’t make a lot of sense to add a note and then try and remove it via HTTP but I don’t see where the system differentiates so I thought I’d use HTTP for both the add and the changes, plus, note.delete seems to work.

Unless I misunderstand things if I do a note.changes with delete=true, I’d get the changes and they would be deleted again (or at least would be marked as already checked or something.

Imagine I am checking for a note from the Notecard via an application using HTTP (whether Android, Windows, Linux, etc.). I would do a note.changes with delete=true and get the changes, process them, and (unless a new note has been pushed) a subsequent note.changes would return no changes.

Otherwise I have to individually delete the changes reported with note.delete.

Let me know if you can’t replicate so I will capture an exact session showing my results.


Hi @BrianP,

It turns out that you found a bug in the API (which has actually been fixed tonight!). note.changes should properly delete the notes as expected. Please let me know if it solves the issue!


1 Like

Great! (Not great there was a bug but now I don’t worry that I’m wasting your time with finger trouble or misunderstanding the docs …!

I’ll try it out and let you know.

Seems to work! Thanks!

FYI something weird happened. I tested and got good results (i.e. got my notes with deleted:true then got nothing with a second request) then set things aside for about an hour to deal with email. When I returned I pushed another couple notes and asked for changes with delete:true and got all the notes (including the ones which I had 'deleted" in a reply).

I tried pushing some more notes and things worked OK. Perhaps it is the delay before trying which is the problem. I do know that I got back {} from a changes then push a few notes and got all 15

{“notes”:{“1:2121”:{“body”:{“api-key1”:“this is another test”}},“1:2385”:{“body”:{“api-key1”:“this is another test2”}},“1:2684”:{“body”:{“api-key1”:“this is another test2”}},“1:2876”:{“body”:{“api-key1”:“this is another test 1”}},“1:3304”:{“body”:{“api-key1”:“this is another test 2”}},“1:3352”:{“body”:{“api-key1”:“this is another test 3”}},“1:3651”:{“body”:{“api-key1”:“this is another test 3”}},“1:3942”:{“body”:{“api-key1”:“May 13 - 1”}},“1:4241”:{“body”:{“api-key1”:“May 13 - 2”}},“1:4428”:{“body”:{“api-key1”:“May 13 - 3”}},“1:4828”:{“body”:{“api-key1”:“this is another test2”}},“1:5075”:{“body”:{“api-key1”:“May 14 another test2”}},“1:5263”:{“body”:{“api-key1”:“May 14 Test 2”}},“1:5427”:{“body”:{“api-key1”:“May 14 Test 3”}},“1:5650”:{“body”:{“api-key1”:“May 14 Test 4”}}},“total”:15}

Here we go (sorry for the spam)
brian@LAPTOP-70Q5CT1Q:/mnt/c/WINDOWS/system32$ curl -L -d ‘{“req”:“note.changes”,“file”:“data.qi”, “delete”:true}’ --header ‘X-SESSION-TOKEN:’
{“notes”:{“1:8074”:{“body”:{“api-key1”:“May 14 New Test10”}}},“total”:1}

***** delay of about 5 minutes

brian@LAPTOP-70Q5CT1Q:/mnt/c/WINDOWS/system32$ curl -L -d ‘{“req”:“note.changes”,“file”:“data.qi”, “delete”:true}’ --header ‘X-SESSION-TOKEN:’
{“notes”:{“1:8074”:{“body”:{“api-key1”:“May 14 New Test10”}}},“total”:1}

***** ^ the note which should have been deleted

brian@LAPTOP-70Q5CT1Q:/mnt/c/WINDOWS/system32$ curl -L -d ‘{“req”:“note.changes”,“file”:“data.qi”, “delete”:true}’ --header ‘X-SESSION-TOKEN:’

****** ^ now empty


****** delay of about 10 minutes
brian@LAPTOP-70Q5CT1Q:/mnt/c/WINDOWS/system32$ curl -L ‘’ -d ‘{“req”:“note.changes”,“file”:“data.qi”, “delete”:true}’ --header ‘X-SESSION-TOKEN:’
{“notes”:{“1:8074”:{“body”:{“api-key1”:“May 14 New Test10”}}},“total”:1}

***** ^ the note which should have been deleted

brian@LAPTOP-70Q5CT1Q:/mnt/c/WINDOWS/system32$ curl -L -d ‘{“req”:“note.changes”,“file”:“data.qi”, “delete”:true}’ --header ‘X-SESSION-TOKEN:’

****** ^ now empty

Hi @BrianP,

I apologize - I jumped the gun on stating that the fix was in place when I did. In fact, it almost looks like our deploy took place while you were actively testing this exact feature.

So now, for real, this issue should be corrected. Sorry again for the confusion!


I’d check again if I were you. I get the same results (i.e. after a delay of 10 minutes the records are back).

I sort of wonder where they went when they came back though.

I see that on my end as well. Looking into it!

No worries. I’m working on a c test program using libcurl so I can push/pull with the HTTP API programatically. Let me know when they believe they have fixed it and I’ll try again.

One other thing.
In the api doc for changes note Requests - API Reference - Blues Developers the reply is described of the format

“setting-one”: {“body”:{“foo”: “bar”},“time”:1598918235},
“setting-two”: {“body”:{“foo”: “bat”},“time”:1598918245},
“setting-three”: {“body”:{“foo”: “baz”},“time”:1598918225},
“setting-four”: {“body”:{“foo”: “foo”},“time”:1598910532}

Whereas I get (edited)

“1:10194”:{“body”:{“api-key1”:“May 15 a test 2”}},
“1:9979”:{“body”:{“api-key1”:“May 15 a test 1”}}},“total”:2}

So there is no “changes” field. Instead I get a string “1:10194” where 10194 is a unique (?) number and apparently not in sequence in that I can get 1:9979, 1:11111, 1:8074. It does appear that 1:11111 is the most recent note, but it may not be in sequence.

In other words, the notes I get arrive in an apparently random order and I have to sort them (?) based on the string “1:xxxx” to figure out which came first, etc…

Is there any documentation reflecting the nature and limitations of the “1:11111” type field? I note that the field is rolling at a much faster rate than I am sending notes so one concern might be that it grows to arbitrary length or rolls over.

I think the API would be more intuitive if notes.changes returned data in a consistent form (i.e. FIFO or something).


Hi @BrianP,

The changes parameter is not available in the Notehub API (this is a doc issue that I will address). Thanks for pointing that out.

The 1:xxxx value you see is the unique internally-generated key of the note. It’s there for you to use if you want to delete a specific note by ID. I would sort by time and not by the ID.

I will follow up with the team about some kind of consistency in how notes are returned (e.g. FIFO).