awe.sm Create API

Create Endpoint

Creates a new 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).

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

POSTapi.awe.sm/url.{format}

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

Required Parameters

Parameter	Type	Description
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.
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.
url	string	The address of the page being shared, subject to redirection patterns.
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`.

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

Create a link to be included in a server-side post to Facebook with full JSON response (using demo API Key and test Tool Key)

POST http://api.awe.sm/url.json?v=3&url=http://developers.awe.sm/&key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9&tool=mKU7uN&channel=facebook-post

{
    "application": "test",
    "awesm_id": "demo.awe.sm_K5s",
    "awesm_url": "http://demo.awe.sm/K5s",
    "campaign": null,
    "campaign_metadata": {
        "description": null,
        "name": null
    },
    "channel": "facebook-post",
    "created_at": "2011-10-04T18:00:57Z",
    "domain": "demo.awe.sm",
    "notes": null,
    "original_url": "http://developers.awe.sm/",
    "parent": null,
    "path": "K5s",
    "redirect_url": "http://developers.awe.sm/",
    "service": "facebook",
    "service_postid": null,
    "service_postid_metadata": {
        "reach": null,
        "shared_at": null
    },
    "service_userid": null,
    "sharer_id": null,
    "tag": null,
    "tool": "test-main",
    "user_id": null,
    "user_id_metadata": {
        "icon_url": null,
        "profile_url": null,
        "username": null
    }
}

Last updated 2012-01-23

Have questions? Talk to us.