Socialcast Developer API

The Socialcast API:

is a REST API for interacting with messages, comments and likes
supports BASIC AUTH authentication
secure using SSL connections

This documentation contains interactive examples below which are using domain:

https://demo.socialcast.com

To change the domain, please log into the community of choice and then return to this page.
With demo you can use credentials: emily@socialcast.com/demo

Additional support is available by visiting the Socialcast Developer API forum

Methods

Groups API

[GET] /api/groups - Listing of Groups
[GET] /api/groups/GROUP_ID/members - Listing Members of a Group
[GET] /api/group_memberships - Listing Group Memberships

Streams API

[GET] /api/streams - Listing User's Streams
[GET] /api/streams/STREAM_ID/messages - Read Stream Messages

Categories API

[GET] /api/categories - Listing Tenant Categories

Content Filters API

[GET] /api/content_filters - Listing Tenant Content Filters

Attachments API

[POST] /api/attachments - Creating Attachments

Attachments API

[POST] /api/attachments - Creating Attachments

Authentication API

[POST] /api/authentication - Retrieve list of Active Communities

Methods

Detailed instructions on the methods available with the Socialcast API and how to use them.

Private Messages API

Getting Private Messages

Return the user's private messages.

Request Type:

HTTP GET

Request Parameters:

page (optional) The page of paginated content to be displayed to the user.
per_page (optional) results per page (default 20, max 500)
since (optional) Retrieve only messages that have been updated since a given time. Expects the format to be seconds from epoch in UTC.

Response

The JSON and XML formats of the stream have the structure outlined in Private Message List Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/private_messages.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/private_messages.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/private_messages.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/private_messages.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Private Messages since 2 hours ago

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages.xml?since=1328194277

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/private_messages.xml?since=1328194277')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/private_messages.xml?since=1328194277");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/private_messages.xml?since=1328194277';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/private_messages.xml?since=1328194277");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Getting unread Private Messages

Return the user's unread private messages.

Request Type:

HTTP GET

Request Parameters:

page (optional) The page of paginated content to be displayed to the user.
per_page (optional) results per page (default 20, max 500)
since (optional) Retrieve only messages that have been updated since a given time. Expects the format to be seconds from epoch in UTC.

Response

The JSON and XML formats of the stream have the structure outlined in Private Message List Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages/unread.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/private_messages/unread.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/private_messages/unread.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/private_messages/unread.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/private_messages/unread.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Unread Private Messages since 2 hours ago

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages/unread.xml?since=1328194277

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/private_messages/unread.xml?since=1328194277')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/private_messages/unread.xml?since=1328194277");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/private_messages/unread.xml?since=1328194277';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/private_messages/unread.xml?since=1328194277");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Getting a Single Private Stream Message

Return a specific private message.

Returning a private message with id = 1

Request Type:

HTTP GET

Request Parameters:

None.

Response

The JSON and XML formats of a message have the structure outlined in Private Message Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages/1.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/private_messages/1.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/private_messages/1.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/private_messages/1.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/private_messages/1.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Sending New Private Messages

Sending a new private message for the authenticated user.

Request Type:

HTTP POST

Request Parameters:

private_message[recipient_id] (required) The user id of the recipient
private_message[body] (required) text for the message.
private_message[url] (optional) external url for this message.
private_message[replied_to] (optional) Message id that this private message is in reply to.
private_message[attachment] (optional) file to attach to this message. Should be sent as an HTTP multipart form and include property 'uploaded_data'
private_message[attachment_ids][] (optional) existing attachment to be connected to this message. See the Creating Attachments API. You can include this parameter multiple times for multiple attachments.

Response:

The JSON and XML formats of a message have the structure outlined in Private Message Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X POST -d "private_message[body]=hello%20Jennifer&private_message[recipient_id]=26" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post.new('/api/private_messages.xml')
      req.set_form_data({"private_message[body]"=>"hello Jennifer", "private_message[recipient_id]"=>26}, ';')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/private_messages.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "private_message[body]=hello%20Jennifer&private_message[recipient_id]=26");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(POST);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = POST 'https://demo.socialcast.com/api/private_messages.xml', ["private_message[body]"=>"hello Jennifer", "private_message[recipient_id]"=>26];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/private_messages.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("POST");
con.setDoOutput(true);
String data = "private_message[body]=hello%20Jennifer&private_message[recipient_id]=26";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Post a new private message with an attachment


      # Curl Example
      curl -X POST -d "private_message[body]=hello%20Jennifer&private_message[recipient_id]=26&private_message[attachments_attributes][0][uploaded_data]=@/path/to/my/file.jpg" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages.xml

Destroy an existing private message

Permanently remove a private message from the system. Only private message owners are allowed to perform this operation. Example deleting a private message with message id = 1

Request Type:

HTTP DELETE

Request Parameters:

None

Response

An HTTP 200 response with an empty body.

Examples

Command Line Usage

