API Documentation

The first thing you need to get started with the Cadmus API is your API key. You can get your API key from here. This key is used when making a call to the API and helps us identify who is making the call. You can also give your API key to third party applications and they can make the calls on your behalf. If at any point you feel that your key is being misused, you can simply reset the key here.

If you have any questions or concerns about the API you can send me an email or contact me on Twitter.

The Posts API

Using the Posts API you can get your filtered stream similar to the way that it is displayed on your homepage.

URL
http://thecadmus.com/api/posts

Parameters
key
The API key. You can get your API key from here.
count
The number of posts to return. Defaults to 30. Restricted to a maximum of 50.
page
The page number of the results. Defaults to 1 (the first page of posts).
timespan
The posts in the past number of hours; capped at 168 (1 week). Defaults to 24 (the past day of posts).
format
The format of the response (xml or json). Defaults to json.
callback
The JSON callback function. Defaults to no value.

Response

JSON

[
 {
  "id":5127572787,
  "text":"Test post content #1.",
  "created_at":"Tue Oct 27 18:02:00 +0000 2009",
  "link":"http:\/\/twitter.com\/fanjiewang\/status\/5127572787",
  "type":"twitter",
  "user": {
   "screen_name":"fanjiewang",
   "name":"Frank Wang",
   "profile_image_url":"http:\/\/s.twimg.com\/image_bigger.png",
   "profile_url":"http:\/\/twitter.com\/fanjiewang"
  },
  "comments": [
   {
    "id":123
    "text":"content",
    "created_at":"Tue Oct 27 18:04:00 +0000 2009",
    "link":"http:\/\/twitter.com\/fanjiewang\/status\/123",
    "type":"twitter",
    "user": {
     "screen_name":"fanjiewang",
     "name":"Frank Wang",
     "profile_image_url":"http:\/\/s.twimg.com\/image.img",
     "profile_url":"http:\/\/twitter.com\/fanjiewang"
    }
   }
  ],
  "related": [
   {
    "id":5127572788,
    "text":"Test post content #2.",
    "created_at":"Tue Oct 27 18:02:00 +0000 2009",
    "link":"http:\/\/twitter.com\/fanjiewang\/status\/5127572788",
    "type":"twitter",
    "user": {
     "screen_name":"fanjiewang",
     "name":"Frank Wang",
     "profile_image_url":"http:\/\/s.twimg.com\/image_bigger.png",
     "profile_url":"http:\/\/twitter.com\/fanjiewang"
    },
    "comments": [
     {
      "id":1234
      "text":"content",
      "created_at":"Tue Oct 27 18:04:00 +0000 2009",
      "link":"http:\/\/twitter.com\/fanjiewang\/status\/1234",
      "type":"twitter",
      "user": {
       "screen_name":"fanjiewang",
       "name":"Frank Wang",
       "profile_image_url":"http:\/\/s.twimg.com\/image.img",
       "profile_url":"http:\/\/twitter.com\/fanjiewang"
      }
     }
    ]
   }
  ]
 },
 ... and so on ...
]

JSON with callback

myCallbackFunction(
 [
  {
   "id":5127572787,
   "text":"Test post content #1.",
   "created_at":"Tue Oct 27 18:02:00 +0000 2009",
   "link":"http:\/\/twitter.com\/fanjiewang\/status\/5127572787",
   "type":"twitter",
   "user": {
    "screen_name":"fanjiewang",
    "name":"Frank Wang",
    "profile_image_url":"http:\/\/s.twimg.com\/image_bigger.png",
    "profile_url":"http:\/\/twitter.com\/fanjiewang"
   },
   "comments": [
    {
     "id":123
     "text":"content",
     "created_at":"Tue Oct 27 18:04:00 +0000 2009",
     "link":"http:\/\/twitter.com\/fanjiewang\/status\/123",
     "type":"twitter",
     "user": {
      "screen_name":"fanjiewang",
      "name":"Frank Wang",
      "profile_image_url":"http:\/\/s.twimg.com\/image.img",
      "profile_url":"http:\/\/twitter.com\/fanjiewang"
     }
    }
   ],
   "related": [
    {
     "id":5127572788,
     "text":"Test post content #2.",
     "created_at":"Tue Oct 27 18:02:00 +0000 2009",
     "link":"http:\/\/twitter.com\/fanjiewang\/status\/5127572788",
     "type":"twitter",
     "user": {
      "screen_name":"fanjiewang",
      "name":"Frank Wang",
      "profile_image_url":"http:\/\/s.twimg.com\/image_bigger.png",
      "profile_url":"http:\/\/twitter.com\/fanjiewang"
     },
     "comments": [
      {
       "id":1234
       "text":"content",
       "created_at":"Tue Oct 27 18:04:00 +0000 2009",
       "link":"http:\/\/twitter.com\/fanjiewang\/status\/1234",
       "type":"twitter",
       "user": {
        "screen_name":"fanjiewang",
        "name":"Frank Wang",
        "profile_image_url":"http:\/\/s.twimg.com\/image.img",
        "profile_url":"http:\/\/twitter.com\/fanjiewang"
       }
      }
     ]
    }
   ]
  },
  ... and so on ...
 ]
);

