awe.sm Create API

Update Endpoint

Updates an existing awesm_url with the specified metadata and returns it in the response. This endpoint is meant to be used by an application that is sharing on the server-side via an authenticated API (e.g., Facebook Connect, Twitter OAuth, etc.) for adding information — like the identifier of the post in which the awesm_url was shared — that is not available when an awesm_url is created.

This endpoint can only be used with awesm_urls that have been created within the last 30 days. All Metadata Parameters can be updated, but original_url, redirect_url, and created_at cannot be changed. Any fields not specified will be unaltered.

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

POSTapi.awe.sm/url/update/{awesm_id}.{format}

The GET method is also supported. HTTPS is supported on this endpoint.

Required Parameters

Parameter	Type	Description
awesm_id	string	The awesm_id form (i.e., substitute "/"s with "_"s) of the awe.sm link you wish to update. This parameter is provided as part of the URL. Passing it as an explicit parameter will have no effect.
format	string	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.
key	string	API key of the project with which the created awe.sm link should be associated.
tool	string	A unique key representing the update method of the awe.sm link. See the Link Creation Overview for more information.
v	integer	API version: `3` for this endpoint.

Optional Parameters

Parameter	Type	Description
callback	string	Returns a JSON-P response named with this parameter's value. Requires `json` as the requested `format`.
channel	string	Where the created awe.sm link was shared. See Services and Channels for list of common values.
service_postid	string	The message id containing the awe.sm link shared. Value must be formatted `service:post_id`, e.g. `twitter:130039394869583873`.
service_postid_reach	integer	The number of fans, friends, followers, etc. of the sharer on the service where the awe.sm link was shared when it was shared.
service_postid_shared_at	date	Timestamp of when the post containing the awe.sm link was shared.

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	A project-specific label for filtering and high cardinality grouping with no additional attributes. Case-sensitive.
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.

Examples

Update an existing link with a new tag value with full JSON response (using a demo API Key and test Tool Key)

POST http://api.awe.sm/url/update/demo.awe.sm_ELZ.json?v=3&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9&tool=mKU7uN&tag=foobar

{
    "awesm_url": "http://demo.awe.sm/ELZ",
    "awesm_id": "demo.awe.sm_ELZ",
    "domain": "demo.awe.sm",
    "path": "ELZ",
    "created_at": "2011-08-19T23:39:15Z",
    "redirect_url": "http://plancast.com/p/6xfs/silicon-valley-tweetup-summer-2011?utm_campaign=&utm_medium=demo.awe.sm-copypaste&utm_source=direct-demo.awe.sm&utm_content=test-main",
    "original_url": "http://plancast.com/p/6xfs/silicon-valley-tweetup-summer-2011",
    "channel": "copypaste",
    "service": "copypaste",
    "tool": "test-main",
    "application": "test",
    "parent": null,
    "sharer_id": null,
    "username":null,
    "service_userid": null,
    "service_postid": null,
    "service_postid_metadata": {
        "reach": null,
        "shared_at": null
    },
    "campaign": null,
    "campaign_metadata": {
        "description": null,
        "name": null
    },
    "user_id": "23291",
    "user_id_metadata": {
        "icon_url": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-snc4/41657_627286_9900_n.jpg",
        "username": "jhstrauss",
        "profile_url": "http://plancast.com/user/23291"
    },
    "tag": null,
    "notes": null,
    "updated_at":"2011-08-19T23:52:55Z"
}

Last updated 2012-01-23