BuiltOn API Documentation
Getting Started
Get Set Up
Setup an Authentication Provider
SDKs
Nuts & Bolts
Authentication
Service Account
Retrieve Items
Expanding Objects
Pagination
Errors
Common GET Parameters
Common Object Fields
Addresses
Images
Templates and Attributes
Building Blocks
Users
Products
Resources
Orders
Subscriptions and Plans
Payments
Webhooks
Machine Learning
Intro to ML
Simple ML
Blueprints (Use Cases)
What Kind of Build?
Sell a Thing
Subscribe!
Powered by GitBook

Resources

We break a Resource into two concepts; a resource as a reusable asset and a retail resource that is meant to be sold.

If not specified, an asset resource is created.

Changes since API version2019-02-01

2019-09-18 - `image` type changed to Object

image changed to Image Object.

2019-09-02 - `image_url` Deprecated

We are deprecating the old image_urland replacing it with Image Object.

Asset Resource Object

Attribute

Type

Description

method

string

The resource type. asset or retail.

user

object

​User associated with the resource.

name

string

Name of the resource item.

description

string

Description of the resource item.

image

object

​Imageobject for this resource.

product

object

​Product associated with the resource.

tags

array

An array of tags.

human_id

string

6 character ID.

status

string

Status of the resource. Default is CREATED, other options are listed below.

Retail Resource Object

In addition to the attributes in the asset resource, the retailresource has the following attributes.

Attribute

Type

Description

_sub_products

array

An array with sub-products associated with the resource.

base_price

number

The sum of the product.price and price in all the _sub_products.

retail_price

number

The amount that this resource is sold for.

currency

string

The currency in the main product in the resource.

vat

number

The VAT from the main product in the resource. A decimal value between 0 and 1, e.g. 0.25 = 25%.

Resource Status

Default status for the resource is CREATED. Change the status by updating the resource.

Status

CREATED

PROCESSING

UTILIZED

IDLE

ON_THE_WAY_FROM

ON_THE_WAY_TO

DONE

User Role

Create a new Resource*

Parameters
HTTP
Core SDK / Node SDK
Parameters

Body Parameters

Type

Description

name

string

Name of the resource item.

product

string

Product ID to be associated with the resource.

description

string

Description of the resource item.

status

string

Status of the resource, default is CREATED other options are PROCESSING, UTILIZED, IDLE.

image

string

Image ID for this resource.

reference_id

string

Customizable ID for the resource

HTTP
Request --
POST /resources HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
  "name": "Electric Scooter W3E7IB",
  "description": "Rent this electric scooter"
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "_id": {"$oid": "596c643ed57ba203be2cf1c9"},
  "method" "asset",
  "name": "Electric Scooter W3E7IB",
  "description": "Rent this electric scooter",
  [...]
}
Core SDK / Node SDK
builton.resources.create({
  name: 'Electric Scooter W3E7IB',
  description: 'Rent this electric scooter',
}).then(console.log);
​
/*
Resource {
  id: '596c643ed57ba203be2cf1c9',
  method: 'asset',
  name: 'Electric Scooter W3E7IB',
  description: 'Rent this electric scooter',
  [...]
}
*/

Update a Resource*

Parameters
HTTP
Core SDK / Node SDK
Parameters

Path Parameter

Type

Description

resource_id

string

The resource’s ID

Body Parameters

Type

Description

name

string

Name of the resource item.

description

string

Description of the resource item.

user

string

User ID to be associated with a user.

status

string

Status of the resource. Default is CREATED; other options are PROCESSING, UTILIZED or IDLE.

product

string

​Product ID to be associated with the resource.

image

string

Image object for this resource.

reference_id

string

Customizable ID for the resource.

HTTP
Request --
PUT /resources/596c643ed57ba203be2cf1c9 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
  "name": "Electric Scooter Q2EW6UV",
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "_id": {"$oid": "596c643ed57ba203be2cf1c9"},
  "method" "asset",
  "name": "Electric Scooter Q2EW6UV",
  "description": "Rent this electric scooter",
  [...]
}
Core SDK / Node SDK
builton.resources.update('596c643ed57ba203be2cf1c9', {
  name: 'Electric Scooter Q2EW6UV',
}).then(console.log);
​
/*
Resource {
  id: '596c643ed57ba203be2cf1c9',
  method: 'asset',
  name: 'Electric Scooter Q2EW6UV',
  description: 'Rent this electric scooter',
  [...]
}
*/

Retrieve a Resource by ID*

Parameters
HTTP
Core SDK / Node SDK
Parameters

Path Parameter

Type

Description

resource_id

string

The resource’s ID.

HTTP
Request --
GET /resources/596c643ed57ba203be2cf1c9 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
​
{
  "_id": {"$oid": "596c643ed57ba203be2cf1c9"},
  "method" "asset",
  "name": "Electric Scooter Q2EW6UV",
  "description": "Rent this electric scooter",
  "product": {"$oid": "58f9f856b70e2a56c4a0db3d"},
  "image": {"$oid": "596c643ed57ba203be2cf2c9"},
  [...]
}
Core SDK / Node SDK
builton.resources.get('596c643ed57ba203be2cf1c9').then(console.log);
​
/*
Resource {
  id: '596c643ed57ba203be2cf1c9',
  method: 'asset',
  name: 'Electric Scooter Q2EW6UV',
  description: 'Rent this electric scooter',
  [...]
}
*/

