The Marvel Comics API is a RESTful service which provides methods for accessing specific resources at canonical URLs and for searching and filtering sets of resources by various criteria. All representations are encoded as JSON objects.

Service Endpoint

The Marvel Comics API’s base endpoint is http(s)://gateway.marvel.com/.

Resources

You can access six resource types using the API:

• Comics: individual print and digital comic issues, collections and graphic novels. For example: Amazing Fantasy #15.
• Comic series: sequentially numbered (well, mostly sequentially numbered) groups comics with the same title. For example, Uncanny X-Men.
• Comic stories: indivisible, reusable components of comics. For example, the cover from Amazing Fantasy #15 or the origin of Spider-Man story from that comic.
• Comic events and crossovers: big, universe-altering storylines. For example, Infinity
• Creators: women, men and organizations who create comics. For example, Jack Kirby.
• Characters: the women, men, organizations, alien species, deities, animals, non-corporeal entities, trans-dimensional manifestations, abstract personifications, and green amorphous blobs which occupy the Marvel Universe (and various alternate universes, timelines and altered realities therein). For example, Spider-Man.

All the entity types are described in detail in our overview of entity types and representations.

Authentication

All requests to the APIs must be authenticated using the methods outlined in the request signing and authentication guidelines. Requests which fail authentication generally pass a 401 HTTP code and an error describing the reason for rejection.

Machine-Readable Documentation

All API endpoints are documented as machine-readable representations using the swagger-doc specification. These representations are available at http://gateway.marvel.com/docs.

Some odds and ends with requests

HTTP Verbs

All endpoints currently accept only HTTP GET requests.

ETags

Most successful results will contain an “etag” attribute and ETag HTTP header with a digest of the returned content. In order to save bandwidth and make your application more performant, you may optionally pass an “if-none-match” HTTP header with that digest for subsequent requests to the same URL. If the content has not changed since the last request, the response code will return with an empty body and a 304/Not Modified HTTP header and you can use a previously-stored value for the content.

Note: Most browsers will do this automatically, but you may need to manually add this logic to server-side applications.

For example:

Initial request:

Request Url: http://gateway.marvel.com/v1/public/comics
                            		Request Method: GET
                            		Params: {
                            		    "apikey": "your api key",
                            		    "ts": "a timestamp",
                            		    "hash": "your hash"
                            		}
                            		Headers: {
                            		  Accept: */*
                            		}

Initial response:

Status Code: 200
                            		Access-Control-Allow-Origin: *
                            		Date: Wed, 18 Dec 2013 22:00:55 GMT
                            		Connection: keep-alive
                            		ETag: f0fbae65eb2f8f28bdeea0a29be8749a4e67acb3
                            		Content-Length: 54943
                            		Content-Type: application/json

Subsequent request:

Request Url: http://gateway.marvel.com/v1/public/comics
                            		Request Method: GET
                            		Params: {
                            		    "apikey": "your api key",
                            		    "ts": "a timestamp",
                            		    "hash": "your hash"
                            		}
                            		Headers: {
                            		    Accept: */*
                            		    If-None-Match: f0fbae65eb2f8f28bdeea0a29be8749a4e67acb3
                            		}

Subsequent response:

Status Code: 304
                            		Access-Control-Allow-Origin: *
                            		Date: Wed, 18 Dec 2013 22:03:20 GMT
                            		Connection: keep-alive
                            		ETag: f0fbae65eb2f8f28bdeea0a29be8749a4e67acb3

Cross-origin requests and JSONP

Responses returned by the Marvel Comics API are compliant with the W3C CORS specification, which allows any properly-authorized requests to be made from any origin domain. This means that you should not need to wrap calls in JSONP callbacks in order to make calls from browser-based applications. If you do prefer to use JSONP, however, all endpoints will accept a callback parameter to all endpoints that will wrap results in a JSONP wrapper.

Examples

Without a callback:

Request: GET http://gateway.marvel.com/v1/public/comics?apikey=yourAPIKEY
                            		Response: 
                            		{
                            		    "code": 200,
                            		    "status": "Ok",
                            		    "etag": "f0fbae65eb2f8f28bdeea0a29be8749a4e67acb3",
                            		    "data": {
                            		 	  … [other data points]
                            		}

With a callback

Request: GET http://gateway.marvel.com/v1/public/comics?apikey=yourAPIKEY&callback=callback_param
                            		Response: 
                            		callback_param({
                            		    "code": 200,
                            		    "status": "Ok",
                            		    "etag": "f0fbae65eb2f8f28bdeea0a29be8749a4e67acb3",
                            		    "data": {
                            		    … [other data points]
                            		})

GZIP Compression

In order to save bandwidth and make your application more performant, the Marvel Comics API can compress responses with GZIP. You may request a GZIP-ed response by passing an Accept-Encoding header to any endpoint.

Example:

Request:

Request Url: http://gateway.marvel.com/v1/public/comics
                            		Request Method: GET
                            		Params: {
                            		    "apikey": "your api key",
                            		    "ts": "a timestamp",
                            		    "hash": "your hash"
                            		}
                            		Headers: {
                            		  Accept-Encoding:gzip
                            		}

Response:

Status Code: 200
                            		Access-Control-Allow-Origin: *
                            		Date: Wed, 18 Dec 2013 22:03:20 GMT
                            		Connection: keep-alive
                            		ETag: f0fbae65eb2f8f28bdeea0a29be8749a4e67acb3
                                            Content-Encoding: gzip