[SOLVED] API Function call not working

Can I please have some help with the API function call as below. I have read many of the others and from what I see it should work however there must be something I am missing.
Photon Code:

int bailnumber(String command);
void setup() {
  Particle.function("Data_Ret", bailnumber);
void loop() {
int bailnumber(String command)
    if(command == "B01"){
        return 100;
            return -1;

Postman API Call:
call: https://api.particle.io/v1/devices/{DeviceID}/Data_Ret?access_token={accesstoken}&args=B01

  "id": "{DeviceID}",
  "last_app": "",
  "connected": true,
  "return_value": -1

Why is it returning -1 when it should return 100. also tested with @Moors7here which didn’t return anything.
BTW it works through Porter.

Mod Edit @harrisonhjones: Formatting

Are you making a POST request? Both access token and args should be form variables

Yes making POST request.

I have followed the particle class example and can get the function to work though it still doesn’t accept the args=coffee when using Postman. However it works when I use Porter. Can I please be pointed in the right direction regarding how to implement args=coffee

Good practice in debugging would be to print out your variables in question to see what you actually getting.
Never only assume things, always confirm your assumtions :wink:

1 Like

Thanks @ScruffR. I’m not assuming and only following what is in other forums and obviously I don’t have a clear understanding what is shown.
So what does the -d in

-d access_token=123412341234
-d “args=coffee”

mean and what do I use to test the example when I haven’t seen it implemented anywhere else. The particle example doesn’t explain it either.

I do understand micro controllers however web code not so much :confused:


If you haven’t curl on your system (Linux and Mac OS come with it AFAIK), install it :wink:
That helps testing the doc samples.

And that command should be

curl https://api.particle.io/v1/devices/0123456789abcdef/brew -d access_token=123412341234 -d "args=coffee"

where the -d marks the following parameter as DATA parameter and in that context implicitly also causes curl to issue a POST request.

But as it seems the request reaches the device but your data is somehow wrong.

Hence Serial.println(command) or Particle.publish("debug", command, PRIVATE) might give you some clue.

1 Like

Awesome thanks @ScruffR that all worked great. I have seen Curl though did not know it could be installed in terminal. Pity its not noted in the examples then I wouldn’t have to annoy the elites.


That’s probably organisational blindness - since it’s so obvious for us, we wouldn’t think that’s something that needs to be explicitly told … till someone proves that assumption wrong :sunglasses:

It is here in the doc:



Thanks @bko. Thats cool that this is in the FAQ however if you don’t know what curl is for you are not going to look for it if it is not stated in example docs. Personally I have been with Particle from the inception and a lot of these docs weren’t here. Particle has grown super fast with enhancements added frequently.
Particle is absolutely brilliant as well as the community like you you guys who support it. Your knowledge with all this is huge though like @ScruffR said

For some of us we only need to learn small parts of things to get our projects to work, hope that makes sense.

Keep up the great work fellas and thanks again for your dedications to this forum

I didn’t know what it was either. Then I Googled a bit. Found out what it was. Tried it. Disliked the fact that it was more complicated/abstract/vague than it was helpful. Moved on to @bko’s excellent tutorials. Never looked back :innocent:


You can also import CURL requests in Postman. That might help the request make more sense since it will show how the variables are set via a UI.


LesG, I feel your pain and went through the same grief. What is obvious to some is not to all!

And, if i remember correctly, the native curl on Windows worked differently than the curl we download, which also drove me nuts for some time.

here are some curl tidbits I have collected:

to get all access tokens from cli
curl https://api.particle.io/v1/access_tokens -u {email}:{password}

to get details of device (use spark-ide token)
curl https://api.particle.io/v1/devices/{device name}?access_token=1234

to get variable value
curl https://api.particle.io/v1/devices/{device name}/var1?access_token=1234

to get stream data
curl https://api.particle.io/v1/devices/events?access_token=1234

calling a function
curl https://api.particle.io/v1/devices/{device ID}/led -d arg=“off” --data-urlencode access_token=1234
or (since data-urlencode is implied)
curl https://api.particle.io/v1/devices/{device ID}/led -d arg=“off” -d access_token=1234
or (just because)
curl -H “Authorization: Bearer 1234(token)” https://api.particle.io/v1/devices/{device ID}/digitalwrite -d “arg=D7,HIGH”

hey thanks heaps @jventerprises for this info. Really appreciate u taking the time to offer this. Cheers

1 Like

Hey Les, can we mark this topic [SOLVED] now? If not, how else can we help?

For those who may not wish to install curl, here is a web based debugger for Particle devices, written and hosted by my friend and co-developer Jim Schrempp. It is extremely easy and intuitive to use and you do not have to copy out device id’s and access tokens, as it uses the Spark.js library:


The web page provides a “login to Spark” button. Click on it and you get the standard Particle login panel. Log in just as you would to the Particle web, and you then get a pick list of all of the Particle devices registered to your account. Simply select the device that you want to test, and you will then see a page with all of your device’s cloud functions and cloud variables. To retrieve and display a cloud variable, click on its button. To call a function, enter the argument (as a string), if any, and click the button. The returned value (if any) will also be displayed. Like I said, easy to use and completely intuitive.

Jim wrote this to help us debug a rather complex Particle project called SIS (see: https://github.com/TeamPracticalProjects/SISProject, if you are interested). However, it is completely general in nature and will work with any Particle device that exposes variables and/or functions to the Particle cloud.