POST accounts

Create an account.

Resource Path

/accounts

Request Body

The request body is a JSON representation of the Account being created.

Example Request

POST https://api.swiftapp.com/v1/accounts

POST DATA

{
   "name":"Dexter Morgan",
   "account_path":"dexter",
   "email":"dexter@example.com",
   "password":"secret"
}
Response
{
   "id":12,
   "active":false,
   "owner":{
      "name":"Dexter Morgan",
      "email":"bmuita+dexter@gmail.com",
      "username":"bmuita+dexter@gmail.com",
      "avatar":"https://secure.gravatar.com/avatar/30e5ade87d8622944d6244e0fc1f0433?s=80&d=mm&r=g",
      "date_added":null
   },
   "rivers":[],
   "buckets":[],
   "follower":false,
   "account_path":"dexter",
   "date_added":[],
   "private":false,
   "river_quota_remaining":0,
   "follower_count":0,
   "following_count":0,
   "is_collaborator":false,
   "is_following":false,
   "collaborating_rivers":[],
   "following_rivers":null,
   "collaborating_buckets":[],
   "following_buckets":[]
}

GET accounts

Returns a list of Account objects for the requested account(s).

Resource Path

/accounts

Query Parameters

Name

Type

Description

account_path

Optional

The name of the desired account.

email

Optional

The email of the desired account.

q

Optional

A search query.

Example Request
GET https://api.swiftapp.com/v1/accounts?account_path=ushahidi
[{
   "id":1234,
   "account_path":"ushahidi",
   "active":true,
   "public":true,
   "river_quota_remaining":10,
   "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
   "owner":{
      "name":"Joe Public",
      "email":"joe.public@example.com",
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
   },
   "follower_count":10,
   "following_count":99,
   "is_owner":true,
   "is_collaborator":false,
   "is_subscribed":false,
   "buckets":[
      {
         "id":2,
         "name":"Another Bucket",
         "account_id":"1234567890",
         "subscriber_count":"1",
         "is_owner":true,
         "is_collaborator":false,
         "is_subscribed":false,
         "public":true
      },
      {
         "id":9,
         "name":"Yet Another Bucket",
         "account_id":"3",
         "subscriber_count":"10",
         "is_owner":false,
         "is_collaborator":true,
         "is_subscribed":false,
         "public":false
      }
   ],
   "rivers":[
      {
         "id":2,
         "name":"Another River",
         "account_id":"3",
         "subscriber_count":"1",
         "is_owner":true,
         "is_collaborator":false,
         "is_subscribed":false,
         "public":true,
         "active":false,
         "drop_count":100,
         "drop_quota":10000,
         "full":false,
         "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
         "expiry_date":"Thu, 07 Feb 2013 13:08:45 +0000",
         "extension_count":0
      },
      {
         "id":9,
         "name":"Yet Another River",
         "account_id":"3",
         "subscriber_count":"10",
         "is_owner":false,
         "is_collaborator":true,
         "is_subscribed":false,
         "public":false,
         "active":false,
         "drop_count":100,
         "drop_quota":10000,
         "full":false,
         "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
         "expiry_date":"Thu, 07 Feb 2013 13:08:45 +0000",
         "extension_count":0
      }
   ]
}]

GET accounts/:id

Returns information about the given account including name, rivers and buckets.

Resource Path

/accounts/:id

Parameters

Name

Type

Description

id

Required

The numerical id of the desired account

