The Raven Tools REST API allows access to our Keyword Manager and Link Manager for developers. Additionally, endpoints are provided to create and manage campaigns (websites) within the platform. The response can be returned in XML or JSON format.
Get an API Key API Testing Console
The API endpoint is https://api.raventools.com/api. The following examples outline how to use query string parameters on this address along with your API Key to access data from your account.
https://api.raventools.com/api
key
This is your assigned API key. It must be provided on every request.
format
This can be xml or json.
This request will return details for a given domain.
method
domain_info
domain
The domain name. Must match exactly.
Example: https://api.raventools.com/api?key=YOURAPIKEY&method=domain_info&domain=tweetstalk.com&format=xml Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <domain> <domain>tweetstalk.com</domain> <description>TweetStalk</description> </domain> </Raven> Sample Response (JSON): {"domain":"tweetstalk.com","description":"TweetStalk"}
https://api.raventools.com/api?key=YOURAPIKEY&method=domain_info&domain=tweetstalk.com&format=xml
<?xml version="1.0" encoding="UTF-8"?> <Raven> <domain> <domain>tweetstalk.com</domain> <description>TweetStalk</description> </domain> </Raven>
{"domain":"tweetstalk.com","description":"TweetStalk"}
This request will return details for the profile associated with your API key.
profile_info
Example: https://api.raventools.com/api?key=YOURAPIKEY&method=profile_info&format=xml Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <profile> <name>Client Accounts</name> </profile> </Raven> Sample Response (JSON): {"name":"Client Accounts"}
https://api.raventools.com/api?key=YOURAPIKEY&method=profile_info&format=xml
<?xml version="1.0" encoding="UTF-8"?> <Raven> <profile> <name>Client Accounts</name> </profile> </Raven>
{"name":"Client Accounts"}
This request will return the available domains for the profile associated with your API key.
domains
Example: https://api.raventools.com/api?key=YOURAPIKEY&method=domains&format=xml Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <domains> <domain>sample.net</domain> <domain>tweetstalk.com</domain> </domains> </Raven> Sample Response (JSON): ["example.com","tweetstalk.com"]
https://api.raventools.com/api?key=YOURAPIKEY&method=domains&format=xml
<?xml version="1.0" encoding="UTF-8"?> <Raven> <domains> <domain>sample.net</domain> <domain>tweetstalk.com</domain> </domains> </Raven>
["example.com","tweetstalk.com"]
This request will permanently remove the specified domain.
remove_domain
The domain name you want to remove - there is no undo.
Example: https://api.raventools.com/api?key=YOURAPIKEY&method=remove_domain&domain=tweetstalk.com&format=xml Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <response> <message>success</message> </response> </Raven> Sample Response (JSON): {"response":"success"}
https://api.raventools.com/api?key=YOURAPIKEY&method=remove_domain&domain=tweetstalk.com&format=xml
<?xml version="1.0" encoding="UTF-8"?> <Raven> <response> <message>success</message> </response> </Raven>
{"response":"success"}
This request will add the domain provided.
add_domain
The domain name you want to add. "www." prefixes are ignored for purposes of matching link checks, but will be stored as part of the domain name for future requests.
Example: https://api.raventools.com/api?key=YOURAPIKEY&method=add_domain&domain=tweetstalk.com&format=xml Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <response> <message>success</message> </response> </Raven> Sample Response (JSON): {"response":"success"}
https://api.raventools.com/api?key=YOURAPIKEY&method=add_domain&domain=tweetstalk.com&format=xml
This request will add keyword to the domain provided.
add_keyword
The domain name you want to add a keyword to. Must match exactly.
keyword
The keyword name you want to add.
Example: https://api.raventools.com/api?key=YOURAPIKEY&method=add_keyword&domain=tweetstalk.com&keyword=nashville+seo&format=xml Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <response> <message>success</message> </response> </Raven> Sample Response (JSON): {"response":"success"}
https://api.raventools.com/api?key=YOURAPIKEY&method=add_keyword&domain=tweetstalk.com&keyword=nashville+seo&format=xml
This request will remove a keyword from the domain provided.
remove_keyword
The domain name you want to remove the keyword from. Must match exactly.
The keyword name you want to remove.
Example: https://api.raventools.com/api?key=YOURAPIKEY&method=remove_keyword&domain=tweetstalk.com&keyword=nashville+seo&format=xml Return Values: "success" or "not found" Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <response> <message>success</message> </response> </Raven> Sample Response (JSON): {"response":"success"}
https://api.raventools.com/api?key=YOURAPIKEY&method=remove_keyword&domain=tweetstalk.com&keyword=nashville+seo&format=xml
"success" or "not found"
This request will return the available competitors for the domain provided.
competitors
The domain of a competitor to add.
Example: https://api.raventools.com/api?key=YOURAPIKEY&method=competitors&domain=tweetstalk.com&format=xml Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <competitors> <competitor>hootsuite.com</competitor> <competitor>seesmic.com</competitor> <competitor>tweetdeck.com</competitor> </competitors> </Raven> Sample Response (JSON): ["hootsuite.com","seesmic.com","tweetdeck.com"]
https://api.raventools.com/api?key=YOURAPIKEY&method=competitors&domain=tweetstalk.com&format=xml
<?xml version="1.0" encoding="UTF-8"?> <Raven> <competitors> <competitor>hootsuite.com</competitor> <competitor>seesmic.com</competitor> <competitor>tweetdeck.com</competitor> </competitors> </Raven>
["hootsuite.com","seesmic.com","tweetdeck.com"]
This request will return the available keywords for the domain provided.
keywords
Example: https://api.raventools.com/api?key=YOURAPIKEY&method=keywords&domain=tweetstalk.com&format=xml Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <keywords> <keyword>best free seo tool</keyword> <keyword>breaking news</keyword> <keyword>stalk twitter</keyword> <keyword>stalking twitter</keyword> <keyword>tweet stalk</keyword> <keyword>tweetstalk</keyword> <keyword>tweetstalker</keyword> <keyword>twitter stalk</keyword> <keyword>twitter stalking</keyword> <keyword>twitterstalk</keyword> </keywords> </Raven> Sample Response (JSON): ["best free seo tool","breaking news","stalk twitter","stalking twitter","tweet stalk","tweetstalk","tweetstalker","twitter stalk","twitter stalking","twitterstalk"]
https://api.raventools.com/api?key=YOURAPIKEY&method=keywords&domain=tweetstalk.com&format=xml
<?xml version="1.0" encoding="UTF-8"?> <Raven> <keywords> <keyword>best free seo tool</keyword> <keyword>breaking news</keyword> <keyword>stalk twitter</keyword> <keyword>stalking twitter</keyword> <keyword>tweet stalk</keyword> <keyword>tweetstalk</keyword> <keyword>tweetstalker</keyword> <keyword>twitter stalk</keyword> <keyword>twitter stalking</keyword> <keyword>twitterstalk</keyword> </keywords> </Raven>
["best free seo tool","breaking news","stalk twitter","stalking twitter","tweet stalk","tweetstalk","tweetstalker","twitter stalk","twitter stalking","twitterstalk"]
keywords_tags
Example: https://api.raventools.com/api?key=YOURAPIKEY&method=keywords_tags&domain=tweetstalk.com&format=xml Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <keywords> <keyword> <value>best free seo tool</value> <tags> <tag>seo</tag> <tag>tool</tag> </tags> </keyword> <keyword> <value>breaking news</value> <tags> <tag>news;/tag> </tags> </keyword> <keyword> <value>stalk twitter</value> <tags /> </keyword> <keyword> <value>stalking twitter</value> <tags> <tag>stalking</tag> </tags> </keyword> <keyword> <value>tweet stalk</value> <tags> <tag>tweet</tag> <tag>stalk</tag> </tags> </keyword> <keyword> <value>tweetstalk</value> <tags> <tag>stalk</tag> </tags> </keyword> <keyword> <value>tweetstalker</value> <tags> <tag>stalker</tag> </tags> </keyword> <keyword> <value>twitter stalk</value> <tags> <tag>stalk</tag> </tags> </keyword> <keyword> <value>twitter stalking</value> <tags> <tag>stalking</tag> </tags> </keyword> <keyword> <value>twitterstalk</value> <tags /> </keyword> </keywords> </Raven> Sample Response (JSON): [{"keyword":"best free seo tool","tags":["seo","tool"]}, {"keyword":"breaking news","tags":["news"]}, {"keyword":"stalk twitter","tags":null}, {"keyword":"stalking twitter","tags":["stalking"]}, {"keyword":"tweet stalk","tags":["tweet","stalk"]}, {"keyword":"tweetstalk","tags":["stalk"]}, {"keyword":"tweetstalker","tags":["stalker"]}, {"keyword":"twitter stalk","tags":["stalk"]}, {"keyword":"twitter stalking","tags":["stalking"]}, {"keyword":"twitterstalk","tags":null}]
https://api.raventools.com/api?key=YOURAPIKEY&method=keywords_tags&domain=tweetstalk.com&format=xml
<?xml version="1.0" encoding="UTF-8"?> <Raven> <keywords> <keyword> <value>best free seo tool</value> <tags> <tag>seo</tag> <tag>tool</tag> </tags> </keyword> <keyword> <value>breaking news</value> <tags> <tag>news;/tag> </tags> </keyword> <keyword> <value>stalk twitter</value> <tags /> </keyword> <keyword> <value>stalking twitter</value> <tags> <tag>stalking</tag> </tags> </keyword> <keyword> <value>tweet stalk</value> <tags> <tag>tweet</tag> <tag>stalk</tag> </tags> </keyword> <keyword> <value>tweetstalk</value> <tags> <tag>stalk</tag> </tags> </keyword> <keyword> <value>tweetstalker</value> <tags> <tag>stalker</tag> </tags> </keyword> <keyword> <value>twitter stalk</value> <tags> <tag>stalk</tag> </tags> </keyword> <keyword> <value>twitter stalking</value> <tags> <tag>stalking</tag> </tags> </keyword> <keyword> <value>twitterstalk</value> <tags /> </keyword> </keywords> </Raven>
[{"keyword":"best free seo tool","tags":["seo","tool"]}, {"keyword":"breaking news","tags":["news"]}, {"keyword":"stalk twitter","tags":null}, {"keyword":"stalking twitter","tags":["stalking"]}, {"keyword":"tweet stalk","tags":["tweet","stalk"]}, {"keyword":"tweetstalk","tags":["stalk"]}, {"keyword":"tweetstalker","tags":["stalker"]}, {"keyword":"twitter stalk","tags":["stalk"]}, {"keyword":"twitter stalking","tags":["stalking"]}, {"keyword":"twitterstalk","tags":null}]
This request allows you to upload a CSV containing your own link data and returns a list of new Link IDs.
upload_links
file
CSV file to be imported. Column order can be varied. Columns available are: "status", "link type", "link text", "link url", "link description", "website name", "website url", "website type", "contact name", "contact email", "content id", "cost", "cost type", "payment method", "payment reference", "start date", "end date", "creation date", "comment", "owner name", "tags"
monitor
If set, link monitoring will be turned on for the uploaded links.
Example: curl -F "file=@sample.csv" -F "monitor=1" "http://api.raventools.com/api/?key=YOURAPIKEY&method=upload_links&domain=DOMAIN&format=json Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <links> <link id="5760823"></link> <link id="5760824"></link> <link id="5760825"></link> </links> </Raven> Sample Response (JSON): ["5760823","5760824","5760825"]
curl -F "file=@sample.csv" -F "monitor=1" "http://api.raventools.com/api/?key=YOURAPIKEY&method=upload_links&domain=DOMAIN&format=json
<?xml version="1.0" encoding="UTF-8"?> <Raven> <links> <link id="5760823"></link> <link id="5760824"></link> <link id="5760825"></link> </links> </Raven>
["5760823","5760824","5760825"]
This request will return the all links for the domain provided.
get_links
tag
Filter your results to a particular tag
limit
Limits the number of results returned. Limits to 100 results by default. Maximum is 1000.
offset
Offsets the number of results returned. Useful when requesting the next group of results with the limit parameter.
Example: https://api.raventools.com/api/?key=YOURAPIKEY&method=get_links&domain=tweetstalk.com&tag=blogs Sample Response (XML): <?xml version="1.0" encoding="UTF-8"?> <Raven> <counts> <all>9001</all> <current>9000</current> </counts> <links> <link id="1234567890"> <link_status>Active</link_status> <link_type>Organic</link_type> <link_text>Raven Tools</link_text> <link_url>http://www.raventools.com</link_url> <website_domain>WebExamples.com</website_domain> <website_url>http://www.example.com/awesome-seo-tools</website_url> <website_type>Example</website_type> <contact_name>Evan Xample</contact_name> <contact_email>example@example.com</contact_email> <link_cost>0.00</link_cost> <cost_type></cost_type> <cost_frequency></cost_frequency> <payment_method></payment_method> <payment_reference></payment_reference> <start_date></start_date> <end_date></end_date> <group_id>0</group_id> <tags></tags> <date_added>2012-02-24</date_added> <user_id>123456</user_id> <user_name>Hovie Lister</user_name> </link> </links> </Raven> Sample Response (JSON): [{"link_id":"1234567890","link_status":"Active","link_type":"Organic","link_text":"Raven Tools","link_url":"http://www.raventools.com","website_domain":"WebExamples.com","website_url":"http://www.example.com/awesome-seo-tools", "website_type":"Example","contact_name":"Evan Xample","contact_email":"example@example.com","link_cost":"0.00","cost_type":null, "cost_frequency":null,"payment_method":null,"payment_reference":"","start_date":"","end_date":"", "group_id":"0","tags":"","date_added":"2012-02-24","user_id":"123456","user_name":"Hovie Lister"}]
https://api.raventools.com/api/?key=YOURAPIKEY&method=get_links&domain=tweetstalk.com&tag=blogs
<?xml version="1.0" encoding="UTF-8"?> <Raven> <counts> <all>9001</all> <current>9000</current> </counts> <links> <link id="1234567890"> <link_status>Active</link_status> <link_type>Organic</link_type> <link_text>Raven Tools</link_text> <link_url>http://www.raventools.com</link_url> <website_domain>WebExamples.com</website_domain> <website_url>http://www.example.com/awesome-seo-tools</website_url> <website_type>Example</website_type> <contact_name>Evan Xample</contact_name> <contact_email>example@example.com</contact_email> <link_cost>0.00</link_cost> <cost_type></cost_type> <cost_frequency></cost_frequency> <payment_method></payment_method> <payment_reference></payment_reference> <start_date></start_date> <end_date></end_date> <group_id>0</group_id> <tags></tags> <date_added>2012-02-24</date_added> <user_id>123456</user_id> <user_name>Hovie Lister</user_name> </link> </links> </Raven>
[{"link_id":"1234567890","link_status":"Active","link_type":"Organic","link_text":"Raven Tools","link_url":"http://www.raventools.com","website_domain":"WebExamples.com","website_url":"http://www.example.com/awesome-seo-tools", "website_type":"Example","contact_name":"Evan Xample","contact_email":"example@example.com","link_cost":"0.00","cost_type":null, "cost_frequency":null,"payment_method":null,"payment_reference":"","start_date":"","end_date":"", "group_id":"0","tags":"","date_added":"2012-02-24","user_id":"123456","user_name":"Hovie Lister"}]
This request allows you to pass in a JSON encoded string with link data for the links you would like to create and returns a liew of new Link IDs.
add_links
The domain name you want the links to be added under. This value is optional, it can be passed in on the individual link records as well, but must be passed in either here or on each link record.
link
JSON Encoded string representing the link data you would like to create. Columns available are:
domain - Website Domain within your Raven Profile the link is part of. You can retrieve all of the domains in this profile with the API's 'domains' method status - Status of link in Raven. Examples: 'active', 'queued','requested','inactive','declined' link type - Type of link in Raven. Examples: 'User Submitted', 'Blog Comment', 'Paid (Permanent)', etc link text - Anchor text of the link on the source page link url - URL the link on the source page points to link description - Description of this link in Raven website name - Name for the website this link is associated with website url - The URL of the source page the link is found on website type - Type of website this link is from contact name - Name to use as the contact on this link contact email - Email address to use as the contact on this link creation date - Creation date to use for link owner name - Raven user who owns the link tags - Tags to associate this link with in the system, comma delimited Paid Link Options cost - Estimated Cost associated with link cost type - Examples: One Time, Daily, Weekly, Monthly, Quarterly, Annually payment method - How payment was made payment reference - Notes relating to payment (255 character max) start date - Start Date for this payment's range end date - End Date for this payment's range
domain - Website Domain within your Raven Profile the link is part of. You can retrieve all of the domains in this profile with the API's 'domains' method
status - Status of link in Raven. Examples: 'active', 'queued','requested','inactive','declined'
link type - Type of link in Raven. Examples: 'User Submitted', 'Blog Comment', 'Paid (Permanent)', etc
link text - Anchor text of the link on the source page
link url - URL the link on the source page points to
link description - Description of this link in Raven
website name - Name for the website this link is associated with
website url - The URL of the source page the link is found on
website type - Type of website this link is from
contact name - Name to use as the contact on this link
contact email - Email address to use as the contact on this link
creation date - Creation date to use for link
owner name - Raven user who owns the link
tags - Tags to associate this link with in the system, comma delimited
Paid Link Options
cost - Estimated Cost associated with link
cost type - Examples: One Time, Daily, Weekly, Monthly, Quarterly, Annually
payment method - How payment was made
payment reference - Notes relating to payment (255 character max)
start date - Start Date for this payment's range
end date - End Date for this payment's range
Example: curl "http://api.raventools.com/api/?key=YOURAPIKEY&method=add_links&domain=DOMAIN&link=[{"domain":"raventools.com","status":"active","link text":"Raven Blog","link url":"http://www.raventools.com/blog","link description":"Raven Tools Blog"}] Sample Response (JSON) ["5760823","5760824","5760825"]
curl "http://api.raventools.com/api/?key=YOURAPIKEY&method=add_links&domain=DOMAIN&link=[{"domain":"raventools.com","status":"active","link text":"Raven Blog","link url":"http://www.raventools.com/blog","link description":"Raven Tools Blog"}]
This request allows you to pass in a JSON encoded string with link data for the links you would like to update and returns a list of the link ID's and if they were properly updated.
update_links
link id - The ID Raven assigned to this link when it was created. Required for this method domain - Website Domain within your Raven Profile the link is part of. You can retrieve all of the domains in this profile with the API's 'domains' method status - Status of link in Raven. Examples: 'active', 'queued','requested','inactive','declined' link type - Type of link in Raven. Examples: 'User Submitted', 'Blog Comment', 'Paid (Permanent)', etc link text - Anchor text of the link on the source page link url - URL the link on the source page points to link description - Description of this link in Raven website name - Name for the website this link is associated with website url - The URL of the source page the link is found on website type - Type of website this link is from contact name - Name to use as the contact on this link contact email - Email address to use as the contact on this link creation date - Creation date to use for link owner name - Raven user who owns the link tags - Tags to associate this link with in the system, comma delimited Paid Link Options cost - Estimated Cost associated with link cost type - Examples: One Time, Daily, Weekly, Monthly, Quarterly, Annually payment method - How payment was made payment reference - Notes relating to payment (255 character max) start date - Start Date for this payment's range end date - End Date for this payment's range
link id - The ID Raven assigned to this link when it was created. Required for this method
Example: curl "http://api.raventools.com/api/?key=YOURAPIKEY&method=update_links&link=[{"link id":"130","status":"active","link text":"Raven Blog","link url":"www.raventools.com/blog","link type":"Paid (Permanent)","link description":"Raven Tools Blog","website type":"Social Media","website url":"www.about.com","tags":"raven,blog","creation date":"2012-07-14","paymentmethod":"paypal","cost":"12.45"}] Sample Response (JSON) {"5760823":1,"5760824":1,"5760825":1}
curl "http://api.raventools.com/api/?key=YOURAPIKEY&method=update_links&link=[{"link id":"130","status":"active","link text":"Raven Blog","link url":"www.raventools.com/blog","link type":"Paid (Permanent)","link description":"Raven Tools Blog","website type":"Social Media","website url":"www.about.com","tags":"raven,blog","creation date":"2012-07-14","paymentmethod":"paypal","cost":"12.45"}]
{"5760823":1,"5760824":1,"5760825":1}
delete_links
JSON Encoded string representing the link data you would like to create. Columns available are: 'link id'
Example: curl "http://api.raventools.com/api/?key=YOURAPIKEY&method=delete_links&link=[{"link id":"130"},{"link id":"131"},{"link id":"132"}] Sample Response (JSON) {"130":1,"131":1,"132":1}
curl "http://api.raventools.com/api/?key=YOURAPIKEY&method=delete_links&link=[{"link id":"130"},{"link id":"131"},{"link id":"132"}]
{"130":1,"131":1,"132":1}
This request will retrieve all of the default link types along with your custom link types your account has in the system.
get_link_types
json or xml
Example: curl "http://api.raventools.com/api/?key=YOURAPIKEY&method=get_link_types&format=json Sample Response (XML) <?xml version="1.0" encoding="UTF-8"?> <Raven> <types> <type>Custom</type> <type>Wahoo!!</type> <type>User Submitted</type> <type>Content Exchange</type> <type>Paid (Permanent)</type> <type>Paid (Temporary)</type> <type>Blog Comment</type> <type>Organic</type> <type>Indirect / Other</type> <type>Competitor Backlink</type> </types> </Raven> Sample Response (JSON) {"results":["Custom","Wahoo!!","User Submitted","Content Exchange","Paid (Permanent)","Paid (Temporary)","Blog Comment","Organic","Indirect \/ Other","Competitor Backlink"]}
curl "http://api.raventools.com/api/?key=YOURAPIKEY&method=get_link_types&format=json
<?xml version="1.0" encoding="UTF-8"?> <Raven> <types> <type>Custom</type> <type>Wahoo!!</type> <type>User Submitted</type> <type>Content Exchange</type> <type>Paid (Permanent)</type> <type>Paid (Temporary)</type> <type>Blog Comment</type> <type>Organic</type> <type>Indirect / Other</type> <type>Competitor Backlink</type> </types> </Raven>
{"results":["Custom","Wahoo!!","User Submitted","Content Exchange","Paid (Permanent)","Paid (Temporary)","Blog Comment","Organic","Indirect \/ Other","Competitor Backlink"]}
This request will retrieve all of the default website types along with any custom website types your account setup in the system.
get_website_types
Example: curl "http://api.raventools.com/api/?key=YOURAPIKEY&method=get_website_types&format=json Sample Response (XML) <?xml version="1.0" encoding="UTF-8"?> <Raven> <types> <type>Corporate Blog</type> <type>Social Media</type> </types> </Raven> Sample Response (JSON) {"results":["Corporate Blog","Social Media"]}
curl "http://api.raventools.com/api/?key=YOURAPIKEY&method=get_website_types&format=json
<?xml version="1.0" encoding="UTF-8"?> <Raven> <types> <type>Corporate Blog</type> <type>Social Media</type> </types> </Raven>
{"results":["Corporate Blog","Social Media"]}
Each API key/IP address is allowed 100 requests per minute. If you exceed the limit, an HTTP 503 error response will be returned.
To construct and test API requests, we've created the API Testing Tool. If you have questions about the API and its usage, please contact us at support at raventools.com.
