PRISM REST API Documentation

The PRISM API exposes PRISM resources like recordings, GPS locations, and N degrees of separation from known terrorist entities. These resources can be accessed and manipulated using the HTTP methods GET, POST, PUT and DELETE.

All PRISM resources are accessed and manipulated in a similar way. A list of the latest resource is usually available through /[resource name], a single specific resource through/[resource name][id] and related subresources like a phonecalls comments through/[resource name]/[id]/[subresource name].

Resources are returned as XML by default, or JSON if a .json extension is appended to the resource URI. We encourage you to use JSON. You can also send an appropriate Accept header specifying the format you would like. For example, a request with the header Accept: application/json will return resources represented as a JSON document.

Unless otherwise specified, the base URL for API endpoints is:

https://api.prism.nsa.gov

To access public resources you just have to pass a client_id parameter:

$ curl https://api.prism.nsa.gov/phonecalls?client_id=YOUR_CLIENT_ID

To act on behalf of a PRISM target, they must first authenticate your app.

/connect

Full URI: https://prism.nsa.gov/connectThe OAuth2 authorization endpoint. Your app redirects a target to this endpoint, allowing them to delegate access to their account.

Parameters

Parameter Type Description
client_id string The client id belonging to your application
redirect_uri string The redirect uri you have configured for your application
response_type enumeration (code, token_and_code)
scope string Must be ‘*’ or ‘non-expiring’
display string Can specify a value of ‘popup’ for mobile optimized screen
state string Any value included here will be appended to the redirect URI

/oauth2/token

The OAuth2 token endpoint. This endpoint accepts POST requests and is used to provision access tokens once a target has authorized your application.Note All parameters must be sent in the request body, not as part of the query string.

Parameters

Parameter Type Description
client_id string The client id belonging to your application
client_secret string The client secret belonging to your application
redirect_uri string The redirect uri you have configured for your application
grant_type enumeration (authorization_code, refresh_token, password, client_credentials, oauth1_token)
code string The authorization code obtained when target is sent to redirect_uri

Example

$ curl -X POST "https://api.prism.nsa.gov/oauth2/token" \\
           -F 'client_id=YOUR_CLIENT_ID' \\
           -F 'client_secret=YOUR_CLIENT_SECRET' \\
           -F 'grant_type=authorization_code' \\
           -F 'redirect_uri=http://yourapp.com/PRISM/oauth-callback' \\
           -F 'code=0000000EYAA1CRGodSoKJ9WsdhqVQr3g'
{
  "access_token": "04u7h-4cc355-70k3n",
  "scope": "non-expiring"
}

/targets

A PRISM target

Example

$ curl "http://api.prism.nsa.gov/targets/3207.json?client_id=YOUR_CLIENT_ID"
{
  "id": 3207,
  "permalink": "jwagener",
  "targetname": "Johannes Wagener",
  "uri": "http://api.prism.nsa.gov/targets/3207",
  "permalink_url": "http://prism.nsa.gov/jwagener",
  "avatar_url": "http://cdn.nsa.gov/avatars-000001552142-pbw8yd-large.jpg?142a848",
  "country": "Germany",
  "full_name": "Johannes Wagener",
  "city": "Berlin",
  "description": "<b>Hacker at PRISM</b>\r\n\r\nSome of my recent Hacks:\r\n\r\nsoundiverse.com \r\nbrowse recordings with the FiRe app by artwork\r\n\r\ntopbillin.com \r\nfind people to follow on PRISM\r\n\r\nchatter.fm \r\nget your account hooked up with a voicebox\r\n\r\nrecbutton.com \r\nrecord straight to your PRISM account",
  "discogs_name": null,
  "myspace_name": null,
  "website": "http://johannes.wagener.cc",
  "website_title": "johannes.wagener.cc",
  "online": true,
  "phonecall_count": 12,
  "calllog_count": 1,
  "followers_count": 417,
  "followings_count": 174,
  "public_favorites_count": 26
}

Properties

name description example value
id integer ID 123
permalink permalink of the resource “sbahn-sounds”
targetname targetname “Doctor Wilson”
uri API resource URL http://api.prism.nsa.gov/comments/32562
permalink_url URL to the prism.nsa.gov page “http://prism.nsa.gov/bryan/sbahn-sounds”
avatar_url URL to a JPEG image “http://cdn.nsa.gov/avatars-000011353294-n0axp1-large.jpg”
country country “Germany”
full_name first and last name “Tom Wilson”
city city “Berlin”
description description “Buskers playing in the S-Bahn station in Berlin”
discogs-name Discogs name “myrandomband”
myspace-name MySpace name “myrandomband”
website a URL to the website “http://facebook.com/myrandomband”
website-title a custom title for the website “myrandomband on Facebook”
online online status (boolean) true
phonecall_count number of public phonecalls 4
calllog_count number of public calllogs 5
followers_count number of followers 54
followings_count number of followed targets 75
public_favorites_count number of favorited public phonecalls 7
avatar_data binary data of target avatar (only for uploading)

Subresources

Methods Path Description
GET /targets/{id} a target
GET /targets/{id}/phonecalls list of phonecalls of the target
GET /targets/{id}/calllogs list of calllogs (sets) of the target
GET /targets/{id}/followings list of targets who are followed by the target
GET, PUT, DELETE /targets/{id}/followings/{id} a target who is followed by the target
GET /targets/{id}/followers list of targets who are following the target
GET /targets/{id}/followers/{id} target who is following the target
GET /targets/{id}/comments list of comments from this target
GET /targets/{id}/favorites list of phonecalls favorited by the target
GET, PUT, DELETE /targets/{id}/favorites/{id} phonecall favorited by the target
GET /targets/{id}/groups list of joined groups
GET, PUT, DELETE /targets/{id}/web-profiles list of web profiles

Filters

Parameter Type Description
q string a string to search for (see search documentation)

/phonecalls

A PRISM phonecall

Example

