awe.sm Create API

Retweet Endpoint

Takes a string of text and creates awesm_urls for any links in the original string. Returns the string with the new awesm_urls substituted for the original links. This endpoint can be used by an application that is sharing on the server side via an authenticated API (e.g., Facebook Connect, Twitter OAuth, etc.) OR directly in end-user-facing UIs attached directly to sharing calls-to-action, like a 'Tweet This' link.

Known bots (like web crawlers) are blacklisted from creating links via this endpoint.

Create API requests are limited to 8,000 per hour.

POSTapi.awe.sm/url/retweet.{format}

GETapi.awe.sm/url/retweet

HTTPS is supported on this endpoint.

Required Parameters

Parameter	Type	Description
format	string	Optional for GET requests. Data format of response: `json` or `txt`. This parameter is provided as part of the URL. Passing it as an explicit parameter will have no effect. A 400 error will be returned if an invalid format is specified.
channel	string	Where the created awe.sm link will be shared. See Services and Channels for list of common values.
key	string	API key of the project with which the created awe.sm link should be associated.
tool	string	A unique key representing the creation method of the awe.sm link. See the Link Creation Overview for more information.
text	string	The URL-encoded text containing the links to be turned into awe.sm links. Only links with a leading `http://` will be recognized.
v	integer	API version: `3` for this endpoint.

Optional Parameters

Parameter	Type	Description
destination	string	Optional for GET requests. Not accepted for POST requests. The URL to which the user should be redirected to upon clicking on this link. All instances of the string "AWESM_TEXT" will be replaced by the specified `text` parameter. This value must be URL encoded, including switching any &'s or #'s to %26 and %23, respectively. If the destination is Twitter, make sure to double encode any &s or #s in the text argument, e.g., . The redirect uses status code 302.
errors	boolean	Default `FALSE`. Determines whether or not the API responds with an error code when awe.sm link creation fails and a `destination` value is specified. If `FALSE` and an error occurs, the user will be redirected to the `destination` value using the specified `url` value for `AWESM_URL`.
make_parent	boolean	Default `TRUE`. If `TRUE`, any awe.sm-powered links passed in `text` will be made parents of the resulting link generated, regardless of whether the link is unwrapped or not. If `FALSE`, the parent-child relationship will be ignored.
unwrap	boolean	Default `FALSE`. If `FALSE`, exact links passed in `text` as will be used as original_url values. If `TRUE`, links passed in `text` will be crawled to find their ultimate destinations as original_url values. Unlike other Create API endpoints, this applies to awe.sm-powered links passed in `text as well.`

Metadata Parameters

Parameter	Type	Description
campaign	string	A project-specific label for filtering and low cardinality grouping. This is the stubified identifier of a `campaign_name` (i.e., a-z0-9_-). If a `campaign` value that isn't stubified (e.g., a human-readable name) is specified, we will automatically stubify it for the `campaign` value and save the submitted value as the `campaign_name`.
campaign_description	string	A human-readable description of a campaign. Requires a valid `campaign`. Must be specified when a campaign is created. Returned when `with_metadata=true` in Stats API requests.
campaign_name	string	A human-readable name of a campaign. Requires a valid `campaign`. Must be specified when a campaign is created. If no `campaign_name` is explicitly specified, the non-stubified `campaign` value will be used. Returned when `with_metadata=true` in Stats API requests.
notes	string	An arbitrary, open-ended field retrievable only on individual awe.sm links. Maximum length of 256 characters.
parent	string	The `awesm_id` that drove the visit that led to this awe.sm link being created. See Link Creation overview for more information. If the `url` itself is an awe.sm link or contains an `awesm` URL parameter that belongs to the project, it automatically will be set as the parent value, unless otherwise specified.
service_userid	string	The user id of the sharer on the service being shared to. Value must be formatted `service:user_id`, where "service" corresponds to the service of the specified `channel`. Example: `twitter:13263` for tweets made by @jhstrauss. A 400 error will be returned if the service is incorrectly specified. If only a numerical user id is specified (i.e., no leading string and colon) and a known `channel` with a corresponding `service` value is specified, the service value and colon will be automatically pre-pended. Do not rely on this behavior.
tag	string or array of strings	A case-sensitive field capable of storing multiple values up to 255 characters. Use a URL array in multiple value mode (`tag_3[]=foo&tag_3[]=bar`) or a key-value pair (`tag_3=foo`) in single value mode. See the Tag Overview for more information.
tag_2
tag_3
tag_4
tag_5
user_id	string	Your application's unique identifier for the user initiating the share. Case-sensitive, so we suggest using numeric identifiers.
user_id_icon_url	string	URL of the profile image of the user initiating the share. Requires a valid `user_id`. Must be specified when the user is first identified with awe.sm. Returned when `with_metadata=true` in Stats API requests.
user_id_profile_url	string	URL of the user's profile in your application. Requires a valid `user_id`. Must be specified when the user is first identified with awe.sm. Returned when `with_metadata=true` in Stats API requests.
user_id_username	string	Human-readable username associated with the user initiating the share. Requires a valid `user_id`. Must be specified when the user is first identified with awe.sm. Returned when `with_metadata=true` in Stats API requests.