Example Request
GET https://api.swiftapp.com/v1/accounts/1234
{
   "id":1234,
   "account_path":"default",
   "active":true,
   "public":true,
   "river_quota_remaining":10,
   "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
   "owner":{
      "name":"Joe Public",
      "email":"joe.public@example.com",
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
   },
   "follower_count":10,
   "following_count":99,
   "is_owner":true,
   "is_collaborator":false,
   "is_subscribed":false,
   "buckets":[
      {
         "id":2,
         "name":"Another Bucket",
         "account_id":"1234567890",
         "subscriber_count":"1",
         "is_owner":true,
         "is_collaborator":false,
         "is_subscribed":false,
         "public":true
      },
      {
         "id":9,
         "name":"Yet Another Bucket",
         "account_id":"3",
         "subscriber_count":"10",
         "is_owner":false,
         "is_collaborator":true,
         "is_subscribed":false,
         "public":false
      }
   ],
   "rivers":[
      {
         "id":2,
         "name":"Another River",
         "account_id":"3",
         "subscriber_count":"1",
         "is_owner":true,
         "is_collaborator":false,
         "is_subscribed":false,
         "public":true,
         "active":false,
         "drop_count":100,
         "drop_quota":10000,
         "full":false,
         "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
         "expiry_date":"Thu, 07 Feb 2013 13:08:45 +0000",
         "extension_count":0
      },
      {
         "id":9,
         "name":"Yet Another River",
         "account_id":"3",
         "subscriber_count":"10",
         "is_owner":false,
         "is_collaborator":true,
         "is_subscribed":false,
         "public":false,
         "active":false,
         "drop_count":100,
         "drop_quota":10000,
         "full":false,
         "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
         "expiry_date":"Thu, 07 Feb 2013 13:08:45 +0000",
         "extension_count":0
      }
   ]
}

GET accounts/me

Returns account information for the authenticated user.

Resource Path

/accounts/me

Example Request
GET https://api.swiftapp.com/v1/accounts/me
{
   "id":1234,
   "account_path":"default",
   "active":true,
   "public":true,
   "river_quota_remaining":10,
   "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
   "owner":{
      "name":"Joe Public",
      "email":"joe.public@example.com",
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
   },
   "follower_count":10,
   "following_count":99,
   "is_owner":true,
   "is_collaborator":false,
   "is_subscribed":false,
   "buckets":[
      {
         "id":2,
         "name":"Another Bucket",
         "account_id":"1234567890",
         "subscriber_count":"1",
         "is_owner":true,
         "is_collaborator":false,
         "is_subscribed":false,
         "public":true
      },
      {
         "id":9,
         "name":"Yet Another Bucket",
         "account_id":"3",
         "subscriber_count":"10",
         "is_owner":false,
         "is_collaborator":true,
         "is_subscribed":false,
         "public":false
      }
   ],
   "rivers":[
      {
         "id":2,
         "name":"Another River",
         "account_id":"3",
         "subscriber_count":"1",
         "is_owner":true,
         "is_collaborator":false,
         "is_subscribed":false,
         "public":true,
         "active":false,
         "drop_count":100,
         "drop_quota":10000,
         "full":false,
         "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
         "expiry_date":"Thu, 07 Feb 2013 13:08:45 +0000",
         "extension_count":0
      },
      {
         "id":9,
         "name":"Yet Another River",
         "account_id":"3",
         "subscriber_count":"10",
         "is_owner":false,
         "is_collaborator":true,
         "is_subscribed":false,
         "public":false,
         "active":false,
         "drop_count":100,
         "drop_quota":10000,
         "full":false,
         "date_added":"Mon, 07 Jan 2013 13:08:45 +0000",
         "expiry_date":"Thu, 07 Feb 2013 13:08:45 +0000",
         "extension_count":0
      }
   ]
}

 

POST accounts/activate

Activates a newly created account using the specified token parameter.

Resource Path

/accounts/activate

Request Parameters
NameTypeDescription
emailRequired -  StringEmail address associated with the account to be activated
tokenRequired - StringA one-time secret value that is used to activate the account.
Example Request

POST https://api.swiftapp.com/v1/accounts/activate  

POST DATA

{
    "email": "emmanuel@swiftapp.com",
    "token": "0484MXJHFLADKDJAJM048539585KKFNSKSIR"
}

 

POST accounts/reset_password

Resets a user's password. This request should be issued after the client has obtained a password reset token

Resource Path

/accounts/reset_password

Request Parameters
NameTypeDescription
emailRequired - StringThe user's email address
passwordRequired - StringThe new password to set for the user associated with the specified email parameter
tokenRequired - StringA secret value used to authenticate the password reset request. This token is generated when a forgot_password request is issued
Example Request