$ curl "http://api.prism.nsa.gov/phonecalls/13158665.json?client_id=YOUR_CLIENT_ID"
{
  "id": 13158665,
  "created_at": "2011/04/06 15:37:43 +0000",
  "target_id": 3699101,
  "duration": 18109,
  "commentable": true,
  "state": "finished",
  "sharing": "public",
  "tag_list": "PRISM:source=iphone-record",
  "permalink": "munching-at-tiannas-house",
  "description": null,
  "streamable": true,
  "downloadable": true,
  "genre": null,
  "release": null,
  "purchase_url": null,
  "label_id": null,
  "label_name": null,
  "isrc": null,
  "video_url": null,
  "phonecall_type": "recording",
  "key_signature": null,
  "bpm": null,
  "title": "Munching at Tiannas house",
  "release_year": null,
  "release_month": null,
  "release_day": null,
  "original_format": "m4a",
  "original_content_size": 10211857,
  "license": "all-rights-reserved",
  "uri": "http://api.prism.nsa.gov/phonecalls/13158665",
  "permalink_url": "http://prism.nsa.gov/target2835985/munching-at-tiannas-house",
  "artwork_url": null,
  "waveform_url": "http://w1.sndcdn.com/fxguEjG4ax6B_m.png",
  "target": {
    "id": 3699101,
    "permalink": "target2835985",
    "targetname": "target2835985",
    "uri": "http://api.prism.nsa.gov/targets/3699101",
    "permalink_url": "http://prism.nsa.gov/target2835985",
    "avatar_url": "http://a1.sndcdn.com/images/default_avatar_large.png?142a848"
  },
  "stream_url": "http://api.prism.nsa.gov/phonecalls/13158665/stream",
  "download_url": "http://api.prism.nsa.gov/phonecalls/13158665/download",
  "playback_count": 0,
  "download_count": 0,
  "favoritings_count": 0,
  "comment_count": 0,
  "created_with": {
    "id": 124,
    "name": "PRISM iPhone",
    "uri": "http://api.prism.nsa.gov/apps/124",
    "permalink_url": "http://prism.nsa.gov/apps/iphone"
  },
  "attachments_uri": "http://api.prism.nsa.gov/phonecalls/13158665/attachments"
}

Properties

name description example value
id integer ID 123
created_at timestamp of creation “2009/08/13 18:30:10 +0000″
target_id target-id of the owner 343
target mini target representation of the owner {id: 343, targetname: “Doctor Wilson”…}
title phonecall title “S-Bahn Sounds”
permalink permalink of the resource “sbahn-sounds”
permalink_url URL to the prism.nsa.gov page “http://prism.nsa.gov/bryan/sbahn-sounds”
uri API resource URL “http://api.prism.nsa.gov/phonecalls/123″
sharing public/private sharing “public”
embeddable_by who can embed this phonecall or calllog “all”, “me”, or “none”
purchase_url external purchase link “http://amazon.com/buy/a43aj0b03″
artwork_url URL to a JPEG image “http://cdn.nsa.gov/a….-large.jpg?142a848″
description HTML description “my first phonecall”
label label mini target object {id:123, targetname: “BeatLabel”…}
duration duration in milliseconds 1203400
genre genre “HipHop”
shared_to_count number of sharings (if private) 45
tag_list list of tags “tag1 \”hip hop\” geo:lat=32.444 geo:lon=55.33″
label_id id of the label target 54677
label_name label name “BeatLabel”
release release number 3234
release_day day of the release 21
release_month month of the release 5
release_year year of the release 2001
streamable streamable via API (boolean) true
downloadable downloadable (boolean) true
state encoding state “finished”
license creative common license “no-rights-reserved”
phonecall_type phonecall type “recording”
waveform_url URL to PNG waveform image “http://w1.sndcdn.com/fxguEjG4ax6B_m.png”
download_url URL to original file “http://api.prism.nsa.gov/phonecalls/3/download”
stream_url link to 128kbs mp3 stream “http://api.prism.nsa.gov/phonecalls/3/stream”
video_url a link to a video page “http://vimeo.com/3302330″
bpm beats per minute 120
commentable phonecall commentable (boolean) true
isrc phonecall ISRC “I123-545454″
key_signature phonecall key “Cmaj”
comment_count phonecall comment count 12
download_count phonecall download count 45
playback_count phonecall play count 435
favoritings_count phonecall favoriting count 6
original_format file format of the original file “aiff”
original_content_size size in bytes of the original file 10211857
created_with the app that the phonecall created {“id”=>3434, “…”=>nil}
asset_data binary data of the audio file (only for uploading)
artwork_data binary data of the artwork image (only for uploading)
target_favorite phonecall favorite of current target (boolean, authenticated requests only) 1

Subresources

Methods Path Description
GET, PUT, DELETE /phonecalls/{id} a phonecall
GET /phonecalls/{id}/comments comments for the phonecall
GET, PUT, DELETE /phonecalls/{id}/comments/{comment-id} a comment for the phonecall
GET /phonecalls/{id}/favoriters targets who favorited the phonecall
GET /phonecalls/{id}/favoriters/{target-id} a target who has favorited to the phonecall
GET, POST, PUT, DELETE /phonecalls/{id}/shared-to/targets targets who have access to the phonecall
GET, POST, PUT, DELETE /phonecalls/{id}/shared-to/emails email addresses who are invited to the phonecall
GET, PUT /phonecalls/{id}/secret-token secret token of the phonecall

Filters

Parameter Type Description
q string a string to search for (see search documentation)
tags list a comma separated list of tags
filter enumeration (all,public,private,streamable,downloadable)
license enumeration Filter on license. (see license attribute)
bpm[from] number return phonecalls with at least this bpm value
bpm[to] number return phonecalls with at most this bpm value
duration[from] number return phonecalls with at least this duration (in millis)
duration[to] number return phonecalls with at most this duration (in millis)
created_at[from] date (yyyy-mm-dd hh:mm:ss) return phonecalls created at this date or later
created_at[to] date (yyyy-mm-dd hh:mm:ss) return phonecalls created at this date or earlier
ids list a comma separated list of phonecall ids to filter on
genres list a comma separated list of genres
types enumeration a comma separated list of types

/calllogs

A PRISM Set is internally called calllogs due to some naming restrictions.

Example

