API Reference - Programmatic Bin Management

Authentication

All API requests require authentication using your Master Key. You can find your Master Key in theAPI Keys sectionof your dashboard.

Authorization Header

Include your Master Key in the Authorization header of every request:

Authorization: Bearer mk_live_your_master_key_here

Security Note

• Keep your Master Key secure and never expose it in client-side code
• Your Master Key provides full access to all your bins
• You can refresh your Master Key anytime from the dashboard

Base URL

https://www.superbins.io/api/v1

All API endpoints are relative to this base URL. For local development, use http://localhost:3000/api/v1

Endpoints

Create Bin

POST/bins

Creates a new bin with the specified data. Returns the bin details and its public URL.

Request Body

{
  "title": "My Workflow Data",
  "data": {
    "status": "success",
    "result": "workflow completed",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "isPublic": false
}

Parameters

Field	Type	Required	Description
title	string	Yes	Display name for the bin
data	object	Yes	JSON data to store in the bin
isPublic	boolean	No	Whether bin is publicly accessible (default: false)

Example Request

curl -X POST "https://www.superbins.io/api/v1/bins" \
  -H "Authorization: Bearer mk_live_your_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "N8N Workflow Result",
    "data": {
      "workflow_id": "wf_123",
      "status": "completed",
      "processed_items": 42
    },
    "isPublic": false
  }'

Response

{
  "success": true,
  "bin": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "N8N Workflow Result",
    "data": {
      "workflow_id": "wf_123",
      "status": "completed",
      "processed_items": 42
    },
    "isPublic": false,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "url": "https://api.superbins.com/api/b/550e8400-e29b-41d4-a716-446655440000"
  }
}

Get Specific Bin

GET/bins/{id}

Retrieves a specific bin by its ID. You can only access bins that belong to your account.

Example Request

curl -X GET "https://www.superbins.io/api/v1/bins/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer mk_live_your_master_key"

Response

{
  "success": true,
  "bin": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "N8N Workflow Result",
    "data": {
      "workflow_id": "wf_123",
      "status": "completed",
      "processed_items": 42
    },
    "isPublic": false,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "url": "https://www.superbins.io/api/b/550e8400-e29b-41d4-a716-446655440000"
  }
}

Replace Bin (PUT)

PUT/bins/{id}

Completely replaces an existing bin with new data. All fields (title, data, isPublic) are required.

Request Body

{
  "title": "Updated Workflow Data",
  "data": {
    "status": "completed",
    "result": "all tasks finished",
    "processed_count": 156
  },
  "isPublic": true
}

Example Request

curl -X PUT "https://www.superbins.io/api/v1/bins/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer mk_live_your_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated N8N Result",
    "data": {
      "workflow_id": "wf_123",
      "status": "completed",
      "final_count": 156
    },
    "isPublic": true
  }'

Response

{
  "success": true,
  "bin": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Updated N8N Result",
    "data": {
      "workflow_id": "wf_123",
      "status": "completed",
      "final_count": 156
    },
    "isPublic": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T12:30:00Z",
    "url": "https://www.superbins.io/api/b/550e8400-e29b-41d4-a716-446655440000"
  }
}

Partial Update Bin (PATCH)

PATCH/bins/{id}

Updates only the specified fields of an existing bin. You can update any combination of title, data, or isPublic.

Request Body Examples

// Update only the title
{
  "title": "New Title"
}

// Update only the data
{
  "data": {
    "status": "updated",
    "new_field": "new_value"
  }
}

// Update multiple fields
{
  "title": "Updated Title",
  "isPublic": false
}

Example Request

curl -X PATCH "https://www.superbins.io/api/v1/bins/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer mk_live_your_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "status": "in_progress",
      "current_step": 3
    }
  }'

Delete Bin

DELETE/bins/{id}

Permanently deletes a bin and all associated data. This action cannot be undone.

Example Request

curl -X DELETE "https://www.superbins.io/api/v1/bins/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer mk_live_your_master_key"

Response

{
  "success": true,
  "message": "Bin 'Updated N8N Result' deleted successfully",
  "deletedBinId": "550e8400-e29b-41d4-a716-446655440000"
}

List Bins

GET/bins

Retrieves all bins associated with your account, ordered by most recently updated.

Example Request

curl -X GET "https://www.superbins.io/api/v1/bins" \
  -H "Authorization: Bearer mk_live_your_master_key"

Response

{
  "success": true,
  "bins": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "N8N Workflow Result",
      "data": {...},
      "isPublic": false,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T11:45:00Z",
      "url": "https://api.superbins.com/api/b/550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "count": 1
}

N8N Integration Examples

SuperBins is perfect for persisting data between N8N workflow runs. Here are common patterns:

Store Workflow Results

Use the HTTP Request node in N8N to save workflow outputs to a bin:

Method: POST

URL: https://www.superbins.io/api/v1/bins

Headers:

Authorization: Bearer mk_live_your_master_key

Content-Type: application/json

Body:

{ "title": "Workflow {{ $workflow.name }} - {{ $now }}", "data": {{ $json }}, "isPublic": false }

Update Persistent State

Keep a running state bin that gets updated with each workflow execution:

Method: PUT

URL: https://www.superbins.io/api/v1/bins

Body:

{ "id": "your-persistent-bin-id", "title": "App State", "data": { "last_run": "{{ $now }}", "total_processed": {{ $('Calculate Total').first().json.count }}, "status": "{{ $node.statusMessage }}" } }

Error Handling

Status Code	Meaning	Common Causes
400	Bad Request	Missing required fields, invalid JSON
401	Unauthorized	Invalid or missing master key
403	Forbidden	Bin limit reached (free tier)
404	Not Found	Bin doesn't exist or not yours
201	Created	Bin successfully created
200	OK	Request successful

Error Response Format

{
  "error": "title and data are required",
  "success": false
}

Rate Limits & Quotas

Free Tier

• Up to 10 bins total
• 10,000 API requests per month
• Rate limiting applies to bin access

Pro Tier

• Unlimited bins
• Higher rate limits
• Priority support

Get Started

Ready to integrate SuperBins into your workflows? Get your Master Key and start making API calls.

Get Your API Key Create Test Bin