Buildbotics API

BuildBotics API


This document describes the resources that are accessible through the BuildBotics API.

This section describes the details of the protocol and the following sections describe individual data models and their API calls.


All API access is over HTTP, and accessed from the root URL All data is sent and received as JSON.

In the API docmentation the root URL and HTTP version are left off. So for example:

PUT /users/{name}/follow

is actually:

PUT{name}/follow HTTP/1.1


API methods may take optional parameters. These request parameters may be specified as follows:

  1. URL parameters as part of the URL path.
  2. As HTTP query string parameters.
  3. As JSON encoded data with Content-Type: application/json.

URL parameters are specified using curly braces. For example:

PUT /users/{name}/follow

In the above case {name} is a URL parameter.

For POST, PUT and DELETE request parameters not included in the URL path should be encoded as JSON.


This section describes how data types are defined in this document.


Types are denoted in this document by a keyword enclosed with < and >. For example: <name> or <integer>.

Compound types are defined a dictionaries of keywords followed by their type definition. For example:

  a: <string>
  b: <bool>
  c: <integer>


Data model inheritance is denoted as follows:

<child>(<parent>) = {
  # Child property definitions here

Meaning the <child> model being defined, inherits all the properties of <parent> model.


Type definitions may be followed by range definitions. For example:


In the case of a number, this indicates the numbers range is from 0 to 64 inclusive. In the case of a string or array it refers to it's length.

Model Comments

Type definitions may also include comments which follow a # sign. For example a complete type definition may appear as follows:

  a: <string> (2,120) # A string, 2 to 120 characters long.
  b: <bool>
  c: <integer> (0,100) # An integer in the range 0 to 100 inclusive.


<name> = <string> (2,64) # Matching regex [A-Za-z0-9][A-Za-z0-9_-]{1,63}

A <name> is a <string> with length (2,64) containing only [A-Za-z0-9_-] and not starting with '_' or '-'.


<ref> = <name>/<name>

A <ref> references a thing as owner name slash thing name. For example, jimmy/fun_with_lasers.


<date> = <string> # In ISO 8601 format

All dates and times are in ISO 8601 format :YYYY-MM-DDTHH:MM:SSZ

Email Addresses

<email_address> = <string> # In RFC 28822 Section 3.4.1 format

Email addressees are formatted as described in RFC 2822 Section 3.4.1.


<markdown> = <string> (0,10KiB) # In Markdown format

Many text fields are in Markdown format. GitHub flavored markdown is also allowed.

Media types

<media_type> = <string> # As defined by

Media types, AKA mime types, are defined by


In case of error, HTTP status codes are returned. These codes are defined by RFC 2068 Section 10 and RFC 4918 Section 11.

Possible errors include:

Other HTTP error codes may be returned where appropriate.

More details about an error may be returned as JSON data defined as follows:

<errors> = [<error>...]

<error> = {
  message: <string>
  code: <integer>
  field: <name> # (Optional) The name of the field in error.

Error Codes

Error Code Description
required The specified field is not optional.
invalid The specified field is invalid.
exists The resource already exists and cannot be created.

HTTP Verbs

This API uses the following HTTP Verbs as described below.


Authentication is provided by third-party providers exclusively. These are as follows:

Provider Type
Google+ OAuth 2.0 API
Facebook OAuth 2.0 API
GitHub OAuth 2.0 API
Twitter OAuth 1.0a API

One or more of these third-parties may be used to associate logins and verified email addresses with the BuildBotics API.


Various API calls require different levels of authorization. Authorization is handled through the badge system and ownership. For example, adding a new license type might require the admin badge whereas editing a project would require that either the user is the owner or has a badge sufficient to override the ownership requirement.

In case a user attempts an operation for which they are not authorized, a 403 Forbidden or possibly 404 Not Found HTTP response code will be returned.


Request which return multiple items are paginated. By default 20 items are returned per call. Each item is supplied with an offset key which tells where it is in the stream.


Name Type Description
limit <integer> (1,100) Default 30. Items per page.
next <string> Key of the item just before the requested page.
prev <string> Key of the item just after the requested page.

Either next or prev may be provided but not both. Both parameters should be copied from the <owner>/<name> of a previous request.

Rate Limiting

Rate limits are as follows:

User Max Requests in
Past 5 Minutes
Unauthenticated 50
Authenticated 200

If you exceed the rate limit 503 Service Unavailable will be returned.



GET /auth/{provider}

Where {provider} is one of:

Login Callback

GET /auth/{provider}/callback


GET /auth/logout

Get Active User Profile

GET /auth/user






Profile Model

User profiles are defined as follows:

<profile> = {
  owner: <name>
  joined: <date>
  fullname: <string> (0,120)
  location: <string> (0,255)
  avatar: <url>
  bio: <markdown>
  url: <url>
  followers: <integer>
  following: <integer>
  stars: <integer>
  points: <integer>
  badges: <integer>

Get user profile

GET /users/{name}



GET /users/johndoe HTTP/1.1


Status: 200 OK
Content-Type: application/json
  owner: "johndoe",
  joined: "2014-09-27T07:15:05Z",
  fullname: "John Doe",
  avatar: "",
  bio: "John is an avid builder...",
  url: "",
  followers: 2,
  following: 2,
  stars: 10,
  points: 10305,
  badges: 1

Update user profile

PUT /users/{name}


Name Type Description
avatar <url> URL to user's avatar.
bio <markdown> User's public biography.
url <url> Link to user's home page.
disabled <bool> Disable the account.

Other profile parameters cannot be changed with this API call.


PUT /users/johndoe HTTP/1.1
  bio: "I like turtles.",
  url: "",
Status: 200 OK

List who a user is following

GET /users/{name}/following

List user followers

GET /users/{name}/followers

Follow User

PUT /users/{name}/follow


PUT /users/johndoe/follow HTTP/1.1
Status: 200 OK

Unfollow User

DELETE /users/{name}/follow


DELETE /users/johndoe/follow HTTP/1.1
Status: 200 OK

List user stars

GET /users/{user}/stars


  projects: [<ref>...]
  machines: [<ref>...]
  tools: [<ref>...]

A list of projects the user has starred.

List user badges

GET /users/{user}/badges

Grant a badge

PUT /users/{user}/badges/{badge}

Revoke a badge

DELETE /users/{user}/badges/{badge}


Name Type Description
reason <markdown> The reason the badge was revoked.


Settings Model

<settings> = {
  accounts: [<account>...]
  email: [<email>...] (0,8)
  notifications: <notifications>
<account> = {
  type: <string>  # google, twitter, facebook, github
  id: <string>
  primary: <bool>
<email> = {
  address: <email_address>
  verified: <bool>
  primary: <bool>
<notifications> = {
  enabled: <bool>
  project_comments: <bool>
  project_starred: <bool>
  when_followed: <bool>
  comment_referenced: <bool>
  stared_project_updates: <bool>
  stared_project_comments: <bool>

Associate an account

PUT /accounts/{type}

Only one account of each type can be associated at a time.


Name Type Description
id <string> Account ID
primary <bool> Is the primary account?

Disassociate an account

DELETE /accounts/{type}

Must not be the primary account.

Get email addresses

GET /emails

Add email address

PUT /emails/{email_address}


Name Type Description
primary <bool> Make this the primary email address.

Remove email address

DELETE /emails/{email_address}

Get notification settings

GET /notifications

Set notification settings

PUT /notifications


enabled<bool> Enable or disable all notifications.
project_comments<bool> Comments on the owner's project.
project_starred<bool> Stars on the owner's project.
project_duplicated<bool> When a project is duplicated.
when_followed<bool> Someone followed the owner.
comment_referenced<bool> The owner's comment was referenced.
stared_project_updates<bool> A project the owner starred was updated.
stared_project_comments<bool> A project the owner starred was commented.


a <thing> is an abstract model from which <project>, <machine> and <tool> inherit.

Thing Model

<thing> = {
  name: <name>
  owner: <name>
  creation: <date>
  modified: <date>
  parent: <ref>
  published: <bool>
  url: <url>
  license: <string> (2,120)
  brief: <markdown> (0,200)
  description: <markdown>
  comments: <integer>
  stars: <integer>
  tags: [<tag>...] (0,64)
  duplications: <integer>
  files: [<file>..] (0,64)

Get a list of things

GET /users/{user}/projects
GET /users/{user}/machines
GET /users/{user}/tools
GET /users/{user}/tools/{tool}/children

See Search.

Create or update a thing

PUT /users/{user}/projects/{project}
PUT /users/{user}/machines/{machine}
PUT /users/{user}/tools/{tool}
PUT /users/{user}/tools/{tool}/children/{tool}


Name Type Description
url <url> A URL to more information about the thing.
license <string> One of the available license names.
published <bool> True to publish the thing publicly.
description <markdown> The thing description.

Get a thing

GET /users/{user}/projects/{project}
GET /users/{user}/machines/{machine}
GET /users/{user}/tools/{tool}
GET /users/{user}/tools/{tool}/children/{tool}

Rename a thing

PUT /users/{user}/projects/{project}
PUT /users/{user}/machines/{machine}
PUT /users/{user}/tools/{tool}
PUT /users/{user}/tools/{tool}/children/{tool}


Name Type Description
name <name> The new thing name.

Duplicate a thing

PUT /users/{user}/projects/{project}
PUT /users/{user}/machines/{machine}
PUT /users/{user}/tools/{tool}


Name Type Description
ref <ref> A reference to the parent owner and thing.

Delete a thing

DELETE /users/{user}/projects/{project}
DELETE /users/{user}/machines/{machine}
DELETE /users/{user}/tools/{tool}
DELETE /users/{user}/tools/{tool}/children/{tool}

List thing stars

GET /users/{user}/projects/{project}/stars
GET /users/{user}/machines/{machine}/stars
GET /users/{user}/tools/{tool}/stars



A list of users who have starred this thing.

Star a thing

PUT /users/{user}/projects/{project}/star
PUT /users/{user}/machines/{machine}/star
PUT /users/{user}/tools/{tool}/star

Unstar a thing

DELETE /users/{user}/projects/{project}/star
DELETE /users/{user}/machines/{machine}/star
DELETE /users/{user}/tools/{tool}/star

Tag a thing

PUT /users/{user}/projects/{project}/tags/{tag}
PUT /users/{user}/machines/{machine}/tags/{tag}
PUT /users/{user}/tools/{tool}/tags/{tag}

Untag a thing

DELETE /users/{user}/projects/{project}/tags/{tag}
DELETE /users/{user}/machines/{machine}/tags/{tag}
DELETE /users/{user}/tools/{tool}/tags/{tag}


Project Model

Inherits from the thing abstract model.

<project>(<thing>) = {
  machine: <ref>
  tools: {<integer>: <ref>...] (0,64)
  workpiece: <workpiece>
  steps: [<step>...] (0,64)
<workpiece> = {
  material: <image>
  dimensions: <vector>
  offset: <vector>
<vector> = {
  x: <real>
  y: <real>
  z: <real>


Step Model

<step> = {
  name: <name>
  brief: <markdown> (0,200)
  description: <markdown>
  comments: <integer>
  files: [<string>...] (0,8)

Create or update a step

PUT /users/{user}/projects/{project}/steps/{step}


Name Type Description
description <markdown> The step description.
video <url> The step video.

Only approved video URLs are allowed.

Rename a step

PUT /users/{user}/projects/{project}/steps/{step}


Name Type Description
name <name> The new step name.

Reorder a step

PUT /users/{user}/projects/{project}/steps/{step}


Name Type Description
position <integer> Required. New position of the step.

Delete a step

DELETE /users/{user}/projects/{project}/steps/{step}


Machine Model

Inherits from the thing abstract model.

<machine>(<thing>) = {
  type: <string>          # "cnc", "3d_printer", "laser", "plasma", "lathe"
  units: <string>         # "imperial" or "metric"
  rotation: <string>      # "degrees" or "radians"
  max_rpm: <real>         # Maximum rotational speed
  spin_up: <real>         # Rate of spin up in RPM/sec
  axes: [<axis>...] (1,9)
<axis> = {
  name: <string>        # "x", "y", "z", "a", "b", "c", "u", "v" or "w"
  min: <real>           # in, mm, deg, radians
  max: <real>           # in, mm, deg, radians
  step: <real>          # in or mm
  rapid_feed: <real>    # in/sec or mm/sec
  cutting_feed: <real>  # in/sec or mm/sec
  ramp_up: <real>       # in/sec/sec or mm/sec/sec
  ramp_down: <real>     # in/sec/sec or mm/sec/sec

Create or update a machine

PUT /users/{user}/machines/{machine}


Name Type Description
type <string> A machine type.
units <string> "imperial" or "metric".
rotation <string> "degrees" or "radians".
max_rpm <real> Maximum rotational speed.
spin_up <real> Rate of spin up in RPM/sec.

Create or update an Axis

PUT /users/{user}/machines/{machine}/axes/{axis}


Name Type Description
min <real> Minimum position of axis.
max <real> Maximum position of axis.
step <real> Minimum step.
rapid_speed <real> Fastest rapid speed.
cutting_speed <real> Fastest cutting speed.
ramp_up <real> Ramp up rate.
ramp_down <real> Ramp down rate.

Delete an Axis

DELETE /users/{user}/machines/{machine}/axes/{axis}


Tool Model

<tool>(<thing>) = {
  type: <string>         # "cylindrical", "conical", "ballnose",
                         # "spheroid" or "composite"
  units: <string>        # "imperial" or "metric"
  length: <real>         # Length of cutter
  diameter: <real>       # Diameter a base
  nose_diameter: <real>  # Diameter a tip
  flutes: <integer>      # Number of flutes
  flute_angle: <real>    # Rake angle of the flute
  lead_angle: <real>     # Angle between cutting edge & perpendicular plane
  max_doc: <real>        # Maximum depth of cut
  max_woc: <real>        # Maximum width of cut
  max_rpm: <real>        # Maximum rotational speed
  max_feed: <real>       # Maximum feed rate
  offset: <real>         # Composite tool children only
  children: [<tool>...]} # Composite tools only

Create or update a tool

PUT /users/{user}/tools/{tool}
PUT /users/{user}/tools/{tool}/children/{tool}


Name Type Description
type <string> Tool type.
units <string> "imperial" or "metric"
length <real> Length of cutting area.
diameter <real> Diameter at base of cutting area.
nose_diameter <real> Diameter at tip of cutting area.
flutes <integer> Number of flutes.
lead_angle <real> Flute lead angle.
max_doc <real> Maximum depth of cut
max_woc <real> Maximum width of cut
max_rpm <real> Maximum rotational speed
max_feed <real> Maximum feed rate
offset <real> Maximum feed rate


Comment Model

<comment> = {
  id: <integer>
  owner: <name>
  creation: <date>
  modified: <date>
  ref: <integer>   # A reference to a previous comment.
  text: <markdown>
  deleted: <bool>  # True if the comment was marked as deleted.

List comments

GET /users/{user}/projects/{project}/comments
GET /users/{user}/projects/{project}/steps/{step}/comments
GET /users/{user}/machines{machine}/comments
GET /users/{user}/tools/{tool}/comments

Post a comment

POST /users/{user}/projects/{project}/comments
POST /users/{user}/projects/{project}/steps/{step}/comments
POST /users/{user}/machines/{machine}/comments
POST /users/{user}/tools/{tool}/comments


Name Type Description
ref <integer> A reference to an existing comment.
text <markdown> Required. The comment text.

Update a comment

PUT /users/{user}/projects/{project}/comments/{comment}
PUT /users/{user}/projects/{project}/steps/{step}/comments/{comment}
PUT /users/{user}/machines/{machine}/comments/{comment}
PUT /users/{user}/tools/{tool}/comments/{comment}


Name Type Description
text <markdown> The updated comment text.

Mark a comment deleted

DELETE /users/{user}/projects/{project}/comments/{comment}
DELETE /users/{user}/projects/{project}/steps/{step}/comments/{comment}
DELETE /users/{user}/machines/{machine}/comments/{comment}
DELETE /users/{user}/tools/{tool}/comments/{comment}


File Model

<file> = {
  name: <string> (1,256)
  type: <media_type>
  creation: <date>
  url: <url>
  downloads: <integer>
  caption: <string> (0,120)
  display: <bool>   # Images only

Actual file data is stored in Amazon S3 storage. Requests to upload or change the contents of a file will generate a signed S3 URL and authorization parameters for file upload.

A file's <media_type> must match its file name extensions according to Amazon's File Extension to Mime Types table.

Upload or update a file

PUT /users/{user}/projects/{project}/files/{file}
PUT /users/{user}/projects/{project}/steps/{step}/files/{file}
PUT /users/{user}/machines/{machine}/files/{file}
PUT /users/{user}/tools/{tool}/files/{file}


Name Type Description
caption <string> (0,120) The file caption.
display <bool> Images only*. Display this image.
position <integer> The file position.


Name Type Description
url <url> S3 file upload URL.
key <string> S3 key.
acl <string> S3 ACL.
policy <string> S3 policy.
signature <string> S3 signature.
access <string> S3 access key.

Rename a file

PUT /users/{user}/projects/{project}/files/{file}
PUT /users/{user}/projects/{project}/steps/{step}/files/{file}
PUT /users/{user}/machines/{machine}/files/{file}
PUT /users/{user}/tools/{tool}/files/{file}
Name Type Description
name <name> The new file name.

Delete a file

DELETE /users/{user}/projects/{project}/files/{file}
DELETE /users/{user}/projects/{project}/steps/{step}/files/{file}
DELETE /users/{user}/machines/{machine}/files/{file}
DELETE /users/{user}/tools/{tool}/files/{file}


Event Model

<event> = {
  type: <string>
  timestamp: <date>
  owner: <name>
  target: <name>
  url: <url>
  summary: <markdown>
  offset: <string>

Event Types

Name Description
publish Someone published a new project.
update Someone updated a project.
tag Someone tagged a project.
untag Someone untagged a project.
comment Someone posted a comment.
star Someone starred a project.
follow Someone followed a user.
unfollow Someone unfollowed a user.
grant A new badge was granted.
revoke A badge was revoked.

Event Parameters

Name Type Description
limit <integer> Limit the number of events returned.
before <string> Return events before this offset.
after <string> Return events after this offset.

View your events

GET /events

View events

GET /users/{user}
GET /users/{user}/projects/{project}
GET /users/{user}/machines/{machine}
GET /users/{user}/tools/{tool}


Get a list of tags

GET /tags

Create a new tag

PUT /tags/{tag}

Delete a tag

DELETE /tags/{tag}


Badge Model

<badge> = {
  name: <name>
  points: <integer>
  description: <markdown>

Get a list of badges

GET /badges

Create a new badge

PUT /badges/{badge}

Delete a badge

DELETE /badges/{badge}


License Model

<license> = {
  name: <string> (2,120)
  url: <url>
  brief: <markdown> (0,200)
  text: <markdown>
  shareable: <bool>
  commercial_use: <bool>
  attribution: <bool>

Get a list of licenses

GET /licenses

Create or update a license

PUT /licenses/{license}


Name Type Description
url URL to license.
brief Brief description of license.
text Full text of license.
shareable Does this license allow sharing.
commercial_use Does this license allow commercial use.
attribution Does this license require attribution.

Delete a license

DELETE /licenses/{license}


Pagination parameters apply to all search operations.

Search for users

GET /users
Name Type Description
query <string> Search string.
order_by <string> points, followers, joined

Search for things

GET /projects
GET /machines
GET /tools
GET /users/{user}/projects
GET /users/{user}/machines
GET /users/{user}/tools


Name Type Description
query <string> Search string.
license <string> Restrict to specified license.
tags <string> Restrict to specified tags.
order_by <string> stars, creation, modified