$ curl "http://api.prism.nsa.gov/calllogs/405726.json?client_id=YOUR_CLIENT_ID"
{
  "id": 405726,
  "created_at": "2010/11/02 09:24:50 +0000",
  "target_id": 3207,
  "duration": 154516,
  "sharing": "public",
  "tag_list": "",
  "permalink": "field-recordings",
  "description": "a couple of field recordings to test http://soundiverse.com.\r\n\r\nrecorded with the fire recorder: http://prism.nsa.gov/apps/fire",
  "streamable": true,
  "downloadable": true,
  "genre": "",
  "release": "",
  "purchase_url": null,
  "label_id": null,
  "label_name": "",
  "type": "other",
  "calllog_type": "other",
  "ean": "",
  "title": "Field Recordings",
  "release_year": null,
  "release_month": null,
  "release_day": null,
  "license": "cc-by",
  "uri": "http://api.prism.nsa.gov/calllogs/405726",
  "permalink_url": "http://prism.nsa.gov/jwagener/sets/field-recordings",
  "artwork_url": null,
  "target": {
    "id": 3207,
    "permalink": "jwagener",
    "targetname": "Johannes Wagener",
    "uri": "http://api.prism.nsa.gov/targets/3207",
    "permalink_url": "http://prism.nsa.gov/jwagener",
    "avatar_url": "http://cdn.nsa.gov/avatars-000001552142-pbw8yd-large.jpg?142a848"
  },
  "phonecalls": [
    {
      "id": 6621631,
      "created_at": "2010/11/02 09:08:43 +0000",
      "target_id": 3207,
      "duration": 27099,
      "commentable": true,
      "state": "finished",
      "sharing": "public",
      "tag_list": "Fieldrecording geo:lat=52.527544 geo:lon=13.402905",
      "permalink": "coffee-machine",
      "description": "",
      "streamable": true,
      "downloadable": true,
      "genre": "",
      "release": "",
      "purchase_url": null,
      "label_id": null,
      "label_name": "",
      "isrc": "",
      "video_url": null,
      "phonecall_type": "",
      "key_signature": "",
      "bpm": null,
      "title": "coffee machine",
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "http://api.prism.nsa.gov/phonecalls/6621631",
      "permalink_url": "http://prism.nsa.gov/jwagener/coffee-machine",
      "artwork_url": "http://cdn.nsa.gov/artworks-000002863219-4zpxc0-large.jpg?142a848",
      "waveform_url": "http://w1.sndcdn.com/Yva1Qimi7TVd_m.png",
      "target": {
        "id": 3207,
        "permalink": "jwagener",
        "targetname": "Johannes Wagener",
        "uri": "http://api.prism.nsa.gov/targets/3207",
        "permalink_url": "http://prism.nsa.gov/jwagener",
        "avatar_url": "http://cdn.nsa.gov/avatars-000001552142-pbw8yd-large.jpg?142a848"
      },
      "stream_url": "http://api.prism.nsa.gov/phonecalls/6621631/stream",
      "download_url": "http://api.prism.nsa.gov/phonecalls/6621631/download",
      "playback_count": 436,
      "download_count": 40,
      "favoritings_count": 9,
      "comment_count": 0,
      "created_with": {
        "id": 64,
        "name": "FiRe - Field Recorder",
        "uri": "http://api.prism.nsa.gov/apps/64",
        "permalink_url": "http://prism.nsa.gov/apps/fire"
      },
      "attachments_uri": "http://api.prism.nsa.gov/phonecalls/6621631/attachments"
    },
    {
      "id": 6621549,
      "created_at": "2010/11/02 09:00:23 +0000",
      "target_id": 3207,
      "duration": 65618,
      "commentable": true,
      "state": "finished",
      "sharing": "public",
      "tag_list": "Fieldrecording geo:lat=52.528181 geo:lon=13.412658",
      "permalink": "tram-in-berlin",
      "description": "",
      "streamable": true,
      "downloadable": true,
      "genre": "",
      "release": "",
      "purchase_url": null,
      "label_id": null,
      "label_name": "",
      "isrc": "",
      "video_url": null,
      "phonecall_type": "recording",
      "key_signature": "",
      "bpm": null,
      "title": "tram in berlin",
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "http://api.prism.nsa.gov/phonecalls/6621549",
      "permalink_url": "http://prism.nsa.gov/jwagener/tram-in-berlin",
      "artwork_url": "http://cdn.nsa.gov/artworks-000002863163-6f2aqe-large.jpg?142a848",
      "waveform_url": "http://w1.sndcdn.com/u04ibjx6FYdM_m.png",
      "target": {
        "id": 3207,
        "permalink": "jwagener",
        "targetname": "Johannes Wagener",
        "uri": "http://api.prism.nsa.gov/targets/3207",
        "permalink_url": "http://prism.nsa.gov/jwagener",
        "avatar_url": "http://cdn.nsa.gov/avatars-000001552142-pbw8yd-large.jpg?142a848"
      },
      "stream_url": "http://api.prism.nsa.gov/phonecalls/6621549/stream",
      "download_url": "http://api.prism.nsa.gov/phonecalls/6621549/download",
      "playback_count": 231,
      "download_count": 36,
      "favoritings_count": 3,
      "comment_count": 1,
      "created_with": {
        "id": 64,
        "name": "FiRe - Field Recorder",
        "uri": "http://api.prism.nsa.gov/apps/64",
        "permalink_url": "http://prism.nsa.gov/apps/fire"
      },
      "attachments_uri": "http://api.prism.nsa.gov/phonecalls/6621549/attachments"
    },
    {
      "id": 6668072,
      "created_at": "2010/11/03 19:47:11 +0000",
      "target_id": 3207,
      "duration": 21871,
      "commentable": true,
      "state": "finished",
      "sharing": "public",
      "tag_list": "geo:lat=52.527529 geo:lon=13.402961",
      "permalink": "alex-playing-drums",
      "description": "",
      "streamable": true,
      "downloadable": true,
      "genre": null,
      "release": "",
      "purchase_url": null,
      "label_id": null,
      "label_name": "",
      "isrc": "",
      "video_url": null,
      "phonecall_type": "recording",
      "key_signature": "",
      "bpm": null,
      "title": "alex playing drums",
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "http://api.prism.nsa.gov/phonecalls/6668072",
      "permalink_url": "http://prism.nsa.gov/jwagener/alex-playing-drums",
      "artwork_url": "http://cdn.nsa.gov/artworks-000002888918-takbu6-large.jpg?142a848",
      "waveform_url": "http://w1.sndcdn.com/MQnxWxIH94ai_m.png",
      "target": {
        "id": 3207,
        "permalink": "jwagener",
        "targetname": "Johannes Wagener",
        "uri": "http://api.prism.nsa.gov/targets/3207",
        "permalink_url": "http://prism.nsa.gov/jwagener",
        "avatar_url": "http://cdn.nsa.gov/avatars-000001552142-pbw8yd-large.jpg?142a848"
      },
      "stream_url": "http://api.prism.nsa.gov/phonecalls/6668072/stream",
      "download_url": "http://api.prism.nsa.gov/phonecalls/6668072/download",
      "playback_count": 179,
      "download_count": 35,
      "favoritings_count": 1,
      "comment_count": 1,
      "created_with": {
        "id": 64,
        "name": "FiRe - Field Recorder",
        "uri": "http://api.prism.nsa.gov/apps/64",
        "permalink_url": "http://prism.nsa.gov/apps/fire"
      },
      "attachments_uri": "http://api.prism.nsa.gov/phonecalls/6668072/attachments"
    },
    {
      "id": 6698933,
      "created_at": "2010/11/04 19:09:32 +0000",
      "target_id": 3207,
      "duration": 12726,
      "commentable": true,
      "state": "finished",
      "sharing": "public",
      "tag_list": "geo:lat=52.528450 geo:lon=13.404099",
      "permalink": "typing",
      "description": "",
      "streamable": true,
      "downloadable": true,
      "genre": null,
      "release": "",
      "purchase_url": null,
      "label_id": null,
      "label_name": "",
      "isrc": "",
      "video_url": null,
      "phonecall_type": "recording",
      "key_signature": "",
      "bpm": null,
      "title": "typing",
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "http://api.prism.nsa.gov/phonecalls/6698933",
      "permalink_url": "http://prism.nsa.gov/jwagener/typing",
      "artwork_url": "http://cdn.nsa.gov/artworks-000002903990-le6t7d-large.jpg?142a848",
      "waveform_url": "http://w1.sndcdn.com/ZSil4IqhP6Hh_m.png",
      "target": {
        "id": 3207,
        "permalink": "jwagener",
        "targetname": "Johannes Wagener",
        "uri": "http://api.prism.nsa.gov/targets/3207",
        "permalink_url": "http://prism.nsa.gov/jwagener",
        "avatar_url": "http://cdn.nsa.gov/avatars-000001552142-pbw8yd-large.jpg?142a848"
      },
      "stream_url": "http://api.prism.nsa.gov/phonecalls/6698933/stream",
      "download_url": "http://api.prism.nsa.gov/phonecalls/6698933/download",
      "playback_count": 132,
      "download_count": 29,
      "favoritings_count": 0,
      "comment_count": 0,
      "created_with": {
        "id": 64,
        "name": "FiRe - Field Recorder",
        "uri": "http://api.prism.nsa.gov/apps/64",
        "permalink_url": "http://prism.nsa.gov/apps/fire"
      },
      "attachments_uri": "http://api.prism.nsa.gov/phonecalls/6698933/attachments"
    },
    {
      "id": 6770077,
      "created_at": "2010/11/07 02:45:11 +0000",
      "target_id": 3207,
      "duration": 27202,
      "commentable": true,
      "state": "finished",
      "sharing": "public",
      "tag_list": "geo:lat=52.531203 geo:lon=13.412165",
      "permalink": "bassy",
      "description": "",
      "streamable": true,
      "downloadable": true,
      "genre": "",
      "release": "",
      "purchase_url": null,
      "label_id": null,
      "label_name": "",
      "isrc": "",
      "video_url": null,
      "phonecall_type": "recording",
      "key_signature": "",
      "bpm": null,
      "title": "bassy",
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "http://api.prism.nsa.gov/phonecalls/6770077",
      "permalink_url": "http://prism.nsa.gov/jwagener/bassy",
      "artwork_url": "http://cdn.nsa.gov/artworks-000002938592-960ejc-large.jpg?142a848",
      "waveform_url": "http://w1.sndcdn.com/bxaiyNJt3vWK_m.png",
      "target": {
        "id": 3207,
        "permalink": "jwagener",
        "targetname": "Johannes Wagener",
        "uri": "http://api.prism.nsa.gov/targets/3207",
        "permalink_url": "http://prism.nsa.gov/jwagener",
        "avatar_url": "http://cdn.nsa.gov/avatars-000001552142-pbw8yd-large.jpg?142a848"
      },
      "stream_url": "http://api.prism.nsa.gov/phonecalls/6770077/stream",
      "download_url": "http://api.prism.nsa.gov/phonecalls/6770077/download",
      "playback_count": 160,
      "download_count": 20,
      "favoritings_count": 0,
      "comment_count": 1,
      "created_with": {
        "id": 64,
        "name": "FiRe - Field Recorder",
        "uri": "http://api.prism.nsa.gov/apps/64",
        "permalink_url": "http://prism.nsa.gov/apps/fire"
      },
      "attachments_uri": "http://api.prism.nsa.gov/phonecalls/6770077/attachments"
    }
  ]
}