List All Resources*

Parameters
HTTP
Core SDK / Node SDK
Parameters

Query Parameters

Type

Description

include_deleted

boolean

If true, the request also returns deleted resources.

size

number

Number of resources per page. Default is 10.

page

number

Defines which page to retrieve. Default is 0.

from_date

number

Start date, timestamp format. Default is None.

to_date

number

End date, timestamp format. Default is None.

sort

string

Field used to sort results. Default is -created.

status

string

Status of the resource. Default is CREATED; other options are PROCESSING, UTILIZED or IDLE

HTTP
Request --
GET /resources HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
​
[
  {
    "_id": {"$oid": "596c643ed57ba203be2cf1c9"},
    "method" "asset",
    "name": "Electric Scooter Q2EW6UV",
    "description": "Rent this electric scooter",
    "product": {"$oid": "58f9f856b70e2a56c4a0db3d"},
    "image": {"$oid": "596c643ed57ba203be2cf2c9"},
    [...]
  },
  [...]
]
Core SDK / Node SDK
builton.resources.get().then(page => {
  console.log(page.current); // First page
});
​
/*
[
  Resource {
    id: '596c643ed57ba203be2cf1c9',
    method: 'asset',
    name: 'Electric Scooter Q2EW6UV',
    description: 'Rent this electric scooter',
    [...]
  },
  [...]
]
*/

Search Resources by Keywords*

Search by _id, name, reference_id, description and image_url. Returns an array that matches the query. Filter the query by using pagination.

Parameters
HTTP
Core SDK / Node SDK
Parameters

Query Parameters

Type

Description

query

string

Partial or full string of name, reference_id, description or image_url.

include_deleted

boolean

If true, the request also returns deleted resources.

size

number

Number of resources per page. Default is 10.

page

number

Defines which page to retrieve. Default is 0.

from_date

number

Start date, timestamp format. Default is None.

to_date

number

End date, timestamp format. Default is None.

sort

string

Field used to sort results. Default is created.

HTTP
Request --
GET /resources/search?query=electric HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
​
[
  {
    "_id": {"$oid": "596c643ed57ba203be2cf1c9"},
    "method" "asset",
    "name": "Electric Scooter Q2EW6UV",
    "description": "Rent this electric scooter",
    "product": {"$oid": "58f9f856b70e2a56c4a0db3d"},
    "image": {"$oid": "596c643ed57ba203be2cf2c9"},
    [...]
  },
  [...]
]
Core SDK / Node SDK
builton.resources.get().then(page => {
  console.log(page.current); // First page
});
​
/*
[
  Resource {
    id: '596c643ed57ba203be2cf1c9',
    method: 'asset',
    name: 'Electric Scooter Q2EW6UV',
    description: 'Rent this electric scooter',
    [...]
  },
  [...]
]
*/

Admin Role

*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.

Create new Resources in Bulk

Parameters
HTTP
Parameters

Body Parameters

Type

Description

name

string

Name of the resource item.

description

string

Description of the resource item.

user

string

User ID to be associated with a User.

status

string

Status of the resource _default is CREATED other options are PROCESSING, UTILIZED, IDLE

product

string

Product ID to be associated with the resource.

image

string

Image ID for this resource.

reference_id

string

Customizable ID for the resource.

HTTP
Request --
POST /resources/bulk HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
[
  {
    "product": "58f9f856b70e2a56c4a0db3d",
    "method": "asset",
    "name": "First resource"
  },
  {
    "product": "58f9f856b70e2a56c4a0db3d",
    "method": "asset",
    "name": "Second resource"
  }
]
Response --
HTTP/1.1 200 OK
Content-Type: application/json
​
[
  {
    "_id": {"$oid": "596c643ed57ba203be2cf1c9"},
    "product": "58f9f856b70e2a56c4a0db3d",
    "method" "asset",
    "name": "First resource",
    [...]
  },
  {
    "_id": {"$oid": "57ee9c71d76d431f8511142f"},
    "product": "58f9f856b70e2a56c4a0db3d",
    "method" "asset",
    "name": "Second resource",
    [...]
  }
]

Delete a Resource

Parameters
HTTP
Node SDK
Parameters

Path Parameters

Type

Description

<resource_id>

string

ID of the resource to be deleted.

HTTP
Request --
DELETE /resources/596c643ed57ba203be2cf1c9 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "_id": {"$oid": "596c643ed57ba203be2cf1c9"},
    "method" "asset",
  "name": "Electric Scooter W3E7IB",
  "description": "Rent this electric scooter",
    "deleted": true,
}
Node SDK
builton.resources.del('5e5e7580a66b2a00089308b5').then(console.log);
​
/*
  Resource {
    id: '596c643ed57ba203be2cf1c9',
    method: 'asset',
    name: 'Electric Scooter Q2EW6UV',
    description: 'Rent this electric scooter',
    delete: true
  }
*/
Building Blocks - Previous
Products
Next - Building Blocks
Orders
3
Last updated 4 weeks ago
Contents
Asset Resource Object
Retail Resource Object
Resource Status
User Role
Create a new Resource*
Update a Resource*
Retrieve a Resource by ID*
List All Resources*
Search Resources by Keywords*
Admin Role
Create new Resources in Bulk
Delete a Resource