On this page
- POST buckets
- GET buckets/:id
- PUT buckets/:id
- DELETE buckets/:id
- POST buckets/:id/collaborators
- GET buckets/:id/collaborators
- PUT buckets/:id/collaborators/:account_id
- DELETE buckets/:id/collaborators/:account_id
- PUT buckets/:id/followers/:account_id
- GET buckets/:id/followers
- DELETE buckets/:id/followers/:account_id
- GET buckets/:id/drops
- PUT buckets/:id/drops/:drop_id
- DELETE buckets/:id/drops/:drop_id
- POST buckets/:id/subscriptions
- GET buckets/:id/subscriptions
- PUT buckets/:id/subscriptions/:subscription_id
- DELETE buckets/:id/subscriptions/:subscription_id
POST buckets
Create a bucket.
Resource Path
/buckets
Request Body
The request body is a JSON representation of the Bucket being created.
Example Request
Below creates a bucket with a single RSS channel.
POST https://api.swiftapp.com/v1/buckets
POST DATA
Response
GET buckets/:id
Returns a Bucket object for the given bucket.
Resource Path
/buckets/:id
Request Parameters
Name |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
Example Request
GET https://api.swiftapp.com/v1/buckets/1234
Response
PUT buckets/:id
Modify an existing bucket.
Resource Path
/buckets/:id
Request Body
The request body is a JSON representation of the Bucket being updated.
Example Request
Renames a bucket and modify its public and active statuses.
PUT https://api.swiftapp.com/v1/buckets/1234
PUT DATA
Response
DELETE buckets/:id
Remove an existing bucket.
Resource Path
/buckets/:id
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
Example Request
DELETE https://api.swiftapp.com/v1/buckets/9999
POST buckets/:id/collaborators
Add a new collaborator to a bucket. Collaborator objects have the following fields:
Field |
Type |
Read/Write |
Description |
|---|---|---|---|
id |
Int64 |
R |
The account id of the collaborator. |
read_only |
Boolean |
RW |
True when the account can modify the bucket details, false otherwise |
active |
Boolean |
RW |
True when the account has accepted collaboration, false otherwise. |
date_added |
String |
R |
Date when the collaborator was added. |
Resource Path
/buckets/:id/collaborators
Request Body
The request body is a JSON representation of the Collaborator being added.
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
Example Request
POST https://api.swiftapp.com/v1/buckets/9999/collaborators
POST DATA
Response
GET buckets/:id/collaborators
Returns a list of collaborators objects of accounts collaborating on the bucket.
Resource Path
/buckets/:id/collaborators
Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
Example Request
GET https://api.swiftapp.com/v1/buckets/9999/collaborators
Response
PUT buckets/:id/collaborators/:account_id
Modify a collaborator. This allows the collaboration level to be modified or collaboration to be activated.
Resource Path
/buckets/:id/collaborators/:account_id
Request Body
The request body is a JSON representation of the Collaborator being added.
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
account_id |
Required |
Account id of the collaborator |
Example Request
PUT https://api.swiftapp.com/v1/buckets/9999/collaborators/1234
PUT DATA
Response
DELETE buckets/:id/collaborators/:account_id
Remove an existing account collaborator. Only bucket owners can perform this action.
Resource Path
/buckets/:id/collaborators/:account_id
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
account_id |
Required |
Account id of the collaborator |
Example Request
DELETE https://api.swiftapp.com/v1/buckets/9999/collaborators/345
PUT buckets/:id/followers/:account_id
Add a new follower to a bucket.
Resource Path
/buckets/:id/followers/:account_id
Request Parameters
Field |
Type |
Description |
|---|---|---|
account_id |
Required |
The numerical id of the desired bucket |
Example Request
PUT https://api.swiftapp.com/v1/buckets/9999/followers/1234
GET buckets/:id/followers
Returns a list of Account objects of accounts following the bucket.
Resource Path
/buckets/:id/followers
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
Example Request
GET https://api.swiftapp.com/v1/buckets/9999/followers
Response
DELETE buckets/:id/followers/:account_id
Remove an existing account follower.
Resource Path
/buckets/:id/followers/:account_id
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
account_id |
Required |
Account id of the follower |
Example Request
DELETE https://api.swiftapp.com/v1/buckets/9999/followers/345
GET buckets/:id/drops
Returns a list of drops in the bucket.
Resource Path
/buckets/:id/drops
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
count |
Optional |
Number of drops to return. Default: 50 |
max_id |
Optional |
Id that is the pagination reference point. Page numbers are relative to this id. |
page |
Optional |
Page number of results to return relative to max_id. |
since_id |
Optional |
Return count drops with and id greater than this id. |
date_from |
Optional |
Returned drops will have a published date greater than this date |
date_to |
Optional |
Returned drops will have a published date smaller than this date |
keywords |
Optional |
Comma separated list of keywords and phrases. Returned drops will contain these keywords |
channels |
Optional |
Comma separated list of channel names. Returned drops will be from the specified channels |
locations |
Optional |
Comma separated list of bounding boxes. A bounding box is specified by a pair of [longitude,latitude] pairs. Returned drops will contain a place within the bounding box. |
Request Headers
Header |
Required |
Description |
|---|---|---|
X-Stream |
Optional |
The server will keep the connection open when this field is present and new drops will be written in realtime as they are added to the Bucket. |
Example Request
The below request will return 1 Facebook OR Twitter drops with an id less than 999999 AND containing the keywords Kenya OR Uganda AND have a location of San Francisco OR New York City.
GET
Response
PUT buckets/:id/drops/:drop_id
Add a drop to a bucket.
Resource Path
/buckets/:id/drops/:drop_id
Request Parameters
Field |
Type |
Description |
|---|---|---|
drop_id |
Required |
The numerical id of the desired bucket |
Example Request
PUT https://api.swiftapp.com/v1/buckets/9999/drops/1111
DELETE buckets/:id/drops/:drop_id
Remove a drop from a Bucket.
Resource Path
/buckets/:id/drops/:drop_id
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
drop_id |
Required |
ID of the drop to be removed from the bucket |
Example Request
DELETE https://api.swiftapp.com/v1/buckets/9999/drops/1111
POST buckets/:id/subscriptions
SwiftRiver can push drops to any URL via an HTTP POST or PUT request. This endpoint is used to define such a subscription.
A list of Drops will be published to the given URL at the specified frequency and SwiftRiver will keep trying to publish new drops to the API for 1 hour from when they are produced.
A subscription consists of the target URL, frequency of data transfer and other parameters as shown below:
Field |
Type |
Read/Write |
Required on Create |
Description |
|---|---|---|---|---|
id |
Int64 |
R |
Unique numerical identified for the subscription. |
|
name |
String |
RW |
Y |
A user defined label for the subscription. |
url |
String |
RW |
Y |
The target URL to push drops to. |
method |
String |
RW |
Y |
"PUT" or "POST". The HTTP Method to use. |
frequency |
Int |
RW |
N |
Seconds after which to push drops to the defined URL. |
max_request_size |
Int |
RW |
N |
Maximum size in bytes of the request to be posted to the defined URL. |
verify_ssl_cert |
Boolean |
RW |
N |
If url is using HTTPs, verify the certificate used when true. |
username |
String |
RW |
N |
Username to use with basic authentication at target URL. |
password |
String |
RW |
N |
Password to use for basic authentication at target URL. |
active |
Boolean |
RW |
N |
When true, SwiftRiver will attempt to post new drops at the URL otherwise no posting will happen. |
date_added |
String |
R |
N |
Date when the subscription was added. |
Resource Path
/buckets/:id/subscriptions
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
Request Body
The request body is a JSON representation of the Subscription being added.
Example Request
POST https://api.swiftapp.com/v1/buckets/9999/subscriptions
POST DATA
Response
GET buckets/:id/subscriptions
Returns a list of Subscriptions defined in the Bucket by the authenticating user.
Resource Path
/buckets/:id/subscriptions
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
Example Request
GET https://api.swiftapp.com/v1/buckets/9999/subscriptions
Response
PUT buckets/:id/subscriptions/:subscription_id
Modify and existing subscription.
Resource Path
/buckets/:id/subscriptions/:subscription_id
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket. |
subscription_id |
Required |
The numerical id of the subscription. |
Request Body
The request body is a JSON representation of the Subscription being modified.
Example Request
PUT https://api.swiftapp.com/v1/buckets/9999/subscriptions/501
PUT DATA
Response
DELETE buckets/:id/subscriptions/:subscription_id
Remove a subscription.
Resource Path
/buckets/:id/subscriptions/:subscription_id
Request Parameters
Field |
Type |
Description |
|---|---|---|
id |
Required |
The numerical id of the desired bucket |
subscription_id |
Required |
ID of the subscription to be removed. |
Example Request
DELETE https://api.swiftapp.com/v1/buckets/9999/subscriptions/1111