cURL (Windows)
curl -X DELETE "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID?logout_only=true" -H "apikey: YOUR_API_KEY"const options = {method: 'DELETE', headers: {apikey: '<api-key>'}};
fetch('https://api.bulkneo.com/v1/instances/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.bulkneo.com/v1/instances/{id}"
headers = {"apikey": "<api-key>"}
response = requests.delete(url, headers=headers)
print(response.text){
"success": true,
"data": {
"instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
"deleted": true
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "invalid_request",
"message": "Field \"text\" is required and must be a non-empty string."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "invalid_api_key",
"message": "Invalid or revoked API key."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "trial_quota_exceeded",
"message": "Trial message quota reached (500 messages). Upgrade to a paid plan to keep sending.",
"details": {
"trial_message_limit": 500
}
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "instance_not_found",
"message": "Instance not found. Check the instance_id and that it belongs to your account."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded, retry in 12s.",
"details": {
"retry_after_seconds": 12,
"limit_per_minute": 20,
"scope": "messages"
}
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "internal_error",
"message": "An unexpected error occurred."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "upstream_unavailable",
"message": "The messaging service is temporarily unavailable. Please retry shortly."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}Instances
Disconnect or delete a number
DELETE /v1/instances/{id} — sign WhatsApp out, or remove the instance entirely.
DELETE
/
v1
/
instances
/
{id}
cURL (Windows)
curl -X DELETE "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID?logout_only=true" -H "apikey: YOUR_API_KEY"const options = {method: 'DELETE', headers: {apikey: '<api-key>'}};
fetch('https://api.bulkneo.com/v1/instances/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.bulkneo.com/v1/instances/{id}"
headers = {"apikey": "<api-key>"}
response = requests.delete(url, headers=headers)
print(response.text){
"success": true,
"data": {
"instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
"deleted": true
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "invalid_request",
"message": "Field \"text\" is required and must be a non-empty string."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "invalid_api_key",
"message": "Invalid or revoked API key."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "trial_quota_exceeded",
"message": "Trial message quota reached (500 messages). Upgrade to a paid plan to keep sending.",
"details": {
"trial_message_limit": 500
}
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "instance_not_found",
"message": "Instance not found. Check the instance_id and that it belongs to your account."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded, retry in 12s.",
"details": {
"retry_after_seconds": 12,
"limit_per_minute": 20,
"scope": "messages"
}
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "internal_error",
"message": "An unexpected error occurred."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}{
"success": false,
"error": {
"code": "upstream_unavailable",
"message": "The messaging service is temporarily unavailable. Please retry shortly."
},
"request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}The playground on this page is live. There is no test mode and no sandbox: pressing Send authenticates with the key you paste and really calls
https://api.bulkneo.com — a send delivers a real WhatsApp message to the number you type, and an instance call really changes your account. Use your own number while you are exploring, and paste a key only from a machine you trust.Your browser remembers what you type into the playground, so a key you paste here is still in the Authorization box on your next visit. Nobody else sees it — it never leaves your machine and it is not part of this site — but on a shared or borrowed computer, clear the site data when you are done.logout_only query parameter decides which.
Read this before you call it. Deleting is permanent: the
instance_id stops working forever, and anything in your code holding it will start returning 404 instance_not_found.The two modes
Disconnect — logout_only=true
Signs WhatsApp out but keeps the instance.
instance_idstays valid- Reconnect by scanning again
- Nothing to change in your code
{ "status": "close", "disconnected": true }.Delete — no parameter
Removes the instance permanently.
instance_idstops working- You would have to create a new one and redeploy
- Frees the slot on your account
{ "deleted": true }.Exactly what each value does
The flag is never guessed at. A value we cannot read is refused, and nothing on your account changes.| You send | What happens |
|---|---|
logout_only=true, =1, =yes, =on (any capitalisation) | Disconnect. The instance and its instance_id survive. |
logout_only=false, =0, =no, =off | Delete permanently — you asked explicitly. |
No logout_only parameter at all | Delete permanently — the long-standing default for a bare DELETE. |
Any other value — =2, =y, =maybe, the literal undefined | 400 invalid_request. Nothing is deleted, nothing is disconnected. |
A bare ?logout_only with no value | 400 invalid_request. Nothing changes. |
The parameter sent twice (?logout_only=true&logout_only=false) | 400 invalid_request. Nothing changes. |
A misspelled name — ?logoutOnly=true, ?logout-only=true, ?logout=true | 400 invalid_request telling you the correct name. Nothing changes. |
If you are building the query string from a variable, this is the case that matters:
?logout_only=${flag} with an undefined flag sends the literal text undefined, and that now returns a 400 instead of destroying the instance.Which one do you want?
| Situation | Use |
|---|---|
| The number keeps dropping and you want a clean re-pair | logout_only=true, then re-scan |
| You are handing the phone to someone else temporarily | logout_only=true |
| You are done with this number for good | Delete |
| You need the slot for a different number | Delete |
If a number has simply gone offline, you usually need neither. Just re-scan the QR on the existing instance — see If your number disconnects.
Examples
curl -X DELETE "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID?logout_only=true" \
-H "apikey: YOUR_API_KEY"
curl -X DELETE "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID?logout_only=true" -H "apikey: YOUR_API_KEY"
curl -X DELETE "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID" \
-H "apikey: YOUR_API_KEY"
curl -X DELETE "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID" -H "apikey: YOUR_API_KEY"
Node.js — never let a falsy variable decide
// Send the parameter only when you actually mean "disconnect". Do not
// interpolate a variable into the query string and hope it renders as "true".
const url = new URL(`https://api.bulkneo.com/v1/instances/${instanceId}`);
if (disconnectOnly) url.searchParams.set("logout_only", "true");
const res = await fetch(url, {
method: "DELETE",
headers: { apikey: process.env.BULKNEO_API_KEY },
});
Deleting or disconnecting a number does not credit anything back for the day it was already active. Reconnecting the same number later the same day costs nothing extra.
Authorizations
Your API key, sent in an apikey request header. Never in the URL, never as a Bearer token.
Path Parameters
The instance_id of one of your numbers.
Query Parameters
true, 1, yes or on (any capitalisation) disconnect WhatsApp and KEEP the instance. false, 0, no or off delete it, as does omitting the parameter entirely. Any other value — including an empty one, and the parameter sent twice — returns 400 invalid_request and changes nothing.
Available options:
true, 1, yes, on, false, 0, no, off 