XML

<?xml version="1.0" encoding="UTF-8"?>
<posts>
 <post>
  <id>123</id>
  <text>content</text>
  <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
  <service_type>twitter</service_type>
  <link>http://twitter.com/fanjiewang/status/123</link>
  <user>
   <screen_name>fanjiewang</screen_name>
   <name>Frank Wang</name>
   <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
   <profile_url>http://twitter.com/fanjiewang</profile_url>
  </user>
  <comments>
   <comment>
    <id>123</id>
    <text>content</text>
    <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
    <service_type>twitter</service_type>
    <link>http://twitter.com/fanjiewang/status/123</link>
    <user>
     <screen_name>fanjiewang</screen_name>
     <name>Frank Wang</name>
     <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
     <profile_url>http://twitter.com/fanjiewang</profile_url>
    </user>
   </comment>
  </comments>
  <related>
   <post>
    <id>1234</id>
    <text>content</text>
    <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
    <service_type>twitter</service_type>
    <link>http://twitter.com/fanjiewang/status/1234</link>
    <user>
     <screen_name>fanjiewang</screen_name>
     <name>Frank Wang</name>
     <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
     <profile_url>http://twitter.com/fanjiewang</profile_url>
    </user>
    <comments>
     <comment>
      <id>123</id>
      <text>content</text>
      <created_at>Tue Oct 27 18:02:00 +0000 2009</created_at>
      <service_type>twitter</service_type>
      <link>http://twitter.com/fanjiewang/status/123</link>
      <user>
       <screen_name>fanjiewang</screen_name>
       <name>Frank Wang</name>
       <profile_image_url>http://s.twimg.com/image.img</profile_image_url>
       <profile_url>http://twitter.com/fanjiewang</profile_url>
      </user>
     </comment>
    </comments>
   </post>
  </related>
 </post>
 ... and so on ...
</posts>

Error in JSON
```
{"error":true,"code":xxx}
					
```

Error in JSON with callback

myCallbackFunction({"error":true,"code":xxx});

Error in XML

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <error>true</error>
 <code>xxx</code>
</response>

Error Codes

Below are the error codes and their descriptions, that are thrown in case something goes wrong. The appropriate HTTP headers are set as well.
404
The API call made does not exist. Check the API url for typos.
401
The API key given is invalid. You can get the right API key from here.
500
Sorry, something went wrong on our end. In all likelihood we have been emailed about it and are looking into it. You can send me an email or contact me via Twitter for further details.

Examples

You can try the examples below in your terminal using cURL or simply put in the url in your browser and try it out. The '******....' value needs to be replaced with your real API key, which you can find here.
Default
curl http://thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Get 10 posts
curl http://thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=10
Get the posts in the past 10 hours
curl http://thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx×pan=10
Get the second page of posts
curl http://thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&page=2
Using a callback
curl http://thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&callback=showPostsFunction
In XML
curl http://thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&format=xml
All options
curl http://thecadmus.com/api/posts?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&count=20&page=1×pan=48&format=json&callback=showPostsFunction

This page was last updated on Jan 16, 2010.

About Us • API • FAQ • Contact • Blog • Twitter

API Documentation

The Posts API

URL

Parameters

Response

JSON

JSON with callback

XML

Error in JSON

Error in JSON with callback

Error in XML

Error Codes

Examples

Default

Get 10 posts

Get the posts in the past 10 hours

Get the second page of posts

Using a callback

In XML

All options