Messages Resources

A Message for the purposes of this API represents an HTTP request and response pair. Each message can contain a request, a response, or both (most common).

Message Lists

The default message list resource returns all messages in the given bucket. This is equivalent to the 'All Traffic' view in the dashboard. Alternately, you may request one of the special stream views, each corresponding to a Traffic Inspector view or you can view your saved Stream Views via their own resource.

Request

GET/buckets/<bucket_key>/messages

GET/buckets/<bucket_key>/errors

GET/buckets/<bucket_key>/shared

GET/buckets/<bucket_key>/captures

Filter Parameters
count integer Maximum number of messages to return. Defaults to 50 if not specified. Maximum value is 1000.
since timestamp Only return messages after the given Unix timestamp
before timestamp Only return messages before the given Unix timestamp
Examples

1. Retrieve all messages for the bucket with the key a1b2c3d4.

GET /buckets/a1b2c3d4/messages

2. Return the most recent 10 messages in the bucket.

GET /buckets/a1b2c3d4/messages?count=10

3. Return all errors in the bucket since the given timestamp.

GET /buckets/a1b2c3d4/errors?since=1371578235

4. Return the last 25 messages that have been shared since the given timestamp.

GET /buckets/a1b2c3d4/shared?count=25&since=1371578235

Response

Each message list resource returns a list of messages, excluding request and response bodies. Request and response bodies can be retrieved by requesting the corresponding individual message detail.

Message Detail

Retrieve the details for a single message.

Request

GET/buckets/<bucket_key>/messages/<message_uuid>

Response

Data Attributes
uuid The unique identifier (UUID) for this message.
bucket_key The bucket where this message is stored.
request The HTTP request data.
request.headers Thre HTTP request headers as an object. The keys of this object are header names and the value is an array of values.
request.host The destination hostname of the HTTP request.
request.method The HTTP method of the request.
request.params Any querystring parameters in the request as an object. The keys of this object are parameter names, and the value is an array of values.
request.path The path portion of the HTTP request
request.scheme The scheme of the request. (http or https)
request.timestamp A unix timestamp representing the time the request was made. This is a floating point number that with microsecond granularity.
request.body A plain-text or base64-encoded string of data. For binary content (like images), we have base64 encoded the content so it can be returned in a JSON object. The key "body_encoding" will be set accordingly for base64 encoded message bodies.
request.body_encoding The encoding of the request.body. Either 'plaintext' or 'base64'.
response The HTTP response data.
response.headers Thre HTTP response headers as an object. The keys of this object are header names and the value is an array of values.
response.status Integer status code for the HTTP response.
response.reason Text status reason that corresponds to response.status. e.g. - 'OK', 'Not Found', etc.
response.size_bytes The size of the response body in bytes.
response.timestamp A unix timestamp representing the time the response was recieved. This is a floating point number that with microsecond granularity.
response.body A plain-text or base64-encoded string of data. For binary content (like images), we have base64 encoded the content so it can be returned in a JSON object. The key "body_encoding" will be set accordingly for base64 encoded message bodies.
response.body_encoding The encoding of the response.body. Either 'plaintext' or 'base64'.
Sample Response Data
{
    "data": {
        "bucket_key": "vnms9d3tgg4u", 
        "uuid": "7a8daf40-60ea-44d8-9b4c-4695b76f3a1d", 
        "request": {
            "body": "", 
            "body_encoding": "plaintext", 
            "headers": {
                "Accept": [
                    "*/*"
                ], 
                "Accept-Encoding": [
                    "gzip, deflate, compress"
                ], 
                "Host": [
                    "api-twilio-com-vnms9d3tgg4u.runscope.net"
                ], 
                "User-Agent": [
                    "runscope/1.0"
                ]
            }, 
            "host": "api.twilio.com", 
            "method": "GET", 
            "params": {}, 
            "path": "/", 
            "scheme": "https", 
            "timestamp": 1368828807.918586
        }, 
        "response": {
            "body": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<TwilioResponse><Versions page=\"0\" numpages=\"1\" pagesize=\"50\" total=\"2\" start=\"0\" end=\"1\" uri=\"/\" firstpageuri=\"\" previouspageuri=\"\" nextpageuri=\"\" lastpageuri=\"\"><Version><Name>2008-08-01</Name><Uri>/2008-08-01</Uri><SubresourceUris><Accounts>/2008-08-01/Accounts</Accounts></SubresourceUris></Version><Version><Name>2010-04-01</Name><Uri>/2010-04-01</Uri><SubresourceUris><Accounts>/2010-04-01/Accounts</Accounts></SubresourceUris></Version></Versions></TwilioResponse>\n", 
            "body_encoding": 'plaintext', 
            "headers": { 
                "Content-Length": [
                    "511"
                ], 
                "Content-Type": [
                    "application/xml"
                ], 
                "Runscope-Message-Id": [
                    "7a8daf40-60ea-44d8-9b4c-4695b76f3a1d"
                ]
            }, 
            "reason": "OK", 
            "size_bytes": 511, 
            "status": 200, 
            "timestamp": 1368828808.555258
        }
    }, 
    "meta": {
        "status": "success"
    }
}