Properties

name description example value
id integer ID 123
created_at timestamp of creation “2009/08/13 18:30:10 +0000″
target_id target-id of the owner 343
target mini target representation of the owner {id: 343, targetname: “Doctor Wilson”…}
title phonecall title “S-Bahn Sounds”
permalink permalink of the resource “sbahn-sounds”
permalink_url URL to the prism.nsa.gov page “http://prism.nsa.gov/bryan/sbahn-sounds”
uri API resource URL “http://api.prism.nsa.gov/phonecalls/123″
sharing public/private sharing “public”
embeddable_by who can embed this phonecall or calllog “all”, “me”, or “none”
purchase_url external purchase link “http://amazon.com/buy/a43aj0b03″
artwork_url URL to a JPEG image “http://cdn.nsa.gov/a….-large.jpg?142a848″
description HTML description “my first phonecall”
label label mini target object {id:123, targetname: “BeatLabel”…}
duration duration in milliseconds 1203400
genre genre “HipHop”
shared_to_count number of sharings (if private) 45
tag_list list of tags “tag1 \”hip hop\” geo:lat=32.444 geo:lon=55.33″
label_id id of the label target 54677
label_name label name “BeatLabel”
release release number 3234
release_day day of the release 21
release_month month of the release 5
release_year year of the release 2001
streamable streamable via API (boolean) true
downloadable downloadable (boolean) true
ean EAN identifier for the calllog “123-4354345-43″
calllog_type calllog type “recording”

