The microPledge developer API

Your dev link to microPledge

Quick-start

We’ve made our API really simple – here are examples that you can fetch with your browser. Get project progress and list pledges:

Now skip over to the microPledge sandbox and try out some of these more advanced examples below.

Basics

Our API is for developers to link their own web tools to microPledge – that is, you can now script microPledge. Use it to make your software do stuff on microPledge as though it were really you browsing around our site. You send commands to our microPlege pages using standard URL encoding, and then our server replies with JSON output.

For most informational queries, appending a simple ?format=json will suffice to give you JSON output.

For signup-only queries such as creating a project, grab your API key from your profile page. Then POST it to the desired microPledge URL along with any other form inputs required by that page. If you use an API key, you don't need to specify the format variable.

The examples below will help. You don’t need to stick with wget. Just pick the URL fetching tool you like best. For example, in Python you would probably use urllib2.

Over time we will be expanding the functions that are accessible through this API, but we’d like to hear what you think is most urgent.

API by example

Creating a project

This API command to start a project is designed to let bug tracking tools automatically create bounty projects for their bugs.

wget /dream -O- --post-data="
  apiKey=YOUR_API_KEY&
  name=Light+Sabre+War&
  description=StarWars+starter&
  details=Start+a+war+by+trying+to+assassinate+Darth+Vader&
  license=open-source&
  minPledge=30000&
  quoting=open&
  tags=StarWars+Vader"

Valid values for the multi-choice fields are:

license: non-software, open-source, closed-source, proprietary
quoting: open, sole, donations
incubator: if on, must also have priorart=YOUR_PRIOR_ART

On success, you’ll get back a JSON object with at least a result string, a nextpage relative URL string, and a messages array. The result will be success, incomplete (you still have to enter a quote, for example), or error if something went wrong.

If there’s an error, the first string in messages will tell you what’s up. If this says it’s a FormError, there will be an errors item whose keys are the invalid form inputs, and their values are what’s wrong with them.

Here’s example output from a successful project creation (edited slightly for brevity):

{
 "messages": [
  "Dreamed: Done! To get pledgers ..."
 ],
 "nextpage": "\/projects\/light-sabre-war",
 "result": "success"
}

And here’s example output with some form input errors (no description given, and minPledge set to only $0.50):

{
 "errors": {
  "description": "FormRequiredField: Terribly sorry ...",
  "minPledge": "FormLessThanMinimum: This value must be ..."
 },
 "messages": [
  "FormError: Some of the form fields weren't filled in ..."
 ],
 "nextpage": "\/dream",
 "result": "error"
}

Getting info about a project

This API command is simply so that you can find out things about your project – how much money has been pledged, how many pledges there are, or how far along it is.

Valid values for the multi-choice fields are:

license: non-software, open-source, closed-source, proprietary
quoting: inactive, quoting, developing, estimateLag, voting, voted, stalled, finished
Also, the progress field is a value between 0 and 1

wget /projects/myproject?format=json

The output looks something like this:

{
 "creationDate": "2008-05-11T21:43:03Z",
 "description": "A project I made to demonstrate JSON",
 "developer": "your-userslug",
 "license": "open-source",
 "minPledge": 1.0,
 "name": "My Project",
 "numPledges": 5,
 "pledged": 532.0,
 "progress": 0.15,
 "quoting": "open",
 "result": "success",
 "startDate": "2008-05-12T22:59:06Z",
 "state": "developing",
 "target": 700.0
}

Most of the fields are self-explanatory, but quoting is the project’s quoting type (see the “Develop this project yourself?” option on the dream page). It can be one of:

open – project was or is open for quotes
sole – project had or has a single developer
donations – project is a donations-only project

Listing a project’s pledgers

You can see who’s pledging to your project, and the amount they’re pledging.

wget /projects/myproject/pledges?format=json

The output looks like this (anonymous pledgers show as null):

{
 "pledges": [
  {
   "amount": 700.0,
   "date": "2008-05-14T22:59:06Z",
   "username": "Jimmy John",
   "userslug": "jimmy-john"
  },
  {
   "amount": 600.0,
   "date": "2008-05-12T19:36:07Z",
   "username": null,
   "userslug": null
  }
 ],
 "result": "success"
}