Creating a Message

You can create one or more messages in a single API call. For creating messages one at a time, post a single JSON object with the message data. When sending multiple messages, include up to 50 messages enclosed in a JSON array.

In the most common case, a message will have both a request and a response, but occasionally you may want to send a message with a request or response only. This is useful to represent a situation where you did not receive a response from the HTTP server, like if the client was unable to connect to the server.

If you need to send the request and response in separate calls to the Runscope API, include a unique_identifier attribute. The unique identifier allows Runscope to link the request and response when sent through two separate API calls.

Request

POST/buckets/<bucket_key>/messages

Format

The body of the request should contain the JSON object or array for the message(s) you are creating. In addition, make sure to include a Content-Type: application/json header.

Each message being created should follow the following JSON object format depending on whether or not a request and/or response is being created:

// request only
{
    "request": { ... }
}
// response only 
{
    "response": { ... }
}
// both (most common)
{
    "request": { ... },
    "response": { ... }
}

The attributes you can send for the request and responses objects are as follows:

Message: Request Data Attributes
method string required HTTP method name (GET, POST, PUT, HEAD, OPTIONS, PATCH, DELETE, etc.)
url string required Full URL of the request, including URL querystring parameters.
headers object   Set of HTTP request headers. Values can either be represented as a string, or as an array of strings as shown above.
form object   Set of form fields included in a POST request. Values can either be represented as a string, or as an array of strings.
body string   HTTP request body (most commonly used for POST and PUT requests). If the request body contains binary data that cannot be included directly in the JSON, encode the content with Base64 and include the body_encoding attribute accordingly.
body_encoding string   If the request body was encoded with Base64, this field should be present and set to "base64". If not specified, defaults to "plaintext".
timestamp float   Unix timestamp indicating when the request was made.
Message: Response Data Attributes
status integer required HTTP status code returned in the response.
reason string   Textual description of HTTP status code. This will be set automatically if not provided in the API call. For example, if the status code is 404, this will be set to "Not Found" unless you explicitly specify a different reason.
body string   HTTP response body. If the response body contains binary data that cannot be included directly in the JSON, you should encode the content with Base64.
body_encoding string   If the response body was encoded with Base64, this field should be present and set to "base64". Default is "plaintext".
headers object   Set of HTTP request headers. Values can either be represented as a string, or as an array of strings as shown above.
response_time float   Length of time it took to receive the response, in seconds.
timestamp float   Unix timestamp indicating when the response was received.
Examples

1. Sample request data for creating a single message.

{
    "request": {
        "method": "GET",
        "url": "https://www.yourapihere.com/thanks.html",
        "headers": {
            "Host": [
                "www.yourapihere.com"
            ],
            "User-Agent": [
                "Mozilla/5.0 AppleWebKit/534.46 (KHTML, like Gecko)"
            ]
        },
        "timestamp": 1371578234.589754
    },
    "response": {
        "headers": {
            "Connection": [
                "keep-alive"
            ],
            "Content-Type": [
                "text/html"
            ],
            "Date": [
                "Tue, 18 Jun 2013 17:57:15 GMT"
            ]
        },
        "status": 200,
        "body": "<html><body>Thank you for your submission!</body></html>",
        "response_time": 0.43353,
        "timestamp": 1371578234.726113
    }
}

2. Sample request data for creating a multiple messages.

