Getting Started

Visit https://givingback.ai to learn more.

Welcome to GivingbackAI Developer's Portal.

Authentication

In order to authenticate to GivingbackAI API, please follow following steps.

Create a new account

Visit Sign Up Page and create a new GivingbackAI Account.

If you already have an account, you may proceed to the next step.

Visit Sign in Page and login to your GivingbackAI Account.

If you do not have a GivingbackAI account yet, Visit Sign Up Page and create a new GivingbackAI Account.

Generate New Token

Once you have signed in by visiting to the Signin Page

Visit Cloud overview page.

Under the Access Token section, click on Generate button to generate new access token.

Click on Copy button to copy the access token to your clipboard.

You can use this token to make new request to the API. If you need to regenerate a token, repeat the above steps.

Password Reset

Visit Reset Password Page and follow the instruction to set up new password.

Once you have reset the password, return to the Signin Page

Requests

Unlock the power of GivingbackAI API for seamless, secure, and dynamic interactions within your applications! By embracing standard HTTP methods, our API seamlessly integrates with any HTTP-fluent tool, putting robust functionality at your fingertips.

Key Features

HTTP Method	Purpose	Key Benefits
GET	Retrieve information about account, VMs, etc.	Effortless retrieval of detailed data
DELETE	Permanently remove resources	Consistent final state, idempotent operation
PUT	Update resource information	Idempotent updates, simplified state modifications
PATCH	Modify specific resource attributes	Incremental changes, flexible partial modifications
POST	Create new objects	Swift initiation of innovative ideas
HEAD	Retrieve metadata information	Insights into API details, rate-limiting, metrics

Elevate your development experience with GivingbackAI API's flexibility and modular approach. Rapidly prototype and seamlessly integrate our API-first platform into your projects, empowering you to craft impactful solutions efficiently. From visionary prototypes to robust applications, GivingbackAI API provides the tools and flexibility to bring your unique vision to life. Start building today and transform your development journey!

HTTP Statuses

In addition to responding to various HTTP methods, GivingbackAI API returns standard HTTP statuses, encompassing both success and error codes.

When a request is successfully fulfilled without encountering errors, the API responds with a status in the 200 range, indicating successful completion.

For requests in the 400 range, it signifies an issue with the request sent. This may include authentication problems, lack of authorization for a requested action, non-existent objects, or malformed requests.

If the API returns a status in the 500 range, it points to a server-side problem. This indicates that GivingbackAI is currently experiencing internal issues and cannot fulfill the request.

In case of errors (both 400 and 500 level), the response body will include a JSON object with detailed attributes, providing additional information about the encountered problem. This structure aims to assist developers in understanding and resolving issues efficiently.

Responses

Name	Type	Description
id	string	A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
message	string	A message providing additional information about the error, including details to help resolve it when possible.
request_id	string	Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Pagination

The links object is included in the response body when pagination is active. By default, each page contains up to 20 objects. If the response has 20 objects or fewer, no links object will be present. However, if the response surpasses 20 objects, the first 20 will be included along with the links object.

To customize pagination, you can specify a different limit or enforce pagination by appending ?per_page= to your request, followed by the desired number of items per page. For example, to display only two results per page, add ?per_page=2 to your query. The maximum limit for results per page is set to 200.

Within the links object, there is a pages object that holds keys indicating relationships with additional pages. The values of these keys are the URLs of the corresponding pages and will be labeled as follows:

first: The URI of the first page of results.
prev: The URI of the previous sequential page of results.
next: The URI of the next sequential page of results.
last: The URI of the last page of results.

The pages object will only include links that are relevant. For example, on the first page, no first or prev links will be set, maintaining consistency in situations where certain links wouldn't make sense.

Rate Limit

Requests made through the GivingbackAI API are subject to rate limiting on a per OAuth token basis. The current rate limits are as follows:

5,000 requests per hour
250 requests per minute (5% of the hourly total)

Exceeding either limit results in rate limiting until the commencement of the next cycle. It's advisable to space out requests that would otherwise be issued in bursts for optimal results.

Rate limiting details are conveyed in the response headers of each request, featuring the following relevant headers:

ratelimit-limit: Specifies the number of requests allowed per hour.
ratelimit-remaining: Indicates the remaining number of requests before reaching the limit.
ratelimit-reset: Represents the time when the oldest request will expire, provided in Unix epoch time.

Additional rate limiting information is included only within burst limit error response headers:

retry-after: Specifies the number of seconds to wait before making another request when rate limited.

As long as the ratelimit-remaining count remains above zero, additional requests can be made. Each request has its own timer, contributing to the ratelimit-remaining count for one complete hour after the request is made. Once the timer for a request expires, it is no longer counted toward the request limit.

The ratelimit-reset header indicates the time when the oldest request will expire, as each request's timer runs independently. If ratelimit-remaining reaches zero, subsequent requests will receive a 429 error code until the request reset is reached.

It's important to note that reaching zero in ratelimit-remaining can signify meeting the "burst limit" of 250 requests per minute, even if the 5,000 requests per hour limit was not reached. In such cases, the 429 error response will include a retry-after header indicating the waiting time (in seconds) before the request can be retried.

Special rate limit requirements apply to certain endpoints, such as:

Only 12 POST requests to the /v2/floating_ips endpoint for creating Floating IPs can be made per 60 seconds.
Only 10 GET requests to the /v2/account/keys endpoint for listing SSH keys can be made per 60 seconds.
Only 5 requests to any and all v2/cdn/endpoints can be made per 10 seconds, including v2/cdn/endpoints, v2/cdn/endpoints/$ENDPOINT_ID, and v2/cdn/endpoints/$ENDPOINT_ID/cache.
Only 50 strings within the files json struct in the v2/cdn/endpoints/$ENDPOINT_ID/cache payload can be requested every 20 seconds.

CORS Policy

To enable requests to the GivingbackAI API from other domains, Cross-Origin Resource Sharing (CORS) support is implemented.

CORS support is essential for facilitating AJAX requests outside the domain of origin, allowing the implementation of projects like control panels that utilize the API. This informs the browser that it is permitted to send requests to an external domain.

When making non-GET requests, the browser initiates a "preflight" request by sending an OPTIONS method with the Origin header. The server responds with the allowed methods and constraints. The client then proceeds with the actual request if it falls within the specified limits.

Although this process is typically handled by the browser in the background, you can use curl to simulate the procedure using the provided example. The headers indicating constraints include:

Access-Control-Allow-Origin: Specifies the domain sent by the client or browser as the origin of the request, set through the Origin header.
Access-Control-Allow-Methods: Defines the allowed options for requests from the specified domain, generally including all available methods.
Access-Control-Expose-Headers: Contains the headers available to requests from the origin domain.
Access-Control-Max-Age: Specifies the validity duration of the access. After expiration, a new preflight request should be sent.
Access-Control-Allow-Credentials: Set to true, allowing the sending of the OAuth token for authentication.

You typically won't need to worry about the specifics of these headers, as the browser handles most of the work for you. GivingbackAI API ensures smooth cross-origin communication, supporting seamless integration with diverse applications and platforms.