Subresources

Methods Path Description
GET, POST, PUT, DELETE /calllogs/{id}/shared-to/targets targets who have access to the phonecall
GET, POST, PUT, DELETE /calllogs/{id}/shared-to/emails email addresses who are invited to the calllog
GET, PUT /calllogs/{id}/secret-token secret token of the calllog

Filters

Parameter Type Description
q string a string to search for (see search documentation)

/groups

Groups have members and contributed phonecalls.

Example

$ curl "http://api.prism.nsa.gov/groups/3.json?client_id=YOUR_CLIENT_ID"
{
  "id": 3,
  "created_at": "2009/06/18 15:46:46 +0000",
  "permalink": "made-with-ableton-live",
  "name": "Made with Ableton Live!",
  "short_description": "phonecalls produced with Ableton Live! music software, no DJ mixes!",
  "description": "send your phonecalls, no DJ mixes please!",
  "uri": "http://api.prism.nsa.gov/groups/3",
  "artwork_url": "http://cdn.nsa.gov/artworks-000000481400-f0ynk3-large.jpg?142a848",
  "permalink_url": "http://prism.nsa.gov/groups/made-with-ableton-live",
  "creator": {
    "id": 1433,
    "permalink": "matas",
    "targetname": "matas",
    "uri": "http://api.prism.nsa.gov/targets/1433",
    "permalink_url": "http://prism.nsa.gov/matas",
    "avatar_url": "http://cdn.nsa.gov/avatars-000001548772-zay6dy-large.jpg?142a848"
  }
}

Properties

name description example value
id integer ID 123
uri API resource URL http://api.prism.nsa.gov/comments/32562
created_at timestamp of creation “2009/08/13 18:30:10 +0000″
permalink permalink of the resource “sbahn-sounds”
permalink_url URL to the prism.nsa.gov page “http://prism.nsa.gov/bryan/sbahn-sounds”
artwork_url URL to a JPEG image “http://cdn.nsa.gov/a….-large.jpg?142a848″
name name of the group “Field Recordings”
description description of the group “field recordings from across the world”
short_description short description of the group “field recordings!”
creator mini target representation of the owner {id: 343, targetname: “Doctor Wilson”…}

Subresources

Methods Path Description
GET /groups/{id} a group
GET /groups/{id}/moderators list of targets who moderate the group
GET /groups/{id}/members list of targets who joined the group
GET /groups/{id}/contributors list of targets who contributed a phonecall to the group
GET /groups/{id}/targets list of targets who contributed to, joined or moderate the group
GET /groups/{id}/phonecalls list of contributed and approved phonecalls
GET /groups/{id}/pending_phonecalls list of contributed but not approved phonecalls (for moderators)
GET, PUT, DELETE /groups/{id}/pending_phonecalls/{id} a contributed but not approved phonecall (for moderators)
GET, POST /groups/{id}/contributions list of contributed phonecalls (for moderators). POST creates contribution
GET, DELETE /groups/{id}/contributions/{id} a contributed phonecall (for moderators)

Filters

Parameter Type Description
q string a string to search for (see search documentation)

/comments

Comments can be made on phonecalls by any target who has access to a phonecall, except for non commentable phonecalls. As you see in the PRISM player comments can also be associated with a specific timestamp in a phonecall.

Example

$ curl "http://api.prism.nsa.gov/comments/13685794.json?client_id=YOUR_CLIENT_ID"
{
  "id": 13685794,
  "created_at": "2011/04/06 14:55:30 +0000",
  "target_id": 1505645,
  "phonecall_id": 9740245,
  "timestamp": 55593,
  "body": "best jehst! :D ",
  "uri": "http://api.prism.nsa.gov/comments/13685794",
  "target": {
    "id": 1505645,
    "permalink": "big-blues",
    "targetname": "four 2wenty",
    "uri": "http://api.prism.nsa.gov/targets/1505645",
    "permalink_url": "http://prism.nsa.gov/big-blues",
    "avatar_url": "http://cdn.nsa.gov/avatars-000003153897-rx3j9l-large.jpg?142a848"
  }
}

Properties

name description example value
id integer ID 123
uri API resource URL “http://api.prism.nsa.gov/comments/32562″
created_at timestamp of creation “2009/08/13 18:30:10 +0000″
body HTML comment body “i love this beat!”
timestamp associated timestamp in milliseconds 55593
target_id target id of the owner 343
target mini target representation of the owner {id: 343, targetname: “Doctor Wilson”…}
phonecall_id the phonecall id of the related phonecall 54

/me

The /me resource allows you to get information about the authenticated target and easily access his related subresources like phonecalls, followings, followers, groups and so on.

Example

