API Introduction

What is Heavstal APIs

Heavstal API is a suite of high-performance REST APIs designed for applications of any type. From conversational AI to cryptographic security to entertainment and more, these endpoints are built for speed, reliability, and ease of use.

Why Heavstal API over traditional scraping

Traditional web scraping is difficult and unreliable due to advanced security measures (such as Cloudflare) and frequent website structure changes. Use Heavstal APIs to eliminate maintenance overhead. Heavstal handles the complexities of data ingestion and protection, ensuring a stable, reliable data stream with a 90% guaranteed uptime.

Why Heavstal APIs over other API Providers

Heavstal Tech provides a cohesive ecosystem of APIs. Instead of making requests to multiple different API providers, you can route your requests through Heavstal servers that are built to handle production workloads.

Beyond this consolidated approach, Heavstal APIs offer several key advantages:

1. Complimentary Weekly Tokens: Every Sunday, users receive 1,000 free tokens. For applications with moderate traffic, this allocation is often sufficient to run your services entirely at no cost.
2. Lightweight SDK Integration: For JavaScript developers, Heavstal offers the @heavstal/api SDK. This zero-dependency, lightweight library allows you to interact with Heavstal services efficiently without managing direct HTTP requests.
3. Competitive Pricing: For high-volume applications that exceed the free weekly quota, Heavstal offers flexible, cost-effective scaling. You can purchase additional capacity starting at 1,000 tokens for ₦3,000 (approximately $3), scaling up to 100,000 tokens for ₦300,000 (approximately $300).
4. Graceful Rate-Limiting: To ensure service continuity, Heavstal implements a buffer system. Before enforcing strict rate limits, Heavstal provides a grace period of 10 additional requests and triggers a notification email, giving you the opportunity to upgrade your plan and avoid service interruptions.

Getting Started

To use Heavstal APIs, you need an API Key. Heavstal APIs also provide an SDK for easy integration into your application.

Step 1: Getting your API key

All API requests require an API Key. Generate one by following the steps below:

1. Go to Heavstal API Key Manager.
2. Select Generate Secret Key.
3. Add a name for your API key.
4. (Optional) Add a description.
5. (Optional) Turn on Strict Mode.
6. (Optional) Enter Authorized IP Addresses (CIDR & range support included).
7. (Optional) Enter Authorized Origins.
8. (Optional) Enter Authorized User-Agents.
9. (Optional) Select Allowed APIs the API key can access.

Tip

You can create up to 5 API Keys.

Step 2: Testing your API Key

Test your API key in the API Playground to verify authentication and view expected response structures.

Code and Examples

Base URL

All endpoints live under:

https://heavstal.com.ng/api/v1

Pass the API key via the x-api-key header to authenticate your requests. If you are using the Heavstal SDK, you can pass a configuration object directly. Refer to the Heavstal API SDK Documentation for more details.

Making a Request

cURL

curl -X POST https://heavstal.com.ng/api/v1/ai \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"prompt": "Hello"}'

JavaScript

const response = await fetch('https://heavstal.com.ng/api/v1/ai', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({
    prompt: "Explain quantum physics like I'm 5",
    persona: "You're a 21st century Quantum physicist"
  })
});

const res = await response.json();
console.log(res.data);

Heavstal SDK

import { ai } from '@heavstal/api';

const chat = await ai.chat(
  "Explain quantum physics like I'm 5",
  "A 21th century Physicists with 5 PhDs"
);

console.log(chat.response);

Python

import requests

url = "https://heavstal.com.ng/api/v1/ai"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}
payload = {
    "prompt": "Explain quantum physics like I'm 5",
    "persona": "You're a 21st century Quantum physicist"
}

response = requests.post(url, headers=headers, json=payload)
res = response.json()
print(res["data"])

Typical Responses

Success Response

{
  "status": "success",
  "creator": "Heavstal Tech",
  "data": { ... }
}

Error Response

{
  "status": "error",
  "error": "...",
}

For more information on specific APIs and their exact responses, refer to their individual documentation pages.

Frequently Asked Questions (FAQ)

How to generate an API Key?

Follow the steps below to generate an API key:

1. Go to Heavstal API Key Manager.
2. Select Generate Secret Key to open the configuration page.
3. Add a name to the API key under the API Key Details section.
4. (Optional) Turn on Strict Mode and set Authorized User-Agents, Origins, IP Address & Allowed API Endpoints.
5. Select Generate API Key.
6. Verify the CAPTCHA and copy the API key from the pop-up window.

How to activate an API key’s Web Application Firewall (WAF)?

The Web Application Firewall is located in the WAF section of the Heavstal API key Manager.

Follow the steps below to activate your API Key’s WAF:

1. Go to Heavstal API key Manager.
2. Horizontally scroll to the key you want to configure and select View Key.
3. Vertically scroll to the Web Application Firewall (WAF) section.
4. At the top right of the WAF section, turn on Strict Mode.
5. Select + Add IP and enter the IP address that your requests will be sent from. You can add up to 5 IP addresses (CIDR ranges are supported). Using the wildcard IP 0.0.0.0/0 will allow requests from all IP addresses.
6. Under Authorized Origins, add up to 5 domains from which requests are expected to originate.
7. Under Authorized User-Agents, add up to 5 specific User-Agents using the same method.
8. Under Allowed APIs, select the specific API endpoints the key is allowed to access. (By default, keys can access all APIs).
9. Select Save Changes and verify the CAPTCHA.

How can I unblock a blocked IP, User-Agent, or Origin?

Follow the steps below to unblock an entity:

1. Go to Heavstal API key Manager.
2. Under the WAF Section, scroll down to WAF Security Detection.
3. Find the blocked IP, User-Agent, or Origin.
4. Select Whitelist this IP/UA/Origin and confirm.

::note

If your whitelist has already reached its limit of 5 entries, you will be unable to whitelist newly blocked entities until you remove an existing one. :::

What happens if my API Key gets accidentally exposed?

If your API key is exposed, Heavstal automatically helps minimize the impact through secret scanning and credential revocation. The affected keys are automatically revoked, and you will be notified via email so you can generate a new key.

How do I manually rotate my API Key?

To rotate your API key manually:

1. Go to Heavstal API Manager.
2. Select Roll Key.
3. Confirm the rotation.

Important

This invalidates your current key immediately. Any applications using it will stop working until you update them with the new key.

How do I manually revoke my API Key?

To revoke your API key manually:

1. Go to Heavstal API Manager.
2. Select Revoke Key.
3. Confirm the revocation.

Important

This deletes your key. You will lose access to all APIs until you generate a new one.

What happens when I hit my rate limit?

Rate limits are monitored closely, and users receive multiple notifications as they approach their quota. Should you exceed your limit, you will receive an email warning detailing a 20-request grace period. Failure to address 429 Too Many Requests errors during this period will result in the permanent revocation of your API key.

API Policy

Developer Fair Use API Policy: This policy governs fair and responsible usage of all Heavstal APIs.

1. Rate Limits Free-tier users are restricted to a moderate request volume of 1,000 requests per week.

2. Prohibited Usage The following activities are strictly prohibited:

• DDoS attacks or scraping
• Account farming
• Token sharing
• Unauthorized resale

Violations of these policies may lead to API Key termination without notice. For further information, refer to the API Policy.