[
    {
        "unique_identifier": "grace-hopper-1",
        "request": {
            "method": "POST",
            "url": "https://www.yourapihere.com/submit?form_id=123",
            "headers": {
                "Host": [
                    "www.yourapihere.com"
                ],
                "User-Agent": [
                    "Mozilla/5.0 AppleWebKit/534.46 (KHTML, like Gecko)"
                ],
                "Content-Type": [
                    "application/x-www-form-urlencoded"
                ]
            },
            "form": {
                "first_name": [
                    "Grace"
                ],
                "last_name": [
                    "Hopper"
                ],
                "award": [
                    "Legion of Merit",
                    "World War II Victory Medal",
                    "Naval Reserve Medal"
                ]
            },
            "body": "first_name=Grace&last_name=Hopper&award=World+War+II+Victory+Medal&award=Naval+Reserve+Medal&award=Legion+of+Merit"
        }
    },
    {
        "unique_identifier": "transparent-gif-1",
        "request": {
            "method": "PUT",
            "url": "https://www.yourapihere.com/upload/transparent.gif",
            "headers": {
                "Host": [
                    "www.yourapihere.com"
                ],
                "User-Agent": [
                    "Mozilla/5.0 AppleWebKit/534.46 (KHTML, like Gecko)"
                ],
                "Content-Type": [
                    "image/gif"
                ]
            },
            "body": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
            "body_encoding": "base64"
        }  
    }
]

Response

The response includes a list of result objects for the message(s) submitted. It will always return an array, even if only one message was created. The order of the result objects corresponds to the order of messages submitted.

Data Attributes
data[].status One of the following: success, error, or warning.
data[].unique_identifier If the message had a unique_identifier, it will be returned in this field, to help match the responses to the messages that were submitted.
data[].uuid This message's Runscope-generated ID.
data[].warning An object representing warnings (non-fatal warnings) for this item. Only present if status is warning, otherwise this will be null.
data[].warning.code A numeric error code for the specific problem we encountered with this message. (warning status only)
data[].warning.message A description of the problem we encountered with this message. (warning status only)
data[].warning.more_info A link to more help about the warning. (warning status only)
data[].error An object representing errors for this item. Only present if status is error, otherwise this will be null.
data[].error.code A numeric error code for the specific problem we encountered with this message. (error status only)
data[].error.message A description of the problem we encountered with this message. (error status only)
data[].error.more_info A link to more help about the warning. (error status only)
meta.success_count Number of items saved in Runscope.
meta.warning_count Number of items saved in Runscope, which contained minor problem(s) in the input data.
meta.error_count Number of items that were unable to be saved in Runscope.
Sample Response Data
{
    "data": [
        {
            "status": "success",
            "unique_identifier": "funky-fresh-1",
            "uuid": "14e43b1c-00c4-4da8-b834-656a56809768"
        },
        {
            "status": "warning",
            "unique_identifier": "funky-fresh-2",
            "uuid": "411d3249-d148-4dc9-b1ed-ad0b704acfad",
            "warning": {
                "code": 51109,
                "message": "The request contained these unexpected fields: \"port\"",
                "more_info": "https://www.runscope.com/docs/api"
            }
        },
        {
            "status": "error",
            "unique_identifier": "funky-fresh-3",
            "error": {
                "code": 51006,
                "message": "You must include a request and/or a response in each message.",
                "more_info": "https://www.runscope.com/docs/api"
            }
        }
    ],
    "meta": {
        "success_count": 1,
        "warning_count": 1,
        "error_count": 1
    }
}

Sharing a Message

Sharing a message will create a publicly-available URL, equivalent to sharing a request in the dashboard.

PUT/buckets/<bucket_key>/shared/<message_uuid>

Response

Returns a Message Detail response with an additional JSON property named public_url that the newly-shared request can be viewed at.

Unsharing a Message

Unsharing a message will revoke the publicly-available URL, equivalent to unsharing a request in the dashboard.

DELETE/buckets/<bucket_key>/shared/<message_uuid>

Response

204 No Content with no body.

Deleting a Message

Deleting a message will permanently remove the request and response information from Runscope. A deleted message will still count toward usage numbers.

DELETE/buckets/<bucket_key>/messages/<message_uuid>

Response

204 No Content with no body.