Needish API

Needish exposes some of its functionality via an API (Application programming interface). This document serves as reference for developers wanting to write fun applications that interact with Needish.

API Discussion Group

A Google Group has been created to discuss Needish API related topics. To keep updated with the API development, and discuss API related topics, suscribe to

Creating Applications

Before creating your application using the Needish API, you must obtain a valid application key. The key will be used to track API usage.

Currently, commercial use of the API is allowed only with prior permission. Requests for API keys intended for commercial use are reviewed by Needish. If your project is personal, artistic, free or otherwise non-commercial please don't request a commercial key. If your project is commercial, please provide sufficient detail to help us decide.

If you want to create an application, obtain your application key here

User Authentication

Most API methods require authentication as in the Needish website. But there are some open functionalities, for example requesting the list of last posted needs.

The only supported authentication scheme at this time is Basic HTTP authentication using the email registered at Needish and the password chosen.


The needish API expects all parameters to be UTF-8 encoded. If you need more information about UTF-8. Additionaly remember to URL encode parameters that take complex strings.


The Needish API is built based on the REST (Representational State Transfer) software architecture style. Methods can return data using the XML or JSON data formats.

To retrieve the last posted needs in the XML data format you should use (replace <your_api_key> with your own API key)<your_api_key>

If you want to user the JSON data format, you should only change the extension to .json<your_api_key>

For JSON requests you can define your own callback function name, using the callback parameter. Example:<your_api_key>



All methods require a GET request, unless noted. Methods that add entities require a POST method to be used.

General Parameters

All the methods that returns lists of entities (ie: needs, users or helps), accept the following parameters:

Limits the number of entities to return.
The page to retrieve. It's 1-base (first page is 1), but if you send 0 the first page will be returned, anyway.
Optional. Returns entities created after the specified date. Date should be in yyyy-mm-dd format or using UNIX time (number of seconds elapsed since 1970-01-01 00:00:00)


If the response is OK, then the following will be returned:

XML Format

<?xml version="1.0" encoding="UTF-8" ?>

JSON Format

	"rsp": {

Also, an "Status-Code: 200" header will be sent

If the response fails, or nothing can be returned (example: no user found):

XML Format

<?xml version="1.0" encoding="UTF-8" ?>
	<status code="[code]" msg="[message]"/>
		<error field="[fieldname]" message="[message]" />

JSON Format

	"rsp": {

Also, an "Status-Code: [code]" header will be sent.

Response Status Code

Unauthorized. Returned when trying to execute an authenticated method without valid credentials.
Method not allowed. Returned when trying to execute with a wrong method (Example: using GET when you should be using POST)
Not Found. No method, or no data found.
API Error. There was an error when executing a method. The message field contains details of the error.