POST https://api.swiftapp.com/v1/accounts/reset_password

POST DATA

{
	"email":"emmmanuel@swiftapp.com",
	"password":"newpa55w0rd",
	"token":"4c1b9bb3405f53cf46731af89f07b01d1ffe974f944d81085cb962abc45ee9c3"
}

 

PUT accounts/:id

Modify and existing Account.

Resource Path

/accounts/:id

Request Parameters

Name

Type

Description

id

Required

The numerical id of the desired account.

Request Body

The request body is a JSON representation of the Account being created.

Example Request

POST https://api.swiftapp.com/v1/accounts/123

POST DATA

{
   "name":"Joe Public Renamed",
}


{
   "id":1234,
   "active":true,
   "name":"Joe Public Renamed",
   "account_path":"joepublic",
   "avatar":"http://example.com/avatar.jpg",
   "email":"joe.public@example.com",
   "verified":"false",
   "password":"secret",
   "follower_count":0,
   "following_count":0,
   "is_owner":true,
   "is_collaborator":false,
   "is_subscribed":false,
   "public":true,
   "river_quota_remaining":10,
   "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
}

PUT accounts/:id/followers/:account_id

Add a new follower to an accounts.

Resource Path

/accounts/:id/followers/:account_id

Request Parameters

Field

Type

Description

id

Required

The numerical id of the desired account

account_id

Required

The numerical id of the account to be added as follower

Example Request

PUT https://api.swiftapp.com/v1/accounts/9999/followers/55

GET accounts/:id/followers

Returns a list of Account objects of accounts following the account.

Resource Path

/accounts/:id/followers

Request Parameters

Field

Type

Description

id

Required

The numerical id of the desired account

follower

Optional

The numerical id of an account that is in the list of followers

Example Request

GET https://api.swiftapp.com/v1/accounts/9999/followers

[
   {
      "id":1234,
      "account_path":"default",
      "subscriber_count":10,
      "subscribed_count":99,
      "is_owner":true,
      "is_collaborator":false,
      "is_subscribed":false,
      "public":true,
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
   },
   {
      "id":43211,
      "account_path":"tluafed",
      "subscriber_count":10,
      "subscribed_count":99,
      "is_owner":true,
      "is_collaborator":false,
      "is_subscribed":false,
      "public":true,
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
   }
]

GET accounts/:id/following

Returns a list of Account objects of accounts the specified account is following.

Resource Path

/accounts/:id/following

Request Parameters

Field

Type

Description

id

Required

The numerical id of the desired account

Example Request

GET https://api.swiftapp.com/v1/accounts/9999/following

[
   {
      "id":1234,
      "account_path":"default",
      "subscriber_count":10,
      "subscribed_count":99,
      "is_owner":true,
      "is_collaborator":false,
      "is_subscribed":false,
      "public":true,
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
   },
   {
      "id":43211,
      "account_path":"tluafed",
      "subscriber_count":10,
      "subscribed_count":99,
      "is_owner":true,
      "is_collaborator":false,
      "is_subscribed":false,
      "public":true,
      "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
   }
]

GET accounts/:id/activities

Get an activity stream.

Returns a list of Activity objects with the following fields:

Field

Type

Description

id

String

The unique identifier for the activity.

date_added

String

RFC822 formated date time string of when the account was created. E.g. "Wed, 27 Aug 2008 13:08:45 +0000"

account

Account

The Account object for the account that performed the action.

action

String

The action perfomed. Either "create", "follow" or "invite".

action_on

String

The name of the type of object on which the action was performed. Either "river", "bucket" or "account"

action_on_obj

Object

The object on which the action was performed. Either Account, River or Bucket

action_to_obj

Account

Account to which the action was directed.

It the authenticating user request their own account, the Activity stream is activities of accounts it is following. For requests on other accounts, the response is the Activity stream of the account requested.

Resource Path

/accounts/:id/activities

Request Parameters

Field

Type

Description

id

Required

The numerical id of the desired account

Query Parameters

Name

Type

Required

Description

count

Int

Optional

Number of activities to return.

last_id

String

Optional

Return activities starting from this id.