bash


      # Curl Example
      curl -X DELETE -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages/1.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Delete.new('/api/private_messages/1.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/private_messages/1.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, URLOPT_CUSTOMREQUEST, "DELETE");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(DELETE);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = DELETE 'https://demo.socialcast.com/api/private_messages/1.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/private_messages/1.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("DELETE");
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Marking a Private Message as Read

Mark a private message as read. No need to do this if the message is replied to.

Sample endpoints when private message id = 1

Request Type:

HTTP POST

Request Parameters:

None.

Response

The JSON and XML formats of a like have the structure outlined in Private Message Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X POST -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages/1/mark_as_read.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post.new('/api/private_messages/1/mark_as_read.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/private_messages/1/mark_as_read.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_POST, TRUE);
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(POST);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = POST 'https://demo.socialcast.com/api/private_messages/1/mark_as_read.xml', [];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/private_messages/1/mark_as_read.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("POST");
con.setDoOutput(true);
String data = "";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Private Message Replies API

Replying to a Private Message

Add a reply for the authenticated user to a particular private message.

Sample endpoints when the private message id = 1

Request Type:

HTTP POST

Request Parameters:

reply[body] The body of the message
reply[attachment] (optional) file to attach to this comment. Should be sent as an HTTP multipart form. Use parameter [attachments_attributes][0][uploaded_data]
reply[attachment_ids][] (optional) existing attachment to be connected to this comment. See the Creating Attachments API. You can include this parameter multiple times for multiple attachments.

Response

The JSON and XML formats of a reply have the structure outlined in Reply Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X POST -d "reply[body]=hello%20Emily" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages/1/replies.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post.new('/api/private_messages/1/replies.xml')
      req.set_form_data({"reply[body]"=>"hello Emily"}, ';')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/private_messages/1/replies.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "reply[body]=hello%20Emily");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(POST);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = POST 'https://demo.socialcast.com/api/private_messages/1/replies.xml', ["reply[body]"=>"hello Emily"];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/private_messages/1/replies.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("POST");
con.setDoOutput(true);
String data = "reply[body]=hello%20Emily";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Deleting a Private Message Reply

Delete a reply for the authenticated user.

Sample endpoints when the private message id = 1 and reply id = 2

Request Type:

HTTP DELETE

Request Parameters:

None

Response

The response will be an empty document with an HTTP status of 200.

Examples

Command Line Usage

bash


      # Curl Example
      curl -X DELETE -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/private_messages/1/replies/2.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Delete.new('/api/private_messages/1/replies/2.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/private_messages/1/replies/2.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, URLOPT_CUSTOMREQUEST, "DELETE");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(DELETE);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = DELETE 'https://demo.socialcast.com/api/private_messages/1/replies/2.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/private_messages/1/replies/2.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("DELETE");
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Messages API

Reading Stream Messages

Return the user's stream messages.

Request Type:

HTTP GET

Request Parameters:

page (optional) The page of paginated content to be displayed to the user.
per_page (optional) results per page (default 20, max 500)
category_id (optional) Messages from the given category. For details on getting a category_id see Categories API
tag (optional) Messages that have been tagged with the given string.
content_filter (optional) Messages that are a certain type of content, i.e. Photo, Attachment. Expects the "key" value retrieved from the content filter response. For details on getting content_filter see Content Filters API
since (optional) Retrieve only messages that have been updated since a given time. Expects the format to be seconds from epoch in UTC.
comments_limit (optional) Limit the number of comment records that will be sent for the message. Most recent comments will be sent.
likes_limit (optional) Limit the number of like records that will be sent for the message.
comment_likes_limit (optional) Limit the number of like records that will be sent for comments.

Response

The JSON and XML formats of the stream have the structure outlined in Message List Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/messages.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/messages.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Messages since 2 hours ago

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages.xml?since=1328359877

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/messages.xml?since=1328359877')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages.xml?since=1328359877");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/messages.xml?since=1328359877';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages.xml?since=1328359877");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Read a Single Stream Message

Return a specific message.

Returning a message with id = 399

Request Type:

HTTP GET

Request Parameters:

None.

Response

The JSON and XML formats of a message have the structure outlined in Message Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/MESSAGE_ID.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/messages/MESSAGE_ID.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/MESSAGE_ID.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/messages/MESSAGE_ID.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/MESSAGE_ID.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Creating New Messages

Create a new message for the authenticated user.

Request Type:

HTTP POST

Request Parameters:

message[body] (required) text for the message.
message[url] (optional) external url for this message.
message[attachment] (optional) file to attach to this message. Should be sent as an HTTP multipart form.
message[attachment_ids][] (optional) existing attachment to be connected to this message. See the Creating Attachments API. You can include this parameter multiple times for multiple attachments.
message[group_id] (optional) Submit this message to a group. For more information on what groups are available for the user see the Group Membership API
message[category_id] (optional) Submit this message in a category. For more information on what categories are available see the Categories API
message[player_url] (optional) Embed a flash player hosted at this URL. If player_url is specified, thumbnail_url must also be specified.
message[thumbnail_url] (optional) Display the image located at this URL before embedding the flash player.
message[player_params] (optional) Pass these FlashVars to the embedded flash player.
origin_stream[id] (optional) Pass the ID of a stream to determine if the newly-created message belongs in it.

Response:

The JSON and XML formats of a message have the structure outlined in Message Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X POST -d "message[title]=trying%20out%20the%20api&message[body]=hello" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post.new('/api/messages.xml')
      req.set_form_data({"message[title]"=>"trying out the api", "message[body]"=>"hello"}, ';')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "message[title]=trying%20out%20the%20api&message[body]=hello");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(POST);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = POST 'https://demo.socialcast.com/api/messages.xml', ["message[title]"=>"trying out the api", "message[body]"=>"hello"];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("POST");
con.setDoOutput(true);
String data = "message[title]=trying%20out%20the%20api&message[body]=hello";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Post a new message with an attachment


      # Curl Example
      curl -X POST -d "message[attachments_attributes][0][uploaded_data]=@/path/to/my/file.jpg" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages.xml

Updating Existing Messages

Update an existing message with new information. Only the message owner may update a message.

Updating a message with id = 399

Request Type:

HTTP PUT

Required Request Headers:

Content-Type: multipart/form-data

Request Parameters:

message[body] (required) text for the message.
message[url] (optional) external url for this message.
message[attachment] (optional) file to attach to this message. Should be sent as an HTTP multipart form.
message[attachment_ids][] (optional) existing attachment to be connected to this message. See the Creating Attachments API. You can include this parameter multiple times for multiple attachments.
message[group_id] (optional) group to associate this message to. See the Group Membership API for how to find groups that the user is a member of.
message[category_id] (optional) Submit this message in a category. For more information on what categories are available see the Categories API

Response:

The JSON and XML formats of the returned message has the structure outlined in Message Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X PUT -d "message[title]=trying%20out%20the%20api%20by%20updating%20my%20sweet%20message&message[body]=hello%20updates" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/38.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Put.new('/api/messages/38.xml')
      req.set_form_data({"message[title]"=>"trying out the api by updating my sweet message", "message[body]"=>"hello updates"}, ';')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/38.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_PUT, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "message[title]=trying%20out%20the%20api%20by%20updating%20my%20sweet%20message&message[body]=hello%20updates");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(PUT);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = PUT 'https://demo.socialcast.com/api/messages/38.xml', ["message[title]"=>"trying out the api by updating my sweet message", "message[body]"=>"hello updates"];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/38.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("PUT");
