General operation

The jokes are available at Use HTTP GET to retrieve what you want (read on below for more details). Results can returned as raw JSON data (the default case) or using a JavaScript callback function for script communication.


In the default case, the result will always look like this:

{ "type":
, "value":

The type will be “success” on success and something else when something went wrong (more details below). An example of the result of a successful request:

{ "type": "success", "value": { "id": 268, "joke": "Time waits for no man. Unless that man is Chuck Norris." } }

Using callback functions

Next to returning raw JSON data, it is also possible to automatically feed the results into a callback function. This is useful for script communication in case regular XMLHttpRequest does not work.

To use a callback function, use the following GET parameter:


The callback function will retrieve the parsed JSON as stated above.

Changing the name of the main character

The API permits changing the name of the main character when fetching a joke. To do this, use the following GET parameters:


Example: To retrieve one random joke with main character called “John Doe”, fetch the URL:

The result will be similar to before, for example:

{ "type": "success", "value": { "id": 268, "joke": "Time waits for no man. Unless that man is John Doe." } }

Escaping special characters

Some jokes contain some special characters such as “, & or <. These special characters can make it hard to show the joke correctly or can even skrew up the syntax of the result. To fix this, the API escapes special characters before returning the result. There are two options: HTML encoding or JavaScript encoding.

HTML encoding is the default. In this case, &, ” (double quotes), < and > are encoded in their respective HTML format (e.g., &amp;). In this case, you can directly insert the resulting joke in an HTML page without errors.

With JavaScript encoding, only quotes (both double and single) are escaped. In this case, backslashes are added (e.g., “Chuck’s fist” becomes “Chuck\’s fist”). JavaScript encoding is only used when you request a joke with the following GET parameter:


Fetching a random joke



{ "type": "success", "value": { "id": , "joke":
 } }

Fetching multiple random jokes




{ "type": "success", "value": &gt; }


{ "type": "success", "value": [ { "id": 1, "joke": "Joke 1" }, { "id": 5, "joke": "Joke 5" }, { "id": 9, "joke": "Joke 9" } ] }

Limiting categories

The jokes in the database are given categories such as “nerdy” or “explicit”. When fetching multiple jokes, it is possible to limit the scope to some of these categories or exclude some of them, as shown below. The list of categories can be retrieved as shown in one of the next sections.

To limit the jokes to certain categories, use the following GET parameter:


Similarly, to exclude jokes from certain categories, use the following GET parameter:


Fetching a specific joke



Result and example: same as with random joke.

Fetching the number of jokes



{ "type": "success", "value":  }


{ "type": "success", "value": 549 }

Fetching the list of joke categories



{ "type": "success", "value": &gt; }


{ "type": "success", "value": [ "nerdy", "explicit", "chuck norris", "bruce schneier" ] }

96 Responses to API

  1. how is development going? :)

    • admin says:

      I have to be honest, not much going on for the moment… Having been busy a lot, but I will continue the project when I can. For the record: planned on adding more categories, increasing the number of jokes and developing the latest-jokes-function.

  2. andy says:

    you get a specific joke part of the api is btw already working:$jokenumber

  3. When you call the count it says 550 right now but there are jokes with an id over 550. That’s because there are some ids that aren’t assigned to a joke, and if you call them you get a fatal error. Could you fix this please?

    • admin says:

      Hi Richard,

      Why is this a problem? I’ve though about this, but this would require shifting existing jokes to lower ids when a joke is removed. I chose to keep each joke at its original id.

  4. could you give a method to get the highest id?

  5. don’t mind the request, I will redo some stuff in the application and I won’t need it now. Thank you for replying though.

  6. tim says:

    Hi, brilliant site. I used your DB in a learning experience and built an Android app for this…see Chuck Norris Jokes. Some of these jokes are cut off in the database. Is there any way to complete them? E.g. “Chuck Norris is expected to win gold in every swimming competition at the 2008 Beijing Olympics, even though Chuck Norris does not swim. This is because when Chuck Norris enters the water, the water gets out of his way and Chuck Norris simply walks across the”.

    • admin says:


      Thanks for the reply, I appreciate you appreciating it :) About the joke: thanks for the bug report, I’ve removed four incomplete jokes.

      If you have other remarks or questions, be sure to let me know!

  7. This has got to be one of the neatest APIs. :)

  8. [...] Google search turned up The Internet Chuck Norris Database, a hilarious site which even contains a REST API!   Great, so this means we can get a single joke back each time by writing appropriate [...]

  9. Yuval says:

    As you’ve already noticed I’ve written a TFS 2010 build activity that will show a random Chuck Norris joke when a build is run. I hope this will make people run their builds more!
    The blog post is here. Thanks for the great work!

  10. Moeses says:

    i’m using python, i’m a new user with it, and i was wondering how can i just get the joke to display instead of the whole thing??

    • admin says:

      Hi Moeses,

      I guess with “the whole thing” you mean the whole json object? To print a random joke in python, I would do something like this:

      import urllib2
      import json

      req = urllib2.Request("")
      full_json = urllib2.urlopen(req).read()
      full = json.loads(full_json)
      print full['value']['joke']

      Hope this helps!

      • Moeses says:

        that does help a lot. had to change some things around to use for my personal siriServer for my iPhone 4. so now whenever i say chuck norris to siri i get a random quote. Thanks so much again. really cool API.

  11. SNXRaven says:

    How would I store multiple jokes in that python script

    • admin says:

      It’s not really clear to me what you mean by “storing multiple jokes”, but to fetch multiple, you can just provided the needed number to the API:

      In that case, the value in the result will be an array of jokes (see API documentation), so we can print all of them like this:

      import urllib2
      import json

      req = urllib2.Request("")
      full_json = urllib2.urlopen(req).read()
      full = json.loads(full_json)
      for joke in full['value']:
          print joke['joke']

  12. Dan Jones says:

    I found a problem with your API. When a string contains double quotes, the quotes aren’t properly escaped, thereby breaking the JSON data.

    Here’s an example I got:
    { “type”: “success”, “value”: { “id”: 394, “joke”: “”Let the Bodies Hit the Floor” was originally written as Chuck Norris’ theme song.”, “categories”: ["chuck norris"] } }

    This should be instead:
    { “type”: “success”, “value”: { “id”: 394, “joke”: “\”Let the Bodies Hit the Floor\” was originally written as Chuck Norris’ theme song.”, “categories”: ["chuck norris"] } }

  13. Dan Jones says:

    It would be good if your API returned the proper mime-type. The servers returns it as text/html, rather than application/json.

  14. 0x89 says:

    Is it really necessary to HTML-Encode the quotes? Its nasty to decode safely in Javascript without being vulnerable to XSS-Attacks.

    Couldn’t you just quote them instead? (ideally you would version the REST API so that clients that depend on the old behavior could still use the old one..).

    There are also some question marks where there should be single quotes, e.g.

    Apart from that: good work, keep it up!

    • admin says:

      Hi ox89,

      I added the option ?escape=javascript (also updated the docs above), this will add backslashes to quotes instead of escaping HTML special characters.

      The issue with joke 141 was not the result of incorrect escaping, it was in the database like that. Fixed it, I’ll go through the other jokes as well.

      • 0x89 says:

        Thanks, that was very responsive. In the meantime, I used to decode the html entities.

        Btw. this is what I have built:

        • admin says:

          No problem, and cool project!

          Your XSS remark before interests me. I don’t see how client-side decoding of the HTML encoding makes you vulnerable to XSS, could you elaborate a bit?

          • 0x89 says:

            Well, lets say someone takes over your database, and changes one of the quotes to

            alert(‘you haven been pwned’)

            If my plugin would insert this within the page


            What would happen? The attacker could execute arbitrary javascript code in the context of my page. This is what I understand as XSS. I might be mistaken though as I don’t know a lot about these topics.

            Btw. the attacker wouldn’t even have to take over your database, as you don’t use https we would also be vulnerable to man-in-the-middle-attacks.

          • 0x89 says:

            whoops, your blog engine stripped the tags out of my post..

            the alert needs to be surrounded by script tags:

            alert('you have been pwned')

            hope this works this time..

          • admin says:

            It still didn’t work, but I get the picture :) You are correct to be worried about this kind of thing, correct escaping of JSON and HTML indeed is a difficult problem.

            What you are describing is an injection attack. Originally, the only way to decode JSON was to use eval(json), in which case JavaScript code in the variable json would also be run, leading to JavaScript injection. Now, browsers allow native JSON decoding with JSON.parse(), making it impossible to sneak in code there.

            For HTML this is more difficult, browsers do not offer a method for isolating parts of the HTML tree or something similar. So $(‘#id’).html(...) could still contain HTML such as a script tag. That’s actually why I escape everything on the server, a joke’s joke attribute should never contain HTML tags, making it easier for the client.

            However, this is still a matter of trust in the web service, its correct functioning, its admin not being malevolent, the security of the web service, the security of the transport etc. Complex problem :)

  15. Sorin says:


    Just wanted t say “Cool idea!” and to point out a small issue, as visible at

    Notice the John Doe’ in the response.

    By the way, is this name replacing feature related to Chuck Norris sueing Penguin (methinks) for using his name?

    • admin says:

      Hi Sorin,

      Thanks for the bug report. The error is a genitive, “Chuck Norris’ theme song”, which should be “John Doe’s theme song” for names not ending with an s.

      And no, this is not a feature against legal issues, it’s just a cool feature. ICNDb is just a database of public jokes, this adds some flavor to it :)

      • Daniel Heath says:

        This is part of a larger difficulty of e.g. conjugating correctly when you change the name.

        For instance “Real Men”, “Ada Lovelace”, “Chuck Norris” all conjugate differently for common words (they/she/he) and tenses (wants an egg / want an egg).

  16. Ram Kashyap says:

    Hi Admin,

    Undoubtedly a very useful API for app developers ;-) Is there a way that I can remove the adult jokes? you know most of the stores are made for 13+ old years, but there is a lot of 18+ material, is there a neat jokes category?

  17. Hi … I created an API wrapper in C#, so you can easily access this API from C# apps :)

  18. Cool project!

    Used this to email all of our product development team before coming to work in the morning to have some laughs :D

    Made a PHP client for the API to contribute back.

  19. David says:

    Hey, how many jokes have you got so far? It’d be cool to display some stats :D Awesome jokes BTW.

  20. Ian Neubert says:

    Howdy Admin,

    It looks like your JSON is sometimes invalid:

    It’s not escaping things properly.

    Thanks for the site and the API!

  21. Pyry Pakkanen says:

    Is the escaping working correctly? I’m not seeing any difference between:

  22. Cloudwalker says:

    Is it just me or callback stopped working?

  23. aurel says:

    hi, first of all, thanks for your work!

    I’am thinking about integrating random jokes in my web site, as a loader message.

    so i’am thinking : if you had a database of jokes in other languages (french for example :)), would it be possible for you to add a language input in the api ?

  24. Mary says:

    I just noticed if you enter a name that does not end with the s there is a problem.
    Original: Chuck Norris’ whatever
    Problem with: Tom William’ whatever –> missing the s

  25. Nice API and good jokes. I was looking for random posts for my twitter app I designed recently. It pulls random jokes from this API and allows user to post to their twitter account.

    Here is the app:

    I hope you will like it :)

    Thanks for sharing this API.

    • admin says:

      Very cool! I had this idea myself, but didn’t come around to it. A nice addition would be to change the name of Chuck Norris into the name of the Twitter user, which you can do with the API.

  26. Erik says:

    You sir are awesome.

    If you had a raw “curl”-able url as well, that’d be great for message of the day services.

    I actually use your api for my mutt email signature!


  27. Don says:

    This is pretty awesome :) For business/HR reasons it would be handy to be able to exclude categories (like “explicit”). I currently just loop and reissue if I get one of those.

  28. Zaw says:


    just wondering if this api is still in service? i wanna use it in making android app for uni assignment. and also what are the type of categories that you have for the jokes?thanks!

  29. Ali Nazari says:

    hi my friend :)
    may i use this api in a commercial android app freely? :D

  30. I just finished up a Google Glass app. I’ll release it as soon as Google provides a way to distribute Glass apps, and give you a huge shout-out in the description.

    Thanks for providing a great API for a great database!

    Chuck Me for Google Glass

  31. Daksh says:

    I am an Android developer and made an application using ‘random’ joke api in Android. Thank you for providing such great database and api.

    Here is my link to the application on Google Play Chuck Norris Jokes on Google Play

    I also mention your website in app description in Google Play and in credits in application for providing such large database of jokes.

  32. Alex Key says:


    This is a great service, I’m making use of it in a mobile application.

    However unfortunately the escaped single quotes in the javascript encoded JSON is causing trouble.

    Although it seems sensible to javascript encode then i.e. ‘ becomes \’

    The JSON standard only specifies a small number of things that can be escaped. You don’t need to encode single quotes.

    In desktop browsers they are looser with this standard and it doesn’t cause a problem, however in a mobile environment (not the web browser itself, but e.g. iOS itself)
    json.Parse() is stricter and will throw an exception when reaching a \’

    Here on the standard page you can see that single quotes are not on the list.

    It would be great if you can not encode the single quotes please.

    Keep up the good work.


  33. Jason says:

    Hi, awesome API :-)

    I was hoping you could help clarify the way the ?exclude filter works. I see an example in the docs that calls for (what looks like) a JSON encoded array? However, in the comments I see just a string example ?exclude=explicit

    Neither of these seem to work all the time for me. I am currently using ?exclude=explicit and I just got one about an erection.

    • admin says:


      It’s both actually, but the recommended usage is using an array (without quotes), e.g.:[explicit,nerdy]


      The reason you still got a joke about an erection is that is was not yet labeled explicit. That has been fixed :) See

      Is it clear now?

  34. Ash Menon says:

    Just wanna point out that in some of the quotes, the lastName parameter isn’t always properly rendered.

    In some cases I got Jeremy Norris, instead of Jeremy Peet.

    (am trying to replicate this but I can’t seem to. Maybe it was just a faulty query on my part :D)

  35. gaarf says:

    Thanks for the API!

    I used it while playing with Angular.js – resulting in this app:

  36. Haris says:

    Hello there,

    Just for fun, I made an Android application and I used your API to pull some random jokes.

    Thanks for publishing it for free, greatly appreciated.

    Here’s the app url:

    Hope you can spread it to others.


  37. Steve Eynon says:


    Just to say thanks for the providing the API and that I’ve knocked up a quick client for the Fantom programming language:

    Fantom meets Chuck Norris



  38. e cooper says:

    hello! I am currently trying to use this in an automated chat bot, that is pretty limited in what it can output. Is there any way to return a result with just the insult? No category labels or anything, just a random text insult? I had planned on using it for Nightbot on

    Nightbot can return API results, but he displays everything he sees. Any suggestions would be great! Love the API!

    • admin says:


      The API only returns JSON, but it’s easy to get the joke itself from this result. Can you really not parse the result before displaying it?

  39. Kris Korsmo says:

    Thanks for putting this together. I built an application for the pilots of my airline which does some extensive sorting, and I use your API to display a Chuck quote while the progress bar is showing during the sort. The guys really love it! And I love the fact that I can substitute the pilot’s name for Chuck Norris. Can’t wait to see what kind of response that gets :) Also, I’ll be happy to offer my ColdFusion code if you’d like to add it to the library.

  40. Marek Lisy says:

    Thanks for the service, I just used it at our backend for our admins :)

  41. Adam W says:

    I set this up on my droid with tasker. I open AutoVoice and say “*about chuck norris*” and it grabs something via RESTasker and the tts reads it out loud. Sooo easy. Sooooo awesome. Thank you!

  42. John says:


    How to change lastname? When I make a request with it returns jokes with lastname “Norris”

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Set your Twitter account name in your settings to use the TwitterBar Section.