Gravio API Documentation

Using the API

Getting started

This describes how to use the Gravio REST API with examples using curl.

Making a request

1. Ensure Gravio is installed and licensed. Refer to the Gravio user documentation for installation and licensing instructions. An account on the HubKit is required.
2. Create a personal access token. Log in to the HubKit and generate your first PAT for authenticating requests. For more information, see Authentication.
3. Choose an endpoint, identify the HTTP method, path, required parameters, and request payload.
4. Use the curl command to make your request. Include your token in the Authorization header, replacing YOUR-TOKEN with your token.

Example request

The following example uses the “GetActions” endpoint to retrieve the list of available Actions:

curl --request GET --insecure \
--url "https://your.graviohubkit.com/public/v1/actions" \
--header "Authorization: Bearer YOUR-TOKEN"

Example request using body parameters

This example uses the “RunActionSync” endpoint to execute the Action named “Today”:

curl --request POST --insecure \
--url "https://your.graviohubkit.com/public/v1/action/run" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "Content-Type: application/json" \
--data '{"action": "Today"}'

Using the response

After making a request, the API returns the status code, headers, and potentially a response body.

Response code and headers

To view status codes and headers, add the –include or -i option in your curl request. Example response for a successful action initiation:

HTTP/2 200
content-type: application/json
date: Wed, 05 Feb 2025 09:39:38 GMT
vary: Origin
content-length: 84

{"out":{"ExitCode":0,"Payload":"Hello world!\n","Stderr":""},"success":true,"tv":{}}

HTTP response status code indicate whtether a specific request has been sucessfully completed. Response codes are categorized as:

1. 200-299 Successful responses
2. 400-499 Cliet error responses
3. 500-599 Server error responses

Response body

Many endpoints will return a respond body. Unless specified, the response body is in JSON format.

Response body of error

When an API response has a 4xx or 5xx status code, indicating error occurred. The body contains these fields to explain error details.

{
  "Type": "GE_Unauthorized",
  "Title": "Unauthorized",
  "Detail": "Validate provided token: invalid token",
  "Timestamp": "2025-02-05T18:59:17.225722+09:00"
}

Timestamp

Timestamp returned are in rfc3339 format, e.g. ‘2025-02-05T11:28:28.485512+09:00’. For more information, please refer to https://www.rfc-editor.org/rfc/rfc3339.

Authentication

The Gravio API uses personal access token (PAT) to authenticate requests.

To authenticate your request, you will need to provide an authentication token. You can create and manage your personal access tokens in the Gravio HubKit. After creating a token, you can authenticate your request by using Authorization: Bearer to pass a token.

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

curl --request GET --insecure \
--url "https://your.graviohubkit.com/public/v1" \
--header "Authorization: Bearer YOUR-TOKEN"

Failed login

If you try to use a REST API endpoint without a token or with a token that is invalid or expired, you will receive a 401 Unauthorized response.

Rate limits

Gravio HubKit limits the number of REST API request you can make within specific amount of time. This limit helps prevent abuse and denial-of-service attacks to ensure service stability.

Token Bucket strategy is applied as the rate limit strategy. It allows 100 tokens per bucket, refilling at 10 tokens per second per IP address. Every request received consume one token.

Rate limit exceeded

If you exceed a rate limit, you will receive a ‘429 Too Many Request’ response, a code ‘GE_Rate_Limit_Exceeded’, and an error message that indicates that you exceeded a the rate limit.

The response body of the ‘GE_Rate_Limit_Exceeded’ error carries extensions Limit which indicates the current rate limit as an number of rate per second.

{
  "Type": "GE_Rate_Limit_Exceeded",
  "Title": "Rate limit exceeded",
  "Detail": "You are being rate-limited. Retry after some time to continue using the service.",
  "Extensions": {
    "Limit": 10
  },
  "Timestamp": "2025-02-05T19:25:21.105904+09:00"
}