con.setDoOutput(true);
String data = "message[title]=trying%20out%20the%20api%20by%20updating%20my%20sweet%20message&message[body]=hello%20updates";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Destroy an existing message

Permanently remove a message from the system. Only message owners or community administrators are allowed to perform this operation. Delete a message with message id = 399

Request Type:

HTTP DELETE

Request Parameters:

None

Response

An HTTP 200 response with an empty body.

Examples

Command Line Usage

bash


      # Curl Example
      curl -X DELETE -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/38.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Delete.new('/api/messages/38.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/38.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, URLOPT_CUSTOMREQUEST, "DELETE");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(DELETE);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = DELETE 'https://demo.socialcast.com/api/messages/38.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/38.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("DELETE");
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Searching Messages

Search through all messages in your community.

Request Type:

HTTP GET

Request Parameters:

q search query string
page (optional) The page of paginated content to be displayed to the user.
per_page (optional) results per page (default 20, max 500)
category_id (optional) Messages from the given category. For details on getting a category_id see Categories API
content_filter (optional) Messages that are a certain type of content, i.e. Photo, Attachment. Expects the "key" value retrieved from the content filter response. For details on getting content_filter see Content Filters API
since (optional) Messages that have been placed in the stream since a given time. Expects the format to be seconds from epoch in UTC.

Response

The JSON and XML formats of the stream have the structure outlined in Message List Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/search.json?q=401k

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/messages/search.json?q=401k')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/search.json?q=401k");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/messages/search.json?q=401k';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/search.json?q=401k");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Messages since 2 hours ago

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/search.xml?q=a&since=1328359877

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/messages/search.xml?q=a&since=1328359877')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/search.xml?q=a&since=1328359877");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/messages/search.xml?q=a&since=1328359877';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/search.xml?q=a&since=1328359877");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Likes API

Liking a Message

Add a like for the authenticated user for a particular message.

Sample endpoints when the message id = 399

Request Type:

HTTP POST

Request Parameters:

None.

Response

The JSON and XML formats of a like have the structure outlined in Like Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X POST -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/39/likes.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post.new('/api/messages/39/likes.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/39/likes.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_POST, TRUE);
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(POST);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = POST 'https://demo.socialcast.com/api/messages/39/likes.xml', [];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/39/likes.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("POST");
con.setDoOutput(true);
String data = "";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Un-liking a Message

Un-like a message for the authenticated user.

Sample endpoints when the message id = 1 and like id = 3

Request Type:

HTTP DELETE

Request Parameters:

None

Response

The response will be an empty document with an HTTP status of 200.

Examples

Command Line Usage

bash


      # Curl Example
      curl -X DELETE -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/60/likes/12.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Delete.new('/api/messages/60/likes/12.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/60/likes/12.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, URLOPT_CUSTOMREQUEST, "DELETE");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(DELETE);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = DELETE 'https://demo.socialcast.com/api/messages/60/likes/12.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/60/likes/12.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("DELETE");
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Comments API

Get a Comment

Lookup a particular comment.

Looking up comment with id = 50

Request Type:

HTTP GET

Request Parameters:

None.

Response

The JSON and XML formats of a comment have the structure outlined in Comment Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/387/comments/43.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/messages/387/comments/43.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/387/comments/43.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/messages/387/comments/43.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/387/comments/43.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Creating Comments

Create a new comment for an existing message. Example message id = 399

Request Type:

HTTP POST

Request Parameters:

comment[text] (required) text for the comment
comment[attachment] (optional) file to attach to this comment. Should be sent as an HTTP multipart form.
comment[attachment_ids][] (optional) existing attachment to be connected to this comment. See the Creating Attachments API. You can include this parameter multiple times for multiple attachments.

Response

The JSON and XML formats of a comment have the structure outlined in Comment Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X POST -d "comment[text]=a%20comment%20from%20the%20api" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/39/comments.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post.new('/api/messages/39/comments.xml')
      req.set_form_data({"comment[text]"=>"a comment from the api"}, ';')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/39/comments.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "comment[text]=a%20comment%20from%20the%20api");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(POST);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = POST 'https://demo.socialcast.com/api/messages/39/comments.xml', ["comment[text]"=>"a comment from the api"];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/39/comments.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("POST");
con.setDoOutput(true);
String data = "comment[text]=a%20comment%20from%20the%20api";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Updating Comments

Update an existing comment on a message. Only the comment owner can perform this operation. Example comment id = 50

Request Type:

HTTP PUT

Required Request Headers:

Content-Type: multipart/form-data

Request Parameters:

comment[text] (required) text for the comment
comment[attachment] (optional) file to attach to this comment. Should be sent as an HTTP multipart form.
comment[attachment_ids][] (optional) existing attachment to be connected to this comment. See the Creating Attachments API. You can include this parameter multiple times for multiple attachments.

Response

The JSON and XML formats of a comment have the structure outlined in Comment Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X PUT -d "comment[text]=an%20updated%20comment%20from%20the%20api" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/387/comments/43.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Put.new('/api/messages/387/comments/43.xml')
      req.set_form_data({"comment[text]"=>"an updated comment from the api"}, ';')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/387/comments/43.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_PUT, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "comment[text]=an%20updated%20comment%20from%20the%20api");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(PUT);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = PUT 'https://demo.socialcast.com/api/messages/387/comments/43.xml', ["comment[text]"=>"an updated comment from the api"];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/387/comments/43.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("PUT");
con.setDoOutput(true);
String data = "comment[text]=an%20updated%20comment%20from%20the%20api";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Deleting a Comment

Delete a comment attached to a particular message. Only comment owners or community administrators are allowed to perform this operation. Example comment id = 50

Request Type:

HTTP DELETE

Request Parameters:

None

Response

An HTTP 200 response with an empty body.

Examples

Command Line Usage

bash


      # Curl Example
      curl -X DELETE -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/387/comments/43.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Delete.new('/api/messages/387/comments/43.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/387/comments/43.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, URLOPT_CUSTOMREQUEST, "DELETE");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(DELETE);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = DELETE 'https://demo.socialcast.com/api/messages/387/comments/43.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/387/comments/43.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("DELETE");
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Comment Likes API

Liking a Comment

Add a like for the authenticated user for a particular comment. Example comment id = 50

Request Type:

HTTP POST

Request Parameters:

None.

Response

The JSON and XML formats of a like have the structure outlined in Like Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X POST -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/39/comments/40/likes.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post.new('/api/messages/39/comments/40/likes.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/39/comments/40/likes.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_POST, TRUE);
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(POST);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = POST 'https://demo.socialcast.com/api/messages/39/comments/40/likes.xml', [];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/39/comments/40/likes.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("POST");
con.setDoOutput(true);
String data = "";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Un-liking a Comment

Un-like a comment for the authenticated user. Example like id = 5

Request Type:

HTTP DELETE

Request Parameters:

None

Response

The response will be an empty document with an HTTP status of 200.

Examples

Command Line Usage

bash


      # Curl Example
      curl -X DELETE -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/60/comments/70/likes/12.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Delete.new('/api/messages/60/comments/70/likes/12.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/60/comments/70/likes/12.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, URLOPT_CUSTOMREQUEST, "DELETE");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(DELETE);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = DELETE 'https://demo.socialcast.com/api/messages/60/comments/70/likes/12.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/60/comments/70/likes/12.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("DELETE");
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Flags API

Flag a Message

Add a flag for the authenticated user for a particular message. Example message id = 399

Request Type:

HTTP POST

Request Parameters:

None.

Response

The JSON and XML formats of a like have the structure outlined in Flag Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X POST -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/39/flags.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post.new('/api/messages/39/flags.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/39/flags.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_POST, TRUE);
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(POST);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = POST 'https://demo.socialcast.com/api/messages/39/flags.xml', [];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/39/flags.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("POST");
con.setDoOutput(true);
String data = "";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Un-Flag a Message

Un-flag a message for the authenticated user. Example message id = 399 and flag id = 6

Request Type:

HTTP DELETE

Request Parameters:

None

Response

The response will be an empty document with an HTTP status of 200.

Examples

Command Line Usage

bash


      # Curl Example
      curl -X DELETE -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages/60/flags/123.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Delete.new('/api/messages/60/flags/123.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/messages/60/flags/123.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, URLOPT_CUSTOMREQUEST, "DELETE");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(DELETE);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = DELETE 'https://demo.socialcast.com/api/messages/60/flags/123.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/messages/60/flags/123.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("DELETE");
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Users API

List all Active Users

Retrieve a paginated set of all active users in your community.

Request Type:

HTTP GET

Request Parameters:

page (optional) page number to view (starting with 1)
per_page (optional) results per page (default 20, max 500)
email (optional) filter list of results to only match the given email address
ids (optional) filter list of results by comma-separated IDs
liked_message (optional) pass a message ID to filter the list of results to people who liked a message
liked_comment (optional) pass a comment ID to filter the list of results to people who liked a comment

Response

Paginated set of users. The JSON and XML formats of a like have the structure outlined in User Profile Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/users.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/users.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/users.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/users.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/users.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Searching Users

Search through all users in your community. Example searching for "emily"

Request Type:

HTTP GET

Request Parameters:

q search query string
page (optional) The page of paginated content to be displayed to the user (starting with 1).
per_page (optional) results per page (default 20, max 500)

Response

The JSON and XML formats of the stream have the structure outlined in User Profile Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/users/search.json?q=emily

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/users/search.json?q=emily')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/users/search.json?q=emily");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/users/search.json?q=emily';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/users/search.json?q=emily");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

View User Profile

View information about a particular user. Example: User with id 25

Request Type:

HTTP GET

Request Parameters:

None.

Response

The JSON and XML formats of a like have the structure outlined in User Profile Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/users/25.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/users/25.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/users/25.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/users/25.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/users/25.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Update User Profile. Example: User with id 25

Request Type:

HTTP PUT

Required Request Headers:

Content-Type: multipart/form-data

Request Parameters:

See User Profile Response for available fields

Response

The JSON and XML formats of a like have the structure outlined in User Profile Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X PUT -d "user[first_name]=Jennifer" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/users/25.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Put.new('/api/users/25.xml')
      req.set_form_data({"user[first_name]"=>"Jennifer"}, ';')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/users/25.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_PUT, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "user[first_name]=Jennifer");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(PUT);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = PUT 'https://demo.socialcast.com/api/users/25.xml', ["user[first_name]"=>"Jennifer"];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/users/25.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("PUT");
con.setDoOutput(true);
String data = "user[first_name]=Jennifer";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Deactivate User. Example: User with id 25

Request Type:

HTTP DELETE

Request Parameters:

None

Response

The JSON and XML formats of a like have the structure outlined in User Profile Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X DELETE -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/users/25.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Delete.new('/api/users/25.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/users/25.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, URLOPT_CUSTOMREQUEST, "DELETE");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(DELETE);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = DELETE 'https://demo.socialcast.com/api/users/25.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/users/25.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("DELETE");
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Follow/Unfollow API

View List of Followers

return a paginated list of a user's followers. Example: User with id 25

Request Type:

HTTP GET

Request Parameters:

page (optional) page number to view (starting with 1)
per_page (optional) results per page (default 20, max 500)

Response

Paginated set of users. The JSON and XML formats of a like have the structure outlined in User Profile Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/users/27/followers.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/users/27/followers.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/users/27/followers.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/users/27/followers.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/users/27/followers.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Follow a User

Request Type:

HTTP POST

Request Parameters:

None.

Response

The JSON and XML formats of a like have the structure outlined in User Profile Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X POST -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/users/27/followers.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post.new('/api/users/27/followers.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/users/27/followers.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_POST, TRUE);
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(POST);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = POST 'https://demo.socialcast.com/api/users/27/followers.xml', [];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/users/27/followers.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("POST");
con.setDoOutput(true);
String data = "";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Un-Follow a User

Remove a following relationship for the authenticated user. Example: User with id 25

Request Type:

HTTP DELETE

Request Parameters:

None.

Response

empty response with an HTTP status code of 200.

Examples

Command Line Usage

bash


      # Curl Example
      curl -X DELETE -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/users/25/followers/26.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Delete.new('/api/users/25/followers/26.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/users/25/followers/26.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, URLOPT_CUSTOMREQUEST, "DELETE");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(DELETE);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = DELETE 'https://demo.socialcast.com/api/users/25/followers/26.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/users/25/followers/26.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("DELETE");
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Following API

View List of Users Being Followed

return a paginated list of users that a user is currently following. Example: User with id 25

Request Type:

HTTP GET

Request Parameters:

page (optional) page number to view (starting with 1)
per_page (optional) results per page (default 20, max 500)

Response

A paginated set of users. The JSON and XML formats of the stream have the structure outlined in User Profile Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/users/27/following.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/users/27/following.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/users/27/following.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/users/27/following.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/users/27/following.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Groups API

Listing Groups

List all the groups that the user has access to.

Request Type:

HTTP GET

Request Parameters:

page (optional) page number to view (starting with 1)
per_page (optional) results per page (default 20, max 500)

Response

Paginated set of groups. The JSON and XML formats have the structure outlined in Group Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/groups

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/groups')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/groups");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/groups';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/groups");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Listing Members of a Group

List all the members of a group that the user has access to. Example: Group with name acmecorpsoftballteam

Request Type:

HTTP GET

Request Parameters:

page (optional) page number to view (starting with 1)
per_page (optional) results per page (default 20, max 500)

Response

Paginated set of users. The JSON and XML formats have the structure outlined in User Profile Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/groups/acmecorpsoftballteam/members

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/groups/acmecorpsoftballteam/members')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/groups/acmecorpsoftballteam/members");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/groups/acmecorpsoftballteam/members';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/groups/acmecorpsoftballteam/members");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Listing Group Memberships

List all groups that the user is a member of.

Request Type:

HTTP GET

Request Parameters:

None.

Response

The JSON and XML formats of a like have the structure outlined in Group Membership Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/group_memberships.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/group_memberships.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/group_memberships.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/group_memberships.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/group_memberships.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Categories API

Listing Tenant Categories

Get a listing of all the categories from the current tenant

Request Type:

HTTP GET

Request Parameters:

None.

Response

The JSON and XML formats of a category have the structure outlined in Category List Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/categories.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/categories.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/categories.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/categories.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/categories.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Content Filters API

Listing Tenant Content Filters

Get a listing of all content filters associated to the current tenant

Request Type:

HTTP GET

Request Parameters:

None.

Response

The JSON and XML formats of a category have the structure outlined in Content Filter List Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/content_filters.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/content_filters.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/content_filters.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/content_filters.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/content_filters.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Streams API

Listing User's Streams

Get a listing of the streams that a user has.

Request Type:

HTTP GET

Request Parameters:

None.

Response

The JSON and XML formats of a stream has the structure outlined in Stream List Response

Examples

Command Line Usage

bash


      # Curl Example
      curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/streams.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Get.new('/api/streams.xml')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/streams.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(GET);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = GET 'https://demo.socialcast.com/api/streams.xml';
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/streams.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
        }
      }

Attachments API

Creating Attachments

Create a message attachment - limit 100MB.

Supports creating Attachments prior to a Create Message or Create Comment call, such as when there is an upload widget which allows the user to complete file uploads before sending a message. To connect your attachment to a message, send the id from the Attachment Response to the Create Message call.

Note that you can also create attachments directly as part of a Create Message call.

Request Type:

HTTP POST

Request Parameters:

attachment (required) file data to upload. Should be sent as an HTTP multipart form.

Response:

The XML and JSON format of the communities returned has the structure outlined in Attachment Response

Command Line Usage

bash

      # Curl Example
      curl -X POST -F "attachment=@/path/to/file.pdf" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/attachments.xml

ruby

      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      require 'rubygems'
      require 'net/http/post/multipart' #see http://github.com/nicksieger/multipart-post
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post::Multipart.new "/api/attachments.xml", "attachment" => UploadIO.new("/path/to/file.pdf", "application/pdf")")
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

Authentication API

Retrieve list of Active Communities

Users may have accounts in multiple communities and this API serves as a single entry point to determine the correct subdomain. Logging into the Socialcast Authentication API gives you access to the list of communities that the user is a member of.

POST requests to /api/authentication with basic auth credentials to determine if the user has correct credentials.

Request Type:

HTTP POST

Request Parameters:

email (required) email of the user
password (required) password of the user

Response:

The XML and JSON format of the communities returned has the structure outlined in Community List Response

Response for invalid credentials will have a 401 response code with the following structure:

authentication-failure Description of authentication request failure
- error-message Human-readable error message describing why the authentication request failed.
- error-code A machine-readable code describing why the authentication request failed. See Authentication Error Codes for a complete list.
- signup-allowed Boolean indicating whether or not this server supports signup.

Authentication Error Codes:

The following error codes may be returned as part of an authentication failure response:

user_account_missing Couldn't find an account associated with the email address supplied.
tenant_inactive The community that user belongs to is no longer active.
user_account_disabled The user account associated with the email address has been disabled.
user_account_reactivating The user account is in the process of being reactivated. An email has been delivered to the email address with further instructions.
password_incorrect The supplied password did not match the password on file.

Examples

Command Line Usage

bash


      # Curl Example
      curl -X POST -d "password=demo&email=emily@socialcast.com" -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/authentication.xml

ruby


      # Ruby example
      require 'net/http'
      require 'net/https'
      require 'openssl'
      
      
      https = Net::HTTP.new('demo.socialcast.com', 443) 
      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
      https.use_ssl = true
      response = ""
      https.start do |session|
        req = Net::HTTP::Post.new('/api/authentication.xml')
      req.set_form_data({"password"=>"demo", "email"=>"emily@socialcast.com"}, ';')
        req.basic_auth 'emily@socialcast.com', 'demo'
        response = session.request(req).body
      end
      
      puts response

php


      <?php
      // PHP example
      // create a new cURL resource
      $ch = curl_init();

      // set URL and other appropriate options
      curl_setopt($ch, CURLOPT_URL, "https://demo.socialcast.com/api/authentication.xml");
      curl_setopt($ch, CURLOPT_HEADER, FALSE);
      curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
      
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "password=demo&email=emily@socialcast.com");
      curl_setopt($ch, CURLOPT_USERPWD, "emily@socialcast.com:demo");
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

      // grab URL and pass it to the browser
      $api_return = curl_exec($ch);

      echo $api_return;

      // close cURL resource, and free up system resources
      curl_close($ch);

      ?>

perl


      # Perl example
      use HTTP::Request::Common qw(POST);
      use LWP::UserAgent;
      use HTTP::Message;
      use strict;

      my $ua = LWP::UserAgent->new;

      my $req = POST 'https://demo.socialcast.com/api/authentication.xml', ["password"=>"demo", "email"=>"emily@socialcast.com"];
      $req->authorization_basic('emily@socialcast.com', 'demo');

      my $response = $ua->request($req)->content;

      print "$response";

java


      // Java example
      import java.io.BufferedReader;
      import java.io.OutputStreamWriter;
      import java.io.InputStream;
      import java.io.InputStreamReader;
      import java.net.Authenticator;
      import java.net.PasswordAuthentication;
      import java.net.URL;
      import java.net.HttpURLConnection;

      public class Api {
        static final String kuser = "emily@socialcast.com";
        static final String kpass = "demo";

        static class SocialcastAuthenticator extends Authenticator {
            public PasswordAuthentication getPasswordAuthentication() {
                return (new PasswordAuthentication(kuser, kpass.toCharArray()));
            }
        }

        public static void main(String[] args) throws java.net.MalformedURLException, java.io.IOException{
            Authenticator.setDefault(new SocialcastAuthenticator());
            
            URL url = new URL("https://demo.socialcast.com/api/authentication.xml");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            
con.setRequestMethod("POST");
con.setDoOutput(true);
String data = "password=demo&email=emily@socialcast.com";
OutputStreamWriter writer = new OutputStreamWriter(con.getOutputStream());
writer.write(data);
writer.flush();
            
            InputStream ins = con.getInputStream();
            BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
            
            String str;
            while((str = reader.readLine()) != null)
                System.out.println(str);

            reader.close();
writer.close();
        }
      }

Response Formats

Private Message List Response

private_messages[] container for all private messages.
- private_message{} individual private message. See Private Message Response for the structure of the hash.

Private Message Response

id The id of the private message
body The text in the private message
url permalink url for the private message api end point
permalink_url permalink url for the private message's human readable page
external_url (optional) If a link was included with the message it will be shown here.
replied_to (optional) If the private message was done in response to another message in the stream. This field will have the id of that message
sender User who sent the message. See User Response for the user format.
recipient User who the message was sent to. See User Response for the user format.
replies[] (optional) array of replies posted for this private message
- reply{} individual reply for the message. See Reply Response for the reply format
unread Boolean set to true if the message has not been marked as read or a reply posted
created_at date/time the message was created. formatted according to iso8601 specification.
last_interacted_at integer field Unix timestamp of last time a message, comment or like was posted to this stream. Available for all streams except Company Stream.
media_files[] (optional) array of referenced media files for this message. Includes images, video, audio, etc. Includes info for URLs referenced in the message as well as attachments.
- title (optional) Label for this media file
- thumbnails{} (optional) Image thumbnail URLs for this media file
  - stream 140x140 pixel or smaller image
  - stream_square 75x75 pixel image
  - square45 45x45 pixel image
  - scaled480 480x480 pixel or smaller image
- page_url (optional) Page in which this media file is embedded. Examples: YouTube video page, Flickr photo page.
- url URL for the media file
- content_type MIME type of the media file
- attachment_id (optional) ID of the corresponding attachment if this media_file entry is for an attached file
source{} (optional) source of this message
- id unique id of the source (examples: web, twitter, desktop)
- name label for this source (examples: web, Twitter, Socialcast Blog)
- url (optional) URL for this source (examples: http://twitter.com/socialcast, http://demo.socialcast.com/services/desktop)
attachments[] (optional) file attachments for this private message
- attachment{} individual attachment for the message. See Attachment Response for the attachment format.

Private Message Response

id The id of the private message reply
message_id The id of the private message that this reply was for
body The text in the private message reply
url permalink url for the private message reply api end point
permalink_url permalink url for the private message reply's human readable page
user User who sent the reply. See User Response for the user format.
unread Boolean set to true if the reply has not been marked as read or a reply posted
created_at date/time the reply was created. formatted according to iso8601 specification.
media_files[] (optional) array of referenced media files for this message. Includes images, video, audio, etc. Includes info for URLs referenced in the message as well as attachments.
- title (optional) Label for this media file
- thumbnails{} (optional) Image thumbnail URLs for this media file
  - stream 140x140 pixel or smaller image
  - stream_square 75x75 pixel image
  - square45 45x45 pixel image
  - scaled480 480x480 pixel or smaller image
- page_url (optional) Page in which this media file is embedded. Examples: YouTube video page, Flickr photo page.
- url URL for the media file
- content_type MIME type of the media file
- attachment_id (optional) ID of the corresponding attachment if this media_file entry is for an attached file
source{} (optional) source of this message
- id unique id of the source (examples: web, twitter, desktop)
- name label for this source (examples: web, Twitter, Socialcast Blog)
- url (optional) URL for this source (examples: http://twitter.com/socialcast, http://demo.socialcast.com/services/desktop)
attachments[] (optional) file attachments for this private message
- attachment{} individual attachment for the message. See Attachment Response for the attachment format.

Message List Response

messages[] container for all messages in the stream.
- message{} individual message in the stream. See Message Response for the structure of the hash.

Message Response

message{} individual message in the stream
- title title of the message
- body (optional) details for the message
- url url for interacting with the message via the API.
- permalink-url url for accessing the message's permalink page.
- action useful text to construct a sentence from the message title, (ex: asked a question)
- external-url (optional) external url for shared links, bookmarks, YouTube videos, etc.
- icon url for the icon image for this message type.
- id unique ID for this message. Use this ID for posting comments or likes on this message.
- likable boolean flag whether this user can "like" the message. (ex: users can not like their own content)
- created-at date/time the message was created. formatted according to iso8601 specification.
- last-interacted-at date/time that the message was last interacted interacted with. formatted as millis since epoch.
- player-url The URL of a flash player which should be embedded in this message in supporting clients.
- thumbnail-url Location of the thumbnail to display before embedding the flash player.
- player-params FlashVars to pass to the embedded flash player.
- user{} owning user of the message. See User Response for the user format.
- group{} (deprecated) Use the groups array to inspect what groups this message belongs to.
- groups[] list of groups that this message belongs to. See Group Response for the group format.
- source{} (optional) source of this message
  - id unique id of the source (examples: web, twitter, desktop)
  - name label for this source (examples: web, Twitter, Socialcast Blog)
  - url (optional) URL for this source (examples: http://twitter.com/socialcast, http://demo.socialcast.com/services/desktop)
- attachments[] (optional) file attachments for this message
  - attachment{} individual attachment for the message. See Attachment Response for the attachment format.
- comments[] (optional) array of comments posted for this message
  - comment{} individual comment for the message. See Comment Response for the comment format
- comments_count integer total number of comments for this message
- likes[] (optional) array of likes for this message
  - like{} individual like for this message. See Like Response for the like format.
- likes_count integer total number of likes for this message
- media_files[] (optional) array of referenced media files for this message. Includes images, video, audio, etc. Includes info for URLs referenced in the message as well as attachments.
  - title (optional) Label for this media file
  - thumbnails{} (optional) Image thumbnail URLs for this media file
    - stream 140x140 pixel or smaller image
    - stream_square 75x75 pixel image
    - square45 45x45 pixel image
    - scaled480 480x480 pixel or smaller image
  - page_url (optional) Page in which this media file is embedded. Examples: YouTube video page, Flickr photo page.
  - url URL for the media file
  - content_type MIME type of the media file
  - attachment_id (optional) ID of the corresponding attachment if this media_file entry is for an attached file
- recipients[] (optional) array of users that this message was sent to
  - recipient{} user that this message was sent to. See User Response for the user format. Note: In this instance the word recipient is used instead of user.
- tags[] (optional) array of tags for this message
  - tag{} individual tag for the message
    - name name of the tag
- flag{} (optional) flag for the current user. See Flag Response for the format.
- in_origin_stream (on create only) boolean flag to notify clients if the message belongs in the stream that it was generated from (see origin_stream[id] parameter in [POST] /api/messages )

User Response

The Lean version only has: id, name and url

user{} user object.
- id unique id for this user
- name full name of the user
- url url for the profile page of the user
- username username for sending direct messages - Not in Lean version
- terminated true if the user has been deactivated - Not in Lean version
- followers_count the number of people following this user.
- following_count the number of people this user is following
- avatars{} urls for various sizes of user avatar pictures - Not in Lean version
  - square140 140x140 pixel image
  - square70 70x70 pixel image
  - square45 45x45 pixel image
  - square30 30x30 pixel image
  - square16 16x16 pixel image

Comment Response

comment{} individual comment for a message.
- id the unique id for this comment
- text plain text comment
- url URL for interacting with the comment via the API.
- user{} owning user of the comment. See User Response for the user format.
- created-at date/time comment was posted. formatted according to iso8601 specification.
- editable boolean flag to notify clients if the comment is editable by the current user.
- deletable boolean flag to notify clients if the comment is deletable by the current user.
- likable boolean flag to notify clients if the comment is likable by the current user.
- likes[] array of likes for this comment
  - like{} individual like for this comment. See Like Response for the like format.
- likes_count integer total number of likes for this comment.
- attachments[] list of attached files to this comment.
  - attachment{} individual attachment for a comment. See Attachment Response for the attachment format.

Like Response

like{} individual like for a message
- id unique ID for this like. (required for removing the like)
- unlikable boolean flag if the current user has access to remove this like
- created-at date/time like was created. formatted according to iso8601 specification.
- user{} user that liked this message. See Lean User Response for the user format.

Flag Response

flag{} individual flag for a message
- id unique ID for this flag. (required for removing the flag)

User Profile Response

user{} user profile information
- id unique ID for this user.
- name full name of the user (includes first and last name)
- username username used for sending direct messages
- status_message{} (optional) current status message for the user. See Message Response for the format
- custom-fields[] (optional) list of custom profile fields for the user
  - id unique identifier for this custom field
  - label displayable text for the custom field label
  - value user value for the custom field
- contact-info{} contact information available for the user
  - email email address for the user
  - office-phone (optional) office phone number
  - cell-phone (optional) cell phone number
  - location (optional) Location of user
  - skype (optional) skype username
  - jabber (optional) XMPP/Jabber username
  - google-talk (optional) Google Talk username
  - aim (optional) AOL Instant Messenger username
  - msn (optional) MSN username
  - yahoo (optional) Yahoo username
- followable flag if current user can follow/unfollow this user
- following-count number of users that this user is following
- followers-count number of users that this user is being followed by
- contact-id (optional) Unique ID if current user is following this user. See Unfollow API for more information.
- avatars{} urls for various sizes of user avatar pictures.
  - square140 140x140 pixel image
  - square70 70x70 pixel image
  - square30 30x30 pixel image
  - square16 16x16 pixel image

Group Response

group {} group information
- admin_ids user ids for the administrators of the group
- description description of the group
- groupname human readable id for the group
- id unique id of the group
- name name of the group
- permission the visibility of the group
- state whether the group is active or archived
- url url to view the group permalink page
- username human readable id for the group
- avatars{} urls for various sizes of group avatar pictures.
  - square140 140x140 pixel image
  - square70 70x70 pixel image
  - square30 30x30 pixel image
  - square16 16x16 pixel image

Group Membership Response

group-memberships[] container for all groups the user is a member of
- group-membership{} information about a specific group membership
  - group{} information about the group this membership record refers to
    - id unique id of the group. can be used to post messages into a specific group.
    - name name of the group
    - url url to view the group permalink page
    - avatars{} urls for various sizes of user avatar pictures.
      - square140 140x140 pixel image
      - square70 70x70 pixel image
      - square30 30x30 pixel image
      - square16 16x16 pixel image
  - role The role that the user plays in this group, "Member" if the user is a member, or "Admin" if the user administers this group.

Community List Response

communities[] array of Socialcast communities that this user has access to.
- community{} community that the user has access to.
  - name name of the Socialcast community
  - subdomain subdomain to access the Socialcast community.
  - domain the fully qualified domain to use for accessing the Socialcast community.
  - profile profile information for the authenticated user's community. See User Profile Response for format.

Attachment Response

attachment{} attachment object.
- id id of the attachment
- filename name of the attachment
- url url for accessing the attachment
- public_filename secure url for downloading file content
- file_extension extension of the attachment file
- content_type mime content type of the attached file

Category List Response

categories[] array of category objects
- category{} category object
  - id unique id for this category. To be used with other API calls.
  - title title for the given category

Content Filter List Response

content_filters[] array of content_filter objects
- content_filter{} content filter object
  - key should be used in API requests to filter stream
  - name name for the given content filter

Stream List Response

streams[] array of stream objects
- stream{} stream object
  - id unique identifier to be used in API requests
  - name name for the given stream
  - default boolean field identifying the user's default stream
  - last_interacted_at integer field Unix timestamp of last time a message, comment or like was posted to this stream. Available for all streams except Company Stream.
  - custom_stream boolean flag identifying if this stream is a user defined custom stream
  - group{} (optional) group that this stream references. See Group Response for the group format.

Standard Error Response

errors[] array of errors from the request
- error specific error message