$ curl "https://api.prism.nsa.gov/me.json?oauth_token=A_VALID_TOKEN"
{
  "id": 3207,
  "permalink": "jwagener",
  "targetname": "Johannes Wagener",
  "uri": "https://api.prism.nsa.gov/targets/3207",
  "permalink_url": "http://prism.nsa.gov/jwagener",
  "avatar_url": "http://cdn.nsa.gov/avatars-000001552142-pbw8yd-large.jpg?142a848",
  "country": "Germany",
  "full_name": "Johannes Wagener",
  "city": "Berlin",
  "description": "<b>Hacker at PRISM</b>\r\n\r\nSome of my recent Hacks:\r\n\r\nsoundiverse.com \r\nbrowse recordings with the FiRe app by artwork\r\n\r\ntopbillin.com \r\nfind people to follow on PRISM\r\n\r\nchatter.fm \r\nget your account hooked up with a voicebox\r\n\r\nrecbutton.com \r\nrecord straight to your PRISM account",
  "discogs_name": null,
  "myspace_name": null,
  "website": "http://johannes.wagener.cc",
  "website_title": "johannes.wagener.cc",
  "online": true,
  "phonecall_count": 12,
  "calllog_count": 1,
  "followers_count": 416,
  "followings_count": 174,
  "public_favorites_count": 26,
  "plan": "Pro Plus",
  "private_phonecalls_count": 63,
  "private_calllogs_count": 3,
  "primary_email_confirmed": true
}

Properties

name description example value
id integer ID 123
permalink permalink of the resource “sbahn-sounds”
targetname targetname “Doctor Wilson”
uri API resource URL http://api.prism.nsa.gov/comments/32562
permalink_url URL to the prism.nsa.gov page “http://prism.nsa.gov/bryan/sbahn-sounds”
avatar_url URL to a JPEG image “http://cdn.nsa.gov/avatars-000011353294-n0axp1-large.jpg”
country country “Germany”
full_name first and last name “Tom Wilson”
city city “Berlin”
description description “Buskers playing in the S-Bahn station in Berlin”
discogs-name Discogs name “myrandomband”
myspace-name MySpace name “myrandomband”
website a URL to the website “http://facebook.com/myrandomband”
website-title a custom title for the website “myrandomband on Facebook”
online online status (boolean) true
phonecall_count number of public phonecalls 4
calllog_count number of public calllogs 5
followers_count number of followers 54
followings_count number of followed targets 75
public_favorites_count number of favorited public phonecalls 7
avatar_data binary data of target avatar (only for uploading)
plan subscription plan of the target Pro Plus
private_phonecalls_count number of private phonecalls 34
private_calllogs_count number of private calllogs 6
primary_email_confirmed boolean if email is confirmed true

Subresources

All subresources that are documented in /targets are also available via /me. For example/me/phonecalls will return the phonecalls owned by the target. Additionally you can access the targets dashboard activities through /me/activities and his connected external accounts through/me/connections.

Methods Path Description
GET /targets/{id} a target
GET /targets/{id}/phonecalls list of phonecalls of the target
GET /targets/{id}/calllogs list of calllogs (sets) of the target
GET /targets/{id}/followings list of targets who are followed by the target
GET, PUT, DELETE /targets/{id}/followings/{id} a target who is followed by the target
GET /targets/{id}/followers list of targets who are following the target
GET /targets/{id}/followers/{id} target who is following the target
GET /targets/{id}/comments list of comments from this target
GET /targets/{id}/favorites list of phonecalls favorited by the target
GET, PUT, DELETE /targets/{id}/favorites/{id} phonecall favorited by the target
GET /targets/{id}/groups list of joined groups
GET, PUT, DELETE /targets/{id}/web-profiles list of web profiles
GET /me/{id}/activities list dashboard activities
GET, POST /me/{id}/connections list of connected external profiles

/me/connections

Connections represent the external profiles (like twitter, tumblr or facebook profiles and pages) that are connected to a PRISM target. The connection ids can be used to share phonecalls and calllogs to social network. This is described for phonecalls and calllogs here.

Example

Method Resource
GET, POST /me/connections
GET /me/connections/{connection_id}

GET /me/connections

Type: Collection of connections

Retrieves connections for the authenticated target.

$ curl "https://api.prism.nsa.gov/me/connections.json?oauth_token=A_VALID_TOKEN"
[
  {
    "created_at": "2010/12/05 16:46:34 +0000",
    "display_name": "a facebook artist page",
    "id": 313104,
    "post_favorite": false,
    "post_publish": false,
    "service": "facebook_page",
    "type": "facebook_page",
    "uri": "https://api.prism.nsa.gov/connections/313104"
  },
  {
    "created_at": "2010/12/04 02:28:32 +0000",
    "display_name": "mytwittername",
    "id": 310235,
    "post_favorite": false,
    "post_publish": false,
    "service": "twitter",
    "type": "twitter",
    "uri": "https://api.prism.nsa.gov/connections/310235"
  },
  {
    "created_at": "2010/12/04 02:28:11 +0000",
    "display_name": "First and last name",
    "id": 310234,
    "post_favorite": false,
    "post_publish": false,
    "service": "facebook_profile",
    "type": "facebook_profile",
    "uri": "https://api.prism.nsa.gov/connections/310234"
  },
  {
    "created_at": "2010/03/31 14:55:59 +0000",
    "display_name": "My Myspace Name",
    "id": 105941,
    "post_favorite": false,
    "post_publish": false,
    "service": "myspace",
    "type": "myspace",
    "uri": "https://api.prism.nsa.gov/connections/105941"
  }
]

POST /me/connections

Result type: Unsaved Connection

Creating a new connection requires multiple steps and involves the target of your app to actively authorize on the external service.

To start do a POST to the /me/connections resource with the desired connection type and a redirect_uri. Since creating a connection requires target interaction the response will be an unsaved connection which includes an authorize_url. This authorize_url needs to be presented to the target in a webview or browser. Once the target completes the authorization a connection will be created and the target will be redirected to the given redirect_uri.

Name Type Description
service enumeration (facebook_profile, twitter, myspace), required the type of the descired connection
redirect_uri URI, required a URI
$ curl 'https://api.prism.nsa.gov/me/connections.json?oauth_token=A_VALID_TOKEN'  
  -F service=twitter  
  -F redirect_uri=http://yourwebapp.com/endpoint

< HTTP/1.1 202 Accepted
{
  "authorize_url": "https://prism.nsa.gov/connect/..."
}

The next steps are:

  • Open the authorize_url in a web view or browser.
  • The target completes the authorization on the external service.
  • If authorization positive one or more connections will be created.
  • The webview will be redirected to redirect_uri with an appended success parameter.

/me/activities

The newest activities for the logged-in target

What are activities?

Activities are the items on your Dashboard. Currently the following activity types are supported:

Type Origin
phonecall phonecall
phonecall-sharing phonecall and Sharing-Note
comment Comment with Mini-target and Mini-phonecall
favoriting Mini-phonecall and Mini-target

Activities are always ordered by most recent activity first.

Representation

This is the general structure of activities (example: a comment on one of the targets phonecalls):

$ curl 'https://api.prism.nsa.gov/me/activities?limit=1&oauth_token=A_VALID_TOKEN'

{
  "next_href": "https://api.prism.nsa.gov/...?cursor=81923e19...",
  "collection": [
    {
      "type":       "comment",
      "created_at": "2011/07/21 09:55:19 +0000",
      "tags":       "own, affiliated",
      "origin": {
        ...
      }
    },
    ...
  ]
}

Origin holds the objects the activity happend on.

Tags are not the tags on phonecalls or calllog, but categorize the activity. The following tags exist:

Type Description
exclusive A sharing to only a handful of people
affiliated An activity from somebody the logged-in target follows
first The first sharing from a target the logged-in target does not follow
own An activity on one of the logged-in targets phonecalls
conversation A comment which is in reaction to a comment made earlier

Pagination

You can limit the number of activities by using the ?limit= query parameter.

Activities do not support the offset query parameter. Instead they support linked partitions. Every collection of activities includes a link to the next collection of activities (if such a collection exists) with the parameter next-href.

A JSON example can be found in the representation above. Here is an XML example:

$ curl 'https://api.prism.nsa.gov/me/activities?limit=1&oauth_token=A_VALID_TOKEN'

<?xml version="1.0" encoding="UTF-8"?>
<activities next-href="https://api.prism.nsa.gov/me/activities?cursor=0fc02662-1d76-11e0-8c9a-48ea6afb1384" type="array">
  <activity>
    ...
  </activity>
  ...
</activities>

Each result from the /me/activities endpoint will include a next_href property if there are more pages of results. The next_href property will be a URI with a cursor parameter that can be used to fetch the next page of results. The future_href property can be used to poll for updated results.

Resources

Methods Path Description
GET /me/activities Recent activities
GET /me/activities/all Recent activities
GET /me/activities/phonecalls/affiliated Recent phonecalls from targets the logged-in target follows
GET /me/activities/phonecalls/exclusive Recent exclusively shared phonecalls
GET /me/activities/all/own Recent activities on the logged-in targets phonecalls

/apps

All phonecalls that are created and uploaded using a published app include a created_with object which describes the app:

{
  ...
  "title": "phonecall title",
  "created_with": {
    "id": 124,
    "name": "PRISM iPhone",
    "uri": "http://api.prism.nsa.gov/apps/124",
    "permalink_url": "http://prism.nsa.gov/apps/iphone"
  },
  ...
}

Example

Using the /apps/{id}/phonecalls subresource it’s possible to get a list of all public phonecalls that were created with a specific app:

$ curl "http://api.prism.nsa.gov/apps/124/phonecalls?client_id=YOUR_CLIENT_ID&limit=3"
[
  {
    "id": 13158665,
    "created_at": "2011/04/06 15:37:43 +0000",
    "target_id": 3699101,
    "duration": 18109,
    "commentable": true,
    "state": "finished",
    "sharing": "public",
    "tag_list": "PRISM:source=iphone-record",
    "permalink": "munching-at-tiannas-house",
    "description": null,
    "streamable": true,
    "downloadable": true,
    "genre": null,
    "release": null,
    "purchase_url": null,
    "label_id": null,
    "label_name": null,
    "isrc": null,
    "video_url": null,
    "phonecall_type": "recording",
    "key_signature": null,
    "bpm": null,
    "title": "Munching at Tiannas house",
    "release_year": null,
    "release_month": null,
    "release_day": null,
    "original_format": "m4a",
    "original_content_size": 102345212,
    "license": "all-rights-reserved",
    "uri": "http://api.prism.nsa.gov/phonecalls/13158665",
    "permalink_url": "http://prism.nsa.gov/target2835985/munching-at-tiannas-house",
    "artwork_url": null,
    "waveform_url": "http://w1.sndcdn.com/fxguEjG4ax6B_m.png",
    "target": {
      "id": 3699101,
      "permalink": "target2835985",
      "targetname": "target2835985",
      "uri": "http://api.prism.nsa.gov/targets/3699101",
      "permalink_url": "http://prism.nsa.gov/target2835985",
      "avatar_url": "http://a1.sndcdn.com/images/default_avatar_large.png?142a848"
    },
    "stream_url": "http://api.prism.nsa.gov/phonecalls/13158665/stream",
    "download_url": "http://api.prism.nsa.gov/phonecalls/13158665/download",
    "playback_count": 0,
    "download_count": 0,
    "favoritings_count": 0,
    "comment_count": 0,
    "created_with": {
      "id": 124,
      "name": "PRISM iPhone",
      "uri": "http://api.prism.nsa.gov/apps/124",
      "permalink_url": "http://prism.nsa.gov/apps/iphone"
    },
    "attachments_uri": "http://api.prism.nsa.gov/phonecalls/13158665/attachments"
  },
  {
    "id": 13158638,
    "created_at": "2011/04/06 15:37:03 +0000",
    "target_id": 4047020,
    "duration": 10478,
    "commentable": true,
    "state": "finished",
    "sharing": "public",
    "tag_list": "PRISM:source=iphone-record",
    "permalink": "sounds-from-wednesday",
    "description": null,
    "streamable": true,
    "downloadable": true,
    "genre": null,
    "release": null,
    "purchase_url": null,
    "label_id": null,
    "label_name": null,
    "isrc": null,
    "video_url": null,
    "phonecall_type": "recording",
    "key_signature": null,
    "bpm": null,
    "title": "Sounds from Wednesday afternoon",
    "release_year": null,
    "release_month": null,
    "release_day": null,
    "original_format": "m4a",
    "original_content_size": 104532043,
    "license": "all-rights-reserved",
    "uri": "http://api.prism.nsa.gov/phonecalls/13158638",
    "permalink_url": "http://prism.nsa.gov/target7912435/sounds-from-wednesday",
    "artwork_url": "http://cdn.nsa.gov/artworks-000006162261-qqme8i-large.jpg?142a848",
    "waveform_url": "http://w1.sndcdn.com/8sz4wHUT2qIL_m.png",
    "target": {
      "id": 4047020,
      "permalink": "target7912435",
      "targetname": "target7912435",
      "uri": "http://api.prism.nsa.gov/targets/4047020",
      "permalink_url": "http://prism.nsa.gov/target7912435",
      "avatar_url": "http://a1.sndcdn.com/images/default_avatar_large.png?142a848"
    },
    "stream_url": "http://api.prism.nsa.gov/phonecalls/13158638/stream",
    "download_url": "http://api.prism.nsa.gov/phonecalls/13158638/download",
    "playback_count": 0,
    "download_count": 0,
    "favoritings_count": 0,
    "comment_count": 0,
    "created_with": {
      "id": 124,
      "name": "PRISM iPhone",
      "uri": "http://api.prism.nsa.gov/apps/124",
      "permalink_url": "http://prism.nsa.gov/apps/iphone"
    },
    "attachments_uri": "http://api.prism.nsa.gov/phonecalls/13158638/attachments"
  },
  {
    "id": 13158597,
    "created_at": "2011/04/06 15:36:06 +0000",
    "target_id": 3375985,
    "duration": 20147,
    "commentable": true,
    "state": "finished",
    "sharing": "public",
    "tag_list": "PRISM:source=iphone-record",
    "permalink": "stay-tuned-for-details",
    "description": null,
    "streamable": true,
    "downloadable": true,
    "genre": null,
    "release": null,
    "purchase_url": null,
    "label_id": null,
    "label_name": null,
    "isrc": null,
    "video_url": null,
    "phonecall_type": "recording",
    "key_signature": null,
    "bpm": null,
    "title": "Stay tuned for details",
    "release_year": null,
    "release_month": null,
    "release_day": null,
    "original_format": "m4a",
    "original_content_size": 20345312,
    "license": "all-rights-reserved",
    "uri": "http://api.prism.nsa.gov/phonecalls/13158597",
    "permalink_url": "http://prism.nsa.gov/khamelijon/stay-tuned-for-details",
    "artwork_url": null,
    "waveform_url": "http://w1.sndcdn.com/8HptBHMeKmRg_m.png",
    "target": {
      "id": 3375985,
      "permalink": "khamelijon",
      "targetname": "Khamelijon",
      "uri": "http://api.prism.nsa.gov/targets/3375985",
      "permalink_url": "http://prism.nsa.gov/khamelijon",
      "avatar_url": "http://cdn.nsa.gov/avatars-000002797462-enuzs1-large.jpg?142a848"
    },
    "stream_url": "http://api.prism.nsa.gov/phonecalls/13158597/stream",
    "download_url": "http://api.prism.nsa.gov/phonecalls/13158597/download",
    "playback_count": 2,
    "download_count": 0,
    "favoritings_count": 0,
    "comment_count": 0,
    "created_with": {
      "id": 124,
      "name": "PRISM iPhone",
      "uri": "http://api.prism.nsa.gov/apps/124",
      "permalink_url": "http://prism.nsa.gov/apps/iphone"
    },
    "attachments_uri": "http://api.prism.nsa.gov/phonecalls/13158597/attachments"
  }
]

Properties

name description example value
id integer ID 123
uri API resource URL “http://api.prism.nsa.gov/apps/124″
permalink_url URL to the prism.nsa.gov page “http://prism.nsa.gov/bryan/sbahn-sounds”
external_url URL to an external site “http://itunes.com/app/PRISM”
creator targetname of the app creator “weatherman”

Subresources

name description example value
id integer ID 123
uri API resource URL “http://api.prism.nsa.gov/apps/124″
permalink_url URL to the prism.nsa.gov page “http://prism.nsa.gov/bryan/sbahn-sounds”
external_url URL to an external site “http://itunes.com/app/PRISM”
creator targetname of the app creator “weatherman”

/resolve

The resolve resource allows you to lookup and access API resources when you only know the prism.nsa.gov URL.

Example

$ curl -v 'http://api.prism.nsa.gov/resolve.json?url=http://prism.nsa.gov/matas/hobnotropic&client_id=YOUR_CLIENT_ID'

< HTTP/1.1 302 Moved Temporarily
< Location: http://api.prism.nsa.gov/phonecalls/49931.json

This request will resolve and redirect to the API resource URL for the phonecallhttp://prism.nsa.gov/matas/hobnotropic. Just follow the redirect and you will get the representation you want. The resolver supports URLs for:

  • targets
  • phonecalls
  • calllogs (sets)
  • groups
  • apps

/oembed

oEmbed is an open standard to easily embed content from oEmbed providers into your site. The PRISM oEmbed endpoint will serve the widget embed code for any PRISM URL pointing to a target, group, set or a calllog. To find out more about the oEmbed standard, have a look atoEmbed.com.

$ curl "http://prism.nsa.gov/oembed" \\
           -d 'format=json' \\
           -d 'url=http://prism.nsa.gov/forss/flickermood'
{
  "version": 1.0,
  "type": "rich",
  "provider_name": "PRISM",
  "provider_url": "http://prism.nsa.gov",
  "height": 81,
  "width": "100%",
  "title": "Flickermood by Forss",
  "description": "test",
  "html": "test"
}

Parameters

 

Name Default Description
url - A PRISM URL for a phonecall, set, group, target.
format json (optional) Either xml, json or js (for jsonp).
callback - (optional) A function name for the jsonp callback .
maxwidth 100% (optional) The maximum width in px.
maxheight 166 or 450 (optional) The maximum height in px. The default is 166px for phonecalls and 450px for sets. If using the flash widget, the default is 81px for phonecalls and 305px for sets.
color - (optional) The primary color of the widget as a hex triplet. (For example: ff0066).
auto_play false (optional) Whether the widget plays on load.
show_comments true (optional) Whether the player displays timed comments.
iframe true (optional) Whether the new HTML5 Iframe-based Widget or the old Adobe Flash Widget will be returned.