API Reference

The Ajibot API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

Ajibot uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Ajibot's servers (these are rare).

Users

Users represent entities using the Ajibot service. Users include both humans and bots.

To read your user details, use the /api/users/me endpoint:

$ curl -u MY_API_KEY: https://www.ajibot.com/api/users/me
{
    "avatar": {
        "imageUrl": "https://usercontent.ajibot.com/avatars/2TK7Csf01hNdy02lPYXfMUyJmgk7J1KJ.jpg",
        "thumbUrl": "https://usercontent.ajibot.com/avatars/Oy64D2bMwXKM0CgYMC31tain0iGmkpwF.jpg"
    },
    "createdDateTime": "2017-11-30T01:00:55.144Z",
    "email": "alice@example.com",
    "handle": "alice",
    "id": "01600a70-d52c-aeed-46bf-80c86d418dd7",
    "location": "San Francisco",
    "name": "Alice Smith",
    "updatedDateTime": "2017-11-30T22:19:15.279Z"
}

To read a different user's details, use the user ID:

$ curl -u MY_API_KEY: https://www.ajibot.com/api/users/01600f08-f88f-93bd-15a5-6feeff095726
{
    "avatar": {
        "imageUrl": "https://usercontent.ajibot.com/avatars/vcShqr5ePBDigNdQa4csz3qtcsgvjdNQ.jpg",
        "thumbUrl": "https://usercontent.ajibot.com/avatars/QUnjMPWaHp1qMITAOvJv2kozwMtmu6U9.jpg"
    },
    "createdDateTime": "2017-11-30T22:25:34.957Z",
    "email": "jarvis@ajibot.com",
    "handle": "jarvis",
    "id": "01600f08-f88f-93bd-15a5-6feeff095726",
    "job": {
        "createdDateTime": "2017-11-30T22:25:34.996Z",
        "details": {
            "partnerId": "01600a70-d52c-aeed-46bf-80c86d418dd7"
        },
        "id": "01600f08-fb14-8595-9217-0779aba50bab",
        "status": "RUNNING",
        "updatedDateTime": "2017-11-30T22:25:36.538Z"
    },
    "name": "Jarvis",
    "updatedDateTime": "2017-11-30T22:25:35.037Z"
}

Messages

Messages represent text sent from one user to another.

To read messages sent between you and one of your bots, use the /api/messages endpoint:

$ curl -u MY_API_KEY: https://www.ajibot.com/api/messages?partner=01600f08-f88f-93bd-15a5-6feeff095726
{
    "messages": [
        {
            "content": "Ready",
            "createdDateTime": "2017-11-30T22:25:37.347Z",
            "from": {
                "handle": "jarvis",
                "id": "01600f08-f88f-93bd-15a5-6feeff095726"
            },
            "id": "01600f09-0439-414b-ecde-3ad95e9614e7",
            "to": {
                "handle": "alice",
                "id": "01600a70-d52c-aeed-46bf-80c86d418dd7"
            },
            "updatedDateTime": "2017-11-30T22:25:37.347Z"
        },
        {
            "content": "hello",
            "createdDateTime": "2017-11-30T22:30:00.109Z",
            "from": {
                "handle": "alice",
                "id": "01600a70-d52c-aeed-46bf-80c86d418dd7"
            },
            "id": "01600f0d-06ad-6c22-f21d-817a8d978227",
            "to": {
                "handle": "jarvis",
                "id": "01600f08-f88f-93bd-15a5-6feeff095726"
            },
            "updatedDateTime": "2017-11-30T22:30:00.109Z"
        },
        {
            "content": "Hello",
            "createdDateTime": "2017-11-30T22:30:00.262Z",
            "from": {
                "handle": "jarvis",
                "id": "01600f08-f88f-93bd-15a5-6feeff095726"
            },
            "id": "01600f0d-0743-c0fb-c34c-a245481757eb",
            "to": {
                "handle": "alice",
                "id": "01600a70-d52c-aeed-46bf-80c86d418dd7"
            },
            "updatedDateTime": "2017-11-30T22:30:00.262Z"
        }
    ],
    "totalCount": 3
}