Ebax Keycode API

Updated: 2012-08-13
API version: v1
Documentation version: 1.3

Ebax Keycode has RESTful API covering the basic functionality of the system.

Security & Authentication

All communication to Keycode API is SSL encrypted. Access to API is available to Keycode users with "Pro" or higher account type. Authentication is handled with Basic HTTP authentication, username: API token, password: API secret. API authentication info is available on the users profile page, click "secret" to reveal code.

Resources

Resource URLs and available methods:

Input

Data can be sent to API with POST and PUT methods as HTML form variables or in the request body in supported serialization formats with proper Content-Type header. All content must be UTF-8 encoded.

Output

Output serilization format can be selected with format URL attribute. Available data formats are listed below.

Example: https://keycode.co/api/v1/targets/?format=xml

Paged lists

Target, batch, keycode and log event list from are API limited to 100 items per page. Use page URL attribute to select page.

Example (JSON target list):

GET https://keycode.co/api/v1/targets/?page=2
{
    "list_type": "paginated",
    "target_list": {
        "items_total": 504,
        "page_number": 2,
        "page_count": 6,
        "items_per_page": 100,
        "items": [
            {
                "code": "test",
                "title": "Example",
                "url": "http://example.com/",
...

Creating targets

Targets are created with POST call to https://keycode.co/api/v1/targets/. Required fields are title and url. To create data targets add type=data attribute to URL and send data in data field. Keycode Enterprise users can use group_code URL attribute to create target in alternative group.

Request (HTML form -style):

POST https://keycode.co/api/v1/targets/

title%3DExample%26url%3Dhttp%3A%2F%2Fexample.com%2F

Response:

{
    "target": {
        "code": "testcode",
        "title": "API Test",
        "url": "http://test.com/",
        "keycode_url": "http://keycode.co/testcode",
...

Edit targets

Targets can be edit with PUT call to https://keycode.co/api/v1/targets/{target_code}/.

Request (JSON in body -style):

PUT https://keycode.co/api/v1/targets/testcode/
Content-Type: application/json; charset=UTF-8

{"title": "API Example", "url": "http://example.com/", "category": "Example"}

Response:

{
    "target": {
        "code": "testcode",
        "title": "API Example",
        "url": "http://example.com/",
        "category": "Example",
        "keycode_url": "http://keycode.co/testcode",
...

Adding keycodes to target

Keycodes can be add to target with POST call to https://keycode.co/api/v1/targets/{target_code}/keycodes/. Select number of keycodes with amount URL attribute, default is 1 and max is 1000. A list of keycode codes generated (keycode_code_list) is returned.

Example (generate 40 keycodes to target testcode):
POST https://keycode.co/api/v1/targets/testcode/keycodes/?amount=40

Using keycode tags in target

Add batch attribute with batch code of your unused keycode tags to POST call to https://keycode.co/api/v1/targets/{target_code}/keycodes/.

Example (use one keycode tag from batch testbatch in target testcode):
POST https://keycode.co/api/v1/targets/testcode/keycodes/?batch=testbatch

Examples with cURL

Target list:
curl -u {api_token}:{api_secret} -X GET https://keycode.co/api/v1/targets/

Target details:
curl -u {api_token}:{api_secret} -X GET https://keycode.co/api/v1/targets/{target_code}/

Create target (HTML form):
curl -u {api_token}:{api_secret} -X POST --data-urlencode 'title=Example' --data-urlencode 'url=http://example.com/' https://keycode.co/api/v1/targets/

Edit target (JSON):
curl -u {api_token}:{api_secret} -X PUT -H 'Content-Type: application/json' --data '{"title": "Test", "url": "https://example.com/"}' https://keycode.co/api/v1/targets/{target_code}/

Create data target (JSON):
curl -u {api_token}:{api_secret} -X POST -H 'Content-Type: application/json' --data '{"title": "Test", "data": "foobar"}' https://keycode.co/api/v1/targets/{target_code}/?type=data

Edit data target (HTML form):
curl -u {api_token}:{api_secret} -X PUT --data-urlencode 'title=Test' --data-urlencode 'data=foobar' https://keycode.co/api/v1/targets/{target_code}/

Delete target (archive):
curl -u {api_token}:{api_secret} -X DELETE https://keycode.co/api/v1/targets/{target_code}/

Add keycodes:
curl -u {api_token}:{api_secret} -X POST https://keycode.co/api/v1/targets/{target_code}/keycodes/?amount=20

Use keycode tags:
curl -u {api_token}:{api_secret} -X POST https://keycode.co/api/v1/targets/{target_code}/keycodes/?amount=5&batch={batch_code}

Event log (YAML):
curl -u {api_token}:{api_secret} -X GET https://keycode.co/api/v1/log_events/?keyword=test&page=2&format=yaml