newer

Boolean

Optional

When present, return activities newer than last_id otherwise older.

Example Request

GET https://api.swiftapp.com/v1/accounts/9999/activities

[
   {
      "id":"1234",
      "account":{
         "id":"1234",
         "account_path":"default",
         "subscriber_count":10,
         "subscribed_count":99,
         "is_owner":true,
         "is_collaborator":false,
         "is_subscribed":false,
         "public":true,
         "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
      },
      "action_on":"bucket",
      "action_on_obj":{
         "id":"1234",
         "name":"Viva Riva",
         "account_id":"3",
         "follower_count":0,
         "is_owner":true,
         "is_collaborator":false,
         "is_following":false,
         "public":false,
         "active":true,
         "drop_count":0,
         "date_added":"Mon, 07 Jan 2013 13:08:45 +0000"
      }
   }
]

POST accounts/:id/apps

Register a client application for API access. Applications are defined by the following fields:

Field

Type

Read/Write

Required on Create

Description

client_id

String

R

 

Unique identitifier for the client application.

client_secret

String

R

 

The client's password.

redirect_uri

String

RW

N

Callback URL for the application after successful authorization calls.

name

String

RW

Y

A name for the application.

Description

String

RW

N

Free text description of the applicaiton.

homepage

String

RW

N

A publicly accessbile homepage for the application

Resource Path

/accounts/:id/apps

Request Body

The request body is a JSON representation of the Application being added.

Request Parameters

Field

Type

Description

id

Required

The numerical id of the account registering the application

Example Request

POST https://api.swiftapp.com/v1/accounts/9999/apps

POST DATA

{
   "name":"My App",
   "description":"App Description",
   "redirect_uri":"http://example.com",
   "homepage":"http://example.com"
}
Response
{
   "id":4,
   "name":"My App",
   "description":"App Description",
   "homepage":"http://example.com",
   "client_id":"c755399c-6226-4183-9256-6df9ab439ef2",
   "client_secret":"59630b95-60ad-4700-b89e-fe0c88da5ab1",
   "redirect_uri":"http://example.com"
}

GET accounts/:id/apps

Returns a list of Applications registered in the specified account.

Resource Path

/accounts/:id/following

Request Parameters

Field

Type

Description

id

Required

The numerical id of the desired account

Example Request

GET https://api.swiftapp.com/v1/accounts/9999/apps

Response
[
   {
      "id":4,
      "name":"My App",
      "description":"App Description",
      "homepage":"http://example.com",
      "client_id":"c755399c-6226-4183-9256-6df9ab439ef2",
      "client_secret":"59630b95-60ad-4700-b89e-fe0c88da5ab1",
      "redirect_uri":"http://example.com"
   }
]

PUT accounts/:id/apps/:app_id

Modify a registered application.

Resource Path

/accounts/:id/apps/:app_id

Request Body

The request body is a JSON representation of the Application being modified.

NOTE: If the client_id field is set in the request body, the client's credentials will be reset.

Request Parameters

Field

Type

Description

id

Required

The numerical id of the desired account.

app_id

Required

The numerical id of the application being modified.

Example Request

PUT https://api.swiftapp.com/v1/accounts/1/apps/4

PUT DATA

{
   "name":"My App",
   "description":"App Description",
   "redirect_uri":"http://example.com",
   "homepage":"http://example.com"
}
Response
{
   "id":4,
   "name":"My App Renamed",
   "description":"App Description Renamed",
   "homepage":"http://example.com/home/renamed",
   "client_id":"c755399c-6226-4183-9256-6df9ab439ef2",
   "client_secret":"59630b95-60ad-4700-b89e-fe0c88da5ab1",
   "redirect_uri":"http://example.com/renamed"
}

DELETE accounts/:id/apps/:app_id

Delete a client application.

Resource Path

/accounts/:id/apps/:app_id

Request Parameters

Field

Type

Description

id

Required

The numerical id of the account that registered the application.

app_id

Required

The numerical id of the application being deleted.

Example Request

DELETE https://api.swiftapp.com/v1/accounts/9999/apps/1234