NAV Navbar
shell
  • Introduction
  • Authentication
  • User
  • Orders
  • Rates
  • Errors
  • Introduction

    Welcome to the Alconost Nitro API! You can use our API to access Nitro API endpoints.

    Authentication

    To authorize, use this code:

    # With shell, you can just pass the correct header with each request
    curl "api_endpoint_here" \
      -H "Authorization: Basic <base64("email:password")>"
    

    Nitro expects credentials to be included in all API requests to the server in authentication header that looks like the following:

    Authorization: Basic <base64("email:password")>

    User

    Get User

    curl "https://nitro.alconost.com/api/v1/user" \
      -H "Authorization: Basic ZW1haWw6cGFzc3dvcmQ="
    

    The above command returns JSON structured like this:

    {
      "id" : 123,
      "email": "test@alconost.com",
      "full_name": "Nitro",
      "balance_overdraft_allowed": false,
      "reserved": 0.24,
      "balance": 174.46
    }
    

    This endpoint retrieves a user.

    HTTP Request

    GET https://nitro.alconost.com/api/v1/user

    Orders

    Get All Orders

    curl "https://nitro.alconost.com/api/v1/orders" \
      -H "Authorization: Basic ZW1haWw6cGFzc3dvcmQ="
    

    The above command returns JSON structured like this:

    [
      {
        "id": 6,
        "status": "QUEUE",
        "snippet": "Test",
        "source_language": "en",
        "target_language": "ru",
        "created_at": "2016-01-29T05:52:17.840197Z",
        "accepted_at": "0001-01-01T00:00:00Z",
        "completed_at": "0001-01-01T00:00:00Z"
      },
      {
        "id": 7,
        "status": "DONE",
        "snippet": "Test",
        "source_language": "en",
        "target_language": "it",
        "created_at": "2016-01-29T05:52:17.840197Z",
        "accepted_at": "2016-01-30T012:45:01.223137Z",
        "completed_at": "2016-01-30T13:00:47.312484Z"
      }
    ]
    

    This endpoint retrieves all user orders.

    HTTP Request

    GET https://nitro.alconost.com/api/v1/orders

    Query Parameters

    Parameter Type Description
    page integer Page number (default: 0)
    per_page Orders count (default: 20)

    Get a Specific Order

    curl "https://nitro.alconost.com/api/v1/orders/6" \
      -H "Authorization: Basic ZW1haWw6cGFzc3dvcmQ="
    

    The above command returns JSON structured like this:

    {
      "id": 6,
      "source_text": "Test",
      "status": "QUEUE",
      "hint": "",
      "snippet": "Test",
      "source_language": "en",
      "target_language": "ru",
      "volume": 4,
      "price": 0.04,
      "created_at": "2016-01-29T05:52:17.840197Z",
      "accepted_at": "0001-01-01T00:00:00Z",
      "completed_at": "0001-01-01T00:00:00Z",
      "quality": "EXCELLENT"
    }
    

    This endpoint retrieves a specific order.

    HTTP Request

    GET https://nitro.alconost.com/api/v1/orders/<ID>

    URL Parameters

    Parameter Description
    ID The ID of the order to retrieve

    Translate

    curl -X POST "https://nitro.alconost.com/api/v1/translate" \
      -H "Authorization: Basic ZW1haWw6cGFzc3dvcmQ=" \
      -d source_language="en" \
      -d target_languages=["ru", "it"] \
      -d text="Text to translate" \
      -d hint="Hint for translator"
    

    The above command returns JSON structured like this:

    {
      "orders": [
        {
          "id": 6,
          "source_language": "en",
          "target_language": "ru",
          "price": 0.04,
          "created_at": "2016-01-29T05:52:17.840197Z"
        },
        {
          "id": 7,
          "source_language": "en",
          "target_language": "it",
          "price": 0.05,
          "created_at": "2016-01-29T05:52:17.840197Z"
        }
      ],
      "text": "Text to translate",
      "hint": "Hint for translator",
      "volume": 4
    }
    

    This endpoint sends the text for translation and creates a list of orders.

    HTTP Request

    POST https://nitro.alconost.com/api/v1/translate

    Attributes

    Parameter Type Description
    source_language string Source language
    target_languages array Collection of target languages
    text string Text to be translated
    hint string Hint for translator
    quality enum Translation quality (at this moment EXCELLENT quality supported only)

    Delete an Order

    curl -X DELETE "https://nitro.alconost.com/api/v1/orders/6" \
      -H "Authorization: Basic ZW1haWw6cGFzc3dvcmQ="
    

    The above command returns 204 No Content:

    This endpoint deletes a specific order.

    HTTP Request

    DELETE https://nitro.alconost.com/api/v1/orders/<ID>

    URL Parameters

    Parameter Type Description
    ID integer The ID of the order to be deleted

    Rates

    Get Rates

    curl "https://nitro.alconost.com/api/v1/rates" \
      -H "Authorization: Basic ZW1haWw6cGFzc3dvcmQ=}"
    

    The above command returns JSON structured like this:

    [
      {"sourceLanguage":"en", "targetLanguage":"ms", "rate":15.4, "quality":"EXCELLENT"},
      {"sourceLanguage":"en", "targetLanguage":"tl", "rate":15.4, "quality":"EXCELLENT"},
      {"sourceLanguage":"en", "targetLanguage":"is", "rate":20.0, "quality":"EXCELLENT"}
    ]
    

    This endpoint retrieves all rates.

    HTTP Request

    GET https://nitro.alconost.com/api/v1/rates

    Errors

    The Nitro API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Something went wrong, see the response body for details (error code, description)
    401 Unauthorized -- Your API key is wrong
    403 Forbidden -- The resource requested is hidden for administrators only
    404 Not Found -- The specified resource could not be found
    405 Method Not Allowed -- You tried to access a resource with an invalid method
    406 Not Acceptable -- You requested a format that isn't json
    429 Too Many Requests -- You're requesting too many resources! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

    In case of 400 (Bad Request) response code, there is an error object returned in the response body. The error object contains the error code, error description and, optionally, additional parameters related to the error. E.g:

    {
      "code" : "HUMAN_READABLE_ERROR_CODE",
      "description": "Human readable description of the error",
      "param1": "Error specific additional parameter 1",
      "param2": "Error specific additional parameter 2"
    }
    

    The 400 error codes are:

    Error Code Meaning
    INSUFFICIENT_FUNDS There's not enough funds on the account to place an order
    WRONG_ORDER_STATUS The order is not in the QUEUE status (already taken or completed) and you try to delete it