Advanced Parameters

Parameter	Type	Description
domain	string	The custom domain on which the awe.sm link will be created. Defaults to the custom domain default set in Project Settings. A 403 error will be returned if the project does not have access to the domain specified.
path	string	The extension you want on the awesm_url to be created. We recommend using this field only when you don't care about tracking, since static links that are used multiple times don't provide the same level of tracking as dynamically-generated links that are unique per share action. Our 404 pass-through feature might make more sense. Cannot be used in the Retweet Endpoint. If multiple values are specified for any other parameters in the Create Batch Endpoint and a single path is specified, an error 400 will be returned.

Examples

Take a string containing a link and substitute it with an awesm_url for the destination URL (i.e., unwrap=true) to be included in a server-side post to Twitter via GET with full JSON response (using a demo API Key and test Tool Key)

GET http://api.awe.sm/url/retweet.json?v=3&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9&tool=mKU7uN&channel=twitter&unwrap=true&make_parent=false&text=I'm%20a%20n00b%20who%20doesn't%20know%20any%20better,%20so%20I%20use%20links%20like%20these:%20http://bit.ly/lYixsm.%20Please%20help!%20:-)&service_userid=twitter:13263

{
    "awesm_text":"I'm a n00b who doesn't know any better, so I use links like these: http://demo.awe.sm/CkK. Please help20:-)",
    "awesm_urls":[
        {
            "awesm_url":"http://demo.awe.sm/CkK",
            "awesm_id":"demo.awe.sm_CkK",
            "domain":"demo.awe.sm",
            "path":"CkK",
            "created_at":"2011-08-05T15:52:38Z",
            "redirect_url":"http://blog.awe.sm/2011/06/17/url-shorteners-are-dead-long-live-url-shorteners/",
            "original_url":"http://blog.awe.sm/2011/06/17/url-shorteners-are-dead-long-live-url-shorteners/",
            "channel":"twitter",
            "service":"twitter",
            "tool":"test-main",
            "application":"test",
            "parent":null,
            "sharer_id":"de20e5d0-a1a8-012e-ee0a-123139042842",
            "username":"null",
            "service_userid":"twitter:13263",
            "service_postid":null,
            "service_postid_metadata":{
                "shared_at":null,
                "reach":null
            },
            "campaign":null,
            "campaign_metadata":{
                "description":null,
                "name":null
            },
            "user_id":null,
            "user_id_metadata":{
                "icon_url":null,
                "username":null,
                "profile_url":null
            },
            "tag":null,
            "notes":null
        }
    ]
}

Share a user-entered Tweet containing a link on Twitter in a new window (using a demo API Key and test Tool Key)

<form name="input" action="http://api.awe.sm/url/retweet" method="get" target="_blank">
   <textarea rows="3" cols="60" name="text">You can write whatever you want as long as you include this link: http://developers.awe.sm/</textarea>
   <input type="hidden" name="v" value="3">
   <input type="hidden" name="tool" value="mKU7uN">
   <input type="hidden" name="key" value="5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9">
   <input type="hidden" name="channel" value="twitter">
   <input type="hidden" name="destination" value="http://twitter.com/intent/tweet?text=AWESM_TEXT">
   <br>
   <input type="submit" value="Tweet">
</form>

Try it:

Last updated 2012-01-23

Have questions? Talk to us.