UserInfo API Overview

Example GET command getting the current credit balance

curl -v -X 'GET' \
  '' \
  -H 'accept: application/json' \
  -H 'Authorization: <Authentication Token>'


The Webshrinker UserInfo API returns the current amount of remaining credits for the current billing cycle.


To make API requests you need to have an access key and secret key. If you don't have an access key yet, you can register for a free account on our account dashboard.

There are two methods of authentication that can be used to make API requests: Basic HTTP Authentication and Pre-signed URLs.

Basic HTTP Authentication

Example HTTP request:

GET /categories/v3/d2Vic2hyaW5rZXIuY29t HTTP/1.1
Authorization: Basic Yzk1NDJkMDFkNjlmOjE3OTAyYzJjOWIzYQ==

Basic authentication requires that you send your API access and secret key with each request to the service over HTTPS. Most programming frameworks and SDKs support sending Basic HTTP Authentication “out of the box” with a simple function call.

The access key and secret key are used as the “username” and “password” for Basic Authentication.

If you are crafting the "Authorization" header yourself it is the word "Basic" followed by the base64-encoded string "your-access-key:your-secret-key". Additional information about this HTTP header can be found on Basic access authentication on Wikipedia.

Pre-signed URLs

    from urllib import urlencode
except ImportError:
    from urllib.parse import urlencode

from base64 import urlsafe_b64encode
import hashlib

def webshrinker_userinfo_v1(access_key, secret_key, params={}):
    params['key'] = access_key

    request = "userinfo/v1/balance?{}".format(urlencode(params, True))
    request_to_sign = "{}:{}".format(secret_key, request).encode('utf-8')
    signed_request = hashlib.md5(request_to_sign).hexdigest()

    return "{}&hash={}".format(request, signed_request)

access_key = "your access key"
secret_key = "your secret key"

url = b""
print(webshrinker_userinfo_v1(access_key, secret_key, url))

Generating a pre-signed URL allows you to make requests without revealing your secret key. It’s perfect for situations where you need to embed a request in an application or in a webpage but don’t want users to know your secret key, preventing a third party from making unauthorized requests against your account.

The URL used to make the API request is signed using your access and secret key but the URL itself doesn’t contain the secret key. Instead it contains an extra parameter called "hash".

The "hash" is the MD5 hash of your secret key, a colon (":"), and the request URL with query parameters.


Example bad request response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

    "error": {
        "message": "Invalid signed hash or no API key/secret given"
Status Code Meaning
200 OK -- The request was successful, the most recent categories are returned
202 Accepted -- Your request was successful but is still being processed on the server, check back soon
400 Bad Request -- One or more parameters in the request are invalid
401 Unauthorized -- Your API key/secret key is wrong or the key doesn't have permission
402 Payment Required -- Your account balance is used up, purchase additional requests in the account dashboard
412 Precondition Failed -- Unable to satisfy the category request because there is not enough information available to classify the given URL
429 Too Many Requests -- Too many requests in a short time
500 Internal Server Error -- There was an issue processing the request, try again